@memberjunction/realtime-runtime 0.0.0 → 6.2.0-edge.0

package/dist/session/RealtimeSessionRuntime.js

@@ -0,0 +1,2585 @@
+import { BehaviorSubject, Subject } from 'rxjs';
+import { Metadata } from '@memberjunction/core';
+import { UserInfoEngine } from '@memberjunction/core-entities';
+import { AIEngineBase } from '@memberjunction/ai-engine-base';
+import { MJGlobal } from '@memberjunction/global';
+import { DEFAULT_REALTIME_AUDIO_TRACKS } from '@memberjunction/ai';
+import { BaseRealtimeClient, LoadAssemblyAIRealtimeClient, LoadElevenLabsRealtimeClient, LoadGeminiRealtimeClient, LoadHuggingFaceRealtimeClient, LoadOpenAIRealtimeClient, LoadxAIRealtimeClient } from '@memberjunction/ai-realtime-client';
+import { BuildNarrationInstructions } from '../narration/narration-template.js';
+import { ParseDelegationResultJson, FormatToolName } from './delegation-result-parser.js';
+import { BaseRealtimeChannelClient } from '../channels/base-realtime-channel-client.js';
+/**
+ * `MJ: User Settings` key for the per-user "record this voice call" consent toggle. Stored as
+ * the literal string `'true'`/`'false'` (read with `=== 'true'`), cross-device via
+ * {@link UserInfoEngine}. The pre-call picker writes it; the session service reads it as the
+ * default when the caller doesn't pass an explicit consent value.
+ */
+export const REALTIME_RECORDING_CONSENT_KEY = 'mj.realtimeVoice.recordingConsent.v1';
+// Tree-shaking prevention: the OpenAI client is resolved dynamically through the
+// ClassFactory (by the server-reported Provider key), so this static call is what keeps
+// its @RegisterClass side effect from being eliminated by the bundler.
+// NOTE: the interactive-channel plugins (resolved dynamically from the `MJ: AI Agent
+// Channels` registry by ClientPluginClass key) get the same treatment, but their Load
+// calls live in `conversations.module.ts` — plugins carry Angular surface COMPONENTS,
+// and this service stays component-free (it must stay importable in plain-node tests).
+LoadOpenAIRealtimeClient();
+LoadGeminiRealtimeClient();
+LoadElevenLabsRealtimeClient();
+LoadAssemblyAIRealtimeClient();
+LoadxAIRealtimeClient();
+LoadHuggingFaceRealtimeClient();
+/**
+ * Converts a {@link RealtimeTrackDescriptor} to its JSON form for the session-config bag.
+ *
+ * Every field's VALUE is already JSON-safe; the interface simply is not assignable to `JSONValue`
+ * because it declares no index signature and `UsageBasis` is `readonly`. Written out field by field
+ * rather than asserted, so adding a descriptor field is a compile error here instead of a field that
+ * silently stops reaching the driver.
+ */
+function trackDescriptorToJSON(track) {
+    const json = { Modality: track.Modality, Direction: track.Direction };
+    if (track.Encoding !== undefined) {
+        json['Encoding'] = track.Encoding;
+    }
+    if (track.Rate !== undefined) {
+        json['Rate'] = track.Rate;
+    }
+    if (track.UsageBasis !== undefined) {
+        json['UsageBasis'] = [...track.UsageBasis];
+    }
+    if (track.RequiresConsent !== undefined) {
+        json['RequiresConsent'] = track.RequiresConsent;
+    }
+    return json;
+}
+/**
+ * Reads the `Direction:Modality` dedupe key off an already-JSON track entry, or `null` when the
+ * entry is not a track-shaped object. Used for tracks the mint supplied, which arrive as raw JSON.
+ */
+function trackKeyFromJSON(raw) {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+        return null;
+    }
+    const direction = raw['Direction'];
+    const modality = raw['Modality'];
+    if (typeof direction !== 'string' || typeof modality !== 'string') {
+        return null;
+    }
+    return `${direction}:${modality}`;
+}
+/**
+ * Drives a **client-direct** real-time voice session: the browser mints an ephemeral
+ * token from the MJ server, then connects DIRECTLY to the realtime provider. Audio
+ * frames never transit the MJ server (low latency); only tool calls and final
+ * transcripts are relayed back to MJ over GraphQL.
+ *
+ * This service is PROVIDER-AGNOSTIC policy/orchestration. All provider wire concerns
+ * (transport, event translation, the response state machine, narration-kind tagging,
+ * playback tracking) live in a {@link BaseRealtimeClient} driver resolved through the
+ * MJ ClassFactory by the server-reported `Provider` key (e.g. `'openai'` →
+ * `OpenAIRealtimeClient`). Future providers (Gemini Live, …) snap in by registering a
+ * new driver — this service does not change.
+ *
+ * The Realtime Co-Agent (server-side) fronts the conversation's current agent — the server
+ * bakes the companion instructions + tool set into `SessionConfigJson`, which the client
+ * driver applies verbatim.
+ *
+ * Lifecycle: {@link StartRealtimeSession} → live duplex → {@link EndRealtimeSession}. A start is
+ * two halves — MINT (the `StartRealtimeClientSession` mutation) and RUN (everything above) — and a
+ * host that must mint through its own server surface enters at the second half via
+ * {@link StartRealtimeSessionFromResult}; there is one implementation of the run half either way.
+ */
+export class RealtimeSessionRuntime {
+    /**
+     * @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).
+     */
+    constructor(mediaHost) {
+        this.mediaHost = mediaHost;
+        // ── Reactive UI state ──────────────────────────────────────────────────────
+        this._connectionState$ = new BehaviorSubject('closed');
+        this._captions$ = new BehaviorSubject([]);
+        this._active$ = new BehaviorSubject(false);
+        this._delegationProgress$ = new Subject();
+        this._delegationResult$ = new Subject();
+        this._delegationNarration$ = new Subject();
+        this._thoughtNarration$ = new Subject();
+        this._agentName$ = new BehaviorSubject('Sage');
+        this._modelName$ = new BehaviorSubject(null);
+        this._minimized$ = new BehaviorSubject(false);
+        this._activeChannels$ = new BehaviorSubject([]);
+        this._channelFocus$ = new Subject();
+        // ─── Generic session-lifecycle events (consumed by RealtimeSessionsAdapter to
+        // bridge into @memberjunction/conversations-runtime's framework-agnostic
+        // SessionsObserver). Why not derive from Active$ + agentSessionId? Because
+        // Active$ flips true before mintSession resolves and sets agentSessionId —
+        // a naive Active$ subscription would emit session-started with sessionId === null.
+        // Emitting explicitly avoids the race entirely. ───
+        this._sessionStarted$ = new Subject();
+        this._sessionEnded$ = new Subject();
+        this._channelActivity$ = new Subject();
+        /** Current connection / turn state. */
+        this.ConnectionState$ = this._connectionState$.asObservable();
+        /** Live captions for both sides of the conversation. */
+        this.Captions$ = this._captions$.asObservable();
+        /** True while a session is open (mic button active, overlay shown). */
+        this.Active$ = this._active$.asObservable();
+        /**
+         * Progress updates from a delegated agent run (e.g. Sage) while the realtime model waits on it.
+         * The future overlay subscribes to render a "working" card; the model also narrates these aloud.
+         */
+        this.DelegationProgress$ = this._delegationProgress$.asObservable();
+        /** Terminal result of a delegation, so the overlay can complete the working card with real content. */
+        this.DelegationResult$ = this._delegationResult$.asObservable();
+        /**
+         * EPHEMERAL spoken progress narrations (see {@link RealtimeDelegationNarration}). These are
+         * deliberately kept OUT of {@link Captions$} and never relayed/persisted — the overlay
+         * renders them as a transient "live note" near the active working card.
+         */
+        this.DelegationNarration$ = this._delegationNarration$.asObservable();
+        /**
+         * Model-authored thought / reasoning narrations (see {@link RealtimeThoughtNarration}). These are
+         * reasoning summaries author-emitted during extended thinking, separate from spoken progress updates.
+         */
+        this.ThoughtNarration$ = this._thoughtNarration$.asObservable();
+        /** Display name of the agent the active session fronts (set at session start). */
+        this.AgentName$ = this._agentName$.asObservable();
+        /**
+         * Display name of the realtime MODEL the active session runs on (server-reported at session
+         * start, e.g. "GPT Realtime 2"). `null` before a session starts / when the server didn't report
+         * one. The overlay banner shows it subtly next to the agent identity.
+         */
+        this.ModelName$ = this._modelName$.asObservable();
+        /**
+         * True while the active call overlay is MINIMIZED to the host's floating "on call" pill
+         * (e.g. after a dev link navigated away). The mic and session stay fully live — this is
+         * pure presentation state, reset to `false` at session start and teardown.
+         */
+        this.Minimized$ = this._minimized$.asObservable();
+        /**
+         * The session's ACTIVE interactive-channel plugins, resolved from the `MJ: AI Agent
+         * Channels` registry at session start (one instance per session, per channel). Emits
+         * `[]` before a session starts and after teardown. The overlay subscribes to register
+         * one surface tab per plugin — it never knows any concrete channel type.
+         */
+        this.ActiveChannels$ = this._activeChannels$.asObservable();
+        /**
+         * Channel requests to enter / leave the FOCUS layout (see
+         * {@link RealtimeChannelFocusEvent}). Fired when a plugin calls its host context's
+         * `SetFocusMode` — e.g. the whiteboard's "Focus board" toggle.
+         */
+        this.ChannelFocus$ = this._channelFocus$.asObservable();
+        /**
+         * Fired EXACTLY ONCE per session after both `agentSessionId` is set AND the
+         * realtime client is connected. Carries the server-issued `sessionId` and the
+         * `ChannelName` of each plugin resolved at session mint. Consumed by
+         * `RealtimeSessionsAdapter` (in this package) to feed
+         * `@memberjunction/conversations-runtime`'s `SessionsObserver`.
+         *
+         * **Why this exists separately from `Active$`:** `Active$` flips `true` BEFORE
+         * `mintSession` resolves, so `agentSessionId` is still `null` at that moment.
+         * Subscribers correlating `(Active$, agentSessionId)` would race; this event
+         * removes the race.
+         */
+        this.SessionStarted$ = this._sessionStarted$.asObservable();
+        /**
+         * Fired EXACTLY ONCE per session as teardown begins, with the prior
+         * `agentSessionId` (so subscribers can correlate against `SessionStarted$`'s
+         * sessionId) and the client-distinguishable reason — `'explicit'` when the
+         * user called `EndRealtimeSession`, `'error'` when teardown ran from a catch
+         * block. Server-side close paths (janitor, shutdown) do NOT propagate here —
+         * they happen out-of-process and have no client push channel today.
+         */
+        this.SessionEnded$ = this._sessionEnded$.asObservable();
+        /**
+         * Fires with the channel PLUGIN every time the agent ACTS on that channel (a tool call
+         * was routed to its local executor — e.g. the agent drew on the whiteboard). The overlay
+         * uses the FIRST emission per channel to auto-reveal + focus the channel's surface tab,
+         * so the user discovers the surface the moment the agent starts using it. Finer-grained
+         * than {@link SessionStarted$}/{@link SessionEnded$} (per tool call, not per session).
+         */
+        this.ChannelActivity$ = this._channelActivity$.asObservable();
+        /**
+         * ID of the active server-side agent session (`MJ: AI Agent Sessions`), or `null` when no
+         * session is open / the session hasn't been minted yet. Powers the overlay's gear-gated
+         * "Open session" dev link.
+         */
+        /** Conversation id the SERVER created for this session (null when the host supplied one). */
+        this.createdConversationId = null;
+        /** The session's conversation id (supplied or server-created). */
+        this.sessionConversationId = null;
+        /** First final user utterance of the live session (the naming seed). */
+        this.firstUserTranscript = null;
+        /** Buffer accumulating streaming user interim deltas into a single in-progress bubble. */
+        this.pendingUserCaption = '';
+        /** Whether an in-place interim user caption is currently placed in `_captions$`. */
+        this.hasActiveInterimUserCaption = false;
+        // ── Session internals ──────────────────────────────────────────────────────
+        /** The provider-direct realtime client driving the live session (ClassFactory-resolved). */
+        this.client = null;
+        /** The mic capture stream — acquired here (permission UX) and handed to the client. */
+        this.localStream = null;
+        this.agentSessionId = null;
+        /**
+         * The application the active session runs in (sources the server-side app config cascade +
+         * RelevantAgents → allowed-agent union, and the default-agent chain). `null` when no app context
+         * was supplied. Set at {@link StartRealtimeSession}; sent to the mint mutation.
+         */
+        this.applicationId = null;
+        /**
+         * The live app-context snapshot (where the user is, what they see, the capability manifest),
+         * pushed by the host (Explorer) at session start and on subsequent changes via
+         * {@link UpdateAppContext}. The headless {@link import('../components/realtime/channels/client-context-channel').ClientContextChannel}
+         * subscribes to {@link AppContext$} and streams deltas to the model via `SendContextNote`.
+         */
+        this._appContext$ = new BehaviorSubject(null);
+        /** Observable of the live app-context snapshot (see {@link _appContext$}). */
+        this.AppContext$ = this._appContext$.asObservable();
+        /**
+         * The DB-driven narration instruction template (server-resolved at session start, containing a
+         * `{{ progressMessage }}` placeholder). `null` when the deployment hasn't synced the narration
+         * prompt — {@link buildNarrationInstructions} then falls back to the built-in wording.
+         */
+        this.narrationTemplate = null;
+        // ── Browser-side call recording ────────────────────────────────────────────
+        /**
+         * 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.
+         */
+        this.recorder = null;
+        /** ISO timestamp of when recording started — sent to the server on session start. */
+        this.recordingStartedAtIso = null;
+        /** Interval that flushes ~15s crash-recovery shards to the server during a recording. */
+        this.segmentTimer = null;
+        /** 0-based index of the next recording shard to upload. */
+        this.segmentIndex = 0;
+        // ── Server-side liveness ───────────────────────────────────────────────────
+        /**
+         * 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.
+         */
+        this.livenessTimer = null;
+        /**
+         * 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}.
+         */
+        this.currentTurnStartMs = null;
+        /**
+         * 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}.
+         */
+        this.sessionClockStartMs = null;
+        /**
+         * Per-turn guard for {@link markTurnAudioStart}: `true` once the in-flight turn's audio-start
+         * offset has been captured, so mid-turn interim deltas don't overwrite it. Reset to `false`
+         * at each finalization so the NEXT turn re-stamps from where ITS audio begins.
+         */
+        this.turnAudioStartCaptured = false;
+        /**
+         * Aggregation buffer: distinct progress messages since the last spoken update (oldest
+         * first, capped at {@link RealtimeSessionRuntime.MaxDigestMessages}). A flood of small
+         * updates becomes ONE digest; the buffer is discarded when the result lands first.
+         */
+        this.pendingNarrationMessages = [];
+        /**
+         * Tool calls currently executing on the server. Progress events ride PubSub and can
+         * lag the (fast) mutation result — any progress for a call NOT in this set is stale
+         * (already completed) and is dropped, so we never narrate "starting up" after the
+         * answer was already spoken.
+         */
+        this.inFlightCallIds = new Set();
+        /** Timer for the deferred narration; cancelled when the delegation result lands first. */
+        this.narrationTimer = null;
+        /**
+         * Call ids the USER explicitly cancelled via {@link CancelDelegation} /
+         * {@link CancelInFlightDelegations}. Their cards were already flipped to the
+         * "Cancelled by user" failed result, so when the original tool mutation later resolves
+         * with the aborted run's outcome, {@link emitDelegationResult} skips the duplicate card
+         * emission (the model still receives the tool result). Cleared at teardown.
+         */
+        this.cancelledCallIds = new Set();
+        /** Accumulated input-token delta since the last flush. */
+        this.pendingUsageInput = 0;
+        /** Accumulated output-token delta since the last flush. */
+        this.pendingUsageOutput = 0;
+        /** Pending debounced usage flush; also force-flushed at teardown. */
+        this.usageFlushTimer = null;
+        /** Active push-status subscription that feeds delegation progress; cleared on teardown. */
+        this.delegationProgressSub = null;
+        /** Timestamp (ms) of the last narration we triggered; 0 = never. */
+        this.lastDelegationNarrationAt = 0;
+        /** When the current delegation burst began (first in-flight call); anchors the 5s first update. */
+        this.delegationBurstStartedAt = 0;
+        /** Spoken updates so far in this burst (1-based numbering for the instructions). */
+        this.narrationCount = 0;
+        /** What the model actually SAID for prior updates this burst — chained in so it never repeats itself. */
+        this.spokenNarrations = [];
+        /** Tail message of the last digest, so an identical trailing progress event isn't re-buffered. */
+        this.lastNarratedTail = '';
+        /**
+         * Registry of CLIENT-EXECUTED UI tool handlers, keyed by tool-name prefix (e.g.
+         * `'Whiteboard_'`). Tool calls whose name matches a registered prefix run LOCALLY through the
+         * handler (never relayed to the server); everything else takes the standard server-relay path.
+         * Cleared at teardown.
+         */
+        this.clientToolHandlers = new Map();
+        /**
+         * Monotonic id for the current start attempt, bumped by every {@link teardown}.
+         *
+         * A session start is a multi-await sequence — mint, acquire the microphone, connect — and a host
+         * can end the session part-way through it (the user taps back while the mint is still in flight).
+         * Teardown at that moment has nothing to tear down: the stream and the client do not exist yet.
+         * Without this, the in-flight start then proceeds to open a microphone and a provider connection
+         * nobody is watching. Each start captures the generation it began under and abandons itself the
+         * moment it no longer matches.
+         */
+        this.startGeneration = 0;
+        /**
+         * The teardown currently running, so a second call awaits it rather than racing it.
+         *
+         * Ending a session commonly fires twice — an explicit stop followed by the host unmounting — and
+         * `teardown` flips `_active$` only at the end, so the second call passes the `IsActive` guard and
+         * runs concurrently with the first: two `Disconnect()` calls, two `CloseAgentSession` mutations,
+         * two `SessionEnded$` emissions for one session.
+         */
+        this.teardownInFlight = null;
+        /**
+         * Why the last session start failed, or `null` when none has.
+         *
+         * 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:
+         * microphone permission. A host that cannot tell "you denied the mic" from "the provider is
+         * down" has to show the same unhelpful copy for both. `AcquireMicrophone` rejects inside the
+         * runtime's own try/catch, so the host never sees that rejection itself.
+         */
+        this.lastStartError = null;
+        /**
+         * Pending DEBOUNCED channel-state saves, keyed by channel name. Each entry keeps the
+         * LATEST serialized state plus the session id captured while the session was live —
+         * the teardown flush runs as the live id is being torn down, so the capture guarantees
+         * the final save still lands on the just-closed session.
+         */
+        this.pendingChannelSaves = new Map();
+        /**
+         * `ChannelName`s the agent has ACTED ON at least once this session (the channel's first
+         * tool call routed to its local executor). The overlay reads this to decide which channel
+         * surface tabs to register: a channel earns its tab only once it's been used (the
+         * whiteboard is the sole exception — it tabs immediately, since a user may draw first).
+         * Reset at session start via {@link resetState}.
+         */
+        this.usedChannelNames = new Set();
+        this._provider = null;
+        /**
+         * Host registry of surface CLIENT TOOLS (Name → handler), fed by the host (Explorer) from the
+         * active surface's `SetAgentClientTools`. The headless ClientContextChannel's `ContextTool` proxy
+         * executes against this via {@link executeAppClientTool}. Keys are lower-cased for case-insensitive
+         * model-supplied action names.
+         */
+        this.appClientToolHandlers = new Map();
+    }
+    /** Synchronous access to the session's active interactive-channel plugins. */
+    get ActiveChannels() {
+        return this._activeChannels$.value;
+    }
+    /**
+     * The `ChannelName`s the agent has used (acted on) at least once this session. The overlay
+     * uses this to register a channel's surface tab only after it has come into play. A fresh
+     * Set snapshot so callers can't mutate the service's tracking.
+     */
+    get UsedChannelNames() {
+        return new Set(this.usedChannelNames);
+    }
+    /** Whether the agent has used (acted on) the named channel at least once this session. */
+    HasChannelBeenUsed(channelName) {
+        return this.usedChannelNames.has(channelName);
+    }
+    /** Synchronous access to the display name of the agent the active session fronts. */
+    get CurrentAgentName() {
+        return this._agentName$.value;
+    }
+    /**
+     * When the active/last session CREATED its conversation (started without one), the new
+     * conversation's id — the host uses it to refresh the cached list, conditionally select
+     * it on close, and auto-name it. Null when the session joined an existing conversation.
+     */
+    get SessionCreatedConversationId() {
+        return this.createdConversationId;
+    }
+    /** The first final user utterance of the session (naming seed); null before the user speaks. */
+    get FirstUserTranscript() {
+        return this.firstUserTranscript;
+    }
+    get CurrentAgentSessionId() {
+        return this.agentSessionId;
+    }
+    /** Synchronous access to the minimized presentation state. */
+    get IsMinimized() {
+        return this._minimized$.value;
+    }
+    /**
+     * Minimizes / restores the active call overlay (host renders the floating pill while
+     * minimized). Presentation-only — the live audio session is untouched.
+     */
+    SetMinimized(minimized) {
+        if (this._minimized$.value !== minimized) {
+            this._minimized$.next(minimized);
+        }
+    }
+    /**
+     * Push an updated app-context snapshot mid-session (the continuous-streaming half of client-context
+     * delivery). The host (Explorer) calls this when the user navigates / the active surface's state or
+     * capability manifest changes; the ClientContextChannel turns the delta into a `SendContextNote`.
+     * No-op semantics when no session is live — the channel simply re-reads on next start.
+     *
+     * @param snapshot The latest app-context snapshot (or null to clear).
+     */
+    UpdateAppContext(snapshot) {
+        this._appContext$.next(snapshot);
+    }
+    /** How often crash-recovery shards are flushed during a recording. */
+    static { this.SegmentFlushMs = 15000; }
+    /**
+     * How often the client asserts liveness. Comfortably under `SessionJanitor`'s
+     * `closeThresholdMinutes` (15 by default) so several pulses must be missed in a row before a
+     * live session is reaped, and well above `SessionManager`'s heartbeat write-coalescing window
+     * so the DB sees at most a trickle of writes per session.
+     */
+    static { this.LivenessPulseMs = 60000; }
+    // ── Delegated-run progress streaming ───────────────────────────────────────
+    /** First spoken update fires no earlier than this long after delegated work starts. */
+    static { this.FirstNarrationDelayMs = 5000; }
+    /** Minimum gap between SUBSEQUENT spoken updates (the 7–10s band; floods aggregate). */
+    static { this.NarrationIntervalMs = 8000; }
+    /** Retry delay when the fire moment finds the model busy / audio still playing. */
+    static { this.NarrationBusyRetryMs = 1500; }
+    /** Max progress messages aggregated into one spoken digest. */
+    static { this.MaxDigestMessages = 4; }
+    /** Max prior spoken narrations chained into the instructions (anti-repetition). */
+    static { this.MaxPriorNarrations = 3; }
+    // ── Usage telemetry relay (B7) ─────────────────────────────────────────────
+    /** Debounce window for relaying accumulated usage deltas to the server. */
+    static { this.UsageFlushDebounceMs = 10000; }
+    // ── Interactive channels (registry-resolved plugins) ───────────────────────
+    /** Debounce window for persisting a channel's state of record after a change burst. */
+    static { this.ChannelSaveDebounceMs = 3000; }
+    /**
+     * Metadata provider used for the GraphQL relay mutations. Falls back to the
+     * global default when unset (single-provider apps see no change).
+     */
+    get Provider() {
+        return this._provider ?? Metadata.Provider;
+    }
+    set Provider(value) {
+        this._provider = value;
+    }
+    /** True when a session is currently open. */
+    get IsActive() {
+        return this._active$.value;
+    }
+    /**
+     * Start a client-direct voice session fronting `targetAgentId`.
+     *
+     * @param targetAgentId The agent the Realtime Co-Agent voices on behalf of.
+     * @param conversationId Optional existing conversation to bind + seed context from.
+     * @param lastSessionId Optional prior session to chain to (resume / continuation).
+     * @param agentName Optional display name of the target agent — resolved by the caller
+     *   (which knows the conversation's routing context) and surfaced on {@link AgentName$}
+     *   so ANY host (composer trigger, chat-area overlay) can render it without re-resolving.
+     * @param preferredModelId Optional EXPLICIT realtime model choice (`MJ: AI Models.ID`). When
+     *   set, the server uses exactly that model and FAILS with a clear reason if it can't (no
+     *   silent fallback). Omit for the server's automatic (highest-PowerRank) selection.
+     * @param clientTools Optional EXTRA client-executed UI tool declarations to expose to the
+     *   realtime model alongside the server's stable tool set and the interactive-channel
+     *   tools (which are aggregated automatically from the registry-resolved plugins — see
+     *   {@link ActiveChannels$}). The server only DECLARES these — execution stays in the
+     *   browser via handlers registered with {@link RegisterClientToolHandler}. This is an
+     *   extension point for hosts with bespoke (non-channel) UI tools; most callers omit it.
+     * @param coAgentId Optional EXPLICIT co-agent choice (`MJ: AI Agents.ID` of an Active,
+     *   Realtime-type agent) — the highest-precedence step of the server's co-agent resolution
+     *   chain. When set, the server uses exactly that co-agent and FAILS with a clear reason if
+     *   it can't (no silent fallback). Omit to let server metadata drive the choice: the target
+     *   agent's `DefaultCoAgentID`, then the type-level `AIAgentCoAgent` default row, then the global Realtime Co-Agent.
+     * @param configOverridesJson Optional JSON payload of SESSION CONFIG overrides (e.g.
+     *   `{"realtime":{"modelPreference":"<modelId>"}}`), forwarded verbatim on the mint
+     *   mutation. The server enforces the `Realtime: Advanced Session Controls`
+     *   authorization on any overrides — hosts only populate this from authorization-gated
+     *   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
+     *   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.
+     */
+    async StartRealtimeSession(targetAgentId, conversationId, lastSessionId, agentName, preferredModelId, clientTools, coAgentId, configOverridesJson, recordingConsent, mediaCollectionId, applicationId, appContext) {
+        if (this.IsActive) {
+            return; // a session is already running — ignore duplicate starts
+        }
+        const consent = this.beginSessionStart({ agentName, recordingConsent, applicationId, appContext });
+        // Captured BEFORE startChannels so the mint carries exactly the snapshot the prologue
+        // resolved, whatever a channel plugin may push in the meantime.
+        const effectiveAppContext = this._appContext$.value;
+        let session;
+        try {
+            // Resolve + initialize the interactive-channel plugins FIRST: their client-executed
+            // tool sets must be declared to the realtime model at session mint.
+            const allClientTools = [...(clientTools ?? []), ...(await this.startChannels())];
+            session = await this.mintSession(targetAgentId, conversationId, lastSessionId, preferredModelId, allClientTools, coAgentId, configOverridesJson, consent, this.recordingStartedAtIso, mediaCollectionId, this.applicationId, effectiveAppContext);
+        }
+        catch (error) {
+            await this.failSessionStart(error);
+            return;
+        }
+        if (!this.hostCanUseProvider(session.Provider)) {
+            await this.abortUnusableSession(session);
+            return;
+        }
+        await this.runMintedSession(session, conversationId ?? null, consent);
+    }
+    /**
+     * Declares which provider keys this host can actually carry audio for.
+     *
+     * The server resolves a realtime model by rank across every configured vendor, so it can
+     * legitimately return a provider whose client driver this host cannot run. A browser can run all
+     * of them; React Native can run the WebRTC ones but not those needing a Web Audio PCM plane.
+     * Connecting anyway gets as far as constructing the driver's playback engine and then throws —
+     * a crash, where the honest answer is "this workspace's voice provider is not one this app can
+     * use".
+     *
+     * The default accepts everything, so existing hosts are unaffected. Override to narrow it.
+     *
+     * @param provider The `Provider` key the server stamped on the minted session.
+     */
+    hostCanUseProvider(_provider) {
+        return true;
+    }
+    /**
+     * Closes a session that was minted but will never be connected, and reports why.
+     *
+     * Minting creates a durable `MJ: AI Agent Sessions` row server-side, so declining to connect
+     * still has to close it — otherwise every rejected attempt leaks an `Active` session for the
+     * janitor to reconcile fifteen minutes later.
+     */
+    async abortUnusableSession(session) {
+        const reason = `[RealtimeSession] This host cannot carry provider '${session.Provider}' ` +
+            `(model '${session.ModelName ?? session.Model}'); closing the minted session without connecting.`;
+        console.error(reason);
+        this.lastStartError = new Error(reason);
+        // Adopt the session id so the shared teardown closes it — and so this path unwinds through
+        // exactly one implementation. The prologue has already initialized the channel plugins and
+        // published them on ActiveChannels$; skipping teardown would leave them undisposed, their tool
+        // handlers registered, and their subscriptions live until the next start replaced them.
+        this.agentSessionId = session.AgentSessionId ?? this.agentSessionId;
+        this._connectionState$.next('error');
+        await this.teardown(true);
+    }
+    /**
+     * Run a session the HOST has already minted itself — the second half of
+     * {@link StartRealtimeSession}, without the `StartRealtimeClientSession` mutation.
+     *
+     * For hosts that must mint through their own server surface because they attach per-session
+     * context the stock mutation cannot carry (e.g. an interview persona baked into the companion
+     * prompt). They call their own mutation, shape the reply into a
+     * {@link StartRealtimeClientSessionResult}, and hand it here: driver resolution, the ephemeral-token
+     * connect, tool/transcript relays, recording, connection state and teardown are all identical to
+     * the all-in-one path — there is exactly one implementation of the run half.
+     *
+     * NOTE: the interactive-channel plugins are NOT started on this path. Their tool sets must be
+     * declared to the model AT MINT, which happened on the host's side — so a host that wants channels
+     * 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.
+     * @param options Host-side inputs the result cannot carry; see {@link RealtimeSessionRunOptions}.
+     *   Every field defaults exactly as its {@link StartRealtimeSession} counterpart does.
+     */
+    async StartRealtimeSessionFromResult(result, options) {
+        if (this.IsActive) {
+            return; // a session is already running — ignore duplicate starts
+        }
+        const effectiveOptions = options ?? {};
+        if (!this.hostCanUseProvider(result.Provider)) {
+            await this.abortUnusableSession(result);
+            return;
+        }
+        const consent = this.beginSessionStart(effectiveOptions);
+        await this.runMintedSession(result, effectiveOptions.conversationId ?? null, consent);
+    }
+    /**
+     * 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.
+     */
+    beginSessionStart(options) {
+        // App awareness (Move 1/3/4): the application the session runs in (sources the app config
+        // cascade + RelevantAgents → allowed-agent union) and the live app-context snapshot injected
+        // into the companion prompt at mint. Stored so the ClientContextChannel can stream subsequent
+        // deltas. Absent ⇒ no app layer / no mint-time context (the pre-app behavior).
+        this.applicationId = options.applicationId ?? null;
+        // Prefer the explicit param, but fall back to the snapshot the host has ALREADY pushed via
+        // UpdateAppContext (explorer-app streams the live snapshot continuously). The overlay's
+        // [appContext] binding can still read null at the instant the mic is clicked — without this
+        // fallback, StartRealtimeSession(null) would clobber a perfectly good snapshot and mint the
+        // companion prompt with no app context (no NavigableApps / no tool schemas → the co-agent guesses
+        // parameter names and navigation fails). Never overwrite a good value with null.
+        this._appContext$.next(options.appContext ?? this._appContext$.value);
+        if (options.agentName) {
+            this._agentName$.next(options.agentName);
+        }
+        this.resetState();
+        this._active$.next(true);
+        this._connectionState$.next('connecting');
+        // Resolve recording consent for this session: explicit value wins, else the per-user
+        // persisted preference. Computed before mint so it can be reported to the server.
+        const consent = options.recordingConsent ?? this.readPersistedRecordingConsent();
+        this.recordingStartedAtIso = consent ? new Date().toISOString() : null;
+        return consent;
+    }
+    /**
+     * 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.
+     */
+    async runMintedSession(session, inputConversationId, consent) {
+        // Captured up front: every await below is a window in which the host can end the session.
+        const generation = this.startGeneration;
+        try {
+            this.agentSessionId = session.AgentSessionId;
+            // A null input conversationId means the SERVER created a fresh conversation for
+            // this session — track it so the host can fold it into the cached list, select
+            // it on close, and auto-name it (via the shared naming helper).
+            this.createdConversationId = !inputConversationId && session.ConversationId ? session.ConversationId : null;
+            this.sessionConversationId = session.ConversationId ?? inputConversationId ?? null;
+            this.firstUserTranscript = null;
+            this.narrationTemplate = session.NarrationInstructionsTemplate ?? null;
+            this._modelName$.next(session.ModelName ?? null);
+            // Resume continuity: rehydrate channel plugins from the PRIOR session's saved states
+            // (e.g. the whiteboard) BEFORE any surface binds — tolerant, never blocks the start.
+            this.applyPriorChannelStates(session.PriorChannelStatesJson);
+            const client = this.createRealtimeClient(session.Provider);
+            this.client = client;
+            this.wireClientHandlers(client);
+            // Everything past here awaits on hardware and the network, during which the host may end the
+            // session. Each await is followed by a staleness check so an abandoned start releases what it
+            // just acquired instead of leaving a live microphone and a live call behind it.
+            this.localStream = await this.mediaHost.AcquireMicrophone();
+            if (this.startGeneration !== generation) {
+                await this.unwindAbandonedStart(session, client);
+                return;
+            }
+            await client.Connect(this.buildClientConfig(session), this.localStream);
+            if (this.startGeneration !== generation) {
+                await this.unwindAbandonedStart(session, client);
+                return;
+            }
+            // Notify active channels that the session client is connected and tracks are established
+            for (const channel of this._activeChannels$.value) {
+                try {
+                    channel.OnSessionStarted?.();
+                }
+                catch (err) {
+                    console.error(`[RealtimeSession] Error in channel '${channel.ChannelName}' OnSessionStarted:`, err);
+                }
+            }
+            // Start browser-side recording (mic + agent mix) when consented. Best-effort: an
+            // unsupported browser / missing remote stream degrades gracefully (mic-only or off)
+            // and never blocks the call. The remote stream may still be null here (the WebRTC
+            // ontrack can land slightly after Connect resolves) — the recorder mixes the mic now
+            // and the agent audio rides through whenever its track is already attached.
+            // The SESSION clock (#3832): anchored the moment the call goes live, whether or not a
+            // recording exists. When the recorder runs, per-turn timings use ITS clock (offsets into a
+            // seekable file); when it does not — every unconsented and every relay-captured session,
+            // which is 100% of turns measured across two databases — this is the fallback that stops
+            // `UtteranceStartMs`/`UtteranceEndMs` being categorically null. An offset into a session
+            // with no audio is not seekable, but it is orderable and displayable ("3:42 into the
+            // interview"), and it is stamped when the SPEECH happened rather than when the relay
+            // mutation landed — which no server-side backfill can ever recover.
+            this.sessionClockStartMs = performance.now();
+            if (consent) {
+                this.startRecording(client);
+            }
+            this.subscribeDelegationProgress();
+            // State advances to 'listening' once the provider control channel opens
+            // (driven by the client's OnStateChange events).
+            // Surface a generic session-started event for the conversations runtime
+            // SessionsObserver bridge. Emitting AFTER Connect() guarantees both that
+            // agentSessionId is set (line ~468) AND the realtime client is connected,
+            // so consumers can act on it without re-checking either condition.
+            this._sessionStarted$.next({
+                sessionId: this.agentSessionId,
+                channelNames: this._activeChannels$.value.map(c => c.ChannelName),
+            });
+            // Same place, same reason: the session is connected and its id is known, which is exactly
+            // the window in which the server needs to be told it is alive.
+            this.startLivenessPulse();
+        }
+        catch (error) {
+            await this.failSessionStart(error);
+        }
+    }
+    /**
+     * 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.
+     */
+    async unwindAbandonedStart(session, client) {
+        console.warn('[RealtimeSession] Session was ended while starting — releasing the partial session.');
+        this.localStream?.getTracks().forEach(t => t.stop());
+        this.localStream = null;
+        try {
+            await client.Disconnect();
+        }
+        catch (error) {
+            console.error('[RealtimeSession] Disconnect of an abandoned start failed:', error);
+        }
+        // Only clear the shared slots when they still point at THIS attempt — a newer start may
+        // already have replaced them.
+        if (this.client === client) {
+            this.client = null;
+        }
+        // Close the server session only if teardown has NOT already done so. It nulls `agentSessionId`
+        // after closing, so a still-matching id means this attempt still owns the row; a cleared one
+        // means the teardown that invalidated this start already closed it, and closing again would
+        // send a second `CloseAgentSession` for one session.
+        if (session.AgentSessionId && this.agentSessionId === session.AgentSessionId) {
+            this.agentSessionId = null;
+            await this.closeServerSession(session.AgentSessionId);
+        }
+    }
+    /**
+     * Why the last session start failed, or `null` when the last start succeeded or none has run.
+     *
+     * 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.
+     */
+    get LastStartError() {
+        return this.lastStartError;
+    }
+    /**
+     * 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.
+     */
+    async failSessionStart(error) {
+        console.error('[RealtimeSession] Failed to start session:', error);
+        this.lastStartError = error instanceof Error ? error : new Error(String(error));
+        this._connectionState$.next('error');
+        await this.teardown(false);
+    }
+    /**
+     * End the active session: stop the mic, tear down the provider connection, and close
+     * the server-side agent session. Safe to call when no session is active.
+     */
+    async EndRealtimeSession() {
+        if (!this.IsActive && !this.agentSessionId) {
+            return;
+        }
+        await this.teardown(true);
+    }
+    /**
+     * Inject a typed message into the live session as a user turn.
+     *
+     * Decomposed into two steps, each mirroring an existing voice path so the typed
+     * turn behaves identically to a spoken one:
+     *  1. {@link BaseRealtimeClient.SendText} injects the text as user input and triggers a
+     *     reply through the SAME collision-safe path tool results use — so it queues behind
+     *     any in-flight response (progress narration / prior turn) instead of colliding.
+     *  2. Relay the turn through the same caption + transcript paths user speech uses
+     *     ({@link onUserTranscript}) so it shows in the live thread AND persists to MJ.
+     *
+     * No-op when no session is open / the control channel isn't ready, or when the text is empty.
+     */
+    SendText(text) {
+        const trimmed = text?.trim() ?? '';
+        if (trimmed.length === 0) {
+            return;
+        }
+        const client = this.client;
+        if (!client || !this.isSessionLive()) {
+            return;
+        }
+        client.SendText(trimmed);
+        // Relay as a user turn — same path spoken input uses (caption + persisted transcript).
+        void this.onUserTranscript(trimmed);
+    }
+    /** Mute / unmute the local microphone track. Returns the new muted state. */
+    ToggleMute() {
+        const tracks = this.localStream?.getAudioTracks() ?? [];
+        if (tracks.length === 0) {
+            return false;
+        }
+        const muted = tracks[0].enabled; // currently enabled → becomes muted
+        this.client?.SetMuted(muted);
+        return muted;
+    }
+    // ── Client-executed UI tools ───────────────────────────────────────────────
+    /**
+     * Registers a handler for CLIENT-EXECUTED UI tools whose names start with `toolNamePrefix`
+     * (e.g. `'Whiteboard_'` → all `Whiteboard_*` calls). Matching tool calls execute LOCALLY via
+     * the handler — they are never relayed to the server — and the handler's result JSON is sent
+     * back to the model as the `tool_response`. Re-registering the same prefix replaces the
+     * handler. The registry is cleared at session teardown.
+     */
+    RegisterClientToolHandler(toolNamePrefix, handler) {
+        this.clientToolHandlers.set(toolNamePrefix, handler);
+    }
+    /** Removes the handler registered for `toolNamePrefix` (no-op when none is registered). */
+    UnregisterClientToolHandler(toolNamePrefix) {
+        this.clientToolHandlers.delete(toolNamePrefix);
+    }
+    /**
+     * Feeds a background context note into the live model (no spoken reply is requested) — the
+     * perception channel interactive surfaces use (e.g. the whiteboard's coalesced scene deltas).
+     * No-op when no session is live.
+     */
+    SendContextNote(text) {
+        const trimmed = text?.trim() ?? '';
+        if (trimmed.length === 0 || !this.client || !this.isSessionLive()) {
+            return;
+        }
+        this.client.SendContextNote(trimmed);
+    }
+    /**
+     * Asks the live model to SPEAK FIRST — before the human has said anything.
+     *
+     * Every other path into the model's voice reacts to something: the human spoke, or a channel
+     * reported input. A host that needs the agent to open the conversation (an interviewer greeting
+     * a candidate, a guide introducing a task) had no way to ask for that, so the session connected
+     * and both sides waited for the other. The instructions are what to say, in the host's words —
+     * the model still speaks in its own voice and persona.
+     *
+     * Returns whether the request was DELIVERED, which is the one way this deliberately differs from
+     * {@link SendContextNote} beside it. A context note that is dropped costs the model a little
+     * perception; an opening line that is dropped is a session that sits in silence, and the host
+     * needs to be able to tell the two apart. `false` means no session was live (or the instructions
+     * were empty) — usually a host that asked before the connection reached a speaking state, which
+     * it can then retry.
+     */
+    RequestSpokenOpening(instructions) {
+        const trimmed = instructions?.trim() ?? '';
+        if (trimmed.length === 0 || !this.client || !this.isSessionLive()) {
+            return false;
+        }
+        this.requestChannelSpokenResponse(trimmed);
+        return true;
+    }
+    /**
+     * The active client's current audio activity (per-direction RMS levels + spectrum
+     * bins), or `null` when no session is live or the driver attached no audio meters.
+     * Sampled by the overlay's animation-frame loop to drive the audio-reactive orb/EQ —
+     * a cheap analyser read, never provider traffic.
+     */
+    GetAudioActivity() {
+        return this.client?.GetAudioActivity() ?? null;
+    }
+    /**
+     * The active {@link BaseRealtimeClient} driving the media plane, or null when not connected.
+     */
+    get Client() {
+        return this.client;
+    }
+    /**
+     * Relays a video frame to the underlying realtime client if active.
+     */
+    SendVideoFrame(base64Image, mimeType) {
+        if (!this.client || !this.isSessionLive()) {
+            return;
+        }
+        this.client.SendVideoFrame?.(base64Image, mimeType);
+    }
+    /**
+     * Checks whether a media track is established on the active realtime client.
+     */
+    IsTrackEstablished(modality, direction) {
+        return this.client?.IsTrackEstablished(modality, direction) ?? false;
+    }
+    // ── Browser-side call recording ────────────────────────────────────────────
+    /**
+     * Reads the per-user recording-consent preference from `MJ: User Settings` (via
+     * {@link UserInfoEngine}'s synchronous cache). Defensive: any failure resolves to `false`
+     * (don't record) so a settings hiccup can never opt a user into recording.
+     */
+    readPersistedRecordingConsent() {
+        try {
+            return UserInfoEngine.Instance.GetSetting(REALTIME_RECORDING_CONSENT_KEY) === 'true';
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Starts the browser-side recorder (mic + agent-audio mix). Best-effort — any failure is
+     * contained so it never disturbs the live call; an unsupported browser simply records
+     * nothing (the recorder disables itself).
+     */
+    startRecording(client) {
+        try {
+            if (!this.localStream) {
+                return;
+            }
+            const remoteStream = client.GetRemoteMediaStream?.() ?? null;
+            const recorder = this.mediaHost.CreateRecorder?.() ?? null;
+            if (!recorder) {
+                return;
+            }
+            recorder.Start(this.localStream, remoteStream);
+            this.recorder = recorder.IsRecording ? recorder : null;
+            // First turn's audio starts at ~0 (recording begins right as the call goes live). Seed it
+            // here so the very first turn has a sane start even if its first interim is missed; later
+            // turns re-stamp from where THEIR audio begins via markTurnAudioStart (handles tool gaps).
+            // Seeded even though the session clock may already have stamped a start: the clocks have
+            // different zeros, and a session-clock start carried into recorder-clock offsets would put
+            // turn one's cue wherever the clocks happen to differ.
+            this.currentTurnStartMs = recorder.IsRecording ? 0 : null;
+            this.turnAudioStartCaptured = false;
+            if (this.recorder) {
+                // The agent's WebRTC audio track usually lands AFTER Connect() resolves, so `remoteStream`
+                // above is typically null and we'd capture mic-only. Attach the agent stream whenever it
+                // arrives (fires immediately if already present) so the recording includes the agent voice.
+                client.OnRemoteMediaStream?.((stream) => this.recorder?.AttachRemoteStream(stream));
+                this.startSegmentFlushing();
+            }
+        }
+        catch (error) {
+            console.warn('[RealtimeSession] Failed to start call recording:', error);
+            this.recorder = null;
+        }
+    }
+    /** Begins flushing ~15s crash-recovery shards to the server for the duration of the recording. */
+    startSegmentFlushing() {
+        this.segmentIndex = 0;
+        this.segmentTimer = setInterval(() => { void this.flushRecordingSegment(); }, RealtimeSessionRuntime.SegmentFlushMs);
+    }
+    /** Stops the periodic crash-recovery shard flush. */
+    stopSegmentFlushing() {
+        if (this.segmentTimer) {
+            clearInterval(this.segmentTimer);
+            this.segmentTimer = null;
+        }
+    }
+    /**
+     * Starts telling the server this session is still in use (#3533).
+     *
+     * **Why the server cannot work this out on its own.** In the client-direct topology the audio
+     * goes browser → provider over WebRTC. The server sees the mint, a few channel actions in the
+     * first seconds, and then nothing at all — so `SessionManager.RecordActivity` stops being
+     * reached while the conversation is still going. `LastActiveAt` freezes ~45 seconds in, and
+     * `SessionJanitor` — which cannot distinguish an active call from an abandoned one — force-closes
+     * it at `closeThresholdMinutes`, mid-sentence, taking the user's surfaces with it. A session
+     * whose channels are all client-side (whiteboard, media) goes quiet from the server's point of
+     * view almost immediately.
+     *
+     * The browser is the only participant that knows the call is alive, so it is the one that has to
+     * say so. Raising `closeThresholdMinutes` is not the fix — it just makes the janitor slower at
+     * its real job (reaping rows orphaned by a crash) without making liveness observable.
+     *
+     * The pulse is best-effort by design: a failed beat is logged and skipped, never surfaced to the
+     * user and never allowed to end the session. Losing one beat costs nothing because the threshold
+     * is many beats wide; turning a transient network blip into a visible error would be a worse
+     * failure than the one this fixes. Write amplification is bounded on the server side too, where
+     * `SessionManager.Heartbeat` coalesces persisted writes.
+     */
+    startLivenessPulse() {
+        this.stopLivenessPulse();
+        this.livenessTimer = setInterval(() => { void this.pulseLiveness(); }, RealtimeSessionRuntime.LivenessPulseMs);
+    }
+    /** Stops the liveness pulse. Idempotent — safe on a session that never started one. */
+    stopLivenessPulse() {
+        if (this.livenessTimer) {
+            clearInterval(this.livenessTimer);
+            this.livenessTimer = null;
+        }
+    }
+    /**
+     * One liveness beat. Reads the session id at fire time rather than closing over it, so a beat
+     * that fires during teardown finds `null` and does nothing instead of resurrecting a closed row.
+     */
+    async pulseLiveness() {
+        const agentSessionId = this.agentSessionId;
+        if (!agentSessionId) {
+            return;
+        }
+        const mutation = `
+      mutation AgentSessionHeartbeat($agentSessionId: String!) {
+        AgentSessionHeartbeat(agentSessionId: $agentSessionId)
+      }
+    `;
+        try {
+            await this.gql().ExecuteGQL(mutation, { agentSessionId });
+        }
+        catch (error) {
+            // Best-effort: the next beat is 60s away and the janitor threshold is many beats wide.
+            console.warn('[RealtimeSession] Liveness pulse failed (session continues):', error);
+        }
+    }
+    /**
+     * 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.
+     */
+    async flushRecordingSegment() {
+        const recorder = this.recorder;
+        const agentSessionId = this.agentSessionId;
+        if (!recorder || !agentSessionId) {
+            return;
+        }
+        try {
+            const audioBase64 = await recorder.SnapshotNewSegmentBase64();
+            if (!audioBase64) {
+                return;
+            }
+            const index = this.segmentIndex++;
+            const mutation = `
+        mutation UploadRealtimeRecordingSegment($agentSessionId: String!, $segmentIndex: Int!, $audioBase64: String!, $mimeType: String!) {
+          UploadRealtimeRecordingSegment(agentSessionId: $agentSessionId, segmentIndex: $segmentIndex, audioBase64: $audioBase64, mimeType: $mimeType)
+        }
+      `;
+            // Shards are HEADER-LESS raw little-endian PCM16 (mime audio/L16 with the capture sample rate),
+            // NOT individually-playable WAV — recovery is concatenate-in-order then WAV-wrap. The canonical
+            // seekable WAV is the consolidated end-of-call upload below.
+            const shardMime = `audio/L16;rate=${recorder.SampleRate}`;
+            await this.gql().ExecuteGQL(mutation, { agentSessionId, segmentIndex: index, audioBase64, mimeType: shardMime });
+        }
+        catch (error) {
+            console.warn('[RealtimeSession] Failed to flush recording shard:', error);
+        }
+    }
+    /**
+     * 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.
+     */
+    async stopAndUploadRecording(agentSessionId) {
+        this.stopSegmentFlushing();
+        const recorder = this.recorder;
+        this.recorder = null;
+        this.currentTurnStartMs = null;
+        this.turnAudioStartCaptured = false;
+        if (!recorder) {
+            return;
+        }
+        try {
+            // Capture the recorder MIME (now 'audio/wav') BEFORE Stop() — the getter reads '' once stopped.
+            const mimeType = recorder.MimeType;
+            const audioBase64 = await recorder.StopAndEncode();
+            // Read the real waveform peaks computed during capture (survives the stop via the snapshot).
+            const peaks = recorder.GetPeaks();
+            if (!audioBase64 || !agentSessionId) {
+                console.warn('[RealtimeSession] ⚠️ recording NOT uploaded — empty recording or no session id.');
+                return;
+            }
+            await this.uploadRecording(agentSessionId, audioBase64, mimeType, peaks);
+        }
+        catch (error) {
+            console.warn('[RealtimeSession] Failed to stop/upload call recording:', error);
+        }
+    }
+    /**
+     * 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.
+     */
+    async uploadRecording(agentSessionId, audioBase64, mimeType, peaks) {
+        const mutation = `
+      mutation UploadRealtimeRecording($agentSessionId: String!, $audioBase64: String!, $mimeType: String!, $consent: Boolean, $peaks: [Float!]) {
+        UploadRealtimeRecording(agentSessionId: $agentSessionId, audioBase64: $audioBase64, mimeType: $mimeType, consent: $consent, peaks: $peaks) {
+          Success
+          FileID
+          ErrorMessage
+        }
+      }
+    `;
+        const result = await this.gql().ExecuteGQL(mutation, {
+            agentSessionId,
+            audioBase64,
+            mimeType,
+            consent: true,
+            peaks
+        });
+        const payload = result?.UploadRealtimeRecording;
+        if (!payload?.Success) {
+            console.warn(`[RealtimeSession] ❌ recording upload reported failure: ${payload?.ErrorMessage ?? 'unknown error'} (full result: ${JSON.stringify(result)})`);
+        }
+    }
+    // ── Interactive channels (registry-driven plugins) ─────────────────────────
+    /**
+     * Resolves, instantiates and initializes the session's interactive-channel plugins from
+     * the `MJ: AI Agent Channels` registry, publishes them on {@link ActiveChannels$}, and
+     * returns their aggregated client-executed tool declarations for the session mint.
+     * Tolerant by design: registry/resolution failures degrade to "no channels" — the voice
+     * session itself always proceeds.
+     */
+    async startChannels() {
+        const channels = await this.loadActiveChannels();
+        for (const plugin of channels) {
+            this.initializeChannel(plugin);
+        }
+        this._activeChannels$.next(channels);
+        return channels.flatMap(plugin => plugin.GetToolDefinitions());
+    }
+    /**
+     * 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.
+     */
+    async loadActiveChannels() {
+        const rows = await this.fetchChannelDefinitions();
+        const channels = [];
+        for (const row of rows) {
+            const plugin = this.resolveChannelPlugin(row);
+            if (plugin) {
+                channels.push(plugin);
+            }
+        }
+        return channels;
+    }
+    /**
+     * Reads the ACTIVE `MJ: AI Agent Channels` rows from {@link AIEngineBase}'s cached
+     * `AgentChannels` (provider-scoped engine instance, lazy `Config` — no RunView
+     * round-trip; the engine's BaseEntity-event reactivity keeps the registry fresh).
+     * Failures are logged and degrade to an empty list — channel availability must
+     * never block the voice session.
+     */
+    async fetchChannelDefinitions() {
+        try {
+            const engine = AIEngineBase.GetProviderInstance(this.Provider, AIEngineBase);
+            await engine.Config(false, undefined, this.Provider);
+            return (engine.AgentChannels ?? [])
+                .filter(c => c.IsActive)
+                .map(c => ({ ID: c.ID, Name: c.Name, ClientPluginClass: c.ClientPluginClass }));
+        }
+        catch (error) {
+            console.warn('[RealtimeSession] Channel registry unavailable — starting with no channels:', error);
+            return [];
+        }
+    }
+    /**
+     * Resolves one registry row's `ClientPluginClass` via the ClassFactory (registration
+     * checked first, exactly like the realtime-client drivers) and instantiates a fresh
+     * per-session plugin. Returns `null` (logged) when no plugin is registered for the key
+     * — e.g. its Load function was never called or the package isn't included client-side.
+     */
+    resolveChannelPlugin(row) {
+        const key = row.ClientPluginClass?.trim();
+        if (!key) {
+            console.warn(`[RealtimeSession] Channel '${row.Name}' has no ClientPluginClass — skipping.`);
+            return null;
+        }
+        const registration = MJGlobal.Instance.ClassFactory.GetRegistration(BaseRealtimeChannelClient, key);
+        if (!registration) {
+            console.warn(`[RealtimeSession] No client plugin registered for channel '${row.Name}' (key '${key}') — skipping.`);
+            return null;
+        }
+        const plugin = MJGlobal.Instance.ClassFactory.CreateInstance(BaseRealtimeChannelClient, key);
+        if (!plugin) {
+            console.warn(`[RealtimeSession] Failed to instantiate client plugin for channel '${row.Name}' (key '${key}').`);
+            return null;
+        }
+        return plugin;
+    }
+    /**
+     * Wires one plugin into the session: hands it its host context and registers its
+     * prefix-routed local tool executor (so `<ToolNamePrefix>*` calls run in the browser
+     * through {@link BaseRealtimeChannelClient.ApplyAgentTool}, never the server relay).
+     */
+    initializeChannel(plugin) {
+        plugin.Initialize(this.buildChannelContext(plugin));
+        this.RegisterClientToolHandler(plugin.ToolNamePrefix, (toolName, argsJson) => {
+            // The agent is ACTING on this channel — surface-discovery signal for the overlay
+            // (first activity registers + auto-reveals + focuses the channel tab) before the
+            // tool applies. Record the channel as USED so the overlay tabs it (channels other
+            // than the whiteboard are tab-less until they're first used).
+            this.usedChannelNames.add(plugin.ChannelName);
+            this._channelActivity$.next(plugin);
+            return plugin.ApplyAgentTool(toolName, argsJson);
+        });
+    }
+    /** Builds the host-services context one channel plugin sees (its only line to the session). */
+    buildChannelContext(plugin) {
+        // Capture the service in a local so the AgentSessionID getter reads the SERVICE's live
+        // field (not the object literal's `this`) every time it's accessed.
+        const service = this;
+        return {
+            AgentName: this.CurrentAgentName,
+            // The live session's provider — threaded by channels into MJ-backed surfaces (e.g. the Media
+            // channel's mj-storage-media-player / CreateMediaAccessToken). `get` so it stays current.
+            get Provider() {
+                return service.Provider;
+            },
+            SendContextNote: (text) => this.SendContextNote(text),
+            RequestSpokenResponse: (instructions) => this.requestChannelSpokenResponse(instructions),
+            RequestSave: (stateJson) => this.scheduleChannelSave(plugin.ChannelName, stateJson),
+            SaveAsArtifact: (name, contentJson) => this.saveChannelArtifact(plugin.ChannelName, name, contentJson),
+            SetFocusMode: (on) => this._channelFocus$.next({ Channel: plugin, Focused: on }),
+            // Live session id + GraphQL escape hatch for SERVER-BACKED channels (e.g. Remote
+            // Browser). `get` so a channel always reads the CURRENT id — it's null at Initialize
+            // (the plugin is built before mintSession resolves) and set once the session is live.
+            get AgentSessionID() {
+                return service.agentSessionId;
+            },
+            ExecuteServerAction: (query, variables) => this.executeChannelServerAction(query, variables),
+            // App-context stream + client-tool execution for the headless ClientContextChannel. The host
+            // (Explorer) feeds both; absent on hosts that supply no app context / register no client tools.
+            AppContext$: this.AppContext$,
+            ExecuteClientTool: (name, params) => this.executeAppClientTool(name, params),
+            get Client() {
+                return service.client;
+            },
+            SendVideoFrame: (base64Image, mimeType) => this.SendVideoFrame(base64Image, mimeType),
+            IsTrackEstablished: (modality, direction) => this.IsTrackEstablished(modality, direction)
+        };
+    }
+    /**
+     * 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.
+     */
+    RegisterAppClientTools(tools) {
+        this.appClientToolHandlers.clear();
+        for (const tool of tools) {
+            if (tool?.Name && typeof tool.Handler === 'function') {
+                this.appClientToolHandlers.set(tool.Name.trim().toLowerCase(), tool.Handler);
+            }
+        }
+    }
+    /**
+     * 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.
+     *
+     * @param name The tool name (the model's `action`).
+     * @param params The tool parameters.
+     * @returns A structured result for the channel to serialize back to the model.
+     */
+    async executeAppClientTool(name, params) {
+        const handler = this.appClientToolHandlers.get((name ?? '').trim().toLowerCase());
+        if (!handler) {
+            const available = Array.from(this.appClientToolHandlers.keys()).join(', ');
+            return {
+                Success: false,
+                ErrorMessage: `No client tool named "${name}" is available on this surface. Available: ${available || '(none)'}.`
+            };
+        }
+        try {
+            const result = await handler(params ?? {});
+            return { Success: true, Result: result };
+        }
+        catch (error) {
+            return { Success: false, ErrorMessage: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    /**
+     * Runs a channel-specific GraphQL operation through the live session's provider (the
+     * {@link RealtimeChannelContext.ExecuteServerAction} implementation). Best-effort: any
+     * transport/server error is logged and resolves to `null` so the calling channel can map
+     * the failure to a model-readable result string without `try/catch`.
+     */
+    async executeChannelServerAction(query, variables) {
+        try {
+            const result = await this.gql().ExecuteGQL(query, variables);
+            return result ?? null;
+        }
+        catch (error) {
+            console.error('[RealtimeSession] Channel server action failed:', error);
+            return null;
+        }
+    }
+    /**
+     * A channel asked the live model to SPEAK in reaction to channel input (e.g. a widget
+     * submission) — routed through the client's spoken-update channel. No-op when the
+     * session isn't live; empty instructions are dropped.
+     */
+    requestChannelSpokenResponse(instructions) {
+        const trimmed = instructions?.trim() ?? '';
+        if (trimmed.length === 0 || !this.client || !this.isSessionLive()) {
+            return;
+        }
+        this.client.RequestSpokenUpdate(trimmed);
+    }
+    /**
+     * Applies the PRIOR session's saved channel states (resume continuity): parses the
+     * server-supplied map and offers each entry to the matching active plugin via
+     * {@link BaseRealtimeChannelClient.RestoreState}. Fully tolerant — malformed payloads,
+     * unknown channels, and plugin rejections are logged and skipped; the session start is
+     * never affected.
+     */
+    applyPriorChannelStates(statesJson) {
+        if (!statesJson) {
+            return;
+        }
+        let states;
+        try {
+            const parsed = JSON.parse(statesJson);
+            if (parsed === null || typeof parsed !== 'object') {
+                return;
+            }
+            states = parsed;
+        }
+        catch {
+            console.warn('[RealtimeSession] PriorChannelStatesJson was malformed — starting channels fresh');
+            return;
+        }
+        for (const plugin of this._activeChannels$.value) {
+            const state = states[plugin.ChannelName];
+            if (typeof state === 'string' && state.length > 0) {
+                try {
+                    const restored = plugin.RestoreState(state);
+                    if (!restored) {
+                        console.warn(`[RealtimeSession] Channel '${plugin.ChannelName}' declined its prior-session state — starting fresh`);
+                    }
+                }
+                catch (error) {
+                    console.warn(`[RealtimeSession] Channel '${plugin.ChannelName}' restore threw — starting fresh`, error);
+                }
+            }
+        }
+    }
+    /**
+     * 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
+     * whiteboard's "Save to artifacts". Best-effort: returns the created Artifact ID, or null
+     * on any failure (logged, never thrown). Uses the live session id, falling back to the
+     * teardown-captured one so "save my board" works right after the call ends.
+     */
+    async saveChannelArtifact(channelName, name, contentJson) {
+        const sessionId = this.agentSessionId ?? this.lastKnownSessionIdForSaves();
+        if (!sessionId || !name.trim() || !contentJson) {
+            return null;
+        }
+        try {
+            const result = await this.gql().ExecuteGQL(`mutation SaveSessionChannelArtifact($agentSessionId: String!, $channelName: String!, $name: String!, $contentJson: String!) {
+          SaveSessionChannelArtifact(agentSessionId: $agentSessionId, channelName: $channelName, name: $name, contentJson: $contentJson) {
+            Success
+            ErrorMessage
+            ArtifactID
+            ArtifactVersionID
+          }
+        }`, { agentSessionId: sessionId, channelName, name: name.trim(), contentJson });
+            const payload = result?.SaveSessionChannelArtifact;
+            if (!payload?.Success) {
+                console.warn(`[RealtimeSession] Save-as-artifact failed for '${channelName}': ${payload?.ErrorMessage ?? 'unknown error'}`);
+                return null;
+            }
+            return payload.ArtifactID ?? null;
+        }
+        catch (error) {
+            console.warn(`[RealtimeSession] Save-as-artifact errored for '${channelName}':`, error);
+            return null;
+        }
+    }
+    /** Most recent session id captured by the save pipeline (post-teardown saves). */
+    lastKnownSessionIdForSaves() {
+        for (const pending of this.pendingChannelSaves.values()) {
+            if (pending.SessionID) {
+                return pending.SessionID;
+            }
+        }
+        return null;
+    }
+    /**
+     * Schedules the DEBOUNCED state-of-record save for a channel: each request replaces the
+     * pending payload (latest state wins) and re-arms the timer; the session id is captured
+     * while live so the teardown flush can persist onto the just-closed session.
+     */
+    scheduleChannelSave(channelName, stateJson) {
+        const pending = this.pendingChannelSaves.get(channelName);
+        if (pending) {
+            clearTimeout(pending.Timer);
+        }
+        this.pendingChannelSaves.set(channelName, {
+            Timer: setTimeout(() => this.flushChannelSave(channelName), RealtimeSessionRuntime.ChannelSaveDebounceMs),
+            StateJson: stateJson,
+            SessionID: this.agentSessionId ?? pending?.SessionID ?? null
+        });
+    }
+    /** Fires one pending channel save (best-effort; {@link SaveChannelState} logs failures). */
+    flushChannelSave(channelName) {
+        const pending = this.pendingChannelSaves.get(channelName);
+        if (!pending) {
+            return;
+        }
+        this.pendingChannelSaves.delete(channelName);
+        clearTimeout(pending.Timer);
+        void this.SaveChannelState(channelName, pending.StateJson, pending.SessionID);
+    }
+    /** Final teardown flush: persist every channel's unsaved state immediately. */
+    flushAllChannelSaves() {
+        for (const channelName of [...this.pendingChannelSaves.keys()]) {
+            this.flushChannelSave(channelName);
+        }
+    }
+    /** Disposes all channel plugins (errors contained per plugin) and clears the live set. */
+    disposeChannels() {
+        for (const plugin of this._activeChannels$.value) {
+            try {
+                plugin.Dispose();
+            }
+            catch (error) {
+                console.error(`[RealtimeSession] Channel '${plugin.ChannelName}' Dispose failed:`, error);
+            }
+        }
+        if (this._activeChannels$.value.length > 0) {
+            this._activeChannels$.next([]);
+        }
+        this.usedChannelNames.clear();
+    }
+    // ── Realtime client resolution + wiring ────────────────────────────────────
+    /**
+     * Resolves the provider-direct realtime client for `provider` through the MJ
+     * ClassFactory — the client-side mirror of how server drivers are resolved from
+     * `BaseRealtimeModel`. Throws a clear error when no driver is registered for the
+     * provider (e.g. its Load function was never called).
+     */
+    createRealtimeClient(provider) {
+        const registration = MJGlobal.Instance.ClassFactory.GetRegistration(BaseRealtimeClient, provider);
+        if (!registration) {
+            throw new Error(`No realtime client registered for provider '${provider}'. ` +
+                `Ensure the provider's client driver package is imported and its Load function called.`);
+        }
+        const client = MJGlobal.Instance.ClassFactory.CreateInstance(BaseRealtimeClient, provider);
+        if (!client) {
+            throw new Error(`Failed to instantiate the realtime client for provider '${provider}'`);
+        }
+        return client;
+    }
+    /**
+     * Builds the client-direct session config the realtime client connects with.
+     * Aggregates tracks sourced by active channels into `requestedTracks` so the driver
+     * can negotiate them (e.g., establishing inbound video streaming for Whiteboard / RemoteBrowser).
+     */
+    buildClientConfig(session) {
+        const sessionConfig = this.parseSessionConfig(session.SessionConfigJson);
+        const channelTracks = this._activeChannels$.value.flatMap((c) => c.GetSourcedTracks());
+        if (channelTracks.length > 0) {
+            // `requestedTracks` crosses a JSON boundary — the driver reads it back out of the session
+            // config bag (`GeminiRealtimeClient.parseSessionConfig`). A `RealtimeTrackDescriptor` is NOT
+            // structurally a `JSONValue`: it has no index signature and `UsageBasis` is readonly, so the
+            // conversion is written out rather than asserted. Dedupe key and precedence are unchanged —
+            // audio floor first, then anything the mint supplied, then the channels' own tracks.
+            const existing = Array.isArray(sessionConfig['requestedTracks'])
+                ? sessionConfig['requestedTracks']
+                : [];
+            const trackMap = new Map();
+            for (const t of DEFAULT_REALTIME_AUDIO_TRACKS) {
+                trackMap.set(`${t.Direction}:${t.Modality}`, trackDescriptorToJSON(t));
+            }
+            for (const raw of existing) {
+                const key = trackKeyFromJSON(raw);
+                if (key) {
+                    trackMap.set(key, raw);
+                }
+            }
+            for (const t of channelTracks) {
+                trackMap.set(`${t.Direction}:${t.Modality}`, trackDescriptorToJSON(t));
+            }
+            sessionConfig['requestedTracks'] = Array.from(trackMap.values());
+        }
+        return {
+            Provider: session.Provider,
+            Model: session.Model,
+            EphemeralToken: session.EphemeralToken,
+            ExpiresAt: session.ExpiresAt,
+            SessionConfig: sessionConfig
+        };
+    }
+    /**
+     * Parses the server-built session config JSON. On failure, logs and returns an empty
+     * object — the client treats an empty config as "nothing to apply", so the session
+     * still opens (mirroring the prior behavior of skipping the config update).
+     */
+    parseSessionConfig(sessionConfigJson) {
+        if (!sessionConfigJson) {
+            return {};
+        }
+        try {
+            return JSON.parse(sessionConfigJson);
+        }
+        catch (error) {
+            console.error('[RealtimeSession] Failed to parse/apply SessionConfigJson:', error);
+            return {};
+        }
+    }
+    /** Subscribes this service's policy handlers to the realtime client's events. */
+    wireClientHandlers(client) {
+        client.OnStateChange((state) => this.onClientStateChange(state));
+        client.OnTranscript((transcript) => {
+            void this.onClientTranscript(transcript);
+        });
+        client.OnToolCall((call) => {
+            void this.handleToolCall(call);
+        });
+        client.OnError((error) => {
+            console.error('[RealtimeSession] Provider error event:', JSON.stringify(error), error);
+        });
+        // Usage telemetry: accumulate the driver's per-response token DELTAS and relay them to
+        // the server (onto the co-agent AIPromptRun) debounced + once at teardown. Providers
+        // without usage events simply never emit — registering is always safe.
+        client.OnUsage((usage) => this.onUsageDelta(usage));
+        // TRUE BARGE-IN (user input cut off active model output — the driver already stopped
+        // the speech): the user took the floor, so any pending/queued progress narration is
+        // stale — cancel it; the next progress event re-schedules at the session-global pace.
+        // HOST POLICY (deliberate): barge-in does NOT abort in-flight delegated runs — the
+        // narration design EXPECTS the user to keep talking while delegated work runs, so
+        // killing the work on speech would cancel exactly the jobs the user asked for.
+        // Explicit cancellation is a separate, intentional act: the overlay's per-card ✕
+        // calls {@link CancelDelegation} (server cancel channel) instead.
+        client.OnInterruption(() => {
+            this.cancelPendingNarration();
+        });
+    }
+    /** Maps a client state event onto the UI connection state. */
+    onClientStateChange(state) {
+        const mapped = this.mapClientState(state);
+        if (mapped) {
+            this._connectionState$.next(mapped);
+        }
+    }
+    /**
+     * Translates {@link RealtimeClientState} into {@link RealtimeConnectionState}. `'connected'`
+     * is suppressed (the UI stays 'connecting' until the control channel opens → 'listening'),
+     * and `'closed'` never overwrites a terminal 'error' the service itself recorded.
+     */
+    mapClientState(state) {
+        switch (state) {
+            case 'connecting':
+                return 'connecting';
+            case 'connected':
+                return null;
+            case 'listening':
+                return 'listening';
+            case 'speaking':
+                return 'speaking';
+            case 'error':
+                return 'error';
+            case 'closed':
+                return this._connectionState$.value === 'error' ? null : 'closed';
+        }
+    }
+    /** True when the live control channel is usable (open and not torn down / failed). */
+    isSessionLive() {
+        const state = this._connectionState$.value;
+        return state === 'listening' || state === 'speaking' || state === 'thinking';
+    }
+    // ── Transcript policy ──────────────────────────────────────────────────────
+    /**
+     * 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
+     * audio-start offset against the recording (the first interim fires as the audio/text
+     * starts flowing — see {@link markTurnAudioStart}). Final NORMAL assistant turns become
+     * captions + persisted transcripts; final NARRATION turns are EPHEMERAL by product
+     * decision — emitted on {@link DelegationNarration$} only, never a caption, never
+     * relayed/persisted. User turns ride the caption + relay path.
+     */
+    async onClientTranscript(transcript) {
+        if (!transcript.IsFinal) {
+            // First interim of a NEW turn = that turn's audio is starting NOW. Stamp the
+            // recording-relative start here so a turn whose audio begins AFTER a tool-call /
+            // silence gap is timed where its audio really is — not inherited from the prior
+            // turn's end. Narration interims are ephemeral and excluded (Kind guard inside).
+            this.markTurnAudioStart(transcript.Kind);
+            if (transcript.Role === 'User') {
+                if (!this.hasActiveInterimUserCaption) {
+                    if (transcript.Text.trim().length === 0) {
+                        return;
+                    }
+                    this.hasActiveInterimUserCaption = true;
+                    this.pendingUserCaption = transcript.Text;
+                    this.appendCaption({ Role: 'User', Text: this.pendingUserCaption });
+                }
+                else {
+                    this.pendingUserCaption += transcript.Text;
+                    this.replaceLastCaption('User', this.pendingUserCaption);
+                }
+            }
+            return;
+        }
+        if (transcript.Role === 'Assistant') {
+            this.hasActiveInterimUserCaption = false;
+            this.pendingUserCaption = '';
+            if (transcript.Kind === 'narration') {
+                if (transcript.IsThought) {
+                    this._thoughtNarration$.next({
+                        CallID: 'thought-session',
+                        Text: transcript.Text,
+                        IsFinal: transcript.IsFinal ?? true,
+                    });
+                }
+                else {
+                    this._delegationNarration$.next({ Text: transcript.Text });
+                    // Remember what was actually SAID so later updates build on it instead of repeating.
+                    this.spokenNarrations.push(transcript.Text);
+                    if (this.spokenNarrations.length > RealtimeSessionRuntime.MaxPriorNarrations) {
+                        this.spokenNarrations.shift();
+                    }
+                }
+            }
+            else if (transcript.ReplacesPrevious) {
+                // CORRECTION (e.g. ElevenLabs post-barge-in re-finalization): this final
+                // SUPERSEDES the previous final assistant turn — replace the caption in place
+                // and tell the server to update the persisted turn instead of appending.
+                this.replaceLastCaption('Assistant', transcript.Text);
+                await this.relayTranscript('assistant', transcript.Text, true);
+            }
+            else {
+                this.appendCaption({ Role: 'Assistant', Text: transcript.Text });
+                await this.relayTranscript('assistant', transcript.Text);
+            }
+        }
+        else if (this.hasActiveInterimUserCaption) {
+            this.hasActiveInterimUserCaption = false;
+            this.pendingUserCaption = '';
+            if (transcript.Text.trim().length === 0) {
+                return;
+            }
+            this.replaceLastCaption('User', transcript.Text);
+            if (this.firstUserTranscript === null) {
+                this.firstUserTranscript = transcript.Text;
+            }
+            await this.relayTranscript('user', transcript.Text);
+        }
+        else if (transcript.ReplacesPrevious) {
+            // STREAMING user transcription: providers like Grok and OpenAI Live emit the growing utterance as repeated
+            // events (each the full text so far), flagging all but the first ReplacesPrevious. Update the
+            // in-place User caption + persisted turn instead of stacking a new bubble per increment — the
+            // same correction semantics the assistant branch uses. (Classic OpenAI Realtime sends one final → the else path.)
+            if (transcript.Text.trim().length === 0) {
+                return;
+            }
+            this.replaceLastCaption('User', transcript.Text);
+            await this.relayTranscript('user', transcript.Text, true);
+        }
+        else {
+            await this.onUserTranscript(transcript.Text);
+        }
+    }
+    /**
+     * Stamps the recording-relative offset at which the IN-FLIGHT turn's audio actually began,
+     * the moment that turn's audio/text first starts flowing (its FIRST interim transcript).
+     *
+     * This is the fix for transcript cues drifting out of sync with the audio when a tool-call /
+     * silence gap sits between turns: the old model inherited the next turn's start from the
+     * PREVIOUS turn's end (assumes contiguous turns), so a post-gap turn's cue pointed ~gap-length
+     * too early. Capturing the start where the audio truly begins keeps the cue aligned.
+     *
+     * Guards:
+     * - only when recording ({@link recorder} present),
+     * - only ONCE per turn ({@link turnAudioStartCaptured}) so mid-turn interim deltas don't move it,
+     * - 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.
+     */
+    markTurnAudioStart(kind) {
+        if (this.turnAudioStartCaptured || kind === 'narration') {
+            return;
+        }
+        const offset = this.nowTurnOffsetMs();
+        if (offset === null) {
+            return;
+        }
+        this.currentTurnStartMs = offset;
+        this.turnAudioStartCaptured = true;
+    }
+    /**
+     * 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.
+     */
+    nowTurnOffsetMs() {
+        if (this.recorder) {
+            return this.recorder.NowOffsetMs();
+        }
+        if (this.sessionClockStartMs !== null) {
+            return Math.max(0, Math.round(performance.now() - this.sessionClockStartMs));
+        }
+        return null;
+    }
+    /**
+     * Replaces the LAST caption of `role` in place (correction semantics); falls back to a
+     * plain append when no such caption exists yet (e.g. the superseded turn predates this
+     * client's caption window).
+     */
+    replaceLastCaption(role, text) {
+        const captions = this._captions$.value;
+        for (let i = captions.length - 1; i >= 0; i--) {
+            if (captions[i].Role === role) {
+                const next = [...captions];
+                next[i] = { Role: role, Text: text };
+                this._captions$.next(next);
+                return;
+            }
+        }
+        this.appendCaption({ Role: role, Text: text });
+    }
+    /** Finalizes the user turn: push a caption + relay the final transcript. */
+    async onUserTranscript(transcript) {
+        if (transcript.trim().length === 0) {
+            return;
+        }
+        if (this.firstUserTranscript === null) {
+            // First spoken user utterance — the naming seed for a session-created conversation.
+            this.firstUserTranscript = transcript;
+        }
+        this.appendCaption({ Role: 'User', Text: transcript });
+        await this.relayTranscript('user', transcript);
+    }
+    // ── Tool calling ───────────────────────────────────────────────────────────
+    /**
+     * Routes a provider tool call: names matching a registered client-tool prefix execute
+     * LOCALLY (UI tools — see {@link RegisterClientToolHandler}); everything else executes on
+     * the MJ server. Either way the result feeds back to the model via
+     * {@link BaseRealtimeClient.SendToolResult} so it speaks the outcome.
+     */
+    async handleToolCall(call) {
+        const clientHandler = this.findClientToolHandler(call.ToolName);
+        if (clientHandler) {
+            // Local UI tool: no server relay, no 'thinking' turn-state / narration burst, and intentionally
+            // NO thread card — these are fast, in-browser surface mutations (e.g. drawing on the whiteboard)
+            // whose visual effects are immediately visible on the dedicated canvas/surface.
+            const resultJson = await this.executeClientTool(clientHandler, call);
+            this.client?.SendToolResult(call.CallID, resultJson);
+            // Observability: record the channel tool call on the co-agent's run (run-only — NOT a chat
+            // turn). Without this the run shows speech but never the browser_/Whiteboard_ actions the
+            // co-agent took. Fire-and-forget; never disturbs the live surface mutation.
+            void this.relayToolTurn(call.ToolName, call.ArgumentsJson, resultJson);
+            return;
+        }
+        this._connectionState$.next('thinking');
+        if (this.inFlightCallIds.size === 0) {
+            // A fresh delegation burst: anchor the first-update delay and clear the digest
+            // buffer. Deliberately NOT reset: lastDelegationNarrationAt (the 8s spacing floor
+            // is SESSION-global — sequential tool calls seconds apart must not re-arm the
+            // faster first-update path, which read as "no debounce") and spokenNarrations
+            // (so the story never repeats across closely-spaced calls).
+            this.delegationBurstStartedAt = Date.now();
+            this.narrationCount = 0;
+            this.pendingNarrationMessages = [];
+            this.lastNarratedTail = '';
+        }
+        this.inFlightCallIds.add(call.CallID);
+        if (call.ToolName !== 'invoke-target-agent') {
+            // Direct action: emit synthetic progress immediately so the conversation thread
+            // and activity rail render an active "working" action card while the tool executes.
+            this._delegationProgress$.next({
+                CallID: call.CallID,
+                ToolName: call.ToolName,
+                Step: 'direct_action',
+                Message: `Executing ${FormatToolName(call.ToolName)}`
+            });
+        }
+        try {
+            const resultJson = await this.executeSessionTool(call.CallID, call.ToolName, call.ArgumentsJson);
+            this.emitDelegationResult(call.CallID, resultJson, call.ToolName);
+            this.client?.SendToolResult(call.CallID, resultJson);
+        }
+        catch (error) {
+            console.error('[RealtimeSession] Tool execution failed:', error);
+            // Feed the error back so the model can narrate it rather than going silent.
+            // success:false matters: ParseDelegationResultJson treats anything else as
+            // success, which would flip the overlay's working card to a SUCCESS card
+            // carrying the error text (matches the server broker's failure shape).
+            const errorJson = JSON.stringify({
+                success: false,
+                error: error instanceof Error ? error.message : String(error)
+            });
+            this.emitDelegationResult(call.CallID, errorJson, call.ToolName);
+            this.client?.SendToolResult(call.CallID, errorJson);
+        }
+    }
+    /** Finds the registered client-tool handler whose prefix matches `toolName`, or `null`. */
+    findClientToolHandler(toolName) {
+        for (const [prefix, handler] of this.clientToolHandlers) {
+            if (toolName.startsWith(prefix)) {
+                return handler;
+            }
+        }
+        return null;
+    }
+    /**
+     * Executes one client-tool call through its handler, wrapping any thrown error into a
+     * `{ success: false, error }` JSON payload so the model can narrate the failure instead of
+     * the call going silent.
+     */
+    async executeClientTool(handler, call) {
+        try {
+            return await handler(call.ToolName, call.ArgumentsJson);
+        }
+        catch (error) {
+            console.error('[RealtimeSession] Client tool execution failed:', error);
+            return JSON.stringify({
+                success: false,
+                error: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+    /**
+     * Emits a delegation result so the overlay's "working" card flips to a result card with real
+     * content. Parses the broker's `{success, output, runId}` | `{success:false, error}` shape via
+     * {@link ParseDelegationResultJson}; if it isn't JSON, surfaces the raw string. The `runId`
+     * (the delegated `MJ: AI Agent Runs` record) rides along as {@link RealtimeDelegationResult.RunID}
+     * for the overlay's dev links, and any `artifacts` ride along as {@link RealtimeDelegationResult.Artifacts}
+     * for the surface panel's artifact tabs.
+     */
+    emitDelegationResult(callId, resultJson, toolName) {
+        // The result will be spoken next — a deferred interim update is now pointless
+        // (this is what keeps fast agents like Sage from narrating over their own answer),
+        // and any progress still in the PubSub pipe for this call is stale.
+        this.inFlightCallIds.delete(callId);
+        this.cancelPendingNarration();
+        if (this.cancelledCallIds.delete(callId)) {
+            // The user explicitly cancelled this call: its card already flipped to the
+            // "Cancelled by user" failed result, so the aborted run's late outcome must not
+            // overwrite it. (The tool result still flows back to the model via the caller.)
+            return;
+        }
+        const parsed = ParseDelegationResultJson(resultJson);
+        this._delegationResult$.next({
+            CallID: callId,
+            ToolName: toolName,
+            Success: parsed.Success,
+            Output: parsed.Output,
+            RunID: parsed.RunID,
+            Artifacts: parsed.Artifacts
+        });
+    }
+    // ── Explicit delegation cancellation (server cancel channel) ───────────────
+    /**
+     * Cancels ONE in-flight delegated tool call — the overlay's per-card ✕ affordance.
+     *
+     * EXPLICIT USER INTENT ONLY (deliberate host policy): true barge-in never aborts
+     * delegations — the narration design expects the user to talk while delegated work runs.
+     * Calls the `CancelRealtimeSessionTool` mutation (ownership-gated server-side); when the
+     * server reports it aborted the run, the card is flipped immediately to a FAILED
+     * "Cancelled by user" result and the eventual late result from the aborted run is
+     * suppressed (see {@link emitDelegationResult}).
+     *
+     * @returns `true` when the server aborted the in-flight run; `false` when there was
+     *   nothing to cancel (the work finished first — its real result is already racing in)
+     *   or the mutation failed (logged, never thrown).
+     */
+    async CancelDelegation(callId) {
+        if (!this.agentSessionId || !this.inFlightCallIds.has(callId)) {
+            return false;
+        }
+        const aborted = await this.cancelSessionTool(callId);
+        if (aborted <= 0) {
+            return false; // finished first / nothing in flight server-side — let the real result land
+        }
+        this.surfaceUserCancellation(callId);
+        return true;
+    }
+    /**
+     * Cancels EVERY in-flight delegated tool call for the active session (callId-less form of
+     * the `CancelRealtimeSessionTool` mutation). Exposed for host policies that need a
+     * sweep-cancel (e.g. an explicit "stop everything" affordance) — NOT wired to barge-in,
+     * by the same deliberate policy as {@link CancelDelegation}.
+     *
+     * @returns The number of in-flight runs the server aborted (0 when nothing was tracked
+     *   in flight client-side, nothing was in flight server-side, or the mutation failed).
+     */
+    async CancelInFlightDelegations() {
+        if (!this.agentSessionId || this.inFlightCallIds.size === 0) {
+            return 0;
+        }
+        const aborted = await this.cancelSessionTool(null);
+        if (aborted <= 0) {
+            return 0;
+        }
+        for (const callId of [...this.inFlightCallIds]) {
+            this.surfaceUserCancellation(callId);
+        }
+        return aborted;
+    }
+    /** Flips a cancelled call's card to the failed "Cancelled by user" result and suppresses the late real result. */
+    surfaceUserCancellation(callId) {
+        this.inFlightCallIds.delete(callId);
+        this.cancelledCallIds.add(callId);
+        this.cancelPendingNarration();
+        this._delegationResult$.next({
+            CallID: callId,
+            Success: false,
+            Output: 'Cancelled by user'
+        });
+    }
+    /**
+     * Calls the `CancelRealtimeSessionTool` mutation and unwraps its structured
+     * `{ AbortedCount, Success, ErrorMessage }` result. Returns the aborted count —
+     * 0 on a structured failure or a thrown transport error (both logged, never thrown).
+     */
+    async cancelSessionTool(callId) {
+        try {
+            const mutation = `
+        mutation CancelRealtimeSessionTool($agentSessionId: String!, $callId: String) {
+          CancelRealtimeSessionTool(agentSessionId: $agentSessionId, callId: $callId) {
+            AbortedCount
+            Success
+            ErrorMessage
+          }
+        }
+      `;
+            const result = await this.gql().ExecuteGQL(mutation, { agentSessionId: this.agentSessionId, callId });
+            const payload = result?.CancelRealtimeSessionTool;
+            if (!payload?.Success) {
+                console.warn(`[RealtimeSession] Cancel reported failure: ${payload?.ErrorMessage ?? 'unknown error'}`);
+                return 0;
+            }
+            return typeof payload.AbortedCount === 'number' ? payload.AbortedCount : 0;
+        }
+        catch (error) {
+            console.error('[RealtimeSession] Failed to cancel in-flight delegation(s):', error);
+            return 0;
+        }
+    }
+    // ── Session minting (GraphQL) ──────────────────────────────────────────────
+    /** Calls the `StartRealtimeClientSession` mutation to obtain an ephemeral token + config. */
+    async mintSession(targetAgentId, conversationId, lastSessionId, preferredModelId, clientTools, coAgentId, configOverridesJson, recordingConsent, recordingStartedAt, mediaCollectionId, applicationId, appContext) {
+        const mutation = `
+      mutation StartRealtimeClientSession($targetAgentId: String!, $conversationId: String, $lastSessionId: String, $preferredModelId: String, $clientToolsJson: String, $coAgentId: String, $configOverridesJson: String, $recordingConsent: Boolean, $recordingStartedAt: String, $mediaCollectionId: String, $applicationId: String, $appContextJson: String) {
+        StartRealtimeClientSession(targetAgentId: $targetAgentId, conversationId: $conversationId, lastSessionId: $lastSessionId, preferredModelId: $preferredModelId, clientToolsJson: $clientToolsJson, coAgentId: $coAgentId, configOverridesJson: $configOverridesJson, recordingConsent: $recordingConsent, recordingStartedAt: $recordingStartedAt, mediaCollectionId: $mediaCollectionId, applicationId: $applicationId, appContextJson: $appContextJson) {
+          AgentSessionId
+          ConversationId
+          Provider
+          Model
+          EphemeralToken
+          ExpiresAt
+          SessionConfigJson
+          ModelName
+          NarrationInstructionsTemplate
+          PriorChannelStatesJson
+        }
+      }
+    `;
+        const variables = {
+            targetAgentId,
+            conversationId: conversationId ?? null,
+            lastSessionId: lastSessionId ?? null,
+            preferredModelId: preferredModelId ?? null,
+            clientToolsJson: clientTools && clientTools.length > 0 ? JSON.stringify(clientTools) : null,
+            coAgentId: coAgentId ?? null,
+            configOverridesJson: configOverridesJson ?? null,
+            recordingConsent: recordingConsent ?? false,
+            recordingStartedAt: recordingStartedAt ?? null,
+            mediaCollectionId: mediaCollectionId ?? null,
+            applicationId: applicationId ?? null,
+            appContextJson: appContext ? JSON.stringify(appContext) : null
+        };
+        const result = await this.gql().ExecuteGQL(mutation, variables);
+        const payload = result?.StartRealtimeClientSession;
+        if (!payload?.EphemeralToken) {
+            throw new Error('StartRealtimeClientSession returned no ephemeral token');
+        }
+        return payload;
+    }
+    /** Calls the `ExecuteRealtimeSessionTool` mutation; returns the ResultJson string. */
+    async executeSessionTool(callId, toolName, argsJson) {
+        if (!this.agentSessionId) {
+            throw new Error('No active agent session for tool execution');
+        }
+        const mutation = `
+      mutation ExecuteRealtimeSessionTool($agentSessionId: String!, $callId: String!, $toolName: String!, $argsJson: String!) {
+        ExecuteRealtimeSessionTool(agentSessionId: $agentSessionId, callId: $callId, toolName: $toolName, argsJson: $argsJson)
+      }
+    `;
+        const result = await this.gql().ExecuteGQL(mutation, {
+            agentSessionId: this.agentSessionId,
+            callId,
+            toolName,
+            argsJson
+        });
+        return result?.ExecuteRealtimeSessionTool ?? '{}';
+    }
+    /**
+     * Persists an interactive channel's state of record (e.g. the whiteboard's serialized scene)
+     * onto the session's `MJ: AI Agent Session Channels` row via `SaveSessionChannelState`.
+     *
+     * @param channelName The channel definition name (e.g. `'Whiteboard'`).
+     * @param stateJson The serialized channel state.
+     * @param agentSessionId Optional EXPLICIT session id. The debounced channel-save pipeline
+     *   captures the id while the session is live and passes it here, so the final teardown
+     *   flush still lands on the just-closed session. Falls back to the active session's id;
+     *   returns `false` when neither is available.
+     * @returns Whether the server persisted the state. Failures are logged, never thrown — channel
+     *   persistence is best-effort and must not disturb the live call.
+     */
+    async SaveChannelState(channelName, stateJson, agentSessionId) {
+        const sessionId = agentSessionId ?? this.agentSessionId;
+        if (!sessionId) {
+            return false;
+        }
+        try {
+            const mutation = `
+        mutation SaveSessionChannelState($agentSessionId: String!, $channelName: String!, $stateJson: String!) {
+          SaveSessionChannelState(agentSessionId: $agentSessionId, channelName: $channelName, stateJson: $stateJson)
+        }
+      `;
+            const result = await this.gql().ExecuteGQL(mutation, { agentSessionId: sessionId, channelName, stateJson });
+            return result?.SaveSessionChannelState ?? false;
+        }
+        catch (error) {
+            console.error('[RealtimeSession] Failed to save channel state:', error);
+            return false;
+        }
+    }
+    // ── Transcript relay (GraphQL) ─────────────────────────────────────────────
+    /**
+     * 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.
+     *
+     * 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.
+     *
+     * @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`).
+     */
+    async relayTranscript(role, text, replacesPrevious = false) {
+        if (!this.agentSessionId) {
+            return;
+        }
+        // Per-turn timing against whichever clock the session is on (#3832): the recorder's when one
+        // runs, else the session clock. `utteranceStartMs` is where this turn's audio actually began
+        // (captured by markTurnAudioStart on the first interim); the `?? 0` fallback covers a turn
+        // whose interim was missed / a final-only first turn.
+        const utteranceEndMs = this.nowTurnOffsetMs();
+        const utteranceStartMs = utteranceEndMs !== null && !replacesPrevious ? (this.currentTurnStartMs ?? 0) : null;
+        if (utteranceEndMs !== null && !replacesPrevious) {
+            // This turn is finalized — arm the NEXT turn to re-stamp its start from its own first
+            // interim (handles a tool-call gap before the next turn). Stop inheriting this end as the
+            // next start. `null` means "not yet captured"; relay falls back to `?? 0` if no interim fires.
+            this.currentTurnStartMs = null;
+            this.turnAudioStartCaptured = false;
+        }
+        try {
+            const mutation = `
+        mutation RelayRealtimeTranscript($agentSessionId: String!, $role: String!, $text: String!, $replacesPrevious: Boolean, $utteranceStartMs: Int, $utteranceEndMs: Int) {
+          RelayRealtimeTranscript(agentSessionId: $agentSessionId, role: $role, text: $text, replacesPrevious: $replacesPrevious, utteranceStartMs: $utteranceStartMs, utteranceEndMs: $utteranceEndMs)
+        }
+      `;
+            await this.gql().ExecuteGQL(mutation, {
+                agentSessionId: this.agentSessionId,
+                role,
+                text,
+                replacesPrevious,
+                utteranceStartMs,
+                utteranceEndMs
+            });
+        }
+        catch (error) {
+            console.error('[RealtimeSession] Failed to relay transcript:', error);
+        }
+    }
+    /**
+     * Relays a co-agent CHANNEL tool-call turn (browser_ / Whiteboard_ etc.) to the session's run for
+     * observability via `RelayRealtimeToolTurn` — so the co-agent's AIPromptRun shows what it DID, not
+     * just what it said. Run-only by design: deliberately NOT a `ConversationDetail` turn, so the chat
+     * thread stays speech-only. Best-effort — a failed relay never disturbs the live call.
+     */
+    async relayToolTurn(toolName, argsJson, resultJson) {
+        if (!this.agentSessionId) {
+            return;
+        }
+        try {
+            const mutation = `
+        mutation RelayRealtimeToolTurn($agentSessionId: String!, $toolName: String!, $argsJson: String, $resultJson: String) {
+          RelayRealtimeToolTurn(agentSessionId: $agentSessionId, toolName: $toolName, argsJson: $argsJson, resultJson: $resultJson)
+        }
+      `;
+            await this.gql().ExecuteGQL(mutation, {
+                agentSessionId: this.agentSessionId,
+                toolName,
+                argsJson,
+                resultJson
+            });
+        }
+        catch (error) {
+            console.error('[RealtimeSession] Failed to relay tool turn:', error);
+        }
+    }
+    // ── Usage telemetry relay (B7) ─────────────────────────────────────────────
+    /**
+     * 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.
+     */
+    onUsageDelta(usage) {
+        const input = this.clampUsageDelta(usage.InputTokens);
+        const output = this.clampUsageDelta(usage.OutputTokens);
+        if (input === 0 && output === 0) {
+            return;
+        }
+        this.pendingUsageInput += input;
+        this.pendingUsageOutput += output;
+        if (!this.usageFlushTimer) {
+            this.usageFlushTimer = setTimeout(() => {
+                this.usageFlushTimer = null;
+                void this.flushPendingUsage();
+            }, RealtimeSessionRuntime.UsageFlushDebounceMs);
+        }
+    }
+    /** Clamps a driver-reported token delta: undefined / negative / non-finite become 0. */
+    clampUsageDelta(value) {
+        return typeof value === 'number' && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+    }
+    /**
+     * Relays the accumulated usage deltas to the server via `RelayRealtimeUsage` (which
+     * accumulates them onto the co-agent `AIPromptRun`). Best-effort: a failed relay
+     * re-accumulates the captured deltas so the next debounce / teardown flush retries —
+     * usage telemetry must never disturb the live call.
+     *
+     * @param agentSessionId Optional EXPLICIT session id (the teardown flush runs while the
+     *   live id is still set, but accepts it as a parameter for symmetry with channel saves).
+     */
+    async flushPendingUsage(agentSessionId) {
+        const sessionId = agentSessionId ?? this.agentSessionId;
+        const input = this.pendingUsageInput;
+        const output = this.pendingUsageOutput;
+        if (!sessionId || (input === 0 && output === 0)) {
+            return;
+        }
+        this.pendingUsageInput = 0;
+        this.pendingUsageOutput = 0;
+        try {
+            const mutation = `
+        mutation RelayRealtimeUsage($agentSessionId: String!, $inputTokens: Int!, $outputTokens: Int!) {
+          RelayRealtimeUsage(agentSessionId: $agentSessionId, inputTokens: $inputTokens, outputTokens: $outputTokens)
+        }
+      `;
+            await this.gql().ExecuteGQL(mutation, { agentSessionId: sessionId, inputTokens: input, outputTokens: output });
+        }
+        catch (error) {
+            console.error('[RealtimeSession] Failed to relay usage telemetry:', error);
+            // Re-accumulate so a later debounce / the teardown flush retries the same deltas.
+            this.pendingUsageInput += input;
+            this.pendingUsageOutput += output;
+        }
+    }
+    /** Cancels the pending debounced usage flush and zeroes the accumulators (teardown tail). */
+    resetUsageRelay() {
+        if (this.usageFlushTimer) {
+            clearTimeout(this.usageFlushTimer);
+            this.usageFlushTimer = null;
+        }
+        this.pendingUsageInput = 0;
+        this.pendingUsageOutput = 0;
+    }
+    // ── Delegated-run progress streaming ───────────────────────────────────────
+    /**
+     * Subscribes to the server's push-status topic (scoped by the GraphQL transport
+     * sessionId) to receive delegated-run progress for the active voice session.
+     * Each matching event is surfaced on {@link DelegationProgress$} and narrated.
+     */
+    subscribeDelegationProgress() {
+        if (this.delegationProgressSub) {
+            return; // already subscribed for this session
+        }
+        const transportSessionId = this.gql().sessionId;
+        this.lastDelegationNarrationAt = 0;
+        this.delegationProgressSub = this.gql()
+            .PushStatusUpdates(transportSessionId)
+            .subscribe({
+            next: (raw) => this.onDelegationStatusMessage(raw),
+            error: (err) => console.error('[RealtimeSession] Delegation progress stream error:', err)
+        });
+    }
+    /**
+     * Parses one push-status message and routes it: a Remote Browser screencast frame goes to the active
+     * Remote Browser channel's canvas; a delegation-progress event is dispatched + narrated. Other shapes
+     * (normal agent-run streams) are ignored. Screencast frames are checked FIRST and short-circuit, so the
+     * delegation path is untouched.
+     */
+    onDelegationStatusMessage(raw) {
+        const frame = this.parseScreencastFrame(raw);
+        if (frame) {
+            this.routeScreencastFrame(frame);
+            return;
+        }
+        const audio = this.parseAudioChunk(raw);
+        if (audio) {
+            this.routeAudioChunk(audio);
+            return;
+        }
+        const progress = this.parseProgress(raw);
+        if (progress) {
+            this.dispatchProgress(progress);
+        }
+    }
+    /**
+     * Parses a push-status message and returns it only when it's a Remote Browser screencast frame for the
+     * active session — otherwise `null` (ignored, so delegation progress falls through). Matched by
+     * `resolver` + `type`, then scoped to THIS session by `agentSessionID`.
+     */
+    parseScreencastFrame(raw) {
+        let payload;
+        try {
+            payload = JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+        const matches = payload?.resolver === 'RemoteBrowserActionResolver' &&
+            payload?.type === 'RemoteBrowserScreencastFrame' &&
+            payload?.agentSessionID === this.agentSessionId &&
+            typeof payload?.dataBase64 === 'string';
+        return matches ? payload : null;
+    }
+    /**
+     * Forwards a screencast frame to the active Remote Browser channel plugin so it paints the frame on its
+     * surface canvas. The plugin is found among the session's active channels by its `ChannelName`; located
+     * via a structural guard so the service stays decoupled from the concrete channel class.
+     */
+    routeScreencastFrame(frame) {
+        for (const channel of this._activeChannels$.value) {
+            if (channel.ChannelName === 'Remote Browser' && this.hasOnScreencastFrame(channel)) {
+                // The URL rides along so the channel can notice a page change nobody on this side caused —
+                // under streaming the snapshot poll is stopped, and frames were pure pixels (#3496).
+                channel.OnScreencastFrame(frame.dataBase64, frame.currentUrl ?? null);
+                return;
+            }
+        }
+    }
+    /** Structural guard: true when the channel exposes an `OnScreencastFrame(dataBase64)` method. */
+    hasOnScreencastFrame(channel) {
+        return typeof channel.OnScreencastFrame === 'function';
+    }
+    /**
+     * Parses a push-status message and returns it only when it's a Remote Browser audio chunk for the active
+     * session — otherwise `null` (ignored). Matched by `resolver` + `type`, then scoped to THIS session by
+     * `agentSessionID`.
+     */
+    parseAudioChunk(raw) {
+        let payload;
+        try {
+            payload = JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+        const matches = payload?.resolver === 'RemoteBrowserActionResolver' &&
+            payload?.type === 'RemoteBrowserAudioChunk' &&
+            payload?.agentSessionID === this.agentSessionId &&
+            typeof payload?.dataBase64 === 'string';
+        return matches ? payload : null;
+    }
+    /**
+     * Forwards an audio chunk to the active Remote Browser channel plugin so it plays the chunk through its
+     * client-side audio player. The plugin is found among the session's active channels by its `ChannelName`;
+     * located via a structural guard so the service stays decoupled from the concrete channel class.
+     */
+    routeAudioChunk(chunk) {
+        for (const channel of this._activeChannels$.value) {
+            if (channel.ChannelName === 'Remote Browser' && this.hasOnAudioChunk(channel)) {
+                channel.OnAudioChunk({
+                    dataBase64: chunk.dataBase64,
+                    codec: chunk.codec,
+                    sampleRate: chunk.sampleRate,
+                    channels: chunk.channels,
+                    seq: chunk.seq,
+                });
+                return;
+            }
+        }
+    }
+    /** Structural guard: true when the channel exposes an `OnAudioChunk(chunk)` method. */
+    hasOnAudioChunk(channel) {
+        return typeof channel.OnAudioChunk === 'function';
+    }
+    /**
+     * Parses a push-status message and returns it only when it's a delegation
+     * progress event for the active voice session — otherwise `null` (ignored).
+     */
+    parseProgress(raw) {
+        let payload;
+        try {
+            payload = JSON.parse(raw);
+        }
+        catch {
+            return null; // non-JSON or unrelated frame
+        }
+        const matches = payload?.resolver === 'RealtimeClientSessionResolver' &&
+            payload?.type === 'RealtimeDelegationProgress' &&
+            payload?.agentSessionID === this.agentSessionId;
+        if (!matches) {
+            return null;
+        }
+        return {
+            CallID: payload.callID,
+            Step: payload.step,
+            Message: payload.message,
+            Percentage: payload.percentage
+        };
+    }
+    /** Emits the progress to the UI observable and feeds it to the realtime model. */
+    dispatchProgress(progress) {
+        // Drop stale progress: PubSub delivery can lag the mutation result, so events for a
+        // call that already completed (or was never seen) must not update cards or narrate.
+        if (!this.inFlightCallIds.has(progress.CallID)) {
+            return;
+        }
+        this._delegationProgress$.next(progress);
+        this.narrateProgress(progress);
+    }
+    /**
+     * Injects the progress into the model's context as a background note every time,
+     * then (throttled) asks the model to briefly voice a reassuring update so the
+     * background work doesn't sit in silence — without chattering or interrupting.
+     */
+    narrateProgress(progress) {
+        const client = this.client;
+        if (!client) {
+            return;
+        }
+        client.SendContextNote(`[delegated-agent progress] ${progress.Message}`);
+        // Floods of small updates AGGREGATE: each distinct message joins the digest buffer,
+        // and ONE spoken update fires per window (first at ~5s into the burst, then every
+        // ~8s). The buffer is discarded if the final result lands first.
+        this.bufferNarrationMessage(progress.Message);
+        if (this.pendingNarrationMessages.length > 0 && !this.narrationTimer) {
+            this.narrationTimer = setTimeout(() => this.fireDeferredNarration(), this.nextNarrationDelayMs());
+        }
+    }
+    /** Adds a progress message to the digest buffer (deduped, capped, oldest-first). */
+    bufferNarrationMessage(message) {
+        if (message === this.lastNarratedTail || this.pendingNarrationMessages.includes(message)) {
+            return;
+        }
+        this.pendingNarrationMessages.push(message);
+        if (this.pendingNarrationMessages.length > RealtimeSessionRuntime.MaxDigestMessages) {
+            this.pendingNarrationMessages.shift();
+        }
+    }
+    /**
+     * ms until the next spoken update is allowed. Two constraints, BOTH enforced:
+     * - first update of a burst: no earlier than ~5s after the burst started;
+     * - ~8s since the last spoken update, SESSION-global — so sequential tool calls
+     *   that reset the burst can never narrate faster than the interval.
+     */
+    nextNarrationDelayMs() {
+        const now = Date.now();
+        const firstAnchor = this.narrationCount === 0
+            ? this.delegationBurstStartedAt + RealtimeSessionRuntime.FirstNarrationDelayMs
+            : 0;
+        const spacingFloor = this.lastDelegationNarrationAt > 0
+            ? this.lastDelegationNarrationAt + RealtimeSessionRuntime.NarrationIntervalMs
+            : 0;
+        return Math.max(250, Math.max(firstAnchor, spacingFloor) - now);
+    }
+    /**
+     * Speaks the aggregated progress digest — unless the work already finished (buffer
+     * cancelled) or the model is busy / audio is still playing, in which case it retries
+     * shortly with the buffer intact (work is still running, so the update stays relevant).
+     */
+    fireDeferredNarration() {
+        this.narrationTimer = null;
+        const client = this.client;
+        if (this.pendingNarrationMessages.length === 0 || !client || this.inFlightCallIds.size === 0) {
+            this.pendingNarrationMessages = [];
+            return;
+        }
+        if (client.IsBusy || client.IsAudioPlaying) {
+            this.narrationTimer = setTimeout(() => this.fireDeferredNarration(), RealtimeSessionRuntime.NarrationBusyRetryMs);
+            return;
+        }
+        const digest = this.pendingNarrationMessages.join(' → ');
+        this.lastNarratedTail = this.pendingNarrationMessages[this.pendingNarrationMessages.length - 1];
+        this.pendingNarrationMessages = [];
+        this.narrationCount++;
+        this.lastDelegationNarrationAt = Date.now();
+        client.RequestSpokenUpdate(this.buildNarrationInstructions(digest));
+    }
+    /** Cancels any deferred narration — the result is about to be spoken, so it's moot. */
+    cancelPendingNarration() {
+        if (this.narrationTimer) {
+            clearTimeout(this.narrationTimer);
+            this.narrationTimer = null;
+        }
+        this.pendingNarrationMessages = [];
+    }
+    /**
+     * Builds the one-off instructions for a short spoken update that conveys THIS specific
+     * progress message naturally — strictly first person, since the co-agent owns the work.
+     * The wording is DB-driven: the server-resolved `Realtime Co-Agent - Progress Narration`
+     * template (substituting `{{ progressMessage }}`) when present, otherwise the built-in
+     * fallback so deployments that haven't synced the prompt behave exactly as before.
+     * The client tags the resulting turn as narration, keeping it EPHEMERAL — surfaced on
+     * {@link DelegationNarration$} instead of becoming a caption / persisted ConversationDetail.
+     */
+    buildNarrationInstructions(digest) {
+        return BuildNarrationInstructions(this.narrationTemplate, digest, {
+            PriorNarrations: this.spokenNarrations.slice(-RealtimeSessionRuntime.MaxPriorNarrations),
+            UpdateNumber: this.narrationCount
+        });
+    }
+    /** Tears down the delegation progress subscription and resets the narration throttle. */
+    teardownDelegationProgress() {
+        if (this.delegationProgressSub) {
+            this.delegationProgressSub.unsubscribe();
+            this.delegationProgressSub = null;
+        }
+        this.cancelPendingNarration();
+        this.inFlightCallIds.clear();
+        this.cancelledCallIds.clear();
+        this.lastDelegationNarrationAt = 0;
+        this.delegationBurstStartedAt = 0;
+        this.narrationCount = 0;
+        this.spokenNarrations = [];
+        this.lastNarratedTail = '';
+    }
+    // ── Teardown ───────────────────────────────────────────────────────────────
+    /**
+     * Tears down all client resources and (optionally) closes the server session.
+     * @param closeServerSession when true, calls `CloseAgentSession` on the server.
+     */
+    async teardown(closeServerSession) {
+        // Invalidate any start still in flight BEFORE anything else, so it abandons itself at its next
+        // await rather than opening a microphone behind a session that is being ended.
+        this.startGeneration++;
+        // Coalesce concurrent teardowns onto one run. Callers still get a promise that resolves when
+        // teardown is actually complete.
+        if (this.teardownInFlight) {
+            await this.teardownInFlight;
+            return;
+        }
+        this.teardownInFlight = this.runTeardown(closeServerSession).finally(() => {
+            this.teardownInFlight = null;
+        });
+        await this.teardownInFlight;
+    }
+    /** The body of {@link teardown}; never called concurrently with itself. */
+    async runTeardown(closeServerSession) {
+        // First: stop asserting liveness. A pulse racing the close would re-stamp LastActiveAt on a
+        // session we are deliberately ending, leaving an Idle row the janitor then has to age out.
+        this.stopLivenessPulse();
+        this.teardownDelegationProgress();
+        // Channels first: flush any unsaved channel state WHILE the live session id is still
+        // set (the captured per-save id covers the race anyway), then dispose the plugins.
+        this.flushAllChannelSaves();
+        this.disposeChannels();
+        // Defensive: stop the mic even when Connect never ran (the client also stops the
+        // tracks it was handed — track.stop() is idempotent).
+        this.localStream?.getTracks().forEach(t => t.stop());
+        this.localStream = null;
+        // Hand the platform back whatever acquiring the microphone changed. Stopping the tracks is not
+        // the same thing: iOS, for instance, is put into a record-and-play audio category for the call,
+        // and leaving it there changes the route and volume behaviour of every sound the app makes
+        // afterwards. Best-effort by contract — a failure here must never block ending a call.
+        try {
+            await this.mediaHost.ReleaseMicrophone?.();
+        }
+        catch (error) {
+            console.error('[RealtimeSession] Media host failed to release the microphone:', error);
+        }
+        if (this.client) {
+            await this.client.Disconnect();
+            this.client = null;
+        }
+        // Stop + upload the call recording WHILE the live session id is still set (the file is
+        // attached to it). Best-effort and never blocks teardown — stopAndUploadRecording swallows
+        // its own errors. No-op when nothing was recorded.
+        await this.stopAndUploadRecording(this.agentSessionId);
+        this.recordingStartedAtIso = null;
+        // Final usage flush WHILE the live session id is still set (the relay mutation also
+        // accepts a Closed session, so ordering vs. CloseAgentSession is belt-and-braces).
+        if (this.usageFlushTimer) {
+            clearTimeout(this.usageFlushTimer);
+            this.usageFlushTimer = null;
+        }
+        await this.flushPendingUsage(this.agentSessionId);
+        this.resetUsageRelay();
+        if (closeServerSession && this.agentSessionId) {
+            await this.closeServerSession(this.agentSessionId);
+        }
+        // Capture the session id BEFORE we null it so the lifecycle emit carries it.
+        // Skip emitting when there was no live session (defensive — teardown is safe
+        // to call without an active session).
+        const closedSessionId = this.agentSessionId;
+        this.agentSessionId = null;
+        this.narrationTemplate = null;
+        this.clientToolHandlers.clear();
+        this._modelName$.next(null);
+        this.SetMinimized(false);
+        this._active$.next(false);
+        if (this._connectionState$.value !== 'error') {
+            this._connectionState$.next('closed');
+        }
+        // Surface generic session-ended for the conversations runtime bridge.
+        // `closeServerSession=true` means the user explicitly called EndRealtimeSession;
+        // `false` means teardown ran from a catch block (start path error path).
+        if (closedSessionId) {
+            this._sessionEnded$.next({
+                sessionId: closedSessionId,
+                reason: closeServerSession ? 'explicit' : 'error',
+            });
+        }
+    }
+    /** Calls the `CloseAgentSession` mutation (provisioned in P4b). */
+    async closeServerSession(agentSessionId) {
+        try {
+            const mutation = `
+        mutation CloseAgentSession($agentSessionId: String!) {
+          CloseAgentSession(agentSessionId: $agentSessionId)
+        }
+      `;
+            await this.gql().ExecuteGQL(mutation, { agentSessionId });
+        }
+        catch (error) {
+            console.error('[RealtimeSession] Failed to close server session:', error);
+        }
+    }
+    // ── Helpers ────────────────────────────────────────────────────────────────
+    /** Pushes a caption onto the live list (immutable update for change detection). */
+    appendCaption(caption) {
+        this._captions$.next([...this._captions$.value, caption]);
+    }
+    /** Resets reactive + internal state at the start of a session. */
+    resetState() {
+        this._captions$.next([]);
+        this.pendingUserCaption = '';
+        this.hasActiveInterimUserCaption = false;
+        this.SetMinimized(false);
+        this.stopSegmentFlushing();
+        this.segmentIndex = 0;
+        this.recorder = null;
+        this.recordingStartedAtIso = null;
+        this.currentTurnStartMs = null;
+        this.turnAudioStartCaptured = false;
+        this.usedChannelNames.clear();
+    }
+    /** The GraphQL provider used for relay mutations. */
+    gql() {
+        return this.Provider;
+    }
+}
+//# sourceMappingURL=RealtimeSessionRuntime.js.map