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

package/dist/session/RealtimeSessionRuntime.d.ts

@@ -0,0 +1,1233 @@
+import { Observable } from 'rxjs';
+import { IMetadataProvider } from '@memberjunction/core';
+import { ClientRealtimeSessionConfig, RealtimeToolDefinition, RealtimeTrackDirection } from '@memberjunction/ai';
+import { AppContextSnapshot } from '@memberjunction/ai-core-plus';
+import { BaseRealtimeClient, RealtimeAudioActivity } from '@memberjunction/ai-realtime-client';
+import { ParsedDelegationArtifact } from './delegation-result-parser.js';
+import { BaseRealtimeChannelClient } from '../channels/base-realtime-channel-client.js';
+import { IRealtimeMediaHost } from '../hosts/IRealtimeMediaHost.js';
+/**
+ * `MJ: User Settings` key for the per-user "record this voice call" consent toggle. Stored as
+ * the literal string `'true'`/`'false'` (read with `=== 'true'`), cross-device via
+ * {@link UserInfoEngine}. The pre-call picker writes it; the session service reads it as the
+ * default when the caller doesn't pass an explicit consent value.
+ */
+export declare const REALTIME_RECORDING_CONSENT_KEY = "mj.realtimeVoice.recordingConsent.v1";
+/**
+ * Connection / turn state for a real-time voice session, surfaced to the UI overlay.
+ * - `connecting`  — negotiating the session + provider handshake
+ * - `listening`   — connected, mic open, waiting for / hearing the user
+ * - `speaking`    — the agent is producing audio
+ * - `thinking`    — the agent delegated work (tool call) and is waiting on a result
+ * - `error`       — a fatal error occurred; the session is no longer usable
+ * - `closed`      — the session has been torn down
+ */
+export type RealtimeConnectionState = 'connecting' | 'listening' | 'speaking' | 'thinking' | 'error' | 'closed';
+/** A single caption line (one side of the conversation) shown in the live-captions list. */
+export interface RealtimeCaption {
+    Role: 'User' | 'Assistant';
+    Text: string;
+}
+/**
+ * A delegated-run progress update surfaced to the UI, emitted on {@link RealtimeSessionRuntime.DelegationProgress$}.
+ * These originate server-side during an `invoke-target-agent` delegation (e.g. while Sage works) and let a
+ * future overlay render a "working" card while the realtime model narrates the same progress aloud.
+ */
+export interface RealtimeDelegationProgress {
+    /** The tool/agent call this progress belongs to. */
+    CallID: string;
+    /** The raw tool name when this progress represents a direct action (e.g. `File_Storage_List_Objects`). */
+    ToolName?: string;
+    /** The delegation phase: `prompt_execution` | `action_execution` | `subagent_execution` | `decision_processing` | `direct_action`. */
+    Step: string;
+    /** Human-readable progress message. */
+    Message: string;
+    /** Optional completion percentage (0–100) when the server can estimate it. */
+    Percentage?: number;
+}
+/**
+ * The terminal result of a delegated tool call, emitted on {@link RealtimeSessionRuntime.DelegationResult$}
+ * when the delegation finishes so the overlay can flip the "working" card into a result card with real
+ * content + provenance.
+ */
+export interface RealtimeDelegationResult {
+    /** The tool/agent call this result belongs to. */
+    CallID: string;
+    /** The raw tool name when this result represents a direct action. */
+    ToolName?: string;
+    /** Whether the delegated work succeeded. */
+    Success: boolean;
+    /** The result text — the agent's output, or an error message on failure. */
+    Output: string;
+    /**
+     * ID of the delegated agent run (`MJ: AI Agent Runs`) when the server reported one
+     * (`runId` in the tool ResultJson). Powers the overlay's gear-gated "Open run" dev link.
+     */
+    RunID?: string;
+    /**
+     * Artifacts the delegated run produced, when the server reported any (`artifacts` in the
+     * tool ResultJson). The overlay's tabbed surface panel auto-opens one artifact tab per
+     * entry and focuses the newest on arrival.
+     */
+    Artifacts?: ParsedDelegationArtifact[];
+}
+/**
+ * Handler for a CLIENT-EXECUTED UI tool (e.g. the live whiteboard's `Whiteboard_*` surface),
+ * registered via {@link RealtimeSessionRuntime.RegisterClientToolHandler}. Receives the tool name +
+ * raw arguments JSON from the realtime model and returns the result JSON string fed back as the
+ * `tool_response`. May be sync or async; thrown errors are wrapped into a
+ * `{ success: false, error }` payload by the service so the model can narrate the failure.
+ */
+export type RealtimeClientToolHandler = (toolName: string, argsJson: string) => string | Promise<string>;
+/**
+ * A channel's request to enter / leave the FOCUS layout, emitted on
+ * {@link RealtimeSessionRuntime.ChannelFocus$} when a plugin calls its context's
+ * `SetFocusMode`. The overlay shell subscribes: it collapses/restores the main call column
+ * and remembers which channel holds focus (so the floating pill's "exit" can be routed
+ * back via {@link BaseRealtimeChannelClient.RequestFocusExit}).
+ */
+export interface RealtimeChannelFocusEvent {
+    /** The channel plugin requesting the layout change. */
+    Channel: BaseRealtimeChannelClient;
+    /** `true` to enter focus mode (surface owns the screen), `false` to leave it. */
+    Focused: boolean;
+}
+/**
+ * One EPHEMERAL spoken narration of delegated-run progress, emitted on
+ * {@link RealtimeSessionRuntime.DelegationNarration$}. These are the interim "here's what's
+ * happening" utterances the realtime model speaks while a delegation runs. By product
+ * decision they are NOT captions and NOT persisted as ConversationDetails — they exist
+ * only as a live note in the overlay, replaced by each newer narration.
+ */
+export interface RealtimeDelegationNarration {
+    /** The narration transcript text. */
+    Text: string;
+}
+/**
+ * One thought/reasoning narration emitted on {@link RealtimeSessionRuntime.ThoughtNarration$}.
+ * Distinct from spoken progress narrations: thought summaries are authored by reasoning models
+ * (e.g. Gemini 3.8 Live Extended Thinking) and are NOT spoken aloud.
+ */
+export interface RealtimeThoughtNarration {
+    /** Correlating call ID if associated with a delegation/turn; otherwise generated or empty. */
+    CallID?: string;
+    /** The model's thought / reasoning text. */
+    Text: string;
+    /** Whether this emission represents the complete finalized thought turn. */
+    IsFinal?: boolean;
+}
+/**
+ * Result shape returned by the `StartRealtimeClientSession` server mutation.
+ * The browser uses these values to open a client-direct realtime session.
+ *
+ * Exported because a host may mint the session ITSELF (its own mutation, carrying
+ * server-side context the stock mutation cannot express) and then hand the result to
+ * {@link RealtimeSessionRuntime.StartRealtimeSessionFromResult} to run it — this is the
+ * contract that path is written against.
+ */
+export interface StartRealtimeClientSessionResult {
+    AgentSessionId: string;
+    ConversationId: string | null;
+    Provider: string;
+    Model: string;
+    EphemeralToken: string;
+    ExpiresAt: string;
+    /** JSON.stringify of the provider session config (instructions + tools) to apply at connect. */
+    SessionConfigJson: string;
+    /** Display name of the realtime model the session uses (e.g. "GPT Realtime 2"). Null when unknown. */
+    ModelName: string | null;
+    /**
+     * DB-driven progress-narration instruction template (contains a `{{ progressMessage }}`
+     * placeholder). Null when the deployment hasn't synced the narration prompt — the client
+     * falls back to its built-in wording.
+     */
+    NarrationInstructionsTemplate: string | null;
+    /**
+     * JSON map of the PRIOR session's saved channel states keyed by channel name (present only
+     * when the start carried `lastSessionId` and the prior session — owned by the same user —
+     * had saved states). Applied to the matching channel plugins via
+     * {@link BaseRealtimeChannelClient.RestoreState} so e.g. the whiteboard resumes where the
+     * last session left off.
+     */
+    PriorChannelStatesJson: string | null;
+}
+/**
+ * Host-supplied inputs that accompany an already-minted session on
+ * {@link RealtimeSessionRuntime.StartRealtimeSessionFromResult} — the values the RUN half needs
+ * that a {@link StartRealtimeClientSessionResult} cannot carry. Every field is optional and
+ * mirrors the same-named {@link RealtimeSessionRuntime.StartRealtimeSession} parameter, defaults
+ * included: omit one and the session behaves exactly as the all-in-one entry point does when that
+ * parameter is omitted.
+ */
+export interface RealtimeSessionRunOptions {
+    /**
+     * The conversation the host asked its OWN mint for, or null/omitted when it asked the server to
+     * create one. Only the ORIGINAL request tells the two apart: a null here plus a
+     * `ConversationId` on the result means the server created that conversation for this session,
+     * which the host is told about via {@link RealtimeSessionRuntime.SessionCreatedConversationId}.
+     */
+    readonly conversationId?: string | null;
+    /**
+     * Display name of the target agent, surfaced on {@link RealtimeSessionRuntime.AgentName$} so any
+     * host can render it without re-resolving. Omitted ⇒ the previous name stands.
+     */
+    readonly agentName?: string | null;
+    /**
+     * EXPLICIT "record this call" consent for THIS session. Omitted/`null` ⇒ the per-user persisted
+     * preference (`mj.realtimeVoice.recordingConsent.v1`) is read as the default; `false` never
+     * records. The host is responsible for reporting its own choice to its own mint.
+     */
+    readonly recordingConsent?: boolean | null;
+    /**
+     * The application the session runs in. Stored so the live ClientContextChannel can stream
+     * subsequent context deltas under it. Omitted ⇒ no app layer (the pre-app behavior).
+     */
+    readonly applicationId?: string | null;
+    /**
+     * Live app-context snapshot. Omitted/`null` ⇒ the snapshot the host has already pushed via
+     * {@link RealtimeSessionRuntime.UpdateAppContext} stands (never clobber a good value with null).
+     */
+    readonly appContext?: AppContextSnapshot | null;
+}
+/**
+ * Drives a **client-direct** real-time voice session: the browser mints an ephemeral
+ * token from the MJ server, then connects DIRECTLY to the realtime provider. Audio
+ * frames never transit the MJ server (low latency); only tool calls and final
+ * transcripts are relayed back to MJ over GraphQL.
+ *
+ * This service is PROVIDER-AGNOSTIC policy/orchestration. All provider wire concerns
+ * (transport, event translation, the response state machine, narration-kind tagging,
+ * playback tracking) live in a {@link BaseRealtimeClient} driver resolved through the
+ * MJ ClassFactory by the server-reported `Provider` key (e.g. `'openai'` →
+ * `OpenAIRealtimeClient`). Future providers (Gemini Live, …) snap in by registering a
+ * new driver — this service does not change.
+ *
+ * The Realtime Co-Agent (server-side) fronts the conversation's current agent — the server
+ * bakes the companion instructions + tool set into `SessionConfigJson`, which the client
+ * driver applies verbatim.
+ *
+ * Lifecycle: {@link StartRealtimeSession} → live duplex → {@link EndRealtimeSession}. A start is
+ * two halves — MINT (the `StartRealtimeClientSession` mutation) and RUN (everything above) — and a
+ * host that must mint through its own server surface enters at the second half via
+ * {@link StartRealtimeSessionFromResult}; there is one implementation of the run half either way.
+ */
+export declare class RealtimeSessionRuntime {
+    protected readonly mediaHost: IRealtimeMediaHost;
+    /**
+     * @param mediaHost the platform's media capabilities. The runtime never touches `navigator`,
+     *                  `Blob` or `FileReader` itself — microphone acquisition and audio recording
+     *                  are the host's, because both are platform-specific product decisions
+     *                  (permission UX, container format, where the bytes live).
+     */
+    constructor(mediaHost: IRealtimeMediaHost);
+    private _connectionState$;
+    private _captions$;
+    private _active$;
+    private _delegationProgress$;
+    private _delegationResult$;
+    private _delegationNarration$;
+    private _thoughtNarration$;
+    private _agentName$;
+    private _modelName$;
+    private _minimized$;
+    private _activeChannels$;
+    private _channelFocus$;
+    private _sessionStarted$;
+    private _sessionEnded$;
+    private _channelActivity$;
+    /** Current connection / turn state. */
+    readonly ConnectionState$: Observable<RealtimeConnectionState>;
+    /** Live captions for both sides of the conversation. */
+    readonly Captions$: Observable<RealtimeCaption[]>;
+    /** True while a session is open (mic button active, overlay shown). */
+    readonly Active$: Observable<boolean>;
+    /**
+     * 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.
+     */
+    readonly DelegationProgress$: Observable<RealtimeDelegationProgress>;
+    /** Terminal result of a delegation, so the overlay can complete the working card with real content. */
+    readonly DelegationResult$: Observable<RealtimeDelegationResult>;
+    /**
+     * 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.
+     */
+    readonly DelegationNarration$: Observable<RealtimeDelegationNarration>;
+    /**
+     * Model-authored thought / reasoning narrations (see {@link RealtimeThoughtNarration}). These are
+     * reasoning summaries author-emitted during extended thinking, separate from spoken progress updates.
+     */
+    readonly ThoughtNarration$: Observable<RealtimeThoughtNarration>;
+    /** Display name of the agent the active session fronts (set at session start). */
+    readonly AgentName$: Observable<string>;
+    /**
+     * 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.
+     */
+    readonly ModelName$: Observable<string | null>;
+    /**
+     * 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.
+     */
+    readonly Minimized$: Observable<boolean>;
+    /**
+     * The session's ACTIVE interactive-channel plugins, resolved from the `MJ: AI Agent
+     * Channels` registry at session start (one instance per session, per channel). Emits
+     * `[]` before a session starts and after teardown. The overlay subscribes to register
+     * one surface tab per plugin — it never knows any concrete channel type.
+     */
+    readonly ActiveChannels$: Observable<BaseRealtimeChannelClient[]>;
+    /**
+     * 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.
+     */
+    readonly ChannelFocus$: Observable<RealtimeChannelFocusEvent>;
+    /**
+     * 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.
+     */
+    readonly SessionStarted$: Observable<{
+        sessionId: string;
+        channelNames: string[];
+    }>;
+    /**
+     * 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.
+     */
+    readonly SessionEnded$: Observable<{
+        sessionId: string;
+        reason: 'explicit' | 'error';
+    }>;
+    /**
+     * 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).
+     */
+    readonly ChannelActivity$: Observable<BaseRealtimeChannelClient>;
+    /** Synchronous access to the session's active interactive-channel plugins. */
+    get ActiveChannels(): readonly BaseRealtimeChannelClient[];
+    /**
+     * 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(): ReadonlySet<string>;
+    /** Whether the agent has used (acted on) the named channel at least once this session. */
+    HasChannelBeenUsed(channelName: string): boolean;
+    /** Synchronous access to the display name of the agent the active session fronts. */
+    get CurrentAgentName(): string;
+    /**
+     * 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). */
+    private createdConversationId;
+    /** The session's conversation id (supplied or server-created). */
+    private sessionConversationId;
+    /** First final user utterance of the live session (the naming seed). */
+    private firstUserTranscript;
+    /** Buffer accumulating streaming user interim deltas into a single in-progress bubble. */
+    private pendingUserCaption;
+    /** Whether an in-place interim user caption is currently placed in `_captions$`. */
+    private hasActiveInterimUserCaption;
+    /**
+     * 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(): string | null;
+    /** The first final user utterance of the session (naming seed); null before the user speaks. */
+    get FirstUserTranscript(): string | null;
+    get CurrentAgentSessionId(): string | null;
+    /** Synchronous access to the minimized presentation state. */
+    get IsMinimized(): boolean;
+    /**
+     * Minimizes / restores the active call overlay (host renders the floating pill while
+     * minimized). Presentation-only — the live audio session is untouched.
+     */
+    SetMinimized(minimized: boolean): void;
+    /** The provider-direct realtime client driving the live session (ClassFactory-resolved). */
+    private client;
+    /** The mic capture stream — acquired here (permission UX) and handed to the client. */
+    private localStream;
+    private agentSessionId;
+    /**
+     * 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.
+     */
+    private applicationId;
+    /**
+     * 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`.
+     */
+    private readonly _appContext$;
+    /** Observable of the live app-context snapshot (see {@link _appContext$}). */
+    readonly AppContext$: Observable<AppContextSnapshot | null>;
+    /**
+     * 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: AppContextSnapshot | null): void;
+    /**
+     * 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.
+     */
+    private narrationTemplate;
+    /**
+     * The active session's audio recorder (mic + agent mix), or `null` when the user didn't
+     * consent or the browser can't record. Created after the client connects; stopped + uploaded
+     * at teardown.
+     */
+    private recorder;
+    /** ISO timestamp of when recording started — sent to the server on session start. */
+    private recordingStartedAtIso;
+    /** Interval that flushes ~15s crash-recovery shards to the server during a recording. */
+    private segmentTimer;
+    /** 0-based index of the next recording shard to upload. */
+    private segmentIndex;
+    /** How often crash-recovery shards are flushed during a recording. */
+    private static readonly segmentFlushMs;
+    /**
+     * Interval that 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.
+     */
+    private livenessTimer;
+    /**
+     * 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.
+     */
+    private static readonly livenessPulseMs;
+    /**
+     * 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}.
+     */
+    private currentTurnStartMs;
+    /**
+     * 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}.
+     */
+    private sessionClockStartMs;
+    /**
+     * 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.
+     */
+    private turnAudioStartCaptured;
+    /** First spoken update fires no earlier than this long after delegated work starts. */
+    private static readonly firstNarrationDelayMs;
+    /** Minimum gap between SUBSEQUENT spoken updates (the 7–10s band; floods aggregate). */
+    private static readonly narrationIntervalMs;
+    /** Retry delay when the fire moment finds the model busy / audio still playing. */
+    private static readonly narrationBusyRetryMs;
+    /** Max progress messages aggregated into one spoken digest. */
+    private static readonly maxDigestMessages;
+    /** Max prior spoken narrations chained into the instructions (anti-repetition). */
+    private static readonly maxPriorNarrations;
+    /**
+     * Aggregation buffer: distinct progress messages since the last spoken update (oldest
+     * first, capped at {@link RealtimeSessionRuntime.MaxDigestMessages}). A flood of small
+     * updates becomes ONE digest; the buffer is discarded when the result lands first.
+     */
+    private 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.
+     */
+    private inFlightCallIds;
+    /** Timer for the deferred narration; cancelled when the delegation result lands first. */
+    private narrationTimer;
+    /**
+     * 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.
+     */
+    private cancelledCallIds;
+    /** Debounce window for relaying accumulated usage deltas to the server. */
+    private static readonly usageFlushDebounceMs;
+    /** Accumulated input-token delta since the last flush. */
+    private pendingUsageInput;
+    /** Accumulated output-token delta since the last flush. */
+    private pendingUsageOutput;
+    /** Pending debounced usage flush; also force-flushed at teardown. */
+    private usageFlushTimer;
+    /** Active push-status subscription that feeds delegation progress; cleared on teardown. */
+    private delegationProgressSub;
+    /** Timestamp (ms) of the last narration we triggered; 0 = never. */
+    private lastDelegationNarrationAt;
+    /** When the current delegation burst began (first in-flight call); anchors the 5s first update. */
+    private delegationBurstStartedAt;
+    /** Spoken updates so far in this burst (1-based numbering for the instructions). */
+    private narrationCount;
+    /** What the model actually SAID for prior updates this burst — chained in so it never repeats itself. */
+    private spokenNarrations;
+    /** Tail message of the last digest, so an identical trailing progress event isn't re-buffered. */
+    private 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.
+     */
+    private clientToolHandlers;
+    /**
+     * Monotonic id for the current start attempt, bumped by every {@link teardown}.
+     *
+     * A session start is a multi-await sequence — mint, acquire the microphone, connect — and a host
+     * can end the session part-way through it (the user taps back while the mint is still in flight).
+     * Teardown at that moment has nothing to tear down: the stream and the client do not exist yet.
+     * Without this, the in-flight start then proceeds to open a microphone and a provider connection
+     * nobody is watching. Each start captures the generation it began under and abandons itself the
+     * moment it no longer matches.
+     */
+    private startGeneration;
+    /**
+     * The teardown currently running, so a second call awaits it rather than racing it.
+     *
+     * Ending a session commonly fires twice — an explicit stop followed by the host unmounting — and
+     * `teardown` flips `_active$` only at the end, so the second call passes the `IsActive` guard and
+     * runs concurrently with the first: two `Disconnect()` calls, two `CloseAgentSession` mutations,
+     * two `SessionEnded$` emissions for one session.
+     */
+    private teardownInFlight;
+    /**
+     * Why the last session start failed, or `null` when none has.
+     *
+     * The runtime reports failure as `'error'` on {@link ConnectionState$}, which is enough to show
+     * *that* something went wrong but not *what* — and the difference matters at exactly one point:
+     * microphone permission. A host that cannot tell "you denied the mic" from "the provider is
+     * down" has to show the same unhelpful copy for both. `AcquireMicrophone` rejects inside the
+     * runtime's own try/catch, so the host never sees that rejection itself.
+     */
+    private lastStartError;
+    /** Debounce window for persisting a channel's state of record after a change burst. */
+    private static readonly channelSaveDebounceMs;
+    /**
+     * 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.
+     */
+    private pendingChannelSaves;
+    /**
+     * `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}.
+     */
+    private usedChannelNames;
+    private _provider;
+    /**
+     * Metadata provider used for the GraphQL relay mutations. Falls back to the
+     * global default when unset (single-provider apps see no change).
+     */
+    get Provider(): IMetadataProvider;
+    set Provider(value: IMetadataProvider | null);
+    /** True when a session is currently open. */
+    get IsActive(): boolean;
+    /**
+     * 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.
+     */
+    StartRealtimeSession(targetAgentId: string, conversationId?: string | null, lastSessionId?: string | null, agentName?: string | null, preferredModelId?: string | null, clientTools?: RealtimeToolDefinition[] | null, coAgentId?: string | null, configOverridesJson?: string | null, recordingConsent?: boolean | null, mediaCollectionId?: string | null, applicationId?: string | null, appContext?: AppContextSnapshot | null): Promise<void>;
+    /**
+     * Declares which provider keys this host can actually carry audio for.
+     *
+     * The server resolves a realtime model by rank across every configured vendor, so it can
+     * legitimately return a provider whose client driver this host cannot run. A browser can run all
+     * of them; React Native can run the WebRTC ones but not those needing a Web Audio PCM plane.
+     * Connecting anyway gets as far as constructing the driver's playback engine and then throws —
+     * a crash, where the honest answer is "this workspace's voice provider is not one this app can
+     * use".
+     *
+     * The default accepts everything, so existing hosts are unaffected. Override to narrow it.
+     *
+     * @param provider The `Provider` key the server stamped on the minted session.
+     */
+    protected hostCanUseProvider(_provider: string): boolean;
+    /**
+     * Closes a session that was minted but will never be connected, and reports why.
+     *
+     * Minting creates a durable `MJ: AI Agent Sessions` row server-side, so declining to connect
+     * still has to close it — otherwise every rejected attempt leaks an `Active` session for the
+     * janitor to reconcile fifteen minutes later.
+     */
+    private abortUnusableSession;
+    /**
+     * 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.
+     */
+    StartRealtimeSessionFromResult(result: StartRealtimeClientSessionResult, options?: RealtimeSessionRunOptions): Promise<void>;
+    /**
+     * Start prologue shared by both entry points: bind the app layer, publish the agent name, reset
+     * per-session state, and flip the session live (which is ALSO what makes the `IsActive` guard
+     * suppress duplicate starts while the mint is still in flight — hence it runs before minting, not
+     * after). Returns the resolved recording consent, which the mint half reports to the server and
+     * the run half uses to decide whether to record.
+     */
+    private beginSessionStart;
+    /**
+     * The RUN half of a session start, shared by both entry points: consume the minted result, open
+     * the provider connection, and go live. `inputConversationId` is the conversation the START asked
+     * for (null ⇒ "server, make me one") — the result alone can't distinguish the two.
+     */
+    private runMintedSession;
+    /**
+     * Releases everything a start acquired after the host had already ended the session.
+     *
+     * Reached only when {@link teardown} ran while this start was awaiting the microphone or the
+     * provider connection. Teardown found nothing to release because nothing existed yet, so this
+     * start owns the cleanup: stop the microphone, close the provider connection, and close the
+     * server-side session row that the mint created.
+     */
+    private unwindAbandonedStart;
+    /**
+     * Why the last session start failed, or `null` when the last start succeeded or none has run.
+     *
+     * Read it when {@link ConnectionState$} reports `'error'`, to tell a denied microphone apart from
+     * a provider or backend failure and show copy the user can act on. Cleared at the start of every
+     * session.
+     */
+    get LastStartError(): Error | null;
+    /**
+     * The single failure path for a session start (mint half or run half): report it, latch the
+     * overlay into 'error', and unwind whatever the half-built session already opened.
+     */
+    private failSessionStart;
+    /**
+     * 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.
+     */
+    EndRealtimeSession(): Promise<void>;
+    /**
+     * 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: string): void;
+    /** Mute / unmute the local microphone track. Returns the new muted state. */
+    ToggleMute(): boolean;
+    /**
+     * 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: string, handler: RealtimeClientToolHandler): void;
+    /** Removes the handler registered for `toolNamePrefix` (no-op when none is registered). */
+    UnregisterClientToolHandler(toolNamePrefix: string): void;
+    /**
+     * 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: string): void;
+    /**
+     * 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: string): boolean;
+    /**
+     * 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(): RealtimeAudioActivity | null;
+    /**
+     * The active {@link BaseRealtimeClient} driving the media plane, or null when not connected.
+     */
+    get Client(): BaseRealtimeClient | null;
+    /**
+     * Relays a video frame to the underlying realtime client if active.
+     */
+    SendVideoFrame(base64Image: string, mimeType?: string): void;
+    /**
+     * Checks whether a media track is established on the active realtime client.
+     */
+    IsTrackEstablished(modality: string, direction: RealtimeTrackDirection): boolean;
+    /**
+     * 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.
+     */
+    private readPersistedRecordingConsent;
+    /**
+     * 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).
+     */
+    private startRecording;
+    /** Begins flushing ~15s crash-recovery shards to the server for the duration of the recording. */
+    private startSegmentFlushing;
+    /** Stops the periodic crash-recovery shard flush. */
+    private stopSegmentFlushing;
+    /**
+     * 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.
+     */
+    private startLivenessPulse;
+    /** Stops the liveness pulse. Idempotent — safe on a session that never started one. */
+    private stopLivenessPulse;
+    /**
+     * 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.
+     */
+    private pulseLiveness;
+    /**
+     * Uploads the chunks captured since the last flush as one crash-recovery shard (durability only;
+     * the canonical file is still the full upload at teardown). Best-effort — never disturbs the call.
+     */
+    private flushRecordingSegment;
+    /**
+     * Stops the active recorder and uploads the captured audio via `UploadRealtimeRecording`.
+     * Fully best-effort and wrapped in try/catch — recording upload must NEVER block teardown.
+     * No-op when nothing was recorded or there's no session id to attach the file to.
+     */
+    private stopAndUploadRecording;
+    /**
+     * 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.
+     */
+    private uploadRecording;
+    /**
+     * 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.
+     */
+    private startChannels;
+    /**
+     * Loads the ACTIVE channel definitions from the registry and resolves each row's
+     * `ClientPluginClass` through the MJ ClassFactory into a per-session plugin instance —
+     * the client-side mirror of how realtime-model drivers resolve from `BaseRealtimeModel`
+     * / `BaseRealtimeClient`. Rows whose plugin class isn't registered are skipped (logged),
+     * never fatal.
+     */
+    private loadActiveChannels;
+    /**
+     * 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.
+     */
+    private fetchChannelDefinitions;
+    /**
+     * 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.
+     */
+    private resolveChannelPlugin;
+    /**
+     * Wires one plugin into the session: hands it its host context and registers its
+     * prefix-routed local tool executor (so `<ToolNamePrefix>*` calls run in the browser
+     * through {@link BaseRealtimeChannelClient.ApplyAgentTool}, never the server relay).
+     */
+    private initializeChannel;
+    /** Builds the host-services context one channel plugin sees (its only line to the session). */
+    private buildChannelContext;
+    /**
+     * Host registry of surface CLIENT TOOLS (Name → handler), fed by the host (Explorer) from the
+     * active surface's `SetAgentClientTools`. The headless ClientContextChannel's `ContextTool` proxy
+     * executes against this via {@link executeAppClientTool}. Keys are lower-cased for case-insensitive
+     * model-supplied action names.
+     */
+    private readonly appClientToolHandlers;
+    /**
+     * 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: ReadonlyArray<{
+        Name: string;
+        Handler: (params: Record<string, unknown>) => Promise<unknown> | unknown;
+    }>): void;
+    /**
+     * 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.
+     */
+    private executeAppClientTool;
+    /**
+     * 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`.
+     */
+    private executeChannelServerAction;
+    /**
+     * 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.
+     */
+    private requestChannelSpokenResponse;
+    /**
+     * 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.
+     */
+    private applyPriorChannelStates;
+    /**
+     * 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.
+     */
+    private saveChannelArtifact;
+    /** Most recent session id captured by the save pipeline (post-teardown saves). */
+    private lastKnownSessionIdForSaves;
+    /**
+     * 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.
+     */
+    private scheduleChannelSave;
+    /** Fires one pending channel save (best-effort; {@link SaveChannelState} logs failures). */
+    private flushChannelSave;
+    /** Final teardown flush: persist every channel's unsaved state immediately. */
+    private flushAllChannelSaves;
+    /** Disposes all channel plugins (errors contained per plugin) and clears the live set. */
+    private disposeChannels;
+    /**
+     * 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).
+     */
+    private createRealtimeClient;
+    /**
+     * 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: StartRealtimeClientSessionResult): ClientRealtimeSessionConfig;
+    /** @deprecated Use {@link BuildClientConfig}. */
+    buildClientConfig(session: StartRealtimeClientSessionResult): ClientRealtimeSessionConfig;
+    /**
+     * 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).
+     */
+    private parseSessionConfig;
+    /** Subscribes this service's policy handlers to the realtime client's events. */
+    private wireClientHandlers;
+    /** Maps a client state event onto the UI connection state. */
+    private onClientStateChange;
+    /**
+     * 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.
+     */
+    private mapClientState;
+    /** True when the live control channel is usable (open and not torn down / failed). */
+    private isSessionLive;
+    /**
+     * 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.
+     */
+    private onClientTranscript;
+    /**
+     * 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.
+     */
+    private markTurnAudioStart;
+    /**
+     * 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.
+     */
+    private nowTurnOffsetMs;
+    /**
+     * 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).
+     */
+    private replaceLastCaption;
+    /** Finalizes the user turn: push a caption + relay the final transcript. */
+    private onUserTranscript;
+    /**
+     * 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.
+     */
+    private handleToolCall;
+    /** Finds the registered client-tool handler whose prefix matches `toolName`, or `null`. */
+    private findClientToolHandler;
+    /**
+     * 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.
+     */
+    private executeClientTool;
+    /**
+     * 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.
+     */
+    private emitDelegationResult;
+    /**
+     * 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).
+     */
+    CancelDelegation(callId: string): Promise<boolean>;
+    /**
+     * 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).
+     */
+    CancelInFlightDelegations(): Promise<number>;
+    /** Flips a cancelled call's card to the failed "Cancelled by user" result and suppresses the late real result. */
+    private surfaceUserCancellation;
+    /**
+     * 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).
+     */
+    private cancelSessionTool;
+    /** Calls the `StartRealtimeClientSession` mutation to obtain an ephemeral token + config. */
+    private mintSession;
+    /** Calls the `ExecuteRealtimeSessionTool` mutation; returns the ResultJson string. */
+    private executeSessionTool;
+    /**
+     * 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.
+     */
+    SaveChannelState(channelName: string, stateJson: string, agentSessionId?: string | null): Promise<boolean>;
+    /**
+     * 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`).
+     */
+    private relayTranscript;
+    /**
+     * 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.
+     */
+    private relayToolTurn;
+    /**
+     * 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.
+     */
+    private onUsageDelta;
+    /** Clamps a driver-reported token delta: undefined / negative / non-finite become 0. */
+    private clampUsageDelta;
+    /**
+     * 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).
+     */
+    private flushPendingUsage;
+    /** Cancels the pending debounced usage flush and zeroes the accumulators (teardown tail). */
+    private resetUsageRelay;
+    /**
+     * 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.
+     */
+    private subscribeDelegationProgress;
+    /**
+     * 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.
+     */
+    private onDelegationStatusMessage;
+    /**
+     * 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`.
+     */
+    private parseScreencastFrame;
+    /**
+     * 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.
+     */
+    private routeScreencastFrame;
+    /** Structural guard: true when the channel exposes an `OnScreencastFrame(dataBase64)` method. */
+    private hasOnScreencastFrame;
+    /**
+     * 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`.
+     */
+    private parseAudioChunk;
+    /**
+     * 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.
+     */
+    private routeAudioChunk;
+    /** Structural guard: true when the channel exposes an `OnAudioChunk(chunk)` method. */
+    private hasOnAudioChunk;
+    /**
+     * Parses a push-status message and returns it only when it's a delegation
+     * progress event for the active voice session — otherwise `null` (ignored).
+     */
+    private parseProgress;
+    /** Emits the progress to the UI observable and feeds it to the realtime model. */
+    private dispatchProgress;
+    /**
+     * 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.
+     */
+    private narrateProgress;
+    /** Adds a progress message to the digest buffer (deduped, capped, oldest-first). */
+    private bufferNarrationMessage;
+    /**
+     * 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.
+     */
+    private nextNarrationDelayMs;
+    /**
+     * 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).
+     */
+    private fireDeferredNarration;
+    /** Cancels any deferred narration — the result is about to be spoken, so it's moot. */
+    private cancelPendingNarration;
+    /**
+     * 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.
+     */
+    private buildNarrationInstructions;
+    /** Tears down the delegation progress subscription and resets the narration throttle. */
+    private teardownDelegationProgress;
+    /**
+     * Tears down all client resources and (optionally) closes the server session.
+     * @param closeServerSession when true, calls `CloseAgentSession` on the server.
+     */
+    private teardown;
+    /** The body of {@link teardown}; never called concurrently with itself. */
+    private runTeardown;
+    /** Calls the `CloseAgentSession` mutation (provisioned in P4b). */
+    private closeServerSession;
+    /** Pushes a caption onto the live list (immutable update for change detection). */
+    private appendCaption;
+    /** Resets reactive + internal state at the start of a session. */
+    private resetState;
+    /** The GraphQL provider used for relay mutations. */
+    private gql;
+}
+//# sourceMappingURL=RealtimeSessionRuntime.d.ts.map