@memberjunction/server 5.43.0 → 5.45.0

package/dist/resolvers/RealtimeClientSessionResolver.js

@@ -36,16 +36,17 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
  *
  * @module @memberjunction/server
  */
-import { Resolver, Mutation, Arg, Ctx, Int, ObjectType, Field, PubSub, PubSubEngine } from 'type-graphql';
+import { Resolver, Mutation, Arg, Ctx, Int, Float, ObjectType, Field, PubSub, PubSubEngine } from 'type-graphql';
 import { AuthorizationEvaluator, LogError, LogStatus, RunView } from '@memberjunction/core';
-import { UUIDsEqual } from '@memberjunction/global';
+import { UUIDsEqual, IsValidUUID } from '@memberjunction/global';
 import { AIEngine } from '@memberjunction/aiengine';
 import { AIAgentPermissionHelper, AIEngineBase } from '@memberjunction/ai-engine-base';
-import { RealtimeClientSessionService, RealtimeChannelServerHost, EvaluateRuntimeOverrideAuthorization, ParseRealtimeTypeConfiguration, ResolveEffectiveRealtimeConfig, REALTIME_ADVANCED_SESSION_CONTROLS_AUTHORIZATION, } from '@memberjunction/ai-agents';
+import { RealtimeClientSessionService, RealtimeChannelServerHost, EvaluateRuntimeOverrideAuthorization, ParseRealtimeTypeConfiguration, ResolveEffectiveRealtimeConfig, REALTIME_ADVANCED_SESSION_CONTROLS_AUTHORIZATION, resolveRecordingStorageAccountID, storeRealtimeRecording, writeRealtimeRecordingSegment, deleteRealtimeRecordingSegments, } from '@memberjunction/ai-agents';
 import { ResolverBase } from '../generic/ResolverBase.js';
 import { PUSH_STATUS_UPDATES_TOPIC } from '../generic/PushStatusResolver.js';
 import { GetReadWriteProvider } from '../util.js';
 import { SessionManager } from '../agentSessions/index.js';
+import { resolveWidgetGuestRunContext } from '../realtimeWidget/widgetGuestElevation.js';
 /**
  * Progress steps worth narrating to the realtime model — mirrors the normal agent-run path's filter
  * in {@link import('./RunAIAgentResolver.js').RunAIAgentResolver}. Initialization/validation/finalization
@@ -222,6 +223,30 @@ CancelRealtimeSessionToolResult = __decorate([
     ObjectType()
 ], CancelRealtimeSessionToolResult);
 export { CancelRealtimeSessionToolResult };
+/**
+ * Result of {@link RealtimeClientSessionResolver.UploadRealtimeRecording} — a structured
+ * success/failure envelope. A recording-storage failure must never throw to the browser (the
+ * session it belongs to has already ended), so problems come back as `Success: false` with a
+ * human-readable reason; only ownership/authn violations (from `loadOwnedSession`) still throw.
+ */
+let UploadRealtimeRecordingResult = class UploadRealtimeRecordingResult {
+};
+__decorate([
+    Field(() => Boolean),
+    __metadata("design:type", Boolean)
+], UploadRealtimeRecordingResult.prototype, "Success", void 0);
+__decorate([
+    Field(() => String, { nullable: true }),
+    __metadata("design:type", String)
+], UploadRealtimeRecordingResult.prototype, "ErrorMessage", void 0);
+__decorate([
+    Field(() => String, { nullable: true }),
+    __metadata("design:type", String)
+], UploadRealtimeRecordingResult.prototype, "FileID", void 0);
+UploadRealtimeRecordingResult = __decorate([
+    ObjectType()
+], UploadRealtimeRecordingResult);
+export { UploadRealtimeRecordingResult };
 /**
  * Resolver for the client-direct realtime voice topology. A single {@link SessionManager} and a
  * single {@link RealtimeClientSessionService} are shared across requests — neither holds per-user or
@@ -272,7 +297,7 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
      *
      * @returns The ephemeral config + session linkage the browser needs to open its socket.
      */
