@memberjunction/server 5.42.0 → 5.44.0

package/dist/resolvers/RealtimeClientSessionResolver.d.ts

@@ -116,6 +116,20 @@ export declare class CancelRealtimeSessionToolResult {
     /** Human-readable failure reason. Null on success. */
     ErrorMessage?: string;
 }
+/**
+ * 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.
+ */
+export declare class UploadRealtimeRecordingResult {
+    /** True when the audio was stored and the session was stamped with the recording file. */
+    Success: boolean;
+    /** Human-readable failure reason. Null on success. */
+    ErrorMessage?: string;
+    /** ID of the created `MJ: Files` row holding the uploaded recording. Null on failure. */
+    FileID?: string;
+}
 /**
  * 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
@@ -163,7 +177,7 @@ export declare class RealtimeClientSessionResolver extends ResolverBase {
      *
      * @returns The ephemeral config + session linkage the browser needs to open its socket.
      */
-    StartRealtimeClientSession(targetAgentId: string | undefined, { userPayload, providers }: AppContext, conversationId?: string, lastSessionId?: string, preferredModelId?: string, clientToolsJson?: string, coAgentId?: string, configOverridesJson?: string): Promise<StartRealtimeClientSessionResult>;
+    StartRealtimeClientSession(targetAgentId: string | undefined, { userPayload, providers }: AppContext, conversationId?: string, lastSessionId?: string, preferredModelId?: string, clientToolsJson?: string, coAgentId?: string, configOverridesJson?: string, recordingStartedAt?: string, recordingConsent?: boolean, mediaCollectionId?: string, applicationId?: string, appContextJson?: string): Promise<StartRealtimeClientSessionResult>;
     /**
      * Execute a single tool call the browser relayed from its provider socket and return the
      * serialized result for the browser to relay back to the model.
@@ -202,13 +216,53 @@ export declare class RealtimeClientSessionResolver extends ResolverBase {
      *
      * @returns `true` when the transcript turn was persisted.
      */
-    RelayRealtimeTranscript(agentSessionId: string, role: string, text: string, { userPayload, providers }: AppContext, replacesPrevious?: boolean): Promise<boolean>;
+    RelayRealtimeTranscript(agentSessionId: string, role: string, text: string, { userPayload, providers }: AppContext, replacesPrevious?: boolean, utteranceStartMs?: number, utteranceEndMs?: number): Promise<boolean>;
     /**
      * Maps the relayed transcript role (`'User'`/`'AI'`/`'Assistant'`, case-insensitive) to the
      * standard chat-message role stored in `AIPromptRun.Messages`. Anything that isn't an explicit
      * user turn is treated as the assistant (the co-agent's own speech).
      */
     private mapTranscriptRoleToChatRole;
+    /**
+     * 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.
+     */
+    UploadRealtimeRecording(agentSessionId: string, audioBase64: string, mimeType: string, ctx: AppContext, durationMs?: number, consent?: boolean, peaks?: number[]): Promise<UploadRealtimeRecordingResult>;
+    /**
+     * 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.
+     */
+    UploadRealtimeRecordingSegment(agentSessionId: string, segmentIndex: number, audioBase64: string, mimeType: string, ctx: AppContext): Promise<boolean>;
     /**
      * 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
@@ -266,6 +320,12 @@ export declare class RealtimeClientSessionResolver extends ResolverBase {
     RelayRealtimeUsage(agentSessionId: string, inputTokens: number, outputTokens: number, { userPayload, providers }: AppContext): Promise<boolean>;
     /** Clamps a relayed token delta: negative / non-finite values become 0. */
     private clampTokenDelta;
+    /**
+     * 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).
+     */
+    private sanitizePeaks;
     /**
      * 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
@@ -643,6 +703,15 @@ export declare class RealtimeClientSessionResolver extends ResolverBase {
      * session-channel row is a silent no-op; failures log and never throw.
      */
     private stampSessionChannelLastActive;
