@memberjunction/ng-conversations 5.40.1 → 5.41.0

package/dist/lib/services/realtime-session.service.d.ts

@@ -0,0 +1,739 @@
+import { Observable } from 'rxjs';
+import { IMetadataProvider } from '@memberjunction/core';
+import { RealtimeToolDefinition } from '@memberjunction/ai';
+import { RealtimeAudioActivity } from '@memberjunction/ai-realtime-client';
+import { ParsedDelegationArtifact } from './delegation-result-parser';
+import { BaseRealtimeChannelClient } from '../components/realtime/channels/base-realtime-channel-client';
+import * as i0 from "@angular/core";
+/**
+ * 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 VoiceConnectionState = 'connecting' | 'listening' | 'speaking' | 'thinking' | 'error' | 'closed';
+/** A single caption line (one side of the conversation) shown in the live-captions list. */
+export interface VoiceCaption {
+    Role: 'User' | 'Assistant';
+    Text: string;
+}
+/**
+ * A delegated-run progress update surfaced to the UI, emitted on {@link RealtimeSessionService.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 VoiceDelegationProgress {
+    /** The `invoke-target-agent` call this progress belongs to. */
+    CallID: string;
+    /** The delegation phase: `prompt_execution` | `action_execution` | `subagent_execution` | `decision_processing`. */
+    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 RealtimeSessionService.DelegationResult$}
+ * when the delegation finishes so the overlay can flip the "working" card into a result card with real
+ * content + provenance.
+ */
+export interface VoiceDelegationResult {
+    /** The `invoke-target-agent` call this result belongs to. */
+    CallID: 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 RealtimeSessionService.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 RealtimeSessionService.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 RealtimeSessionService.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 VoiceDelegationNarration {
+    /** The narration transcript text. */
+    Text: string;
+}
+/**
+ * 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 StartVoiceSession} → live duplex → {@link EndVoiceSession}.
+ */
+export declare class RealtimeSessionService {
+    private _connectionState$;
+    private _captions$;
+    private _active$;
+    private _delegationProgress$;
+    private _delegationResult$;
+    private _delegationNarration$;
+    private _agentName$;
+    private _modelName$;
+    private _minimized$;
+    private _activeChannels$;
+    private _channelFocus$;
+    private _sessionStarted$;
+    private _sessionEnded$;
+    private _channelActivity$;
+    /** Current connection / turn state. */
+    readonly ConnectionState$: Observable<VoiceConnectionState>;
+    /** Live captions for both sides of the conversation. */
+    readonly Captions$: Observable<VoiceCaption[]>;
+    /** 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<VoiceDelegationProgress>;
+    /** Terminal result of a delegation, so the overlay can complete the working card with real content. */
+    readonly DelegationResult$: Observable<VoiceDelegationResult>;
+    /**
+     * EPHEMERAL spoken progress narrations (see {@link VoiceDelegationNarration}). 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<VoiceDelegationNarration>;
+    /** 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 `EndVoiceSession`, `'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[];
+    /** 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;
+    /**
+     * 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 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;
+    /** 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 RealtimeSessionService.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;
+    /** 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;
+    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).
+     */
+    StartVoiceSession(targetAgentId: string, conversationId?: string | null, lastSessionId?: string | null, agentName?: string | null, preferredModelId?: string | null, clientTools?: RealtimeToolDefinition[] | null, coAgentId?: string | null, configOverridesJson?: string | null): Promise<void>;
+    /**
+     * 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.
+     */
+    EndVoiceSession(): 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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. */
+    private buildClientConfig;
+    /**
+     * 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 VoiceConnectionState}. `'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 are ignored
+     * (the client already drives the speaking state). 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;
+    /**
+     * 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. Only delegation
+     * cards (created from progress events) react — non-delegation tool results have no card and are
+     * harmlessly ignored downstream. The `runId` (the delegated `MJ: AI Agent Runs` record) rides
+     * along as {@link VoiceDelegationResult.RunID} for the overlay's dev links, and any `artifacts`
+     * ride along as {@link VoiceDelegationResult.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`.
+     * @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;
+    /** 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;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RealtimeSessionService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<RealtimeSessionService>;
+}
+//# sourceMappingURL=realtime-session.service.d.ts.map