@memberjunction/ai-agents 5.43.0 → 5.44.0

package/dist/realtime/realtime-recording-capture.js

@@ -0,0 +1,317 @@
+/**
+ * @fileoverview Pure, zero-dependency server-side audio recording utility for
+ * MemberJunction realtime sessions.
+ *
+ * Accumulates realtime PCM audio frames (model output + user input), mixes them
+ * into a single mono PCM16 timeline, and encodes a canonical WAV file. The only
+ * runtime dependency is the Node `Buffer` global — no external npm packages.
+ *
+ * @module @memberjunction/ai-agents/realtime/realtime-recording-capture
+ */
+/** Lowest value representable by signed 16-bit PCM. */
+const PCM16_MIN = -32768;
+/** Highest value representable by signed 16-bit PCM. */
+const PCM16_MAX = 32767;
+/** Canonical WAV/PCM header size in bytes. */
+const WAV_HEADER_BYTES = 44;
+/** Default waveform resolution (bucket count) produced by {@link RealtimeRecordingController.GetPeaks}. */
+const DEFAULT_PEAK_BUCKETS = 600;
+/**
+ * Accumulates realtime PCM audio frames from both the model (outbound) and the
+ * user (inbound) and mixes them into a single mono PCM16 WAV on demand.
+ *
+ * Lifecycle: construct → {@link Start} → {@link AppendOutbound}/{@link AppendInbound}
+ * (many) → {@link Stop} → {@link EncodeWav}. {@link Reset} returns the instance to
+ * a pristine state so it can be reused.
+ */
+export class RealtimeRecordingController {
+    constructor(options) {
+        this.recording = false;
+        this.startedAt = null;
+        this.startEpochMs = null;
+        this.outboundFrames = [];
+        this.inboundFrames = [];
+        this.outputSampleRate = options?.OutputSampleRate ?? 24000;
+        this.inputSampleRate = options?.InputSampleRate ?? 24000;
+        this.media = options?.Media ?? 'Audio';
+        this.now = options?.Now ?? (() => Date.now());
+    }
+    /** Stamp t0 and begin accepting frames. Idempotent (second call is a no-op). */
+    Start() {
+        if (this.recording) {
+            return;
+        }
+        const epoch = this.now();
+        this.startEpochMs = epoch;
+        this.startedAt = new Date(epoch);
+        this.recording = true;
+    }
+    /** Stop accepting frames. Idempotent. Does NOT clear buffers. */
+    Stop() {
+        this.recording = false;
+    }
+    /** Clear all state so the instance can be reused. */
+    Reset() {
+        this.recording = false;
+        this.startedAt = null;
+        this.startEpochMs = null;
+        this.outboundFrames = [];
+        this.inboundFrames = [];
+    }
+    get IsRecording() {
+        return this.recording;
+    }
+    /** The wall-clock moment {@link Start} stamped, or null if never started. */
+    get StartedAt() {
+        return this.startedAt;
+    }
+    get Media() {
+        return this.media;
+    }
+    /** Whether any non-empty frame was captured. */
+    get HasAudio() {
+        return this.frameHasSamples(this.outboundFrames) || this.frameHasSamples(this.inboundFrames);
+    }
+    /** ms since {@link Start} per the injected clock; 0 if not started (never negative). */
+    NowOffsetMs() {
+        if (this.startEpochMs == null) {
+            return 0;
+        }
+        const delta = this.now() - this.startEpochMs;
+        return delta > 0 ? delta : 0;
+    }
+    /**
+     * Append a model-output audio frame (ArrayBuffer of little-endian PCM16).
+     * No-op if not recording or empty. The bytes are copied — the caller's
+     * ArrayBuffer is not retained.
+     */
+    AppendOutbound(chunk) {
+        this.appendFrame(this.outboundFrames, chunk);
+    }
+    /** Append a user-input audio frame. Same contract as {@link AppendOutbound}. */
+    AppendInbound(chunk) {
+        this.appendFrame(this.inboundFrames, chunk);
+    }
+    /**
+     * Mix everything captured into a mono PCM16 WAV.
+     * @returns The encoded buffer, duration, and sample rate; or null if {@link HasAudio} is false.
+     */
+    EncodeWav() {
+        const mixed = this.mixTimeline();
+        if (!mixed) {
+            return null;
+        }
+        const buffer = this.encodeWavBuffer(mixed.Pcm, mixed.SampleRate);
+        const durationMs = (mixed.Pcm.length / mixed.SampleRate) * 1000;
+        return { Buffer: buffer, DurationMs: durationMs, SampleRate: mixed.SampleRate };
+    }
+    /**
+     * Compute capture-time waveform peaks from the accumulated PCM: a normalized `0..1` max-abs
+     * amplitude per bucket (one bucket per rendered waveform bar). Mirrors the client-direct peak
+     * math so server-bridged recordings render the same kind of waveform; the result is persisted
+     * as a `peaks.json` sidecar so a viewer renders the waveform without re-decoding the audio.
+     *
+     * @param buckets Desired bucket count (waveform resolution). Default 600; clamped to `>= 1` and
+     *   never exceeds the sample count (a short recording yields at most one peak per sample).
+     * @returns A bounded array of normalized `0..1` peaks; `[]` when there is no audio (or silence).
+     */
+    GetPeaks(buckets = DEFAULT_PEAK_BUCKETS) {
+        const mixed = this.mixTimeline();
+        if (!mixed) {
+            return [];
+        }
+        return this.computePeaks(mixed.Pcm, buckets);
+    }
+    // ---------------------------------------------------------------------
+    // Internal helpers
+    // ---------------------------------------------------------------------
+    /**
+     * Mix all captured frames into a single mono PCM16 timeline at the output sample rate.
+     * Shared by {@link EncodeWav} and {@link GetPeaks} so the WAV and the peaks describe the
+     * exact same signal. Returns `null` when nothing was captured.
+     */
+    mixTimeline() {
+        if (!this.HasAudio) {
+            return null;
+        }
+        const targetRate = this.outputSampleRate;
+        const timelineLength = this.computeTimelineLength(targetRate);
+        if (timelineLength <= 0) {
+            return null;
+        }
+        const accumulator = new Float64Array(timelineLength);
+        this.mixFrames(accumulator, this.outboundFrames, targetRate, this.outputSampleRate);
+        this.mixFrames(accumulator, this.inboundFrames, targetRate, this.inputSampleRate);
+        return { Pcm: this.clampToInt16(accumulator), SampleRate: targetRate };
+    }
+    /**
+     * Downsample a PCM16 timeline into `buckets` normalized `0..1` max-abs peaks. Contiguous,
+     * index-ordered buckets; the loudest bucket becomes `1`. An all-silent timeline yields `[]`.
+     */
+    computePeaks(pcm, buckets) {
+        const length = pcm.length;
+        if (length === 0) {
+            return [];
+        }
+        const count = Math.min(Math.max(1, Math.floor(buckets)), length);
+        const out = new Array(count).fill(0);
+        let globalMax = 0;
+        for (let b = 0; b < count; b++) {
+            const start = Math.floor((b * length) / count);
+            const end = b === count - 1 ? length : Math.floor(((b + 1) * length) / count);
+            let localMax = 0;
+            for (let i = start; i < end; i++) {
+                const abs = Math.abs(pcm[i]);
+                if (abs > localMax) {
+                    localMax = abs;
+                }
+            }
+            out[b] = localMax;
+            if (localMax > globalMax) {
+                globalMax = localMax;
+            }
+        }
+        if (globalMax <= 0) {
+            return [];
+        }
+        return out.map((v) => v / globalMax);
+    }
+    /** Decode + copy a chunk into a frame and push it onto the given list. */
+    appendFrame(list, chunk) {
+        if (!this.recording || chunk == null || chunk.byteLength < 2) {
+            return;
+        }
+        const samples = this.decodePcm16(chunk);
+        if (samples.length === 0) {
+            return;
+        }
+        list.push({ offsetMs: this.NowOffsetMs(), samples });
+    }
+    /**
+     * Decode a little-endian PCM16 ArrayBuffer into a copied Int16Array.
+     * Odd-length buffers (not a multiple of 2) drop the trailing byte.
+     */
+    decodePcm16(chunk) {
+        const usableBytes = chunk.byteLength - (chunk.byteLength % 2);
+        // Copy the bytes so later mutation of the caller's source is safe.
+        const copy = chunk.slice(0, usableBytes);
+        return new Int16Array(copy);
+    }
+    /** Whether any frame in the list carries at least one sample. */
+    frameHasSamples(list) {
+        return list.some((frame) => frame.samples.length > 0);
+    }
+    /** The number of target-rate samples a frame occupies (after any resample). */
+    frameTargetLength(frame, targetRate, sourceRate) {
+        if (sourceRate === targetRate) {
+            return frame.samples.length;
+        }
+        return Math.round((frame.samples.length * targetRate) / sourceRate);
+    }
+    /** Start sample index for a frame given its offset and the target rate. */
+    frameStartSample(frame, targetRate) {
+        return Math.round((frame.offsetMs * targetRate) / 1000);
+    }
+    /** The total length (in target-rate samples) needed to cover the furthest frame end. */
+    computeTimelineLength(targetRate) {
+        let maxEnd = 0;
+        const consider = (list, sourceRate) => {
+            for (const frame of list) {
+                if (frame.samples.length === 0) {
+                    continue;
+                }
+                const start = this.frameStartSample(frame, targetRate);
+                const end = start + this.frameTargetLength(frame, targetRate, sourceRate);
+                if (end > maxEnd) {
+                    maxEnd = end;
+                }
+            }
+        };
+        consider(this.outboundFrames, this.outputSampleRate);
+        consider(this.inboundFrames, this.inputSampleRate);
+        return maxEnd;
+    }
+    /** Sum each frame's (possibly resampled) samples into the mono accumulator. */
+    mixFrames(accumulator, list, targetRate, sourceRate) {
+        for (const frame of list) {
+            if (frame.samples.length === 0) {
+                continue;
+            }
+            const start = this.frameStartSample(frame, targetRate);
+            const resampled = sourceRate === targetRate ? frame.samples : this.resampleLinear(frame.samples, sourceRate, targetRate);
+            for (let i = 0; i < resampled.length; i++) {
+                const idx = start + i;
+                if (idx >= 0 && idx < accumulator.length) {
+                    accumulator[idx] += resampled[i];
+                }
+            }
+        }
+    }
+    /**
+     * Resample PCM16 samples from sourceRate to targetRate via simple linear
+     * interpolation. Returns a Float64Array (caller sums into the accumulator).
+     */
+    resampleLinear(samples, sourceRate, targetRate) {
+        const outLength = Math.round((samples.length * targetRate) / sourceRate);
+        const out = new Float64Array(outLength);
+        if (samples.length === 1) {
+            out.fill(samples[0]);
+            return out;
+        }
+        const ratio = (samples.length - 1) / Math.max(1, outLength - 1);
+        for (let i = 0; i < outLength; i++) {
+            const srcPos = i * ratio;
+            const lower = Math.floor(srcPos);
+            const upper = Math.min(lower + 1, samples.length - 1);
+            const frac = srcPos - lower;
+            out[i] = samples[lower] * (1 - frac) + samples[upper] * frac;
+        }
+        return out;
+    }
+    /** Clamp the float accumulator into the Int16 range and round to integers. */
+    clampToInt16(accumulator) {
+        const out = new Int16Array(accumulator.length);
+        for (let i = 0; i < accumulator.length; i++) {
+            let value = Math.round(accumulator[i]);
+            if (value > PCM16_MAX) {
+                value = PCM16_MAX;
+            }
+            else if (value < PCM16_MIN) {
+                value = PCM16_MIN;
+            }
+            out[i] = value;
+        }
+        return out;
+    }
+    /** Build a canonical 44-byte WAV/PCM header followed by the sample data. */
+    encodeWavBuffer(pcm, sampleRate) {
+        const numChannels = 1;
+        const bitsPerSample = 16;
+        const bytesPerSample = bitsPerSample / 8;
+        const blockAlign = numChannels * bytesPerSample;
+        const byteRate = sampleRate * blockAlign;
+        const dataSize = pcm.length * bytesPerSample;
+        const buffer = Buffer.alloc(WAV_HEADER_BYTES + dataSize);
+        // RIFF chunk descriptor
+        buffer.write('RIFF', 0, 'ascii');
+        buffer.writeUInt32LE(36 + dataSize, 4); // ChunkSize = 36 + Subchunk2Size
+        buffer.write('WAVE', 8, 'ascii');
+        // fmt sub-chunk
+        buffer.write('fmt ', 12, 'ascii');
+        buffer.writeUInt32LE(16, 16); // Subchunk1Size for PCM
+        buffer.writeUInt16LE(1, 20); // AudioFormat = PCM
+        buffer.writeUInt16LE(numChannels, 22);
+        buffer.writeUInt32LE(sampleRate, 24);
+        buffer.writeUInt32LE(byteRate, 28);
+        buffer.writeUInt16LE(blockAlign, 32);
+        buffer.writeUInt16LE(bitsPerSample, 34);
+        // data sub-chunk
+        buffer.write('data', 36, 'ascii');
+        buffer.writeUInt32LE(dataSize, 40);
+        for (let i = 0; i < pcm.length; i++) {
+            buffer.writeInt16LE(pcm[i], WAV_HEADER_BYTES + i * bytesPerSample);
+        }
+        return buffer;
+    }
+}
+//# sourceMappingURL=realtime-recording-capture.js.map

