@memberjunction/ng-conversations 6.1.3 → 6.2.0-edge.0

package/dist/lib/services/realtime-session.service.js

@@ -1,2444 +1,42 @@
 import { Injectable } from '@angular/core';
-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-template';
-import { ParseDelegationResultJson, FormatToolName } from './delegation-result-parser';
-import { BaseRealtimeChannelClient } from '../components/realtime/channels/base-realtime-channel-client';
-import { RealtimeAudioRecorder } from './realtime-audio-recorder';
+import { RealtimeSessionRuntime } from '@memberjunction/realtime-runtime';
+import { LoadAssemblyAIRealtimeClient, LoadElevenLabsRealtimeClient, LoadGeminiRealtimeClient, LoadHuggingFaceRealtimeClient, LoadOpenAILiveClient, LoadOpenAIRealtimeClient, LoadxAIRealtimeClient, } from '@memberjunction/ai-realtime-client';
+import { BrowserRealtimeMediaHost } from './browser-realtime-media-host';
 import * as i0 from "@angular/core";
-/**
- * `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).
+// Tree-shaking prevention: client drivers are resolved dynamically through the ClassFactory (by
+// the server-reported Provider key), so these static calls are what keep their @RegisterClass side
+// effects 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.
 LoadOpenAIRealtimeClient();
+LoadOpenAILiveClient();
 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.
+ * Angular host for MemberJunction's realtime co-agent sessions.
  *
- * 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.
+ * All orchestration — mint, driver resolution, transcripts, tool relay, delegation narration,
+ * channel lifecycle, usage relay, teardown — lives in
+ * {@link RealtimeSessionRuntime} (`@memberjunction/realtime-runtime`), which is framework-agnostic
+ * and shared with every other host, including the React Native app. This class supplies the two
+ * things that are genuinely Angular/browser: the `@Injectable` shell that lets components inject
+ * it, and the browser's media host.
  *
- * 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.
+ * Consumers are unaffected by that split — the injectable token, class name, and public surface
+ * are unchanged. Types that used to be declared in this file (`RealtimeCaption`,
+ * `RealtimeConnectionState`, `RealtimeSessionRunOptions`, …) now come from
+ * `@memberjunction/realtime-runtime`; import them from there directly, since MJ does not
+ * re-export across package boundaries.
  */
