@memberjunction/ng-conversations 5.43.0 → 5.45.0

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

@@ -1,13 +1,22 @@
 import { Injectable } from '@angular/core';
 import { BehaviorSubject, Subject } from 'rxjs';
 import { Metadata } from '@memberjunction/core';
+import { UserInfoEngine } from '@memberjunction/core-entities';
 import { AIEngineBase } from '@memberjunction/ai-engine-base';
 import { MJGlobal } from '@memberjunction/global';
 import { BaseRealtimeClient, LoadAssemblyAIRealtimeClient, LoadElevenLabsRealtimeClient, LoadGeminiRealtimeClient, LoadOpenAIRealtimeClient, LoadxAIRealtimeClient } from '@memberjunction/ai-realtime-client';
 import { BuildNarrationInstructions } from './narration-template';
 import { ParseDelegationResultJson } from './delegation-result-parser';
 import { BaseRealtimeChannelClient } from '../components/realtime/channels/base-realtime-channel-client';
+import { RealtimeAudioRecorder } from './realtime-audio-recorder';
 import * as i0 from "@angular/core";
+/**
+ * `MJ: User Settings` key for the per-user "record this voice call" consent toggle. Stored as
+ * the literal string `'true'`/`'false'` (read with `=== 'true'`), cross-device via
+ * {@link UserInfoEngine}. The pre-call picker writes it; the session service reads it as the
+ * default when the caller doesn't pass an explicit consent value.
+ */
+export const REALTIME_RECORDING_CONSENT_KEY = 'mj.realtimeVoice.recordingConsent.v1';
 // Tree-shaking prevention: the OpenAI client is resolved dynamically through the
 // ClassFactory (by the server-reported Provider key), so this static call is what keeps
 // its @RegisterClass side effect from being eliminated by the bundler.
@@ -37,7 +46,7 @@ LoadxAIRealtimeClient();
  * bakes the companion instructions + tool set into `SessionConfigJson`, which the client
  * driver applies verbatim.
  *