+    /**
+     * 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`.
+     */
+    private parseAppContext;
     /**
      * Tolerantly parses + validates client-declared UI tool definitions (see the SECURITY NOTE on
      * {@link StartRealtimeClientSession}). Never throws — any rejection logs and returns
@@ -669,6 +738,16 @@ export declare class RealtimeClientSessionResolver extends ResolverBase {
      *
      * @returns The boolean save result (logs `CompleteMessage` on failure).
      */
+    /**
+     * 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.
+     */
+    private stampRecordingStart;
     private persistTranscriptTurn;
     /**
      * CORRECTION persistence (the client transcript's `ReplacesPrevious` marker — e.g.

package/dist/resolvers/RealtimeClientSessionResolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RealtimeClientSessionResolver.d.ts","sourceRoot":"","sources":["../../src/resolvers/RealtimeClientSessionResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAAgE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC1G,OAAO,EAAE,UAAU,EAAe,MAAM,aAAa,CAAC;AAyBtD,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AA2G1D;;;GAGG;AACH,qBACa,gCAAgC;IACzC,uDAAuD;IAEvD,cAAc,EAAE,MAAM,CAAC;IAEvB,uFAAuF;IAEvF,cAAc,EAAE,MAAM,CAAC;IAEvB,iEAAiE;IAEjE,QAAQ,EAAE,MAAM,CAAC;IAEjB,qFAAqF;IAErF,KAAK,EAAE,MAAM,CAAC;IAEd,0FAA0F;IAE1F,cAAc,EAAE,MAAM,CAAC;IAEvB,mGAAmG;IAEnG,SAAS,EAAE,MAAM,CAAC;IAElB,sFAAsF;IAEtF,iBAAiB,EAAE,MAAM,CAAC;IAE1B,sGAAsG;IAEtG,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;OAIG;IAEH,6BAA6B,CAAC,EAAE,MAAM,CAAC;IAEvC;;;;;;OAMG;IAEH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAEhC;;;;;OAKG;IAEH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;;OAMG;IAEH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;GAGG;AACH,qBACa,gCAAgC;IACzC,kEAAkE;IAElE,OAAO,EAAE,OAAO,CAAC;IAEjB,sDAAsD;IAEtD,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,gGAAgG;IAEhG,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,kFAAkF;IAElF,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;;;;OAKG;IAEH,wBAAwB,EAAE,OAAO,CAAC;CACrC;AAED;;;;;GAKG;AACH,qBACa,+BAA+B;IACxC;;;OAGG;IAEH,YAAY,EAAE,MAAM,CAAC;IAErB,oFAAoF;IAEpF,OAAO,EAAE,OAAO,CAAC;IAEjB,sDAAsD;IAEtD,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,qBACa,6BAA8B,SAAQ,YAAY;IAC3D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAwB;IACvD,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAsC;IAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IAEG,0BAA0B,CAC4B,aAAa,EAAE,MAAM,GAAG,SAAS,EAClF,EAAE,WAAW,EAAE,SAAS,EAAE,EAAE,UAAU,EACY,cAAc,CAAC,EAAE,MAAM,EACxB,aAAa,CAAC,EAAE,MAAM,EACnB,gBAAgB,CAAC,EAAE,MAAM,EAC1B,eAAe,CAAC,EAAE,MAAM,EAC9B,SAAS,CAAC,EAAE,MAAM,EACR,mBAAmB,CAAC,EAAE,MAAM,GAC3F,OAAO,CAAC,gCAAgC,CAAC;IA0C5C;;;;;;;;OAQG;IAEG,0BAA0B,CACS,cAAc,EAAE,MAAM,EAC9B,MAAM,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EACxC,EAAE,WAAW,EAAE,SAAS,EAAE,EAAE,UAAU,EACnC,MAAM,EAAE,YAAY,GAC/B,OAAO,CAAC,MAAM,CAAC;IAgClB;;;;;;OAMG;IACH,OAAO,CAAC,+BAA+B;IAyBvC;;;;;OAKG;YACW,0BAA0B;IAwBxC;;;;;;;;;;;;OAYG;IAEG,uBAAuB,CACY,cAAc,EAAE,MAAM,EAChC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EAChC,EAAE,WAAW,EAAE,SAAS,EAAE,EAAE,UAAU,EACe,gBAAgB,CAAC,EAAE,OAAO,GACvF,OAAO,CAAC,OAAO,CAAC;IA2BnB;;;;OAIG;IACH,OAAO,CAAC,2BAA2B;IAInC;;;;;;;OAOG;IAEG,qBAAqB,CACc,cAAc,EAAE,MAAM,EAC5B,QAAQ,EAAE,MAAM,EACxC,EAAE,WAAW,EAAE,SAAS,EAAE,EAAE,UAAU,EACM,QAAQ,CAAC,EAAE,MAAM,EACf,UAAU,CAAC,EAAE,MAAM,GACzE,OAAO,CAAC,OAAO,CAAC;IAiBnB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAUtB;;;;;;;;;;;;;;;;;;OAkBG;IAEG,yBAAyB,CACU,cAAc,EAAE,MAAM,EACpD,EAAE,WAAW,EAAE,SAAS,EAAE,EAAE,UAAU,EACI,MAAM,CAAC,EAAE,MAAM,GACjE,OAAO,CAAC,+BAA+B,CAAC;IAa3C;;;;;;;;;;;;;;;;;;;OAmBG;IAEG,kBAAkB,CACiB,cAAc,EAAE,MAAM,EAC5B,WAAW,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EAC7C,EAAE,WAAW,EAAE,SAAS,EAAE,EAAE,UAAU,GAC9C,OAAO,CAAC,OAAO,CAAC;IAmBnB,2EAA2E;IAC3E,OAAO,CAAC,eAAe;IAIvB;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAiBvB;;;;;;;;;;;;;;;;;;;;OAoBG;IAEG,uBAAuB,CACY,cAAc,EAAE,MAAM,EACzB,WAAW,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,EAC1C,EAAE,WAAW,EAAE,SAAS,EAAE,EAAE,UAAU,GAC9C,OAAO,CAAC,OAAO,CAAC;IAqBnB;;;;;;OAMG;YACW,wBAAwB;IAoBtC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IAEG,0BAA0B,CACS,cAAc,EAAE,MAAM,EACzB,WAAW,EAAE,MAAM,EAC1B,IAAI,EAAE,MAAM,EACL,WAAW,EAAE,MAAM,EAC9C,EAAE,WAAW,EAAE,SAAS,EAAE,EAAE,UAAU,GAC9C,OAAO,CAAC,gCAAgC,CAAC;IA4B5C,iGAAiG;IACjG,OAAO,CAAC,sBAAsB;IAW9B;;;OAGG;YACW,kBAAkB;IAahC;;;;;;;;;;;;;;;;;;;;OAoBG;YACW,+BAA+B;IAwC7C;;;;;;;;;OASG;YACW,eAAe;IAwB7B;;;;;OAKG;YACW,sBAAsB;IAMpC;;;;;;;;;;;;OAYG;YACW,gCAAgC;IA2B9C;;;;OAIG;IACH,OAAO,CAAC,8BAA8B;IActC;;;;;;;;OAQG;IACH,OAAO,CAAC,+BAA+B;IAiBvC;;;;;OAKG;IACH,OAAO,CAAC,8BAA8B;IAuBtC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;YACW,gBAAgB;IAiD9B;;;;;;;OAOG;YACW,wBAAwB;IA0BtC;;;;;OAKG;IACH,OAAO,CAAC,sBAAsB;IAe9B;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAoBxB;;;;;;;OAOG;IACH,OAAO,CAAC,sBAAsB;IAmB9B,4FAA4F;IAC5F,OAAO,CAAC,eAAe;IAKvB;;;;;;;;;OASG;YACW,2BAA2B;IA2DzC;;;;;OAKG;YACW,0BAA0B;IAiBxC;;;OAGG;YACW,sBAAsB;IAYpC;;;;OAIG;YACW,gBAAgB;IAmB9B;;;;;;;OAOG;YACW,gBAAgB;IA2B9B;;;;OAIG;YACW,yBAAyB;IAuCvC;;;;;;;;;;;;;OAaG;YACW,0BAA0B;IA8CxC;;;;;;;;;;;;;;;;;;;OAmBG;YACW,mBAAmB;IAwBjC;;;;OAIG;YACW,uBAAuB;IAqCrC;;;OAGG;YACW,wBAAwB;IA8BtC;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAW1B;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAuB5B;;;;OAIG;YACW,+BAA+B;IA0B7C;;;;;OAKG;YACW,qBAAqB;IAwCnC;;;;;;;OAOG;YACW,gCAAgC;IAqB9C;;;;;;;;;;;;;;;;;;;;OAoBG;YACW,oCAAoC;IAwBlD;;;OAGG;YACW,yBAAyB;IAsBvC;;;;;OAKG;YACW,+BAA+B;IAuB7C;;;OAGG;YACW,0BAA0B;IAwBxC;;;;OAIG;YACW,6BAA6B;IAqC3C;;;;;;;;;;OAUG;IACH,OAAO,CAAC,gBAAgB;IA8BxB,wHAAwH;IACxH,OAAO,CAAC,iBAAiB;IAYzB;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAsBzB;;;;;OAKG;YACW,qBAAqB;IA2BnC;;;;;;OAMG;YACW,6BAA6B;IAiC3C;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;CAG5B"}
+{"version":3,"file":"RealtimeClientSessionResolver.d.ts","sourceRoot":"","sources":["../../src/resolvers/RealtimeClientSessionResolver.ts"],"names":[],"mappings":"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"}

package/dist/resolvers/RealtimeClientSessionResolver.js

@@ -36,12 +36,12 @@ 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';
@@ -222,6 +222,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 +296,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
@@ -285,6 +309,19 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
         // silent ignore). Plain starts and within-pairing target selection are never gated here.
         await this.assertRuntimeOverridesAuthorized(coAgentID, configOverridesJson, preferredModelId, contextUser, provider);
         const config = { targetAgentID: effectiveTargetId };
+        // 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 +329,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, 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 +358,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 +420,8 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
             promptRunID: config.promptRunID,
             coAgentRunStepID: config.coAgentRunStepID,
             pendingFeedbackRunID: pausedRunID,
+            applicationID: config.applicationID,
+            allowedAgents: config.allowedAgents,
         };
         session.Config_ = JSON.stringify(next);
         if (!(await session.Save())) {
@@ -397,12 +441,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 +467,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 +685,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,7 +1190,7 @@ 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, applicationId, appContext) {
         const prep = await this.clientSessionService.PrepareClientSession({
             CoAgentID: coAgentID,
             TargetAgentID: targetAgentId,
@@ -1033,13 +1209,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 +1241,11 @@ 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) {
+        const config = {
+            targetAgentID, coAgentRunID, promptRunID, coAgentRunStepID, applicationID,
+            allowedAgents: allowedAgents && allowedAgents.length > 0 ? allowedAgents : undefined,
+        };
         session.Config_ = JSON.stringify(config);
         const saved = await session.Save();
         if (!saved) {
@@ -1545,6 +1728,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 +1818,8 @@ 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,
+                        applicationID: typeof parsed.applicationID === 'string' ? parsed.applicationID : undefined,
+                        allowedAgents: Array.isArray(parsed.allowedAgents) ? parsed.allowedAgents : undefined,
                     };
                 }
             }
@@ -1628,7 +1835,31 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
      *
      * @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 +1867,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 +1886,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 +1898,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 +1934,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 +1962,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)),