-export class RealtimeSessionService {
-    // ── Reactive UI state ──────────────────────────────────────────────────────
-    _connectionState$ = new BehaviorSubject('closed');
-    _captions$ = new BehaviorSubject([]);
-    _active$ = new BehaviorSubject(false);
-    _delegationProgress$ = new Subject();
-    _delegationResult$ = new Subject();
-    _delegationNarration$ = new Subject();
-    _thoughtNarration$ = new Subject();
-    _agentName$ = new BehaviorSubject('Sage');
-    _modelName$ = new BehaviorSubject(null);
-    _minimized$ = new BehaviorSubject(false);
-    _activeChannels$ = new BehaviorSubject([]);
-    _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. ───
-    _sessionStarted$ = new Subject();
-    _sessionEnded$ = new Subject();
-    _channelActivity$ = new Subject();
-    /** Current connection / turn state. */
-    ConnectionState$ = this._connectionState$.asObservable();
-    /** Live captions for both sides of the conversation. */
-    Captions$ = this._captions$.asObservable();
-    /** True while a session is open (mic button active, overlay shown). */
-    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.
-     */
-    DelegationProgress$ = this._delegationProgress$.asObservable();
-    /** Terminal result of a delegation, so the overlay can complete the working card with real content. */
-    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.
-     */
-    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.
-     */
-    ThoughtNarration$ = this._thoughtNarration$.asObservable();
-    /** Display name of the agent the active session fronts (set at session start). */
-    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.
-     */
-    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.
-     */
-    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.
-     */
-    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.
-     */
-    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.
-     */
-    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.
-     */
-    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).
-     */
-    ChannelActivity$ = this._channelActivity$.asObservable();
-    /** 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;
-    }
-    /**
-     * 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). */
-    createdConversationId = null;
-    /** The session's conversation id (supplied or server-created). */
-    sessionConversationId = null;
-    /** First final user utterance of the live session (the naming seed). */
-    firstUserTranscript = null;
-    /** Buffer accumulating streaming user interim deltas into a single in-progress bubble. */
-    pendingUserCaption = '';
-    /** Whether an in-place interim user caption is currently placed in `_captions$`. */
-    hasActiveInterimUserCaption = false;
-    /**
-     * 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);
-        }
-    }
-    // ── Session internals ──────────────────────────────────────────────────────
-    /** The provider-direct realtime client driving the live session (ClassFactory-resolved). */
-    client = null;
-    /** The mic capture stream — acquired here (permission UX) and handed to the client. */
-    localStream = null;
-    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.
-     */
-    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`.
-     */
-    _appContext$ = new BehaviorSubject(null);
-    /** Observable of the live app-context snapshot (see {@link _appContext$}). */
-    AppContext$ = this._appContext$.asObservable();
-    /**
-     * 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);
-    }
-    /**
-     * 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.
-     */
-    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.
-     */
-    recorder = null;
-    /** ISO timestamp of when recording started — sent to the server on session start. */
-    recordingStartedAtIso = null;
-    /** Interval that flushes ~15s crash-recovery shards to the server during a recording. */
-    segmentTimer = null;
-    /** 0-based index of the next recording shard to upload. */
-    segmentIndex = 0;
-    /** How often crash-recovery shards are flushed during a recording. */
-    static SegmentFlushMs = 15000;
-    // ── 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.
-     */
-    livenessTimer = null;
-    /**
-     * 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 LivenessPulseMs = 60000;
-    /**
-     * 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}.
-     */
-    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}.
-     */
-    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.
-     */
-    turnAudioStartCaptured = false;
-    // ── Delegated-run progress streaming ───────────────────────────────────────
-    /** First spoken update fires no earlier than this long after delegated work starts. */
-    static FirstNarrationDelayMs = 5000;
-    /** Minimum gap between SUBSEQUENT spoken updates (the 7–10s band; floods aggregate). */
-    static NarrationIntervalMs = 8000;
-    /** Retry delay when the fire moment finds the model busy / audio still playing. */
-    static NarrationBusyRetryMs = 1500;
-    /** Max progress messages aggregated into one spoken digest. */
-    static MaxDigestMessages = 4;
-    /** Max prior spoken narrations chained into the instructions (anti-repetition). */
-    static MaxPriorNarrations = 3;
-    /**
-     * Aggregation buffer: distinct progress messages since the last spoken update (oldest
-     * first, capped at {@link RealtimeSessionService.MaxDigestMessages}). A flood of small
-     * updates becomes ONE digest; the buffer is discarded when the result lands first.
-     */
-    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.
-     */
-    inFlightCallIds = new Set();
-    /** Timer for the deferred narration; cancelled when the delegation result lands first. */
-    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.
-     */
-    cancelledCallIds = new Set();
-    // ── Usage telemetry relay (B7) ─────────────────────────────────────────────
-    /** Debounce window for relaying accumulated usage deltas to the server. */
-    static UsageFlushDebounceMs = 10000;
-    /** Accumulated input-token delta since the last flush. */
-    pendingUsageInput = 0;
-    /** Accumulated output-token delta since the last flush. */
-    pendingUsageOutput = 0;
-    /** Pending debounced usage flush; also force-flushed at teardown. */
-    usageFlushTimer = null;
-    /** Active push-status subscription that feeds delegation progress; cleared on teardown. */
-    delegationProgressSub = null;
-    /** Timestamp (ms) of the last narration we triggered; 0 = never. */
-    lastDelegationNarrationAt = 0;
-    /** When the current delegation burst began (first in-flight call); anchors the 5s first update. */
-    delegationBurstStartedAt = 0;
-    /** Spoken updates so far in this burst (1-based numbering for the instructions). */
-    narrationCount = 0;
-    /** What the model actually SAID for prior updates this burst — chained in so it never repeats itself. */
-    spokenNarrations = [];
-    /** Tail message of the last digest, so an identical trailing progress event isn't re-buffered. */
-    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.
-     */
-    clientToolHandlers = new Map();
-    // ── Interactive channels (registry-resolved plugins) ───────────────────────
-    /** Debounce window for persisting a channel's state of record after a change burst. */
-    static ChannelSaveDebounceMs = 3000;
-    /**
-     * 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.
-     */
-    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}.
-     */
-    usedChannelNames = new Set();
-    _provider = null;
-    /**
-     * 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;
-        }
-        await this.runMintedSession(session, conversationId ?? null, consent);
-    }
-    /**
-     * 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 ?? {};
-        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) {
-        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);
-            this.localStream = await navigator.mediaDevices.getUserMedia({ audio: true });
-            await client.Connect(this.buildClientConfig(session), this.localStream);
-            // 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);
-        }
-    }
-    /**
-     * 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._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 = new RealtimeAudioRecorder();
-            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(); }, RealtimeSessionService.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(); }, RealtimeSessionService.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;
-        }
-        const segment = recorder.SnapshotNewSegment();
-        if (!segment || segment.size === 0) {
-            return;
-        }
-        try {
-            const audioBase64 = await this.blobToBase64(segment);
-            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 blob = await recorder.Stop();
-            // Read the real waveform peaks computed during capture (survives Stop via the recorder's snapshot).
-            const peaks = recorder.GetPeaks();
-            if (!blob || blob.size === 0 || !agentSessionId) {
-                console.warn('[RealtimeSession] ⚠️ recording NOT uploaded — empty blob or no session id.');
-                return;
-            }
-            const audioBase64 = await this.blobToBase64(blob);
-            if (!audioBase64) {
-                console.warn('[RealtimeSession] ⚠️ recording NOT uploaded — base64 encoding failed.');
-                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)})`);
-        }
-    }
-    /**
-     * Encodes a {@link Blob} as a base64 string (the data: prefix stripped) via {@link FileReader}.
-     * Resolves `''` on any read failure so the upload path can bail cleanly.
-     */
-    blobToBase64(blob) {
-        return new Promise((resolve) => {
-            const reader = new FileReader();
-            reader.onloadend = () => {
-                const result = typeof reader.result === 'string' ? reader.result : '';
-                const commaIndex = result.indexOf(',');
-                resolve(commaIndex >= 0 ? result.slice(commaIndex + 1) : '');
-            };
-            reader.onerror = () => resolve('');
-            reader.readAsDataURL(blob);
-        });
-    }
-    // ── 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),
-        };
-    }
-    /**
-     * 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.
-     */
-    appClientToolHandlers = new Map();
-    /**
-     * 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), RealtimeSessionService.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 > RealtimeSessionService.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();
-            }, RealtimeSessionService.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 > RealtimeSessionService.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 + RealtimeSessionService.FirstNarrationDelayMs
-            : 0;
-        const spacingFloor = this.lastDelegationNarrationAt > 0
-            ? this.lastDelegationNarrationAt + RealtimeSessionService.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(), RealtimeSessionService.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(-RealtimeSessionService.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) {
-        // 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;
-        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;
+export class RealtimeSessionService extends RealtimeSessionRuntime {
+    constructor() {
+        super(new BrowserRealtimeMediaHost());
     }
     static ɵfac = function RealtimeSessionService_Factory(__ngFactoryType__) { return new (__ngFactoryType__ || RealtimeSessionService)(); };
     static ɵprov = /*@__PURE__*/ i0.ɵɵdefineInjectable({ token: RealtimeSessionService, factory: RealtimeSessionService.ɵfac, providedIn: 'root' });
@@ -2446,5 +44,5 @@ export class RealtimeSessionService {
 (() => { (typeof ngDevMode === "undefined" || ngDevMode) && i0.ɵsetClassMetadata(RealtimeSessionService, [{
         type: Injectable,
         args: [{ providedIn: 'root' }]
-    }], null, null); })();
+    }], () => [], null); })();
 //# sourceMappingURL=realtime-session.service.js.map