- * Lifecycle: {@link StartVoiceSession} → live duplex → {@link EndVoiceSession}.
+ * Lifecycle: {@link StartRealtimeSession} → live duplex → {@link EndRealtimeSession}.
  */
 export class RealtimeSessionService {
     // ── Reactive UI state ──────────────────────────────────────────────────────
@@ -75,7 +84,7 @@ export class RealtimeSessionService {
     /** Terminal result of a delegation, so the overlay can complete the working card with real content. */
     DelegationResult$ = this._delegationResult$.asObservable();
     /**
-     * EPHEMERAL spoken progress narrations (see {@link VoiceDelegationNarration}). These are
+     * 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.
      */
@@ -124,7 +133,7 @@ export class RealtimeSessionService {
      * 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
+     * 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.
      */
@@ -141,6 +150,18 @@ export class RealtimeSessionService {
     get ActiveChannels() {
         return this._activeChannels$.value;
     }
+    /**
+     * The `ChannelName`s the agent has used (acted on) at least once this session. The overlay
+     * uses this to register a channel's surface tab only after it has come into play. A fresh
+     * Set snapshot so callers can't mutate the service's tracking.
+     */
+    get UsedChannelNames() {
+        return new Set(this.usedChannelNames);
+    }
+    /** Whether the agent has used (acted on) the named channel at least once this session. */
+    HasChannelBeenUsed(channelName) {
+        return this.usedChannelNames.has(channelName);
+    }
     /** Synchronous access to the display name of the agent the active session fronts. */
     get CurrentAgentName() {
         return this._agentName$.value;
@@ -190,12 +211,69 @@ export class RealtimeSessionService {
     /** The mic capture stream — acquired here (permission UX) and handed to the client. */
     localStream = null;
     agentSessionId = null;
+    /**
+     * The application the active session runs in (sources the server-side app config cascade +
+     * RelevantAgents → allowed-agent union, and the default-agent chain). `null` when no app context
+     * was supplied. Set at {@link StartRealtimeSession}; sent to the mint mutation.
+     */
+    applicationId = null;
+    /**
+     * The live app-context snapshot (where the user is, what they see, the capability manifest),
+     * pushed by the host (Explorer) at session start and on subsequent changes via
+     * {@link UpdateAppContext}. The headless {@link import('../components/realtime/channels/client-context-channel').ClientContextChannel}
+     * subscribes to {@link AppContext$} and streams deltas to the model via `SendContextNote`.
+     */
+    _appContext$ = new BehaviorSubject(null);
+    /** Observable of the live app-context snapshot (see {@link _appContext$}). */
+    AppContext$ = this._appContext$.asObservable();
+    /**
+     * Push an updated app-context snapshot mid-session (the continuous-streaming half of client-context
+     * delivery). The host (Explorer) calls this when the user navigates / the active surface's state or
+     * capability manifest changes; the ClientContextChannel turns the delta into a `SendContextNote`.
+     * No-op semantics when no session is live — the channel simply re-reads on next start.
+     *
+     * @param snapshot The latest app-context snapshot (or null to clear).
+     */
+    UpdateAppContext(snapshot) {
+        this._appContext$.next(snapshot);
+    }
     /**
      * The DB-driven narration instruction template (server-resolved at session start, containing a
      * `{{ progressMessage }}` placeholder). `null` when the deployment hasn't synced the narration
      * prompt — {@link buildNarrationInstructions} then falls back to the built-in wording.
      */
     narrationTemplate = null;
+    // ── Browser-side call recording ────────────────────────────────────────────
+    /**
+     * The active session's audio recorder (mic + agent mix), or `null` when the user didn't
+     * consent or the browser can't record. Created after the client connects; stopped + uploaded
+     * at teardown.
+     */
+    recorder = null;
+    /** ISO timestamp of when recording started — sent to the server on session start. */
+    recordingStartedAtIso = null;
+    /** Interval that flushes ~15s crash-recovery shards to the server during a recording. */
+    segmentTimer = null;
+    /** 0-based index of the next recording shard to upload. */
+    segmentIndex = 0;
+    /** How often crash-recovery shards are flushed during a recording. */
+    static SegmentFlushMs = 15000;
+    /**
+     * Recording-relative ms offset at which the IN-FLIGHT (not-yet-finalized) turn's audio
+     * actually BEGAN — captured the moment that turn's audio/text starts flowing (its first
+     * interim transcript), NOT inherited from the previous turn's end. `null` before the first
+     * turn / between turns (until the next turn's audio starts). Sent as `utteranceStartMs` on
+     * the turn's final transcript so per-turn timing lines up with the recording even when a
+     * tool-call / silence gap sits between turns (the inherit-previous-end model mis-stamped
+     * the post-gap turn at the pre-gap offset). See {@link markTurnAudioStart}.
+     */
+    currentTurnStartMs = null;
+    /**
+     * Per-turn guard for {@link markTurnAudioStart}: `true` once the in-flight turn's audio-start
+     * offset has been captured, so mid-turn interim deltas don't overwrite it. Reset to `false`
+     * at each finalization so the NEXT turn re-stamps from where ITS audio begins.
+     */
+    turnAudioStartCaptured = false;
     // ── Delegated-run progress streaming ───────────────────────────────────────
     /** First spoken update fires no earlier than this long after delegated work starts. */
     static FirstNarrationDelayMs = 5000;
@@ -268,6 +346,14 @@ export class RealtimeSessionService {
      * the final save still lands on the just-closed session.
      */
     pendingChannelSaves = new Map();
+    /**
+     * `ChannelName`s the agent has ACTED ON at least once this session (the channel's first
+     * tool call routed to its local executor). The overlay reads this to decide which channel
+     * surface tabs to register: a channel earns its tab only once it's been used (the
+     * whiteboard is the sole exception — it tabs immediately, since a user may draw first).
+     * Reset at session start via {@link resetState}.
+     */
+    usedChannelNames = new Set();
     _provider = null;
     /**
      * Metadata provider used for the GraphQL relay mutations. Falls back to the
@@ -312,22 +398,47 @@ export class RealtimeSessionService {
      *   authorization on any overrides — hosts only populate this from authorization-gated
      *   pickers, and never synthesize overrides beyond what the user explicitly chose.
      *   Omit/`null` for the server's defaults (today's behavior).
+     * @param recordingConsent Optional EXPLICIT "record this call" consent for THIS session. When
+     *   `true`, the browser records a mic + agent-audio mix and uploads it at session end. When
+     *   omitted/`null`, the per-user persisted preference (`mj.realtimeVoice.recordingConsent.v1`
+     *   via {@link UserInfoEngine}) is read as the default. `false` never records.
+     * @param mediaCollectionId Optional per-session media-kit override (`MJ: Collections.ID`). When set,
+     *   the server-side Media channel resolves THIS collection as the agent's media kit for the session,
+     *   taking precedence over the agent's `DefaultMediaCollectionID`. The server UUID-validates it
+     *   (malformed ⇒ ignored, the agent default applies). Omit/`null` to use the agent default kit.
      */
-    async StartVoiceSession(targetAgentId, conversationId, lastSessionId, agentName, preferredModelId, clientTools, coAgentId, configOverridesJson) {
+    async StartRealtimeSession(targetAgentId, conversationId, lastSessionId, agentName, preferredModelId, clientTools, coAgentId, configOverridesJson, recordingConsent, mediaCollectionId, applicationId, appContext) {
         if (this.IsActive) {
             return; // a session is already running — ignore duplicate starts
         }
+        // App awareness (Move 1/3/4): the application the session runs in (sources the app config
+        // cascade + RelevantAgents → allowed-agent union) and the live app-context snapshot injected
+        // into the companion prompt at mint. Stored so the ClientContextChannel can stream subsequent
+        // deltas. Absent ⇒ no app layer / no mint-time context (the pre-app behavior).
+        this.applicationId = applicationId ?? null;
+        // Prefer the explicit param, but fall back to the snapshot the host has ALREADY pushed via
+        // UpdateAppContext (explorer-app streams the live snapshot continuously). The overlay's
+        // [appContext] binding can still read null at the instant the mic is clicked — without this
+        // fallback, StartRealtimeSession(null) would clobber a perfectly good snapshot and mint the
+        // companion prompt with no app context (no NavigableApps / no tool schemas → the co-agent guesses
+        // parameter names and navigation fails). Never overwrite a good value with null.
+        const effectiveAppContext = appContext ?? this._appContext$.value;
+        this._appContext$.next(effectiveAppContext);
         if (agentName) {
             this._agentName$.next(agentName);
         }
         this.resetState();
         this._active$.next(true);
         this._connectionState$.next('connecting');
+        // Resolve recording consent for this session: explicit value wins, else the per-user
+        // persisted preference. Computed before mint so it can be reported to the server.
+        const consent = recordingConsent ?? this.readPersistedRecordingConsent();
+        this.recordingStartedAtIso = consent ? new Date().toISOString() : null;
         try {
             // Resolve + initialize the interactive-channel plugins FIRST: their client-executed
             // tool sets must be declared to the realtime model at session mint.
             const allClientTools = [...(clientTools ?? []), ...(await this.startChannels())];
-            const session = await this.mintSession(targetAgentId, conversationId, lastSessionId, preferredModelId, allClientTools, coAgentId, configOverridesJson);
+            const session = await this.mintSession(targetAgentId, conversationId, lastSessionId, preferredModelId, allClientTools, coAgentId, configOverridesJson, consent, this.recordingStartedAtIso, mediaCollectionId, this.applicationId, effectiveAppContext);
             this.agentSessionId = session.AgentSessionId;
             // A null input conversationId means the SERVER created a fresh conversation for
             // this session — track it so the host can fold it into the cached list, select
@@ -345,6 +456,14 @@ export class RealtimeSessionService {
             this.wireClientHandlers(client);
             this.localStream = await navigator.mediaDevices.getUserMedia({ audio: true });
             await client.Connect(this.buildClientConfig(session), this.localStream);
+            // Start browser-side recording (mic + agent mix) when consented. Best-effort: an
+            // unsupported browser / missing remote stream degrades gracefully (mic-only or off)
+            // and never blocks the call. The remote stream may still be null here (the WebRTC
+            // ontrack can land slightly after Connect resolves) — the recorder mixes the mic now
+            // and the agent audio rides through whenever its track is already attached.
+            if (consent) {
+                this.startRecording(client);
+            }
             this.subscribeDelegationProgress();
             // State advances to 'listening' once the provider control channel opens
             // (driven by the client's OnStateChange events).
@@ -367,7 +486,7 @@ export class RealtimeSessionService {
      * End the active session: stop the mic, tear down the provider connection, and close
      * the server-side agent session. Safe to call when no session is active.
      */
-    async EndVoiceSession() {
+    async EndRealtimeSession() {
         if (!this.IsActive && !this.agentSessionId) {
             return;
         }
@@ -445,6 +564,177 @@ export class RealtimeSessionService {
     GetAudioActivity() {
         return this.client?.GetAudioActivity() ?? null;
     }
+    // ── Browser-side call recording ────────────────────────────────────────────
+    /**
+     * Reads the per-user recording-consent preference from `MJ: User Settings` (via
+     * {@link UserInfoEngine}'s synchronous cache). Defensive: any failure resolves to `false`
+     * (don't record) so a settings hiccup can never opt a user into recording.
+     */
+    readPersistedRecordingConsent() {
+        try {
+            return UserInfoEngine.Instance.GetSetting(REALTIME_RECORDING_CONSENT_KEY) === 'true';
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Starts the browser-side recorder (mic + agent-audio mix). Best-effort — any failure is
+     * contained so it never disturbs the live call; an unsupported browser simply records
+     * nothing (the recorder disables itself).
+     */
+    startRecording(client) {
+        try {
+            if (!this.localStream) {
+                return;
+            }
+            const remoteStream = client.GetRemoteMediaStream?.() ?? null;
+            const recorder = new RealtimeAudioRecorder();
+            recorder.Start(this.localStream, remoteStream);
+            this.recorder = recorder.IsRecording ? recorder : null;
+            // First turn's audio starts at ~0 (recording begins right as the call goes live). Seed it
+            // here so the very first turn has a sane start even if its first interim is missed; later
+            // turns re-stamp from where THEIR audio begins via markTurnAudioStart (handles tool gaps).
+            this.currentTurnStartMs = recorder.IsRecording ? 0 : null;
+            this.turnAudioStartCaptured = false;
+            if (this.recorder) {
+                // The agent's WebRTC audio track usually lands AFTER Connect() resolves, so `remoteStream`
+                // above is typically null and we'd capture mic-only. Attach the agent stream whenever it
+                // arrives (fires immediately if already present) so the recording includes the agent voice.
+                client.OnRemoteMediaStream?.((stream) => this.recorder?.AttachRemoteStream(stream));
+                this.startSegmentFlushing();
+            }
+        }
+        catch (error) {
+            console.warn('[RealtimeSession] Failed to start call recording:', error);
+            this.recorder = null;
+        }
+    }
+    /** Begins flushing ~15s crash-recovery shards to the server for the duration of the recording. */
+    startSegmentFlushing() {
+        this.segmentIndex = 0;
+        this.segmentTimer = setInterval(() => { void this.flushRecordingSegment(); }, RealtimeSessionService.SegmentFlushMs);
+    }
+    /** Stops the periodic crash-recovery shard flush. */
+    stopSegmentFlushing() {
+        if (this.segmentTimer) {
+            clearInterval(this.segmentTimer);
+            this.segmentTimer = null;
+        }
+    }
+    /**
+     * Uploads the chunks captured since the last flush as one crash-recovery shard (durability only;
+     * the canonical file is still the full upload at teardown). Best-effort — never disturbs the call.
+     */
+    async flushRecordingSegment() {
+        const recorder = this.recorder;
+        const agentSessionId = this.agentSessionId;
+        if (!recorder || !agentSessionId) {
+            return;
+        }
+        const segment = recorder.SnapshotNewSegment();
+        if (!segment || segment.size === 0) {
+            return;
+        }
+        try {
+            const audioBase64 = await this.blobToBase64(segment);
+            if (!audioBase64) {
+                return;
+            }
+            const index = this.segmentIndex++;
+            const mutation = `
+        mutation UploadRealtimeRecordingSegment($agentSessionId: String!, $segmentIndex: Int!, $audioBase64: String!, $mimeType: String!) {
+          UploadRealtimeRecordingSegment(agentSessionId: $agentSessionId, segmentIndex: $segmentIndex, audioBase64: $audioBase64, mimeType: $mimeType)
+        }
+      `;
+            // Shards are HEADER-LESS raw little-endian PCM16 (mime audio/L16 with the capture sample rate),
+            // NOT individually-playable WAV — recovery is concatenate-in-order then WAV-wrap. The canonical
+            // seekable WAV is the consolidated end-of-call upload below.
+            const shardMime = `audio/L16;rate=${recorder.SampleRate}`;
+            await this.gql().ExecuteGQL(mutation, { agentSessionId, segmentIndex: index, audioBase64, mimeType: shardMime });
+        }
+        catch (error) {
+            console.warn('[RealtimeSession] Failed to flush recording shard:', error);
+        }
+    }
+    /**
+     * Stops the active recorder and uploads the captured audio via `UploadRealtimeRecording`.
+     * Fully best-effort and wrapped in try/catch — recording upload must NEVER block teardown.
+     * No-op when nothing was recorded or there's no session id to attach the file to.
+     */
+    async stopAndUploadRecording(agentSessionId) {
+        this.stopSegmentFlushing();
+        const recorder = this.recorder;
+        this.recorder = null;
+        this.currentTurnStartMs = null;
+        this.turnAudioStartCaptured = false;
+        if (!recorder) {
+            return;
+        }
+        try {
+            // Capture the recorder MIME (now 'audio/wav') BEFORE Stop() — the getter reads '' once stopped.
+            const mimeType = recorder.MimeType;
+            const blob = await recorder.Stop();
+            // Read the real waveform peaks computed during capture (survives Stop via the recorder's snapshot).
+            const peaks = recorder.GetPeaks();
+            if (!blob || blob.size === 0 || !agentSessionId) {
+                console.warn('[RealtimeSession] ⚠️ recording NOT uploaded — empty blob or no session id.');
+                return;
+            }
+            const audioBase64 = await this.blobToBase64(blob);
+            if (!audioBase64) {
+                console.warn('[RealtimeSession] ⚠️ recording NOT uploaded — base64 encoding failed.');
+                return;
+            }
+            await this.uploadRecording(agentSessionId, audioBase64, mimeType, peaks);
+        }
+        catch (error) {
+            console.warn('[RealtimeSession] Failed to stop/upload call recording:', error);
+        }
+    }
+    /**
+     * Runs the `UploadRealtimeRecording` mutation; failures are logged, never thrown. Sends the
+     * capture-time waveform `peaks` (max-abs per bucket, normalized 0..1) so the server can persist a
+     * `peaks.json` sidecar for fast waveform rendering without re-decoding the audio.
+     */
+    async uploadRecording(agentSessionId, audioBase64, mimeType, peaks) {
+        const mutation = `
+      mutation UploadRealtimeRecording($agentSessionId: String!, $audioBase64: String!, $mimeType: String!, $consent: Boolean, $peaks: [Float!]) {
+        UploadRealtimeRecording(agentSessionId: $agentSessionId, audioBase64: $audioBase64, mimeType: $mimeType, consent: $consent, peaks: $peaks) {
+          Success
+          FileID
+          ErrorMessage
+        }
+      }
+    `;
+        const result = await this.gql().ExecuteGQL(mutation, {
+            agentSessionId,
+            audioBase64,
+            mimeType,
+            consent: true,
+            peaks
+        });
+        const payload = result?.UploadRealtimeRecording;
+        if (!payload?.Success) {
+            console.warn(`[RealtimeSession] ❌ recording upload reported failure: ${payload?.ErrorMessage ?? 'unknown error'} (full result: ${JSON.stringify(result)})`);
+        }
+    }
+    /**
+     * Encodes a {@link Blob} as a base64 string (the data: prefix stripped) via {@link FileReader}.
+     * Resolves `''` on any read failure so the upload path can bail cleanly.
+     */
+    blobToBase64(blob) {
+        return new Promise((resolve) => {
+            const reader = new FileReader();
+            reader.onloadend = () => {
+                const result = typeof reader.result === 'string' ? reader.result : '';
+                const commaIndex = result.indexOf(',');
+                resolve(commaIndex >= 0 ? result.slice(commaIndex + 1) : '');
+            };
+            reader.onerror = () => resolve('');
+            reader.readAsDataURL(blob);
+        });
+    }
     // ── Interactive channels (registry-driven plugins) ─────────────────────────
     /**
      * Resolves, instantiates and initializes the session's interactive-channel plugins from
@@ -532,7 +822,10 @@ export class RealtimeSessionService {
         plugin.Initialize(this.buildChannelContext(plugin));
         this.RegisterClientToolHandler(plugin.ToolNamePrefix, (toolName, argsJson) => {
             // The agent is ACTING on this channel — surface-discovery signal for the overlay
-            // (first activity auto-reveals + focuses the channel tab) before the tool applies.
+            // (first activity registers + auto-reveals + focuses the channel tab) before the
+            // tool applies. Record the channel as USED so the overlay tabs it (channels other
+            // than the whiteboard are tab-less until they're first used).
+            this.usedChannelNames.add(plugin.ChannelName);
             this._channelActivity$.next(plugin);
             return plugin.ApplyAgentTool(toolName, argsJson);
         });
@@ -544,6 +837,11 @@ export class RealtimeSessionService {
         const service = this;
         return {
             AgentName: this.CurrentAgentName,
+            // The live session's provider — threaded by channels into MJ-backed surfaces (e.g. the Media
+            // channel's mj-storage-media-player / CreateMediaAccessToken). `get` so it stays current.
+            get Provider() {
+                return service.Provider;
+            },
             SendContextNote: (text) => this.SendContextNote(text),
             RequestSpokenResponse: (instructions) => this.requestChannelSpokenResponse(instructions),
             RequestSave: (stateJson) => this.scheduleChannelSave(plugin.ChannelName, stateJson),
@@ -555,9 +853,62 @@ export class RealtimeSessionService {
             get AgentSessionID() {
                 return service.agentSessionId;
             },
-            ExecuteServerAction: (query, variables) => this.executeChannelServerAction(query, variables)
+            ExecuteServerAction: (query, variables) => this.executeChannelServerAction(query, variables),
+            // App-context stream + client-tool execution for the headless ClientContextChannel. The host
+            // (Explorer) feeds both; absent on hosts that supply no app context / register no client tools.
+            AppContext$: this.AppContext$,
+            ExecuteClientTool: (name, params) => this.executeAppClientTool(name, params)
         };
     }
+    /**
+     * Host registry of surface CLIENT TOOLS (Name → handler), fed by the host (Explorer) from the
+     * active surface's `SetAgentClientTools`. The headless ClientContextChannel's `ContextTool` proxy
+     * executes against this via {@link executeAppClientTool}. Keys are lower-cased for case-insensitive
+     * model-supplied action names.
+     */
+    appClientToolHandlers = new Map();
+    /**
+     * Replaces the set of host-registered surface client tools the realtime ContextTool can execute.
+     * The host calls this at session start and whenever the active surface's tool set changes (the
+     * continuous-capability half of client-context delivery). Passing `[]` clears them.
+     *
+     * @param tools The current surface client tools (name + handler). Descriptions/schemas ride the
+     *   app-context manifest separately; only the executable handler is needed here.
+     */
+    RegisterAppClientTools(tools) {
+        this.appClientToolHandlers.clear();
+        for (const tool of tools) {
+            if (tool?.Name && typeof tool.Handler === 'function') {
+                this.appClientToolHandlers.set(tool.Name.trim().toLowerCase(), tool.Handler);
+            }
+        }
+    }
+    /**
+     * Executes a host-registered surface client tool by name (the {@link RealtimeChannelContext.ExecuteClientTool}
+     * implementation). Tolerant: an unknown tool or a thrown handler resolves to a structured
+     * `Success: false` result the channel narrates — never throws.
+     *
+     * @param name The tool name (the model's `action`).
+     * @param params The tool parameters.
+     * @returns A structured result for the channel to serialize back to the model.
+     */
+    async executeAppClientTool(name, params) {
+        const handler = this.appClientToolHandlers.get((name ?? '').trim().toLowerCase());
+        if (!handler) {
+            const available = Array.from(this.appClientToolHandlers.keys()).join(', ');
+            return {
+                Success: false,
+                ErrorMessage: `No client tool named "${name}" is available on this surface. Available: ${available || '(none)'}.`
+            };
+        }
+        try {
+            const result = await handler(params ?? {});
+            return { Success: true, Result: result };
+        }
+        catch (error) {
+            return { Success: false, ErrorMessage: error instanceof Error ? error.message : String(error) };
+        }
+    }
     /**
      * Runs a channel-specific GraphQL operation through the live session's provider (the
      * {@link RealtimeChannelContext.ExecuteServerAction} implementation). Best-effort: any
@@ -711,6 +1062,7 @@ export class RealtimeSessionService {
         if (this._activeChannels$.value.length > 0) {
             this._activeChannels$.next([]);
         }
+        this.usedChannelNames.clear();
     }
     // ── Realtime client resolution + wiring ────────────────────────────────────
     /**
@@ -794,7 +1146,7 @@ export class RealtimeSessionService {
         }
     }
     /**
-     * Translates {@link RealtimeClientState} into {@link VoiceConnectionState}. `'connected'`
+     * 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.
      */
@@ -821,14 +1173,21 @@ export class RealtimeSessionService {
     }
     // ── Transcript policy ──────────────────────────────────────────────────────
     /**
-     * Applies transcript policy to client transcript events. Interim deltas are ignored
-     * (the client already drives the speaking state). Final NORMAL assistant turns become
+     * Applies transcript policy to client transcript events. Interim deltas don't become
+     * captions/turns (the client already drives the speaking state) but DO mark this turn's
+     * audio-start offset against the recording (the first interim fires as the audio/text
+     * starts flowing — see {@link markTurnAudioStart}). Final NORMAL assistant turns become
      * captions + persisted transcripts; final NARRATION turns are EPHEMERAL by product
      * decision — emitted on {@link DelegationNarration$} only, never a caption, never
      * relayed/persisted. User turns ride the caption + relay path.
      */
     async onClientTranscript(transcript) {
         if (!transcript.IsFinal) {
+            // First interim of a NEW turn = that turn's audio is starting NOW. Stamp the
+            // recording-relative start here so a turn whose audio begins AFTER a tool-call /
+            // silence gap is timed where its audio really is — not inherited from the prior
+            // turn's end. Narration interims are ephemeral and excluded (Kind guard inside).
+            this.markTurnAudioStart(transcript.Kind);
             return;
         }
         if (transcript.Role === 'Assistant') {
@@ -864,6 +1223,34 @@ export class RealtimeSessionService {
             await this.onUserTranscript(transcript.Text);
         }
     }
+    /**
+     * Stamps the recording-relative offset at which the IN-FLIGHT turn's audio actually began,
+     * the moment that turn's audio/text first starts flowing (its FIRST interim transcript).
+     *
+     * This is the fix for transcript cues drifting out of sync with the audio when a tool-call /
+     * silence gap sits between turns: the old model inherited the next turn's start from the
+     * PREVIOUS turn's end (assumes contiguous turns), so a post-gap turn's cue pointed ~gap-length
+     * too early. Capturing the start where the audio truly begins keeps the cue aligned.
+     *
+     * Guards:
+     * - only when recording ({@link recorder} present),
+     * - only ONCE per turn ({@link turnAudioStartCaptured}) so mid-turn interim deltas don't move it,
+     * - NORMAL turns only — NARRATION interims are ephemeral and never persisted, so they must not
+     *   claim the next real turn's start slot.
+     *
+     * Works for any role whose driver surfaces interim deltas (all drivers for the assistant; the
+     * relevant case here — the post-tool-gap assistant answer — and user-interim drivers like
+     * Gemini/AssemblyAI). For final-only user turns (OpenAI/xAI/ElevenLabs) no interim arrives, so
+     * {@link relayTranscript} falls back to the seeded/prior start — the gap case that drifts is the
+     * assistant answer, which always has interims.
+     */
+    markTurnAudioStart(kind) {
+        if (!this.recorder || this.turnAudioStartCaptured || kind === 'narration') {
+            return;
+        }
+        this.currentTurnStartMs = this.recorder.NowOffsetMs();
+        this.turnAudioStartCaptured = true;
+    }
     /**
      * 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
@@ -977,8 +1364,8 @@ export class RealtimeSessionService {
      * {@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.
+     * along as {@link RealtimeDelegationResult.RunID} for the overlay's dev links, and any `artifacts`
+     * ride along as {@link RealtimeDelegationResult.Artifacts} for the surface panel's artifact tabs.
      */
     emitDelegationResult(callId, resultJson) {
         // The result will be spoken next — a deferred interim update is now pointless
@@ -1091,10 +1478,10 @@ export class RealtimeSessionService {
     }
     // ── Session minting (GraphQL) ──────────────────────────────────────────────
     /** Calls the `StartRealtimeClientSession` mutation to obtain an ephemeral token + config. */
-    async mintSession(targetAgentId, conversationId, lastSessionId, preferredModelId, clientTools, coAgentId, configOverridesJson) {
+    async mintSession(targetAgentId, conversationId, lastSessionId, preferredModelId, clientTools, coAgentId, configOverridesJson, recordingConsent, recordingStartedAt, mediaCollectionId, applicationId, appContext) {
         const mutation = `
-      mutation StartRealtimeClientSession($targetAgentId: String!, $conversationId: String, $lastSessionId: String, $preferredModelId: String, $clientToolsJson: String, $coAgentId: String, $configOverridesJson: String) {
-        StartRealtimeClientSession(targetAgentId: $targetAgentId, conversationId: $conversationId, lastSessionId: $lastSessionId, preferredModelId: $preferredModelId, clientToolsJson: $clientToolsJson, coAgentId: $coAgentId, configOverridesJson: $configOverridesJson) {
+      mutation StartRealtimeClientSession($targetAgentId: String!, $conversationId: String, $lastSessionId: String, $preferredModelId: String, $clientToolsJson: String, $coAgentId: String, $configOverridesJson: String, $recordingConsent: Boolean, $recordingStartedAt: String, $mediaCollectionId: String, $applicationId: String, $appContextJson: String) {
+        StartRealtimeClientSession(targetAgentId: $targetAgentId, conversationId: $conversationId, lastSessionId: $lastSessionId, preferredModelId: $preferredModelId, clientToolsJson: $clientToolsJson, coAgentId: $coAgentId, configOverridesJson: $configOverridesJson, recordingConsent: $recordingConsent, recordingStartedAt: $recordingStartedAt, mediaCollectionId: $mediaCollectionId, applicationId: $applicationId, appContextJson: $appContextJson) {
           AgentSessionId
           ConversationId
           Provider
@@ -1115,7 +1502,12 @@ export class RealtimeSessionService {
             preferredModelId: preferredModelId ?? null,
             clientToolsJson: clientTools && clientTools.length > 0 ? JSON.stringify(clientTools) : null,
             coAgentId: coAgentId ?? null,
-            configOverridesJson: configOverridesJson ?? null
+            configOverridesJson: configOverridesJson ?? null,
+            recordingConsent: recordingConsent ?? false,
+            recordingStartedAt: recordingStartedAt ?? null,
+            mediaCollectionId: mediaCollectionId ?? null,
+            applicationId: applicationId ?? null,
+            appContextJson: appContext ? JSON.stringify(appContext) : null
         };
         const result = await this.gql().ExecuteGQL(mutation, variables);
         const payload = result?.StartRealtimeClientSession;
@@ -1177,6 +1569,19 @@ export class RealtimeSessionService {
     // ── Transcript relay (GraphQL) ─────────────────────────────────────────────
     /**
      * Relays a final transcript turn to MJ via `RelayRealtimeTranscript`.
+     *
+     * When the session is being recorded, per-turn timing rides along: `utteranceEndMs` is the
+     * recording-relative offset at finalization, and `utteranceStartMs` is the offset captured by
+     * {@link markTurnAudioStart} when THIS turn's audio actually began (its first interim) — NOT
+     * inherited from the previous turn's end. That distinction is the timing fix: when a tool-call
+     * / silence gap sits between turns, the post-gap turn's audio starts much later, so inheriting
+     * the prior turn's end stamped the cue ~gap-length too early. Both are omitted (left `null`)
+     * when the session isn't being recorded.
+     *
+     * A correction (`replacesPrevious`) doesn't open a new turn, so it carries no start and doesn't
+     * reset the per-turn start guard. After a normal finalization the guard is cleared so the NEXT
+     * turn re-stamps its start from where ITS audio begins.
+     *
      * @param replacesPrevious CORRECTION semantics: the server updates the session's most
      *   recent persisted turn of this role IN PLACE instead of appending (e.g. ElevenLabs'
      *   post-barge-in `agent_response_correction`).
@@ -1185,17 +1590,31 @@ export class RealtimeSessionService {
         if (!this.agentSessionId) {
             return;
         }
+        // Per-turn timing against the recording (when recording). `utteranceStartMs` is where this
+        // turn's audio actually began (captured by markTurnAudioStart on the first interim); the
+        // `?? 0` fallback covers a turn whose interim was missed / a final-only first turn.
+        const utteranceEndMs = this.recorder ? this.recorder.NowOffsetMs() : null;
+        const utteranceStartMs = this.recorder && !replacesPrevious ? (this.currentTurnStartMs ?? 0) : null;
+        if (this.recorder && !replacesPrevious) {
+            // This turn is finalized — arm the NEXT turn to re-stamp its start from its own first
+            // interim (handles a tool-call gap before the next turn). Stop inheriting this end as the
+            // next start. `null` means "not yet captured"; relay falls back to `?? 0` if no interim fires.
+            this.currentTurnStartMs = null;
+            this.turnAudioStartCaptured = false;
+        }
         try {
             const mutation = `
-        mutation RelayRealtimeTranscript($agentSessionId: String!, $role: String!, $text: String!, $replacesPrevious: Boolean) {
-          RelayRealtimeTranscript(agentSessionId: $agentSessionId, role: $role, text: $text, replacesPrevious: $replacesPrevious)
+        mutation RelayRealtimeTranscript($agentSessionId: String!, $role: String!, $text: String!, $replacesPrevious: Boolean, $utteranceStartMs: Int, $utteranceEndMs: Int) {
+          RelayRealtimeTranscript(agentSessionId: $agentSessionId, role: $role, text: $text, replacesPrevious: $replacesPrevious, utteranceStartMs: $utteranceStartMs, utteranceEndMs: $utteranceEndMs)
         }
       `;
             await this.gql().ExecuteGQL(mutation, {
                 agentSessionId: this.agentSessionId,
                 role,
                 text,
-                replacesPrevious
+                replacesPrevious,
+                utteranceStartMs,
+                utteranceEndMs
             });
         }
         catch (error) {
@@ -1575,6 +1994,11 @@ export class RealtimeSessionService {
             await this.client.Disconnect();
             this.client = null;
         }
+        // Stop + upload the call recording WHILE the live session id is still set (the file is
+        // attached to it). Best-effort and never blocks teardown — stopAndUploadRecording swallows
+        // its own errors. No-op when nothing was recorded.
+        await this.stopAndUploadRecording(this.agentSessionId);
+        this.recordingStartedAtIso = null;
         // Final usage flush WHILE the live session id is still set (the relay mutation also
         // accepts a Closed session, so ordering vs. CloseAgentSession is belt-and-braces).
         if (this.usageFlushTimer) {
@@ -1600,7 +2024,7 @@ export class RealtimeSessionService {
             this._connectionState$.next('closed');
         }
         // Surface generic session-ended for the conversations runtime bridge.
-        // `closeServerSession=true` means the user explicitly called EndVoiceSession;
+        // `closeServerSession=true` means the user explicitly called EndRealtimeSession;
         // `false` means teardown ran from a catch block (start path error path).
         if (closedSessionId) {
             this._sessionEnded$.next({
@@ -1632,6 +2056,13 @@ export class RealtimeSessionService {
     resetState() {
         this._captions$.next([]);
         this.SetMinimized(false);
+        this.stopSegmentFlushing();
+        this.segmentIndex = 0;
+        this.recorder = null;
+        this.recordingStartedAtIso = null;
+        this.currentTurnStartMs = null;
+        this.turnAudioStartCaptured = false;
+        this.usedChannelNames.clear();
     }
     /** The GraphQL provider used for relay mutations. */
     gql() {