-    async StartRealtimeClientSession(targetAgentId, { userPayload, providers }, conversationId, lastSessionId, preferredModelId, clientToolsJson, coAgentId, configOverridesJson) {
+    async StartRealtimeClientSession(targetAgentId, { userPayload, providers }, conversationId, lastSessionId, preferredModelId, clientToolsJson, coAgentId, configOverridesJson, recordingStartedAt, recordingConsent, mediaCollectionId, applicationId, appContextJson) {
         const { contextUser, provider } = this.requireUserAndProvider(userPayload, providers);
         const coAgentID = await this.resolveCoAgentID(targetAgentId, coAgentId, contextUser, provider);
         // PAIRING CONSTRAINTS: a co-agent with pairing rows is restricted to that target list
@@ -284,7 +309,28 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
         // the 'Realtime: Advanced Session Controls' authorization (structured rejection, never a
         // silent ignore). Plain starts and within-pairing target selection are never gated here.
         await this.assertRuntimeOverridesAuthorized(coAgentID, configOverridesJson, preferredModelId, contextUser, provider);
+        // PUBLIC WEB-WIDGET VOICE CAP (public-web-widget.md W4): when the caller is a widget guest,
+        // resolve the deployment's hard duration ceiling and stamp an absolute deadline on the session.
+        // The SessionJanitor force-closes (finalizing runs) past the deadline — a server-authoritative
+        // bound that does not depend on the client honoring its own abuse guard or the ephemeral token TTL.
+        const maxSessionSeconds = await this.resolveWidgetVoiceCapSeconds(userPayload, providers);
         const config = { targetAgentID: effectiveTargetId };
+        if (maxSessionSeconds) {
+            config.maxSessionDeadlineIso = new Date(Date.now() + maxSessionSeconds * 1000).toISOString();
+        }
+        // Per-session media-kit override: stored on the session config so the server-side MediaChannelServer
+        // resolves it (over the agent default) at start. Validate the id here — a malformed value is
+        // dropped (logged), never interpolated; the session still starts and falls back to the agent kit.
+        const mediaOverride = mediaCollectionId?.trim();
+        if (mediaOverride) {
+            if (IsValidUUID(mediaOverride)) {
+                config.mediaCollectionID = mediaOverride;
+            }
+            else {
+                LogStatus(`StartRealtimeClientSession: ignoring malformed mediaCollectionId '${mediaCollectionId}' — ` +
+                    'using the agent default media kit.');
+            }
+        }
         const session = await this.sessionManager.CreateSession({
             agentID: coAgentID,
             userID: contextUser.ID,
@@ -292,12 +338,14 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
             lastSessionID: lastSessionId,
             config: JSON.stringify(config),
         }, contextUser, provider);
+        // Best-effort: stamp recording-start metadata when the browser captured (with consent) at start.
+        await this.stampRecordingStart(session, recordingConsent, recordingStartedAt);
         const clientTools = this.parseClientTools(clientToolsJson);
         // Best-effort model-context hydration: the PRIOR session chain's transcript (ownership-
         // checked, capped) is framed into the system prompt so the model REMEMBERS the last leg.
         // Strictly tolerant — any problem yields no hydration, never a failed start.
         const priorTranscript = await this.loadPriorTranscript(lastSessionId, contextUser, provider);
-        const result = await this.prepareClientSessionOrClose(session, coAgentID, effectiveTargetId, contextUser, provider, preferredModelId, clientTools, priorTranscript, configOverridesJson);
+        const result = await this.prepareClientSessionOrClose(session, coAgentID, effectiveTargetId, contextUser, provider, preferredModelId, clientTools, priorTranscript, configOverridesJson, maxSessionSeconds, applicationId, this.parseAppContext(appContextJson));
         // Best-effort restore of the PRIOR session's persisted channel states (e.g. the whiteboard
         // board). Strictly tolerant — any problem yields a null field, never a failed start.
         result.PriorChannelStatesJson = (await this.loadPriorChannelStatesJson(lastSessionId, contextUser, provider)) ?? undefined;
@@ -319,6 +367,9 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
         const { ResultJson, PausedRunID, Artifacts } = await this.clientSessionService.ExecuteRelayedTool({
             AgentSessionID: agentSessionId,
             TargetAgentID: config.targetAgentID,
+            // Multi-target (Move 4): the session's persisted allowed-agent union — a model-named
+            // colleague in the call is validated against this; absent ⇒ single-target behavior.
+            AllowedAgents: config.allowedAgents,
             // Nest the delegated target-agent run under the co-agent observability run (when present).
             ParentRunID: config.coAgentRunID,
             Call: { CallID: callId, ToolName: toolName, Arguments: argsJson },
@@ -378,6 +429,10 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
             promptRunID: config.promptRunID,
             coAgentRunStepID: config.coAgentRunStepID,
             pendingFeedbackRunID: pausedRunID,
+            // Preserve the server-authoritative voice deadline across config rewrites.
+            maxSessionDeadlineIso: config.maxSessionDeadlineIso,
+            applicationID: config.applicationID,
+            allowedAgents: config.allowedAgents,
         };
         session.Config_ = JSON.stringify(next);
         if (!(await session.Save())) {
@@ -397,12 +452,12 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
      *
      * @returns `true` when the transcript turn was persisted.
      */
-    async RelayRealtimeTranscript(agentSessionId, role, text, { userPayload, providers }, replacesPrevious) {
+    async RelayRealtimeTranscript(agentSessionId, role, text, { userPayload, providers }, replacesPrevious, utteranceStartMs, utteranceEndMs) {
         const { contextUser, provider } = this.requireUserAndProvider(userPayload, providers);
         const session = await this.loadOwnedActiveSession(agentSessionId, contextUser, provider);
         const saved = replacesPrevious
-            ? await this.replacePreviousTranscriptTurn(session, role, text, contextUser, provider)
-            : await this.persistTranscriptTurn(session, role, text, contextUser, provider);
+            ? await this.replacePreviousTranscriptTurn(session, role, text, contextUser, provider, utteranceStartMs, utteranceEndMs)
+            : await this.persistTranscriptTurn(session, role, text, contextUser, provider, utteranceStartMs, utteranceEndMs);
         if (!saved) {
             return false;
         }
@@ -423,6 +478,122 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
     mapTranscriptRoleToChatRole(role) {
         return role.trim().toLowerCase() === 'user' ? 'user' : 'assistant';
     }
+    /**
+     * Upload a CLIENT-DIRECT session audio recording, store it in MJStorage, link it to the owning
+     * `AIAgentSession`, and stamp the session's recording fields. The browser records locally during
+     * the call and uploads the assembled blob (base64) once the session ends.
+     *
+     * Hard gates (in order):
+     * 1. Ownership — `loadOwnedSession` enforces `UserID === contextUser.ID` (throws on violation).
+     * 2. Consent — `consent !== true` is a hard refusal: no audio is ever stored without it.
+     * 3. Storage configuration — the session's agent must resolve a recording storage account (the
+     *    agent's `RecordingStorageProviderID`, else `AttachmentStorageProviderID`).
+     *
+     * Storage failures (and any unexpected throw) come back as `Success: false` with a reason — they
+     * NEVER throw to the browser, mirroring the shared {@link storeRealtimeRecording} contract.
+     *
+     * @param agentSessionId The session the recording belongs to (ownership-gated).
+     * @param audioBase64 The base64-encoded recording bytes (client-direct: seekable WAV/PCM).
+     * @param mimeType The audio MIME type (`audio/wav` for client-direct; legacy `audio/webm`/`ogg`/`mp4`).
+     * @param durationMs Optional client-measured recording duration (ms) — informational.
+     * @param consent Whether the user consented to recording. MUST be `true` or the upload is refused.
+     * @param peaks Optional capture-time waveform peaks (max-abs per bucket, normalized 0..1). When
+     *   present, persisted as a `peaks.json` sidecar beside the recording for fast waveform rendering
+     *   without re-decoding the audio.
+     * @returns A structured {@link UploadRealtimeRecordingResult} with the created `MJ: Files` id.
+     */
+    async UploadRealtimeRecording(agentSessionId, audioBase64, mimeType, ctx, durationMs, consent, peaks) {
+        const { contextUser, provider } = this.requireUserAndProvider(ctx.userPayload, ctx.providers);
+        const session = await this.loadOwnedSession(agentSessionId, contextUser, provider);
+        // HARD consent gate — no audio is ever stored without an explicit grant.
+        if (consent !== true) {
+            return { Success: false, ErrorMessage: 'Recording consent was not granted.' };
+        }
+        try {
+            const agent = await provider.GetEntityObject('MJ: AI Agents', contextUser);
+            if (!(await agent.Load(session.AgentID))) {
+                return { Success: false, ErrorMessage: `Co-agent ${session.AgentID} for the session could not be loaded.` };
+            }
+            const accountID = await resolveRecordingStorageAccountID(agent, contextUser, provider);
+            if (!accountID) {
+                return { Success: false, ErrorMessage: 'No recording storage account is configured for this agent.' };
+            }
+            const buffer = Buffer.from(audioBase64, 'base64');
+            if (buffer.length === 0) {
+                return { Success: false, ErrorMessage: 'The uploaded recording was empty.' };
+            }
+            const fileID = await storeRealtimeRecording({
+                Audio: buffer,
+                MimeType: mimeType,
+                Media: 'Audio',
+                StartedAt: session.RecordingStartedAt ?? new Date(),
+                StorageAccountID: accountID,
+                SessionID: agentSessionId,
+                ContextUser: contextUser,
+                Provider: provider,
+                // Sanitized capture-time waveform peaks → persisted as a peaks.json sidecar.
+                Peaks: this.sanitizePeaks(peaks),
+            });
+            // Canonical consolidated file written — drop the crash-recovery shards (best-effort).
+            if (fileID) {
+                await deleteRealtimeRecordingSegments(agentSessionId, accountID, contextUser);
+            }
+            return {
+                Success: !!fileID,
+                FileID: fileID ?? undefined,
+                ErrorMessage: fileID ? undefined : 'Storage upload failed.',
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            LogError(`RealtimeClientSessionResolver.UploadRealtimeRecording failed for session ${agentSessionId}: ${message}`);
+            return { Success: false, ErrorMessage: message };
+        }
+    }
+    /**
+     * Uploads ONE crash-recovery audio shard (~15s) for an IN-PROGRESS recording into the session's
+     * folder (`realtime-recordings/<sessionId>/seg-NNNN.<ext>`) as a raw storage object. Durability
+     * insurance during a live call so a browser/tab death loses at most the last window; the shards are
+     * deleted once the canonical consolidated file lands via {@link UploadRealtimeRecording}. Ownership-
+     * gated; consent was already established at session start. Best-effort — returns `false` (never
+     * throws) on any problem so a failed shard never disrupts the live call.
+     *
+     * @param agentSessionId The in-progress session (ownership-gated).
+     * @param segmentIndex 0-based shard index within the session.
+     * @param audioBase64 The base64-encoded shard bytes.
+     * @param mimeType The audio MIME type.
+     * @returns `true` when the shard was stored.
+     */
+    async UploadRealtimeRecordingSegment(agentSessionId, segmentIndex, audioBase64, mimeType, ctx) {
+        try {
+            const { contextUser, provider } = this.requireUserAndProvider(ctx.userPayload, ctx.providers);
+            const session = await this.loadOwnedSession(agentSessionId, contextUser, provider);
+            const agent = await provider.GetEntityObject('MJ: AI Agents', contextUser);
+            if (!(await agent.Load(session.AgentID))) {
+                return false;
+            }
+            const accountID = await resolveRecordingStorageAccountID(agent, contextUser, provider);
+            if (!accountID) {
+                return false;
+            }
+            const buffer = Buffer.from(audioBase64, 'base64');
+            if (buffer.length === 0) {
+                return false;
+            }
+            return await writeRealtimeRecordingSegment({
+                SessionID: agentSessionId,
+                SegmentIndex: segmentIndex,
+                Audio: buffer,
+                MimeType: mimeType,
+                StorageAccountID: accountID,
+                ContextUser: contextUser,
+            });
+        }
+        catch (error) {
+            LogError(`RealtimeClientSessionResolver.UploadRealtimeRecordingSegment failed for session ${agentSessionId}: ${error instanceof Error ? error.message : String(error)}`);
+            return false;
+        }
+    }
     /**
      * Relays a co-agent CHANNEL tool-call (browser_ / Whiteboard_ etc.) onto the session's co-agent
      * AIPromptRun.Messages — run-only observability so the run captures what the co-agent DID, not just
@@ -525,6 +696,22 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
     clampTokenDelta(value) {
         return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
     }
+    /**
+     * Sanitizes client-supplied waveform peaks before they're persisted: drops anything that isn't a
+     * finite number, clamps each to `[0, 1]`, and caps the array length so a hostile client can't bloat
+     * the sidecar. Returns `undefined` for a missing/empty array (no sidecar written).
+     */
+    sanitizePeaks(peaks) {
+        if (!Array.isArray(peaks) || peaks.length === 0) {
+            return undefined;
+        }
+        const MAX_PEAKS = 4096; // generous ceiling above the client's ~600-bucket target
+        const cleaned = peaks
+            .slice(0, MAX_PEAKS)
+            .filter((v) => Number.isFinite(v))
+            .map((v) => (v < 0 ? 0 : v > 1 ? 1 : v));
+        return cleaned.length > 0 ? cleaned : undefined;
+    }
     /**
      * Reads the co-agent `AIPromptRun` id from the session config WITHOUT the relay path's
      * throw-on-missing-target semantics — usage relay is best-effort, so a missing/malformed
@@ -1014,12 +1201,15 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
      *   (from {@link loadPriorTranscript}) — the service frames it into the system prompt so a
      *   resumed session remembers the previous leg(s).
      */
-    async prepareClientSessionOrClose(session, coAgentID, targetAgentId, contextUser, provider, preferredModelId, clientTools, priorTranscript, configOverridesJson) {
+    async prepareClientSessionOrClose(session, coAgentID, targetAgentId, contextUser, provider, preferredModelId, clientTools, priorTranscript, configOverridesJson, maxSessionSeconds, applicationId, appContext) {
         const prep = await this.clientSessionService.PrepareClientSession({
             CoAgentID: coAgentID,
             TargetAgentID: targetAgentId,
             AgentSessionID: session.ID,
             ConversationID: session.ConversationID ?? undefined,
+            // Server-authoritative voice duration cap (widget guests) — bounds the driver session
+            // where supported; the janitor enforces the session deadline regardless.
+            MaxSessionSeconds: maxSessionSeconds,
             // MVP: conversation history is not yet hydrated into ChatMessage[]; the co-agent
             // companion prompt runs without prior turns. A later phase loads the session's
             // Conversation into ChatMessage[] for richer context.
@@ -1033,13 +1223,17 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
             PriorTranscript: priorTranscript,
             // Pre-authorized runtime override layer (assertRuntimeOverridesAuthorized gated it).
             ConfigOverridesJson: configOverridesJson,
+            // App awareness (Move 1/3/4): the app sources the app cascade layer + RelevantAgents
+            // (allowed-agent union); the snapshot is injected into the system prompt at mint.
+            ApplicationID: applicationId,
+            AppContext: appContext,
         }, contextUser, provider);
         if (!prep.Success || !prep.ClientConfig) {
             // Prep failure is an ERROR close, not an explicit user hang-up — stamp it as such.
             await this.sessionManager.CloseSession(session.ID, contextUser, provider, 'Error');
             throw new Error(prep.ErrorMessage ?? 'Failed to prepare the client realtime session.');
         }
-        await this.persistObservabilityRunIDs(session, targetAgentId, prep.CoAgentRunID, prep.PromptRunID, prep.CoAgentRunStepID);
+        await this.persistObservabilityRunIDs(session, targetAgentId, prep.CoAgentRunID, prep.PromptRunID, prep.CoAgentRunStepID, applicationId, prep.EffectiveConfig?.realtime?.allowedAgents);
         const cfg = prep.ClientConfig;
         return {
             AgentSessionId: session.ID,
@@ -1061,8 +1255,19 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
      * finalize the runs (and on relay to nest delegated runs). Best-effort: a save failure is logged,
      * not thrown — the voice session still proceeds, it just won't carry the run ids.
      */
-    async persistObservabilityRunIDs(session, targetAgentID, coAgentRunID, promptRunID, coAgentRunStepID) {
-        const config = { targetAgentID, coAgentRunID, promptRunID, coAgentRunStepID };
+    async persistObservabilityRunIDs(session, targetAgentID, coAgentRunID, promptRunID, coAgentRunStepID, applicationID, allowedAgents) {
+        // Preserve any server-authoritative voice deadline stamped at session start (this rebuilds the
+        // full config, so read the existing value forward rather than dropping it).
+        const existing = this.tryReadSessionConfig(session);
+        const config = {
+            targetAgentID,
+            coAgentRunID,
+            promptRunID,
+            coAgentRunStepID,
+            maxSessionDeadlineIso: existing?.maxSessionDeadlineIso,
+            applicationID,
+            allowedAgents: allowedAgents && allowedAgents.length > 0 ? allowedAgents : undefined,
+        };
         session.Config_ = JSON.stringify(config);
         const saved = await session.Save();
         if (!saved) {
@@ -1545,6 +1750,28 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
             LogError(`SaveSessionChannelArtifact: LastActiveAt stamp failed: ${error.message}`);
         }
     }
+    /**
+     * Tolerantly parses the `appContextJson` mutation arg into an {@link AppContextSnapshot}. Returns
+     * `undefined` for absent/blank/malformed/non-object payloads — app context is best-effort enrichment
+     * and must never fail a session start.
+     *
+     * @param appContextJson The raw JSON string the browser sent, or undefined.
+     * @returns The parsed snapshot, or `undefined`.
+     */
+    parseAppContext(appContextJson) {
+        if (!appContextJson || !appContextJson.trim()) {
+            return undefined;
+        }
+        try {
+            const parsed = JSON.parse(appContextJson);
+            return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+                ? parsed
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
     /**
      * Tolerantly parses + validates client-declared UI tool definitions (see the SECURITY NOTE on
      * {@link StartRealtimeClientSession}). Never throws — any rejection logs and returns
@@ -1613,6 +1840,9 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
                         promptRunID: typeof parsed.promptRunID === 'string' ? parsed.promptRunID : undefined,
                         coAgentRunStepID: typeof parsed.coAgentRunStepID === 'string' ? parsed.coAgentRunStepID : undefined,
                         pendingFeedbackRunID: typeof parsed.pendingFeedbackRunID === 'string' ? parsed.pendingFeedbackRunID : undefined,
+                        maxSessionDeadlineIso: typeof parsed.maxSessionDeadlineIso === 'string' ? parsed.maxSessionDeadlineIso : undefined,
+                        applicationID: typeof parsed.applicationID === 'string' ? parsed.applicationID : undefined,
+                        allowedAgents: Array.isArray(parsed.allowedAgents) ? parsed.allowedAgents : undefined,
                     };
                 }
             }
@@ -1622,13 +1852,58 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
         }
         throw new Error(`Realtime session ${session.ID} has no target agent configured`);
     }
+    /** Like {@link readSessionConfig} but returns `undefined` instead of throwing (for best-effort reads). */
+    tryReadSessionConfig(session) {
+        try {
+            return this.readSessionConfig(session);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Resolves the server-authoritative voice duration cap (seconds) for a session start, or `undefined`
+     * when no cap applies (the common, uncapped case). A cap applies only when the caller is a public
+     * web-widget guest with a configured `VoiceMaxSessionMinutes` on its widget instance (the same value
+     * surfaced to the client guard at mint). Never throws — a resolution failure yields no cap rather
+     * than blocking the start.
+     */
+    async resolveWidgetVoiceCapSeconds(userPayload, providers) {
+        const elevation = await resolveWidgetGuestRunContext(userPayload, GetReadWriteProvider(providers));
+        const minutes = elevation?.widget.VoiceMaxSessionMinutes;
+        return minutes && minutes > 0 ? minutes * 60 : undefined;
+    }
     /**
      * Persists a single transcript turn as a `Conversation Detail` stamped with the session's
      * conversation, the mapped role, the turn text, the session id, and the owning user.
      *
      * @returns The boolean save result (logs `CompleteMessage` on failure).
      */
-    async persistTranscriptTurn(session, role, text, contextUser, provider) {
+    /**
+     * Stamps `RecordingStartedAt` (the recording `t0` alignment origin) + `RecordingMedia` on a
+     * just-started session when the browser captured WITH consent. Best-effort: a parse/save failure
+     * is logged and swallowed — a recording-metadata problem must never fail the session start.
+     *
+     * @param session The freshly created/loaded session.
+     * @param recordingConsent Whether the user consented to recording — only `true` stamps anything.
+     * @param recordingStartedAt ISO-8601 recording start timestamp from the browser.
+     */
+    async stampRecordingStart(session, recordingConsent, recordingStartedAt) {
+        if (recordingConsent !== true || !recordingStartedAt) {
+            return;
+        }
+        const startedAt = new Date(recordingStartedAt);
+        if (Number.isNaN(startedAt.getTime())) {
+            LogError(`RealtimeClientSessionResolver.stampRecordingStart: invalid recordingStartedAt '${recordingStartedAt}' for session ${session.ID}`);
+            return;
+        }
+        session.RecordingStartedAt = startedAt;
+        session.RecordingMedia = 'Audio';
+        if (!(await session.Save())) {
+            LogError(`RealtimeClientSessionResolver.stampRecordingStart save failed: ${session.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+        }
+    }
+    async persistTranscriptTurn(session, role, text, contextUser, provider, utteranceStartMs, utteranceEndMs) {
         const detail = await provider.GetEntityObject(CONVERSATION_DETAIL_ENTITY, contextUser);
         detail.NewRecord();
         detail.ConversationID = session.ConversationID;
@@ -1636,6 +1911,12 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
         detail.Message = text;
         detail.AgentSessionID = session.ID;
         detail.UserID = contextUser.ID;
+        if (typeof utteranceStartMs === 'number' && utteranceStartMs >= 0) {
+            detail.UtteranceStartMs = utteranceStartMs;
+        }
+        if (typeof utteranceEndMs === 'number' && utteranceEndMs >= 0) {
+            detail.UtteranceEndMs = utteranceEndMs;
+        }
         const saved = await detail.Save();
         if (!saved) {
             LogError(`RealtimeClientSessionResolver.persistTranscriptTurn save failed: ${detail.LatestResult?.CompleteMessage ?? 'unknown error'}`);
@@ -1649,7 +1930,7 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
      * appending a near-duplicate. Falls back to a plain insert when no prior turn exists
      * (the superseded turn may have failed to persist) — a correction is never dropped.
      */
-    async replacePreviousTranscriptTurn(session, role, text, contextUser, provider) {
+    async replacePreviousTranscriptTurn(session, role, text, contextUser, provider, utteranceStartMs, utteranceEndMs) {
         const mappedRole = this.mapTranscriptRole(role);
         const rv = RunView.FromMetadataProvider(provider);
         const result = await rv.RunView({
@@ -1661,9 +1942,17 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
         }, contextUser);
         const previous = result.Success ? (result.Results?.[0] ?? null) : null;
         if (!previous) {
-            return this.persistTranscriptTurn(session, role, text, contextUser, provider);
+            return this.persistTranscriptTurn(session, role, text, contextUser, provider, utteranceStartMs, utteranceEndMs);
         }
         previous.Message = text;
+        // The correction extends the existing turn: always refresh the end boundary when provided,
+        // but only set the start when it wasn't already captured on the superseded turn.
+        if (typeof utteranceEndMs === 'number' && utteranceEndMs >= 0) {
+            previous.UtteranceEndMs = utteranceEndMs;
+        }
+        if (typeof utteranceStartMs === 'number' && utteranceStartMs >= 0 && previous.UtteranceStartMs == null) {
+            previous.UtteranceStartMs = utteranceStartMs;
+        }
         const saved = await previous.Save();
         if (!saved) {
             LogError(`RealtimeClientSessionResolver.replacePreviousTranscriptTurn save failed: ${previous.LatestResult?.CompleteMessage ?? 'unknown error'}`);
@@ -1689,8 +1978,13 @@ __decorate([
     __param(5, Arg('clientToolsJson', () => String, { nullable: true })),
     __param(6, Arg('coAgentId', () => String, { nullable: true })),
     __param(7, Arg('configOverridesJson', () => String, { nullable: true })),
+    __param(8, Arg('recordingStartedAt', () => String, { nullable: true })),
+    __param(9, Arg('recordingConsent', () => Boolean, { nullable: true })),
+    __param(10, Arg('mediaCollectionId', () => String, { nullable: true })),
+    __param(11, Arg('applicationId', () => String, { nullable: true })),
+    __param(12, Arg('appContextJson', () => String, { nullable: true })),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [String, Object, String, String, String, String, String, String]),
+    __metadata("design:paramtypes", [String, Object, String, String, String, String, String, String, String, Boolean, String, String, String]),
     __metadata("design:returntype", Promise)
 ], RealtimeClientSessionResolver.prototype, "StartRealtimeClientSession", null);
 __decorate([
@@ -1712,10 +2006,36 @@ __decorate([
     __param(2, Arg('text', () => String)),
     __param(3, Ctx()),
     __param(4, Arg('replacesPrevious', () => Boolean, { nullable: true })),
+    __param(5, Arg('utteranceStartMs', () => Int, { nullable: true })),
+    __param(6, Arg('utteranceEndMs', () => Int, { nullable: true })),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [String, String, String, Object, Boolean]),
+    __metadata("design:paramtypes", [String, String, String, Object, Boolean, Number, Number]),
     __metadata("design:returntype", Promise)
 ], RealtimeClientSessionResolver.prototype, "RelayRealtimeTranscript", null);
+__decorate([
+    Mutation(() => UploadRealtimeRecordingResult),
+    __param(0, Arg('agentSessionId', () => String)),
+    __param(1, Arg('audioBase64', () => String)),
+    __param(2, Arg('mimeType', () => String)),
+    __param(3, Ctx()),
+    __param(4, Arg('durationMs', () => Int, { nullable: true })),
+    __param(5, Arg('consent', () => Boolean, { nullable: true })),
+    __param(6, Arg('peaks', () => [Float], { nullable: true })),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String, String, Object, Number, Boolean, Array]),
+    __metadata("design:returntype", Promise)
+], RealtimeClientSessionResolver.prototype, "UploadRealtimeRecording", null);
+__decorate([
+    Mutation(() => Boolean),
+    __param(0, Arg('agentSessionId', () => String)),
+    __param(1, Arg('segmentIndex', () => Int)),
+    __param(2, Arg('audioBase64', () => String)),
+    __param(3, Arg('mimeType', () => String)),
+    __param(4, Ctx()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Number, String, String, Object]),
+    __metadata("design:returntype", Promise)
+], RealtimeClientSessionResolver.prototype, "UploadRealtimeRecordingSegment", null);
 __decorate([
     Mutation(() => Boolean),
     __param(0, Arg('agentSessionId', () => String)),