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

package/dist/session/RealtimeSessionRuntime.d.ts

@@ -1,11 +1,45 @@
 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';
+import { type IRecordingShardStore } from './RecordingShardStore.js';
+import type { IRecordingTransport } from './RecordingTransport.js';
+/**
+ * How long teardown waits for the server to acknowledge the recording's terminal request, measured
+ * from after `CloseAgentSession`. The terminal is `keepalive`, so it completes even if the page goes
+ * away; the wait only keeps `SavingRecording$` (and so a host's "don't close yet" guard) up while the
+ * server has not confirmed. Bounded so a dead server can never hold the End of a call hostage —
+ * unacknowledged shards stay in the local store and the server janitor assembles what arrived.
+ */
+export declare const RECORDING_TERMINAL_ACK_TIMEOUT_MS = 3000;
+/**
+ * How long teardown waits for the recorder to stop and flush its encoder. `Stop()` runs BEFORE
+ * `CloseAgentSession`, so a wedged encoder must not be able to hold the End of a call (and the
+ * server session) open; past this the recording ends at the packets already encoded.
+ */
+export declare const RECORDER_STOP_TIMEOUT_MS = 2000;
+/** Options of {@link RealtimeSessionRuntime.SendRecordingTerminal}. */
+export interface RecordingTerminalOptions {
+    /**
+     * False when the call may continue — the host's `visibilitychange → hidden` handler. The server then
+     * stamps the counts but assembles only after its grace period, so switching tabs does not rewrite the
+     * recording each time. Defaults to true (`pagehide`: the page is going away).
+     */
+    Final?: boolean;
+}
 /**
  * `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 +164,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 +185,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
@@ -215,12 +275,13 @@ export declare class RealtimeSessionRuntime {
     protected readonly mediaHost: IRealtimeMediaHost;
     /**
      * @param mediaHost the platform's media capabilities. The runtime never touches `navigator`,
-     *                  `Blob` or `FileReader` itself — microphone acquisition and audio recording
-     *                  are the host's, because both are platform-specific product decisions
-     *                  (permission UX, container format, where the bytes live).
+     *                  `Blob` or `FileReader` itself — microphone acquisition and audio capture/encoding
+     *                  are the host's, because both are platform-specific (permission UX, which
+     *                  encoder the platform offers).
      */
     constructor(mediaHost: IRealtimeMediaHost);
     private _connectionState$;
+    private readonly _resuming$;
     private _captions$;
     private _active$;
     private _delegationProgress$;