package/dist/realtime/realtime-recording-capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-recording-capture.js","sourceRoot":"","sources":["../../src/realtime/realtime-recording-capture.ts"],"names":[],"mappings":"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"}

package/dist/realtime/realtime-recording-store.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @fileoverview Shared MJStorage finalize for realtime session recordings — the single code path both
+ * the **server-bridged** capture (`BaseAgent.finalizeRealtimeRecording`) and the **client-direct**
+ * browser upload (`RealtimeClientSessionResolver.UploadRealtimeRecording`) use to: resolve the agent's
+ * recording storage account, upload the audio, link it to the `AIAgentSession`, and stamp the session's
+ * recording fields. Keeps the storage policy in one place rather than duplicated per topology.
+ *
+ * @module @memberjunction/ai-agents
+ */
+import { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { MJAIAgentEntity } from '@memberjunction/core-entities';
+import { RealtimeRecordingMedia } from './realtime-recording-capture.js';
+/**
+ * Resolves the storage account a session recording should be written to: the agent's
+ * `RecordingStorageProviderID` if set, else its `AttachmentStorageProviderID` (recordings default to the
+ * attachments account), resolved to that provider's first account. Returns `null` when nothing is
+ * configured — callers treat that as "do not record" (fail-closed).
+ *
+ * @param agent The agent whose recording/attachment storage configuration drives the choice.
+ * @returns The resolved storage account id, or `null`.
+ */
+export declare function resolveRecordingStorageAccountID(agent: MJAIAgentEntity, contextUser: UserInfo, provider?: IMetadataProvider): Promise<string | null>;
+/** Input to {@link storeRealtimeRecording}. */
+export interface StoreRealtimeRecordingInput {
+    /** The encoded recording bytes (e.g. a WAV from the server mixer, or the browser's seekable WAV). */
+    Audio: Buffer;
+    /** MIME type of the audio (`audio/wav`, `audio/webm`, `audio/ogg`, `audio/mp4`). */
+    MimeType: string;
+    /** What was captured, stamped on the session. */
+    Media: RealtimeRecordingMedia;
+    /** The recording `t0` (alignment origin), stamped on the session. */
+    StartedAt: Date;
+    /** The resolved storage account id (see {@link resolveRecordingStorageAccountID}). */
+    StorageAccountID: string;
+    /** The `AIAgentSession` id the recording belongs to. */
+    SessionID: string;
+    ContextUser: UserInfo;
+    Provider: IMetadataProvider;
+    /**
+     * Optional capture-time waveform peaks (max-abs per bucket, normalized 0..1). When present, written
+     * as a `peaks.json` sidecar in the SAME session folder as the recording so a viewer can render the
+     * waveform without re-decoding the audio. Best-effort — a sidecar failure never fails the recording.
+     */
+    Peaks?: number[];
+}
+/**
+ * Reads a stored recording's bytes back through **authenticated** MJStorage (server-side `GetObject` on
+ * the file's own provider/account) — NOT a public pre-signed link. Used to stream a recording to an
+ * authorized browser securely. Never throws.
+ *
+ * @param fileID The `MJ: Files` id of the recording.
+ * @returns `{ Bytes, MimeType }` or `null` when the file/account/object can't be resolved.
+ */
+export declare function readRealtimeRecordingFile(fileID: string, contextUser: UserInfo, provider: IMetadataProvider): Promise<{
+    Bytes: Buffer;
+    MimeType: string;
+} | null>;
+/** Input to {@link writeRealtimeRecordingSegment}. */
+export interface WriteRecordingSegmentInput {
+    SessionID: string;
+    /** 0-based index of this ~15s shard within the session. */
+    SegmentIndex: number;
+    Audio: Buffer;
+    MimeType: string;
+    StorageAccountID: string;
+    ContextUser: UserInfo;
+}
+/**
+ * Writes ONE crash-recovery segment shard (`seg-NNNN.<ext>`) into the session's folder as a RAW
+ * storage object — no `MJ: Files` row, no session stamping. Shards are durability insurance during a
+ * live call (so a browser/tab death loses at most the last window); they are byte-slices of one
+ * continuous stream (only the first carries the container header), so they are NOT individually
+ * playable — recovery is "concatenate the folder's shards in order". They are deleted once the
+ * canonical consolidated file lands ({@link deleteRealtimeRecordingSegments}). Never throws.
+ *
+ * @returns `true` on success.
+ */
+export declare function writeRealtimeRecordingSegment(input: WriteRecordingSegmentInput): Promise<boolean>;
+/**
+ * Writes the capture-time waveform peaks as a `peaks.json` sidecar (a JSON array of numbers) into the
+ * session's recording folder via the storage driver. Best-effort and tolerant — a missing/empty peaks
+ * array is a no-op, and any storage failure is logged and swallowed (the recording itself already
+ * succeeded). Never throws.
+ *
+ * @returns `true` when a sidecar was written.
+ */
+export declare function writeRecordingPeaksSidecar(sessionID: string, storageAccountID: string, peaks: number[] | undefined, contextUser: UserInfo): Promise<boolean>;
+/**
+ * Deletes the `seg-*` shards in a session's folder, leaving the consolidated `recording.*` file. Called
+ * after {@link storeRealtimeRecording} writes the canonical file at end of call. Never throws.
+ *
+ * @returns The number of shards deleted.
+ */
+export declare function deleteRealtimeRecordingSegments(sessionID: string, storageAccountID: string, contextUser: UserInfo): Promise<number>;
+/**
+ * Uploads a session recording to MJStorage, links it to the `AIAgentSession` (via
+ * `MJ: File Entity Record Links`), and stamps `RecordingFileID` / `RecordingMedia` / `RecordingStartedAt`
+ * on the session. Never throws — a recording-storage failure must not fail the session; failures are
+ * logged and surfaced as a `null` return.
+ *
+ * @param input The recording bytes + storage account + session context.
+ * @returns The created `MJ: Files` id, or `null` on failure.
+ */
+export declare function storeRealtimeRecording(input: StoreRealtimeRecordingInput): Promise<string | null>;
+//# sourceMappingURL=realtime-recording-store.d.ts.map

package/dist/realtime/realtime-recording-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-recording-store.d.ts","sourceRoot":"","sources":["../../src/realtime/realtime-recording-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAY,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EAAE,eAAe,EAAsE,MAAM,+BAA+B,CAAC;AAEpI,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAEtE;;;;;;;;GAQG;AACH,wBAAsB,gCAAgC,CAClD,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,iBAAiB,GAC5E,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAgBxB;AAED,+CAA+C;AAC/C,MAAM,WAAW,2BAA2B;IACxC,qGAAqG;IACrG,KAAK,EAAE,MAAM,CAAC;IACd,oFAAoF;IACpF,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,KAAK,EAAE,sBAAsB,CAAC;IAC9B,qEAAqE;IACrE,SAAS,EAAE,IAAI,CAAC;IAChB,sFAAsF;IACtF,gBAAgB,EAAE,MAAM,CAAC;IACzB,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,QAAQ,CAAC;IACtB,QAAQ,EAAE,iBAAiB,CAAC;IAC5B;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAkBD;;;;;;;GAOG;AACH,wBAAsB,yBAAyB,CAC3C,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,iBAAiB,GACnE,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CA2BrD;AAED,sDAAsD;AACtD,MAAM,WAAW,0BAA0B;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,QAAQ,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,wBAAsB,6BAA6B,CAAC,KAAK,EAAE,0BAA0B,GAAG,OAAO,CAAC,OAAO,CAAC,CAUvG;AAED;;;;;;;GAOG;AACH,wBAAsB,0BAA0B,CAC5C,SAAS,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,SAAS,EAAE,WAAW,EAAE,QAAQ,GAChG,OAAO,CAAC,OAAO,CAAC,CAYlB;AAED;;;;;GAKG;AACH,wBAAsB,+BAA+B,CAAC,SAAS,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAiBzI;AAED;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAAC,KAAK,EAAE,2BAA2B,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CA8CvG"}

package/dist/realtime/realtime-recording-store.js

@@ -0,0 +1,216 @@
+/**
+ * @fileoverview Shared MJStorage finalize for realtime session recordings — the single code path both
+ * the **server-bridged** capture (`BaseAgent.finalizeRealtimeRecording`) and the **client-direct**
+ * browser upload (`RealtimeClientSessionResolver.UploadRealtimeRecording`) use to: resolve the agent's
+ * recording storage account, upload the audio, link it to the `AIAgentSession`, and stamp the session's
+ * recording fields. Keeps the storage policy in one place rather than duplicated per topology.
+ *
+ * @module @memberjunction/ai-agents
+ */
+import { LogError } from '@memberjunction/core';
+import { FileStorageEngine } from '@memberjunction/storage';
+/**
+ * Resolves the storage account a session recording should be written to: the agent's
+ * `RecordingStorageProviderID` if set, else its `AttachmentStorageProviderID` (recordings default to the
+ * attachments account), resolved to that provider's first account. Returns `null` when nothing is
+ * configured — callers treat that as "do not record" (fail-closed).
+ *
+ * @param agent The agent whose recording/attachment storage configuration drives the choice.
+ * @returns The resolved storage account id, or `null`.
+ */
+export async function resolveRecordingStorageAccountID(agent, contextUser, provider) {
+    const providerID = agent.RecordingStorageProviderID || agent.AttachmentStorageProviderID;
+    if (!providerID) {
+        return null;
+    }
+    // Ensure the storage engine has loaded its accounts before reading them. The engine may be
+    // unconfigured in this process, or configured BEFORE this storage account was provisioned (a stale
+    // cache). Try the loaded cache first; if the provider's account isn't found, force a one-time refresh
+    // so a newly-provisioned account is picked up WITHOUT requiring a server restart.
+    await FileStorageEngine.Instance.Config(false, contextUser, provider);
+    let accounts = FileStorageEngine.Instance.GetAccountsByProviderID(providerID);
+    if (accounts.length === 0) {
+        await FileStorageEngine.Instance.Config(true, contextUser, provider);
+        accounts = FileStorageEngine.Instance.GetAccountsByProviderID(providerID);
+    }
+    return accounts[0]?.ID ?? null;
+}
+/** A short, stable file extension for the recording's MIME type. */
+function extensionForMime(mimeType) {
+    if (mimeType.includes('webm'))
+        return 'webm';
+    if (mimeType.includes('ogg'))
+        return 'ogg';
+    if (mimeType.includes('mp4') || mimeType.includes('m4a'))
+        return 'm4a';
+    // Header-less raw PCM crash-recovery shards (audio/L16 / audio/pcm) — NOT individually playable;
+    // recovery concatenates them in order and WAV-wraps. The consolidated file is always WAV.
+    if (mimeType.includes('L16') || mimeType.includes('pcm'))
+        return 'pcm';
+    return 'wav';
+}
+/** The per-session folder all of a session's recording artifacts live in (shards + final file). */
+function recordingFolder(sessionID) {
+    return `realtime-recordings/${sessionID}`;
+}
+/**
+ * Reads a stored recording's bytes back through **authenticated** MJStorage (server-side `GetObject` on
+ * the file's own provider/account) — NOT a public pre-signed link. Used to stream a recording to an
+ * authorized browser securely. Never throws.
+ *
+ * @param fileID The `MJ: Files` id of the recording.
+ * @returns `{ Bytes, MimeType }` or `null` when the file/account/object can't be resolved.
+ */
+export async function readRealtimeRecordingFile(fileID, contextUser, provider) {
+    try {
+        const file = await provider.GetEntityObject('MJ: Files', contextUser);
+        if (!await file.Load(fileID) || !file.ProviderKey) {
+            return null;
+        }
+        // Ensure the engine knows this provider's accounts (idempotent; force-refresh if missing).
+        await FileStorageEngine.Instance.Config(false, contextUser, provider);
+        let accounts = FileStorageEngine.Instance.GetAccountsByProviderID(file.ProviderID);
+        if (accounts.length === 0) {
+            await FileStorageEngine.Instance.Config(true, contextUser, provider);
+            accounts = FileStorageEngine.Instance.GetAccountsByProviderID(file.ProviderID);
+        }
+        const account = accounts[0];
+        if (!account) {
+            return null;
+        }
+        const driver = await FileStorageEngine.Instance.GetDriver(account.ID, contextUser);
+        const bytes = await driver.GetObject({ fullPath: file.ProviderKey });
+        if (!bytes || bytes.length === 0) {
+            return null;
+        }
+        return { Bytes: bytes, MimeType: file.ContentType ?? 'audio/webm' };
+    }
+    catch (error) {
+        LogError(`readRealtimeRecordingFile failed (file ${fileID}): ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+/**
+ * Writes ONE crash-recovery segment shard (`seg-NNNN.<ext>`) into the session's folder as a RAW
+ * storage object — no `MJ: Files` row, no session stamping. Shards are durability insurance during a
+ * live call (so a browser/tab death loses at most the last window); they are byte-slices of one
+ * continuous stream (only the first carries the container header), so they are NOT individually
+ * playable — recovery is "concatenate the folder's shards in order". They are deleted once the
+ * canonical consolidated file lands ({@link deleteRealtimeRecordingSegments}). Never throws.
+ *
+ * @returns `true` on success.
+ */
+export async function writeRealtimeRecordingSegment(input) {
+    const { SessionID, SegmentIndex, Audio, MimeType, StorageAccountID, ContextUser } = input;
+    try {
+        const driver = await FileStorageEngine.Instance.GetDriver(StorageAccountID, ContextUser);
+        const name = `seg-${String(SegmentIndex).padStart(4, '0')}.${extensionForMime(MimeType)}`;
+        return await driver.PutObject(`${recordingFolder(SessionID)}/${name}`, Audio, MimeType);
+    }
+    catch (error) {
+        LogError(`writeRealtimeRecordingSegment failed (session ${SessionID}, seg ${SegmentIndex}): ${error instanceof Error ? error.message : String(error)}`);
+        return false;
+    }
+}
+/**
+ * Writes the capture-time waveform peaks as a `peaks.json` sidecar (a JSON array of numbers) into the
+ * session's recording folder via the storage driver. Best-effort and tolerant — a missing/empty peaks
+ * array is a no-op, and any storage failure is logged and swallowed (the recording itself already
+ * succeeded). Never throws.
+ *
+ * @returns `true` when a sidecar was written.
+ */
+export async function writeRecordingPeaksSidecar(sessionID, storageAccountID, peaks, contextUser) {
+    if (!Array.isArray(peaks) || peaks.length === 0) {
+        return false;
+    }
+    try {
+        const driver = await FileStorageEngine.Instance.GetDriver(storageAccountID, contextUser);
+        const payload = Buffer.from(JSON.stringify(peaks), 'utf8');
+        return await driver.PutObject(`${recordingFolder(sessionID)}/peaks.json`, payload, 'application/json');
+    }
+    catch (error) {
+        LogError(`writeRecordingPeaksSidecar failed (session ${sessionID}): ${error instanceof Error ? error.message : String(error)}`);
+        return false;
+    }
+}
+/**
+ * Deletes the `seg-*` shards in a session's folder, leaving the consolidated `recording.*` file. Called
+ * after {@link storeRealtimeRecording} writes the canonical file at end of call. Never throws.
+ *
+ * @returns The number of shards deleted.
+ */
+export async function deleteRealtimeRecordingSegments(sessionID, storageAccountID, contextUser) {
+    try {
+        const driver = await FileStorageEngine.Instance.GetDriver(storageAccountID, contextUser);
+        const folder = recordingFolder(sessionID);
+        const listed = await driver.ListObjects(folder);
+        let deleted = 0;
+        for (const obj of listed.objects ?? []) {
+            const base = (obj.name.split('/').pop() ?? obj.name);
+            if (base.startsWith('seg-') && await driver.DeleteObject(`${folder}/${base}`)) {
+                deleted++;
+            }
+        }
+        return deleted;
+    }
+    catch (error) {
+        LogError(`deleteRealtimeRecordingSegments failed (session ${sessionID}): ${error instanceof Error ? error.message : String(error)}`);
+        return 0;
+    }
+}
+/**
+ * Uploads a session recording to MJStorage, links it to the `AIAgentSession` (via
+ * `MJ: File Entity Record Links`), and stamps `RecordingFileID` / `RecordingMedia` / `RecordingStartedAt`
+ * on the session. Never throws — a recording-storage failure must not fail the session; failures are
+ * logged and surfaced as a `null` return.
+ *
+ * @param input The recording bytes + storage account + session context.
+ * @returns The created `MJ: Files` id, or `null` on failure.
+ */
+export async function storeRealtimeRecording(input) {
+    const { Audio, MimeType, Media, StartedAt, StorageAccountID, SessionID, ContextUser, Provider, Peaks } = input;
+    try {
+        // Canonical consolidated file in the session's own folder, alongside (then replacing) its shards.
+        const uploaded = await FileStorageEngine.Instance.UploadFile({
+            content: Audio,
+            fileName: `recording.${extensionForMime(MimeType)}`,
+            mimeType: MimeType,
+            contextUser: ContextUser,
+            storageAccountId: StorageAccountID,
+            provider: Provider,
+            pathPrefix: recordingFolder(SessionID)
+        });
+        // Best-effort waveform-peaks sidecar (peaks.json) next to the recording, for fast waveform
+        // rendering without re-decoding the audio. A sidecar failure never fails the recording itself.
+        await writeRecordingPeaksSidecar(SessionID, StorageAccountID, Peaks, ContextUser);
+        // Link the file to the session record so it's discoverable via MJ: File Entity Record Links.
+        const sessionEntityID = Provider.EntityByName('MJ: AI Agent Sessions')?.ID;
+        if (sessionEntityID) {
+            const link = await Provider.GetEntityObject('MJ: File Entity Record Links', ContextUser);
+            link.NewRecord();
+            link.FileID = uploaded.FileID;
+            link.EntityID = sessionEntityID;
+            link.RecordID = SessionID;
+            if (!await link.Save()) {
+                LogError(`storeRealtimeRecording: failed to link recording to session ${SessionID}: ${link.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+            }
+        }
+        // Stamp the recording fields on the session (file + media kind + t0).
+        const session = await Provider.GetEntityObject('MJ: AI Agent Sessions', ContextUser);
+        if (await session.Load(SessionID)) {
+            session.RecordingFileID = uploaded.FileID;
+            session.RecordingMedia = Media;
+            session.RecordingStartedAt = StartedAt;
+            if (!await session.Save()) {
+                LogError(`storeRealtimeRecording: failed to stamp recording fields on session ${SessionID}: ${session.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+            }
+        }
+        return uploaded.FileID;
+    }
+    catch (error) {
+        LogError(`storeRealtimeRecording failed for session ${SessionID}: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+//# sourceMappingURL=realtime-recording-store.js.map