@@ -230,6 +291,7 @@ export declare class RealtimeSessionRuntime {
     private _agentName$;
     private _modelName$;
     private _minimized$;
+    private _savingRecording$;
     private _activeChannels$;
     private _channelFocus$;
     private _sessionStarted$;
@@ -237,6 +299,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 +345,17 @@ 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 — which includes waiting (at most
+     * {@link RECORDING_TERMINAL_ACK_TIMEOUT_MS}) for the server to acknowledge the recording's terminal
+     * request. False at construction and for unrecorded sessions. Exists for #5195; the runtime is
+     * platform-free, so hosts own the reaction (a "saving" indicator, a disabled navigation button,
+     * 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 +363,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 +477,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 +507,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 +
@@ -402,18 +562,54 @@ export declare class RealtimeSessionRuntime {
     private narrationTemplate;
     /**
      * The active session's audio recorder (mic + agent mix), or `null` when the user didn't
-     * consent or the browser can't record. Created after the client connects; stopped + uploaded
-     * at teardown.
+     * consent or the browser can't record. Created after the client connects; its packets are
+     * shipped as 5 s shards during the call, and it is stopped at teardown.
      */
     private recorder;
     /** ISO timestamp of when recording started — sent to the server on session start. */
     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;
-    /** How often crash-recovery shards are flushed during a recording. */
-    private static readonly segmentFlushMs;
+    /** Interval that cuts and uploads a shard every {@link recordingShardFlushMs} during a recording. */
+    private shardFlushTimer;
+    /**
+     * The current recording's shard pipeline (window → store → queue → transport), or null when not
+     * recording. A fresh pipeline per recording keeps a flush still in flight from a previous session
+     * off this session's indexes. Its queue is closed when the recording ends; anything it had not
+     * delivered stays in the local store for the next-load drain.
+     */
+    private recordingShards;
+    /** How often packets are cut into shards: the 5 s shard window, so each tick seals about one window. */
+    private static readonly recordingShardFlushMs;
+    /**
+     * Bytes of `keepalive` request bodies one terminal may use, the tail included. Browsers share about
+     * 64 KiB of in-flight keepalive bodies per page; the brief reserves 48 KiB of it for the recording,
+     * leaving room for a host's own close beacon (Caliber sends one from `pagehide` too).
+     */
+    private static readonly recordingKeepaliveBudgetBytes;
+    /**
+     * Bytes of this page's recording `keepalive` requests still in flight. The browser's keepalive budget
+     * is per page, and closing a tab fires `visibilitychange` and `pagehide` back to back, so each dispatch
+     * budgets against what the previous one has not finished sending.
+     */
+    private keepaliveBytesInFlight;
+    /** `sessionId/index` of shards whose `keepalive` copy is still in flight; never sent twice at once. */
+    private readonly keepaliveShardsInFlight;
+    /**
+     * Most runs one drain call makes (each run is itself bounded): it runs again when it was re-armed while
+     * running, or when a run deleted shards the server refused for good, which frees the page for the
+     * shards behind them.
+     */
+    private static readonly maxDrainRunsPerCall;
+    /** The durable local shard store, created on first use and shared by every recording of this runtime. */
+    private shardStore;
+    /**
+     * True once a drain ran with a transport; the drain then does nothing until a recording ends and
+     * re-arms it ({@link rearmPendingShardDrain}).
+     */
+    private pendingShardsDrained;
+    /** Bumped by every re-arm, so a drain already in flight cannot mark itself done over a re-arm. */
+    private drainGeneration;
+    /** The drain in flight, so overlapping callers share it instead of uploading the same shards twice. */
+    private drainInFlight;
     /**
      * Interval that tells the server this session is still in use, or `null` when no session is
      * running. See {@link startLivenessPulse} for why the server cannot work this out itself.
@@ -430,12 +626,33 @@ export declare class RealtimeSessionRuntime {
      * Recording-relative ms offset at which the IN-FLIGHT (not-yet-finalized) turn's audio
      * actually BEGAN — captured the moment that turn's audio/text starts flowing (its first
      * interim transcript), NOT inherited from the previous turn's end. `null` before the first
-     * turn / between turns (until the next turn's audio starts). Sent as `utteranceStartMs` on
-     * the turn's final transcript so per-turn timing lines up with the recording even when a
-     * tool-call / silence gap sits between turns (the inherit-previous-end model mis-stamped
-     * the post-gap turn at the pre-gap offset). See {@link markTurnAudioStart}.
+     * turn / between turns (until the next turn's audio starts), and it stays `null` for a turn
+     * whose start was never measured. Sent as `utteranceStartMs` on the turn's final transcript
+     * AS-IS — `null` is relayed as `null`, never replaced with 0 — so per-turn timing lines up
+     * with the recording even when a tool-call / silence gap sits between turns (the
+     * inherit-previous-end model mis-stamped the post-gap turn at the pre-gap offset). See
+     * {@link markTurnAudioStart}. A user speech onset signalled by the client does NOT land here;
+     * it has its own slot, {@link userSpeechStartMs}.
      */
     private currentTurnStartMs;
+    /**
+     * Recording-relative ms offset of the first user speech onset the client signalled
+     * (`OnUserSpeechStart`) since the last final user transcript, or `null` when none was signalled.
+     * It has its own slot, apart from {@link currentTurnStartMs}, so a user onset never claims the
+     * assistant turn's start: OpenAI user transcripts arrive asynchronously, often after the
+     * assistant's interims (or its final) for the reply have already flowed. See
+     * {@link markUserSpeechStart}.
+     */
+    private userSpeechStartMs;
+    /**
+     * `true` once an assistant turn has finalized after {@link userSpeechStartMs} was stamped BEFORE
+     * that turn began. The held onset may still be claimed by a late user transcript (OpenAI
+     * transcribes asynchronously), but the NEXT onset replaces it: an onset no transcript ever claimed
+     * (a VAD false positive, a failed transcription) must not become the start of the next real user
+     * turn. A barge-in onset (stamped during the assistant turn) is not superseded by that turn's
+     * final. An EMPTY user transcript releases the onset outright (see onClientTranscript).
+     */
+    private userSpeechStartSuperseded;
     /**
      * Wall-anchor of the SESSION clock (#3832): `performance.now()` at the moment the call went
      * live, or `null` before any call has. Read only through {@link nowTurnOffsetMs}.
@@ -486,6 +703,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 +750,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 +772,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 +801,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`.
      *
@@ -593,15 +907,22 @@ export declare class RealtimeSessionRuntime {
      *   pickers, and never synthesize overrides beyond what the user explicitly chose.
      *   Omit/`null` for the server's defaults (today's behavior).
      * @param recordingConsent Optional EXPLICIT "record this call" consent for THIS session. When
-     *   `true`, the browser records a mic + agent-audio mix and uploads it at session end. When
+     *   `true`, the browser records a mic + agent-audio mix and uploads it as 5 s Opus shards during the call. When
      *   omitted/`null`, the per-user persisted preference (`mj.realtimeVoice.recordingConsent.v1`
      *   via {@link UserInfoEngine}) is read as the default. `false` never records.
      * @param mediaCollectionId Optional per-session media-kit override (`MJ: Collections.ID`). When set,
      *   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 +962,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 +1153,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 +1204,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.
      */
@@ -767,10 +1231,60 @@ export declare class RealtimeSessionRuntime {
      * nothing (the recorder disables itself).
      */
     private startRecording;
-    /** Begins flushing ~15s crash-recovery shards to the server for the duration of the recording. */
-    private startSegmentFlushing;
-    /** Stops the periodic crash-recovery shard flush. */
-    private stopSegmentFlushing;
+    /**
+     * Builds the transport for shard uploads and terminal requests. The default posts to MJAPI's REST
+     * recording routes, derived from the session's GraphQL provider configuration, with credentials
+     * read per request so a refreshed token is used. Returns null — shards then wait in the local
+     * store — when the provider has no URL (a test double, a provider that is not GraphQL, or one not
+     * configured yet). Override to supply another transport.
+     */
+    protected createRecordingTransport(): IRecordingTransport | null;
+    /**
+     * Builds the durable local shard store. The default is IndexedDB where the host has it and a no-op
+     * store elsewhere (Node, some React Native runtimes). Called once per runtime. Override to supply
+     * another store.
+     */
+    protected createRecordingShardStore(): IRecordingShardStore;
+    /** The provider's signed-in user, or null (no provider yet, or an anonymous page). */
+    private signedInUserID;
+    /** The runtime's shard store, created on first use. */
+    private ensureShardStore;
+    /**
+     * Re-uploads shards an earlier, interrupted call left in the local store (crash, closed tab, dead
+     * network), each under its OWN session id and index, oldest first, at most
+     * {@link MAX_DRAINED_SHARDS_PER_LOAD} per runtime. A shard is deleted only on the server's ack.
+     *
+     * Runs once per runtime instance, re-armed whenever a recording ends (which may leave shards behind
+     * for the next session start on the same page). When there is no transport yet (no provider configuration, e.g.
+     * before login) it returns 0 WITHOUT marking itself done, so a later call — session start — drains
+     * instead of the shards being skipped for this page. Concurrent calls share one run. Never rejects.
+     *
+     * @returns the number of shards the server acknowledged in this call.
+     */
+    DrainPendingRecordingShards(): Promise<number>;
+    /** Makes the next {@link DrainPendingRecordingShards} call run again, even one already in flight. */
+    private rearmPendingShardDrain;
+    /**
+     * The body of {@link DrainPendingRecordingShards}, up to {@link maxDrainRunsPerCall} runs. It runs
+     * again after a re-arm while a run is in flight (a recovery after an outage gave up on more shards),
+     * because the running pass listed the store before those shards were there; and after a run deleted
+     * refused shards, because those filled the page that the shards behind them now get.
+     */
+    private drainPendingShards;
+    /** One drain pass over the signed-in user's stored shards (see {@link DrainStoredRecordingShardsOnce}). */
+    private drainStoredShardsOnce;
+    /** Builds this recording's shard pipeline and starts the 5 s flush. */
+    private startShardFlushing;
+    /**
+     * Uploads succeed again after failing: re-sends, from the local store, the shards the queue gave up
+     * on during the outage. The queue's attempts run out after about 10 s of a dead network (or an
+     * expired token), and without this those shards would wait for a later page load — which a widget
+     * guest never makes — leaving a permanent gap. Runs in the background, outside any page-lifecycle
+     * handler, so the IndexedDB read is allowed. Never rejects.
+     */
+    private recoverStoredShardsAfterOutage;
+    /** Stops the periodic shard flush. */
+    private stopShardFlushing;
     /**
      * Starts telling the server this session is still in use (#3533).
      *
@@ -802,51 +1316,285 @@ 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.
+     * One 5 s tick: cuts the packets encoded since the last tick into shards, stores each one, then
+     * uploads them. Best-effort — never disturbs the call and never rejects. Overlapping ticks are
+     * safe: `Append` and `SealTail` are synchronous, so indexes are assigned in order, and the queue
+     * bounds how many flushes upload at once. A failed shard is retained by the queue and resent under
+     * its own index on later ticks (#5197), and stays in the store until acknowledged.
+     *
+     * Every tick seals whatever it took, even under a full window (the window's 250-packet and byte caps
+     * still split a larger batch). Capture starts slightly after this timer, so a tick almost never
+     * holds exactly 250 packets; sealing only full windows would leave nearly 5 s of encoded audio in
+     * memory at every moment, unstored and unsent, which a killed tab loses.
+     */
+    private flushRecordingShards;
+    /** Writes shards to the local store, in order, before their upload starts. Never rejects. */
+    private storeShards;
+    /** Removes an acknowledged shard from the local store. Never rejects. */
+    private deleteStoredShard;
+    /**
+     * Tells the server, right now, how much of the recording exists — for a host's `pagehide` and
+     * `visibilitychange → hidden` handlers, where the page may be gone a moment later. Synchronous:
+     * it seals the pending partial shard and fires the `keepalive` terminal with it, then re-sends
+     * with `keepalive` whatever the server has not acknowledged yet (see
+     * {@link dispatchRecordingTerminal}), and returns without waiting. Never stops the recorder: after
+     * a `hidden` the call may well continue, and later audio simply starts the next shard index (the
+     * tail is sealed, so no index is ever re-sent with different bytes). Also works while End is still
+     * stopping the recorder, which is exactly when a host that does not await End navigates away.
+     * No-op when nothing is recording, there is no session id or no transport, or nothing was
+     * captured. Never throws.
+     *
+     * Deliberately opens NO IndexedDB transaction inside the handler: a `pagehide` handler gets a few
+     * milliseconds, and a store write started there could not complete during unload anyway. The
+     * shards it sealed are written to the store from a `setTimeout(0)` task after the handler returns:
+     * on a page that is merely hidden (the call goes on) that keeps the durable copy until the server
+     * acknowledges it; on a page that is unloading the task just never runs.
+     */
+    SendRecordingTerminal(options?: RecordingTerminalOptions): void;
+    /**
+     * Fires the terminal request, then re-sends with `keepalive` every shard the server has not
+     * acknowledged, then stores the shards sealed for this terminal. Shared by End and the page-lifecycle
+     * handlers. Everything that needs the network is dispatched synchronously, before any storage work,
+     * because the page may close at any moment from here on: an ordinary `fetch` is aborted on unload,
+     * and a `keepalive` one is not.
+     *
+     * - The terminal goes first so it always gets the keepalive budget. The server waits for the shards
+     *   the terminal says exist, and assembles as soon as the last missing one arrives.
+     * - The re-sent shards are the queue's unacknowledged ones (on the wire, waiting in a batch, or
+     *   retained after a failure) plus `sealedNow`, oldest first, within
+     *   {@link recordingKeepaliveBudgetBytes} together with the tail. A `sealedNow` shard that does not
+     *   fit, or whose keepalive upload fails, goes through the ordinary queue instead (it may still
+     *   land if the page stays). The queue keeps its own shards either way; a duplicate is acked as one.
+     * - `sealedNow` and the tail are stored after the dispatch, from a `setTimeout(0)` task when called
+     *   from a page-lifecycle handler (`deferStore`). A shard's stored copy is deleted on its ack, after
+     *   the store write, so a fast ack can never leave an orphan row.
+     *
+     * Resolves true when the terminal was acknowledged. Never rejects.
+     */
+    private dispatchRecordingTerminal;
+    /** Counts `bytes` against the page's keepalive budget until `request` settles. */
+    private trackKeepalive;
+    /**
+     * The `keepalive` re-send part of {@link dispatchRecordingTerminal}, budgeted against everything this
+     * page still has in flight (the terminal just sent included). A shard whose `keepalive` copy is already
+     * on the wire is not sent again. Never throws.
+     */
+    private resendUnacknowledgedWithKeepalive;
+    /**
+     * Stores shards from a `setTimeout(0)` task rather than now — the path for shards sealed inside a
+     * page-lifecycle handler, which must not open an IndexedDB transaction itself. Resolves once they
+     * are stored (never, if the page unloads first). Never rejects.
+     */
+    private storeShardsLater;
+    /**
+     * Sends the terminal request for a pipeline whose tail is already sealed. Resolves true on a server
+     * ack and logs the outcome with the session id. Never rejects.
+     */
+    private sendRecordingTerminal;
+    /**
+     * Ends the recording at teardown and STARTS its terminal request: stops the recorder (flushing the
+     * encoder), cuts the remaining packets into shards with the tail trimmed to the recorder's captured
+     * sample count, and dispatches the `keepalive` terminal plus `keepalive` re-sends of everything not
+     * yet acknowledged, before storing anything ({@link dispatchRecordingTerminal}). Teardown awaits the
+     * returned terminal only after `CloseAgentSession` ({@link awaitRecordingTerminal}), so the small,
+     * critical close never waits behind the recording (#5195).
+     *
+     * The recorder and pipeline stay visible to {@link SendRecordingTerminal} until the recorder has
+     * stopped: a `pagehide` in that window (a host that navigates away without awaiting End) still
+     * sends what was captured, and End then continues at the next index.
+     *
+     * Returns null when nothing was recording or nothing was captured (no terminal is sent then).
+     * Best-effort: never throws, never blocks teardown on the network.
+     */
+    private finishRecording;
+    /**
+     * Stops the recorder, bounded by {@link RECORDER_STOP_TIMEOUT_MS}. Resolves the captured sample
+     * count, or null when the recorder threw or did not finish in time (logged) — the caller then ends
+     * the recording at the packets already encoded. Never rejects.
+     */
+    private stopRecorder;
+    /**
+     * Waits for the terminal {@link finishRecording} started, bounded by
+     * {@link RECORDING_TERMINAL_ACK_TIMEOUT_MS}, logs the outcome, then closes the recording's queue
+     * (anything it had not delivered stays in the local store for the next-load drain). Never throws.
+     */
+    private awaitRecordingTerminal;
+    /** 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).
      */
-    private flushRecordingSegment;
+    GetChannelExposure(channelName: string): RealtimeChannelExposure | null;
     /**
-     * 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.
+     * 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`.
      */
-    private stopAndUploadRecording;
+    SetFocusedChannel(channelKey: string | null): void;
+    /** Stops following the arbiter and clears {@link VideoSources$}. Safe to call when nothing is watched. */
+    private unwatchVideoSources;
+    private stopWatchingVideoSources;
     /**
-     * Runs the `UploadRealtimeRecording` mutation; failures are logged, never thrown. 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.
+     * 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.
      */
-    private uploadRecording;
+    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 loadActiveChannels;
+    private prepareChannelScope;
     /**
-     * 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.
+     * 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 prepareChannels;
+    /**
+     * 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 +1602,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 +1725,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 +1758,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 +1774,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 +1792,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
@@ -994,18 +1822,28 @@ export declare class RealtimeSessionRuntime {
      * - NORMAL turns only — NARRATION interims are ephemeral and never persisted, so they must not
      *   claim the next real turn's start slot.
      *
-     * Works for any role whose driver surfaces interim deltas (all drivers for the assistant; the
-     * relevant case here — the post-tool-gap assistant answer — and user-interim drivers like
-     * Gemini/AssemblyAI). For final-only user turns (OpenAI/xAI/ElevenLabs) no interim arrives, so
-     * {@link relayTranscript} falls back to the seeded/prior start — the gap case that drifts is the
-     * assistant answer, which always has interims.
+     * Stamped on a turn's first interim transcript (all drivers for the assistant — the post-tool-gap
+     * assistant answer — and user-interim drivers like Gemini/AssemblyAI). Final-only user turns
+     * (OpenAI-protocol drivers) take their start from {@link markUserSpeechStart}'s own slot
+     * instead; one with no speech-start signal either (ElevenLabs) relays `null` as-is.
      */
     private markTurnAudioStart;
+    /**
+     * Stamps {@link userSpeechStartMs} when the client signals that the user began to speak. Keeps
+     * the FIRST onset since the last final user transcript: the VAD fires again after a
+     * mid-sentence pause, and that second onset is not where the utterance began. An onset that an
+     * assistant turn which began after it has since superseded ({@link userSpeechStartSuperseded}) is
+     * replaced instead.
+     */
+    private markUserSpeechStart;
+    /** Ends the held user onset: a final user transcript (empty or not) closed the utterance it began. */
+    private releaseUserSpeechStart;
     /**
      * The current per-turn offset in ms — the RECORDER's clock when one runs (an offset into a
      * seekable file), else the SESSION clock (#3832: orderable and displayable, not seekable),
      * else `null` before any call is live. One function so the two stamp sites cannot disagree
-     * about which clock a session is on.
+     * about which clock a session is on. Always whole milliseconds: the offsets travel as GraphQL
+     * `Int`, which refuses a fraction, and a 48 kHz sample clock rarely lands on a whole millisecond.
      */
     private nowTurnOffsetMs;
     /**
@@ -1014,7 +1852,12 @@ export declare class RealtimeSessionRuntime {
      * client's caption window).
      */
     private replaceLastCaption;
-    /** Finalizes the user turn: push a caption + relay the final transcript. */
+    /**
+     * Finalizes the user turn: push a caption + relay the final transcript.
+     *
+     * @param source `'typed'` for a {@link SendText} turn: it has no speech onset, so it neither takes
+     *   nor clears the held one (a spoken transcript may still be pending for it).
+     */
     private onUserTranscript;
     /**
      * Routes a provider tool call: names matching a registered client-tool prefix execute
@@ -1040,6 +1883,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 +1924,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;
@@ -1095,20 +1951,27 @@ export declare class RealtimeSessionRuntime {
      * Relays a final transcript turn to MJ via `RelayRealtimeTranscript`.
      *
      * When the session is being recorded, per-turn timing rides along: `utteranceEndMs` is the
-     * recording-relative offset at finalization, and `utteranceStartMs` is the offset captured by
-     * {@link markTurnAudioStart} when THIS turn's audio actually began (its first interim) — NOT
-     * inherited from the previous turn's end. That distinction is the timing fix: when a tool-call
-     * / silence gap sits between turns, the post-gap turn's audio starts much later, so inheriting
-     * the prior turn's end stamped the cue ~gap-length too early. Both are omitted (left `null`)
-     * when the session isn't being recorded.
+     * recording-relative offset at finalization, and `utteranceStartMs` is where THIS turn's audio
+     * actually began — NOT inherited from the previous turn's end. For a user turn whose onset the
+     * client signalled, that is {@link userSpeechStartMs}; otherwise it is the offset captured by
+     * {@link markTurnAudioStart} on the turn's first interim. That distinction is the timing fix:
+     * when a tool-call / silence gap sits between turns, the post-gap turn's audio starts much
+     * later, so inheriting the prior turn's end stamped the cue ~gap-length too early. Both are
+     * omitted (left `null`) when the session isn't being recorded. `utteranceStartMs` is also
+     * `null` when no start was measured for this turn; it is never replaced with a placeholder 0.
      *
      * A correction (`replacesPrevious`) doesn't open a new turn, so it carries no start and doesn't
      * reset the per-turn start guard. After a normal finalization the guard is cleared so the NEXT
-     * turn re-stamps its start from where ITS audio begins.
+     * turn re-stamps its start from where ITS audio begins — except for a user turn that used its
+     * own speech-start slot, which leaves the shared slot alone (it may hold the in-flight
+     * assistant turn's start). Every final user transcript, corrections included, clears the
+     * speech-start slot.
      *
      * @param replacesPrevious CORRECTION semantics: the server updates the session's most
      *   recent persisted turn of this role IN PLACE instead of appending (e.g. ElevenLabs'
      *   post-barge-in `agent_response_correction`).
+     * @param source `'typed'` for a user turn sent with {@link SendText}: it does not read or clear
+     *   {@link userSpeechStartMs}, which belongs to the user's speech.
      */
     private relayTranscript;
     /**
@@ -1121,9 +1984,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 +2096,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). */