@memberjunction/core-entities 5.21.0 → 5.23.0

package/dist/engines/conversations.js

@@ -0,0 +1,1102 @@
+import { BaseEngine, Metadata, RunQuery, RunView, TransformSimpleObjectToEntityObject } from "@memberjunction/core";
+import { NormalizeUUID, UUIDsEqual } from "@memberjunction/global";
+import { BehaviorSubject } from "rxjs";
+import { ArtifactMetadataEngine } from "./artifacts.js";
+/**
+ * Helper: parse a raw ConversationDetailComplete row into typed arrays.
+ */
+export function parseConversationDetailComplete(queryResult) {
+    return {
+        ...queryResult,
+        agentRuns: queryResult.AgentRunsJSON
+            ? JSON.parse(queryResult.AgentRunsJSON)
+            : [],
+        artifacts: queryResult.ArtifactsJSON
+            ? JSON.parse(queryResult.ArtifactsJSON)
+            : [],
+        ratings: queryResult.RatingsJSON
+            ? JSON.parse(queryResult.RatingsJSON)
+            : []
+    };
+}
+/**
+ * ConversationEngine provides centralized, reactive caching for conversations,
+ * conversation details (messages), and peripheral data (agent runs, artifacts).
+ *
+ * This engine is the single source of truth for conversation data across all UI
+ * consumers (chat area, sidebar, overlay, etc.). It replaces per-component caching
+ * that previously lived in conversation-chat-area component,
+ * and other scattered locations.
+ *
+ * Usage:
+ * ```typescript
+ * // Initialize (call once at app startup after metadata is loaded)
+ * await ConversationEngine.Instance.Config(false, contextUser);
+ *
+ * // Load conversations for the current user
+ * await ConversationEngine.Instance.LoadConversations('env-id', contextUser);
+ *
+ * // Subscribe to conversation list changes
+ * ConversationEngine.Instance.Conversations$.subscribe(conversations => {
+ *     // React to changes
+ * });
+ *
+ * // Load details for a specific conversation
+ * const details = await ConversationEngine.Instance.LoadConversationDetails('conv-id', contextUser);
+ *
+ * // Get cached details (instant, no DB round-trip)
+ * const cached = ConversationEngine.Instance.GetCachedDetails('conv-id');
+ * ```
+ */
+export class ConversationEngine extends BaseEngine {
+    constructor() {
+        super(...arguments);
+        // ========================================================================
+        // REACTIVE STATE
+        // ========================================================================
+        this._conversations$ = new BehaviorSubject([]);
+        // ========================================================================
+        // INTERNAL STATE
+        // ========================================================================
+        /** Detail cache keyed by normalized conversation ID */
+        this._detailCache = new Map();
+        /** Track the environment ID used for the last load */
+        this._lastEnvironmentId = null;
+        /**
+         * Guard flag: set true while the engine itself is performing a mutation.
+         * Prevents the entity event handler from re-processing our own saves/deletes,
+         * which would cause redundant cache updates or infinite loops.
+         */
+        this._selfMutating = false;
+    }
+    /**
+     * Returns the global instance of the class. This is a singleton class, so there is only
+     * one instance of it in the application. Do not directly create new instances of it,
+     * always use this method to get the instance.
+     */
+    static get Instance() {
+        return super.getInstance();
+    }
+    /**
+     * Observable stream of the current user's conversation list.
+     * Emits whenever conversations are loaded, created, deleted, archived, or pinned.
+     */
+    get Conversations$() {
+        return this._conversations$.asObservable();
+    }
+    /**
+     * Current snapshot of conversations (non-reactive).
+     */
+    get Conversations() {
+        return this._conversations$.value;
+    }
+    // ========================================================================
+    // ENGINE CONFIG (BaseEngine pattern)
+    // ========================================================================
+    /**
+     * Configures the engine. Unlike other engines that bulk-load entity tables via BaseEngine.Load(),
+     * ConversationEngine manages its own caching because conversations are user-scoped and filtered
+     * by environment, which doesn't fit the standard "load all rows" pattern.
+     *
+     * Call this once at startup to initialize the engine. Conversation data is loaded
+     * separately via LoadConversations().
+     */
+    async Config(forceRefresh, contextUser, provider) {
+        // Ensure ArtifactMetadataEngine is loaded — conversation details reference artifacts
+        // and we need artifact types available before processing. Passing false means
+        // this is a no-op if it's already loaded.
+        await ArtifactMetadataEngine.Instance.Config(forceRefresh, contextUser, provider);
+        // We don't use BaseEngine.Load() because conversations are user-scoped.
+        // Mark the engine as "configured" so consumers can check .Loaded.
+        // We call Load with an empty config array just to set the Loaded flag and wire up
+        // the BaseEngine infrastructure (entity event listeners, etc.)
+        const configs = [];
+        await this.Load(configs, provider, forceRefresh, contextUser);
+    }
+    // ========================================================================
+    // CONVERSATION LIST OPERATIONS
+    // ========================================================================
+    /**
+     * Loads conversations from the database for the given user and environment.
+     * Results are cached and emitted via Conversations$.
+     *
+     * @param environmentId - The environment to filter conversations by
+     * @param contextUser - The current user context
+     * @param forceRefresh - If true, reloads even if data is already cached
+     */
+    async LoadConversations(environmentId, contextUser, forceRefresh = false) {
+        // Skip if already loaded for this environment (unless forcing)
+        if (!forceRefresh && this._lastEnvironmentId === environmentId && this._conversations$.value.length > 0) {
+            return;
+        }
+        this._lastEnvironmentId = environmentId;
+        const rv = new RunView();
+        const filter = `EnvironmentID='${environmentId}' AND UserID='${contextUser.ID}' AND (IsArchived IS NULL OR IsArchived=0)`;
+        const result = await rv.RunView({
+            EntityName: 'MJ: Conversations',
+            ExtraFilter: filter,
+            OrderBy: 'IsPinned DESC, __mj_UpdatedAt DESC',
+            MaxRows: 1000,
+            ResultType: 'entity_object'
+        }, contextUser);
+        if (result.Success) {
+            this._conversations$.next(result.Results || []);
+        }
+        else {
+            console.error('[ConversationEngine] Failed to load conversations:', result.ErrorMessage);
+            this._conversations$.next([]);
+        }
+    }
+    /**
+     * Creates a new conversation, saves it to the database, and adds it to the cached list.
+     *
+     * @param name - Display name for the conversation
+     * @param environmentId - The environment ID
+     * @param contextUser - The current user context
+     * @param description - Optional description
+     * @param projectId - Optional project ID
+     * @returns The newly created conversation entity
+     * @throws Error if save fails
+     */
+    async CreateConversation(name, environmentId, contextUser, description, projectId) {
+        const md = new Metadata();
+        const conversation = await md.GetEntityObject('MJ: Conversations', contextUser);
+        conversation.Name = name;
+        conversation.EnvironmentID = environmentId;
+        conversation.UserID = contextUser.ID;
+        if (description)
+            conversation.Description = description;
+        if (projectId)
+            conversation.ProjectID = projectId;
+        const saved = await conversation.Save();
+        if (!saved) {
+            throw new Error(conversation.LatestResult?.Message || 'Failed to create conversation');
+        }
+        // Prepend to the list and emit
+        const updated = [conversation, ...this._conversations$.value];
+        this._conversations$.next(updated);
+        return conversation;
+    }
+    /**
+     * Deletes a conversation from the database and removes it from the cached list.
+     *
+     * @param id - The conversation ID to delete
+     * @param contextUser - The current user context
+     * @returns true if successful
+     * @throws Error if conversation not found or delete fails
+     */
+    async DeleteConversation(id, contextUser) {
+        // Try to use the cached entity object first to avoid a DB round-trip
+        let conversation = this.GetConversation(id);
+        if (!conversation) {
+            // Not in cache — load from DB as fallback
+            const md = new Metadata();
+            conversation = await md.GetEntityObject('MJ: Conversations', contextUser);
+            const loaded = await conversation.Load(id);
+            if (!loaded) {
+                throw new Error('Conversation not found');
+            }
+        }
+        // Remove from the list and cache BEFORE calling Delete(), because
+        // BaseEntity.Delete() calls NewRecord() which wipes the entity's fields.
+        // Since the cached entity is the same object reference in the list,
+        // wiping it causes a blank render frame before removal.
+        this.removeFromList(id);
+        this.removeDetailCache(id);
+        this._selfMutating = true;
+        try {
+            const deleted = await conversation.Delete();
+            if (!deleted) {
+                // Delete failed — restore to list
+                const current = this._conversations$.value;
+                this._conversations$.next([conversation, ...current]);
+                throw new Error(conversation.LatestResult?.Message || 'Failed to delete conversation');
+            }
+        }
+        finally {
+            this._selfMutating = false;
+        }
+        return true;
+    }
+    /**
+     * Archives a conversation (sets IsArchived = true) and removes it from the active list.
+     *
+     * @param id - The conversation ID to archive
+     * @param contextUser - The current user context
+     * @returns true if successful
+     */
+    async ArchiveConversation(id, contextUser) {
+        const result = await this.saveConversationField(id, { IsArchived: true }, contextUser);
+        if (result) {
+            // Archived conversations disappear from the active list
+            this.removeFromList(id);
+            this.removeDetailCache(id);
+        }
+        return result;
+    }
+    /**
+     * Toggles or sets the pinned status of a conversation.
+     *
+     * @param id - The conversation ID
+     * @param isPinned - Whether the conversation should be pinned
+     * @param contextUser - The current user context
+     * @returns true if successful
+     */
+    async PinConversation(id, isPinned, contextUser) {
+        const result = await this.saveConversationField(id, { IsPinned: isPinned }, contextUser);
+        if (result) {
+            // Update the in-memory entity and re-emit
+            const conversation = this.GetConversation(id);
+            if (conversation) {
+                conversation.IsPinned = isPinned;
+                // Re-sort: pinned first, then by updated date
+                const sorted = this.sortConversations(this._conversations$.value);
+                this._conversations$.next(sorted);
+            }
+        }
+        return result;
+    }
+    /**
+     * Finds a conversation by ID in the cached list.
+     *
+     * @param id - The conversation ID to find
+     * @returns The conversation entity, or undefined if not in cache
+     */
+    GetConversation(id) {
+        return this._conversations$.value.find(c => UUIDsEqual(c.ID, id));
+    }
+    /**
+     * Saves partial updates to a conversation (Name, Description, or any writable field).
+     * Loads the entity from DB, applies updates, saves, and updates the in-memory list.
+     *
+     * @param id - The conversation ID to update
+     * @param updates - Partial fields to update
+     * @param contextUser - The current user context
+     * @returns true if saved successfully
+     * @throws Error if conversation not found or save fails
+     */
+    async SaveConversation(id, updates, contextUser) {
+        // Try to use the cached entity to avoid a DB round-trip
+        let conversation = this.GetConversation(id);
+        if (!conversation) {
+            // Not in cache — load from DB as fallback
+            const md = new Metadata();
+            conversation = await md.GetEntityObject('MJ: Conversations', contextUser);
+            const loaded = await conversation.Load(id);
+            if (!loaded) {
+                throw new Error('Conversation not found');
+            }
+        }
+        this.mergeDataOntoRecord(conversation, updates);
+        this._selfMutating = true;
+        try {
+            const saved = await conversation.Save();
+            if (!saved) {
+                throw new Error(conversation.LatestResult?.Message || 'Failed to update conversation');
+            }
+        }
+        finally {
+            this._selfMutating = false;
+        }
+        // Re-emit the list so subscribers see the update
+        this._conversations$.next([...this._conversations$.value]);
+        return true;
+    }
+    /**
+     * Deletes multiple conversations in a batch operation with per-item error tracking.
+     *
+     * @param ids - Array of conversation IDs to delete
+     * @param contextUser - The current user context
+     * @returns Object with successful and failed deletions
+     */
+    async DeleteMultipleConversations(ids, contextUser) {
+        if (ids.length === 0) {
+            return { Successful: [], Failed: [] };
+        }
+        const md = new Metadata();
+        const successful = [];
+        const failed = [];
+        const entitiesToDelete = [];
+        // Phase 1: Gather entities — use cached objects when available to avoid DB round-trips
+        for (const id of ids) {
+            const cached = this.GetConversation(id);
+            if (cached) {
+                entitiesToDelete.push(cached);
+            }
+            else {
+                // Not in cache — try loading from DB
+                try {
+                    const entity = await md.GetEntityObject('MJ: Conversations', contextUser);
+                    const loaded = await entity.Load(id);
+                    if (!loaded) {
+                        failed.push({ ID: id, Name: 'Unknown', Error: 'Conversation not found' });
+                    }
+                    else {
+                        entitiesToDelete.push(entity);
+                    }
+                }
+                catch (error) {
+                    failed.push({ ID: id, Name: 'Unknown', Error: error instanceof Error ? error.message : 'Unknown error' });
+                }
+            }
+        }
+        if (entitiesToDelete.length === 0) {
+            return { Successful: successful, Failed: failed };
+        }
+        // Phase 2: Delete each conversation individually.
+        // We use individual deletes rather than TransactionGroup because cached entities
+        // from RunView may have stale state on the server (e.g., already deleted records
+        // cause InnerLoad failures inside TransactionGroup, failing the entire batch).
+        // Individual deletes let us handle partial success gracefully.
+        this._selfMutating = true;
+        try {
+            for (const entity of entitiesToDelete) {
+                const name = entity.Name || 'Unknown';
+                try {
+                    // Use DeleteConversation which handles Load + Delete properly
+                    // and removes from list/cache on success
+                    await this.DeleteConversation(entity.ID, contextUser);
+                    successful.push(entity.ID);
+                }
+                catch (deleteError) {
+                    const errMsg = deleteError instanceof Error ? deleteError.message : 'Delete failed';
+                    // If the record wasn't found (already deleted), treat as success for UI purposes
+                    if (errMsg.includes('not found') || errMsg.includes('hasn\'t yet been saved')) {
+                        successful.push(entity.ID);
+                        this.removeDetailCache(entity.ID);
+                    }
+                    else {
+                        failed.push({ ID: entity.ID, Name: name, Error: errMsg });
+                    }
+                }
+            }
+        }
+        finally {
+            this._selfMutating = false;
+        }
+        // Phase 3: Ensure all successful IDs are removed from the list.
+        // DeleteConversation handles its own removal, but "already deleted" items
+        // (counted as successful above) may still be in the stale cache.
+        this.removeMultipleFromList(successful);
+        return { Successful: successful, Failed: failed };
+    }
+    // ========================================================================
+    // CONVERSATION DETAILS (Messages)
+    // ========================================================================
+    /**
+     * Loads conversation details (messages) for a specific conversation.
+     * Results are cached for instant retrieval on subsequent calls.
+     *
+     * @param conversationId - The conversation to load details for
+     * @param contextUser - The current user context
+     * @param forceRefresh - If true, reloads even if cached
+     * @returns Array of conversation detail entities
+     */
+    /**
+     * Loads conversation details using the efficient GetConversationComplete query
+     * which returns messages, agent runs, artifacts, ratings, and user avatars in one round-trip.
+     * Results are cached for instant retrieval on subsequent calls.
+     *
+     * @param conversationId - The conversation to load details for
+     * @param contextUser - The current user context
+     * @param forceRefresh - If true, reloads even if cached
+     * @returns The full cache entry with all peripheral data
+     */
+    async LoadConversationDetails(conversationId, contextUser, forceRefresh = false) {
+        const key = NormalizeUUID(conversationId);
+        // Return cached if available and not forcing
+        if (!forceRefresh) {
+            const cached = this._detailCache.get(key);
+            if (cached) {
+                return cached;
+            }
+        }
+        // Use GetConversationComplete for one-round-trip loading of all data
+        const rq = new RunQuery();
+        const result = await rq.RunQuery({
+            QueryName: 'GetConversationComplete',
+            CategoryPath: 'MJ/Conversations',
+            Parameters: { ConversationID: conversationId }
+        }, contextUser);
+        if (!result.Success || !result.Results) {
+            console.error('[ConversationEngine] Failed to load conversation details:', result.ErrorMessage);
+            // Return empty cache entry
+            const empty = {
+                Details: [],
+                RawData: [],
+                AgentRunsByDetailId: new Map(),
+                UserAvatars: new Map(),
+                RatingsByDetailId: new Map(),
+                ArtifactsByDetailId: new Map(),
+                LoadedAt: new Date(),
+                PeripheralDataStale: false
+            };
+            return empty;
+        }
+        const rawData = result.Results;
+        // Build the cache entry from the rich query result
+        const cacheEntry = await this.buildDetailCacheFromRawData(rawData, contextUser);
+        this._detailCache.set(key, cacheEntry);
+        return cacheEntry;
+    }
+    /**
+     * Builds a full ConversationDetailCache from raw GetConversationComplete query results.
+     * Hydrates entity objects and parses peripheral JSON data in one pass.
+     */
+    async buildDetailCacheFromRawData(rawData, contextUser) {
+        const md = new Metadata();
+        // Hydrate raw rows into MJConversationDetailEntity objects
+        const validRows = rawData.filter(row => !!row.ID);
+        const details = await TransformSimpleObjectToEntityObject(Metadata.Provider, 'MJ: Conversation Details', validRows, contextUser);
+        // Build peripheral data maps from parsed JSON in one pass
+        const agentRuns = new Map();
+        const userAvatars = new Map();
+        const ratingsByDetailId = new Map();
+        const artifactsByDetailId = new Map();
+        for (const row of rawData) {
+            if (!row.ID)
+                continue;
+            const parsed = parseConversationDetailComplete(row);
+            // Agent runs
+            if (parsed.agentRuns.length > 0) {
+                const agentRunData = parsed.agentRuns[0];
+                const agentRun = await md.GetEntityObject('MJ: AI Agent Runs', contextUser);
+                agentRun.LoadFromData({
+                    ID: agentRunData.ID,
+                    AgentID: agentRunData.AgentID,
+                    Agent: agentRunData.Agent,
+                    Status: agentRunData.Status,
+                    __mj_CreatedAt: agentRunData.__mj_CreatedAt,
+                    __mj_UpdatedAt: agentRunData.__mj_UpdatedAt,
+                    TotalPromptTokensUsed: agentRunData.TotalPromptTokensUsed,
+                    TotalCompletionTokensUsed: agentRunData.TotalCompletionTokensUsed,
+                    TotalCost: agentRunData.TotalCost,
+                    ConversationDetailID: agentRunData.ConversationDetailID
+                });
+                agentRuns.set(row.ID, agentRun);
+            }
+            // Artifacts
+            if (parsed.artifacts.length > 0) {
+                artifactsByDetailId.set(row.ID, parsed.artifacts);
+            }
+            // Ratings
+            if (parsed.ratings.length > 0) {
+                ratingsByDetailId.set(row.ID, parsed.ratings);
+            }
+            // User avatars (deduplicate by UserID)
+            if (row.Role?.toLowerCase() === 'user' && row.UserID && !userAvatars.has(row.UserID)) {
+                userAvatars.set(row.UserID, {
+                    ImageURL: row.UserImageURL || null,
+                    IconClass: row.UserImageIconClass || null
+                });
+            }
+        }
+        return {
+            Details: details,
+            RawData: rawData,
+            AgentRunsByDetailId: agentRuns,
+            UserAvatars: userAvatars,
+            RatingsByDetailId: ratingsByDetailId,
+            ArtifactsByDetailId: artifactsByDetailId,
+            LoadedAt: new Date(),
+            PeripheralDataStale: false
+        };
+    }
+    /**
+     * Refreshes conversation details by re-running the GetConversationComplete query
+     * and surgically merging results into the existing cache. Existing objects that
+     * haven't changed keep their references (minimizing Angular re-renders).
+     *
+     * - New messages: appended to Details array
+     * - Existing messages: fields updated in-place on the same object
+     * - Agent runs: updated in-place or added
+     * - Artifacts/ratings: replaced per-detail (cheap — plain data, not entity objects)
+     * - User avatars: merged (new users added)
+     *
+     * If no cache exists yet, falls back to a full load.
+     *
+     * @param conversationId - The conversation to refresh
+     * @param contextUser - The current user context
+     * @returns The updated cache entry
+     */
+    async RefreshConversationDetails(conversationId, contextUser) {
+        const key = NormalizeUUID(conversationId);
+        const existing = this._detailCache.get(key);
+        // No cache yet — do a full load
+        if (!existing) {
+            return this.LoadConversationDetails(conversationId, contextUser);
+        }
+        // Run the query
+        const rq = new RunQuery();
+        const result = await rq.RunQuery({
+            QueryName: 'GetConversationComplete',
+            CategoryPath: 'MJ/Conversations',
+            Parameters: { ConversationID: conversationId }
+        }, contextUser);
+        if (!result.Success || !result.Results) {
+            console.error('[ConversationEngine] Failed to refresh conversation details:', result.ErrorMessage);
+            return existing;
+        }
+        const freshRows = result.Results;
+        const md = new Metadata();
+        // Build a lookup of existing details by ID for fast comparison
+        const existingDetailsMap = new Map();
+        for (const detail of existing.Details) {
+            existingDetailsMap.set(detail.ID, detail);
+        }
+        // Process each row in parallel — sync mutations happen immediately,
+        // async hydrations (new entities) run concurrently
+        await Promise.all(freshRows.map(async (row) => {
+            if (!row.ID)
+                return;
+            const existingDetail = existingDetailsMap.get(row.ID);
+            if (existingDetail) {
+                // Update fields in-place on the existing entity object (preserves reference)
+                existingDetail.LoadFromData(row);
+                existingDetailsMap.delete(row.ID);
+            }
+            else {
+                // New message — hydrate and append
+                const newDetail = await md.GetEntityObject('MJ: Conversation Details', contextUser);
+                newDetail.LoadFromData(row);
+                existing.Details.push(newDetail);
+            }
+            const parsed = parseConversationDetailComplete(row);
+            // Merge agent runs: update in-place or add
+            if (parsed.agentRuns.length > 0) {
+                const agentRunData = parsed.agentRuns[0];
+                const existingRun = existing.AgentRunsByDetailId.get(row.ID);
+                if (existingRun) {
+                    existingRun.LoadFromData({
+                        ID: agentRunData.ID,
+                        AgentID: agentRunData.AgentID,
+                        Agent: agentRunData.Agent,
+                        Status: agentRunData.Status,
+                        __mj_CreatedAt: agentRunData.__mj_CreatedAt,
+                        __mj_UpdatedAt: agentRunData.__mj_UpdatedAt,
+                        TotalPromptTokensUsed: agentRunData.TotalPromptTokensUsed,
+                        TotalCompletionTokensUsed: agentRunData.TotalCompletionTokensUsed,
+                        TotalCost: agentRunData.TotalCost,
+                        ConversationDetailID: agentRunData.ConversationDetailID
+                    });
+                }
+                else {
+                    const newRun = await md.GetEntityObject('MJ: AI Agent Runs', contextUser);
+                    newRun.LoadFromData(agentRunData);
+                    existing.AgentRunsByDetailId.set(row.ID, newRun);
+                }
+            }
+            // Replace artifacts per-detail (plain data, cheap to replace)
+            if (parsed.artifacts.length > 0) {
+                existing.ArtifactsByDetailId.set(row.ID, parsed.artifacts);
+            }
+            // Replace ratings per-detail
+            if (parsed.ratings.length > 0) {
+                existing.RatingsByDetailId.set(row.ID, parsed.ratings);
+            }
+            // Merge user avatars
+            if (row.Role?.toLowerCase() === 'user' && row.UserID && !existing.UserAvatars.has(row.UserID)) {
+                existing.UserAvatars.set(row.UserID, {
+                    ImageURL: row.UserImageURL || null,
+                    IconClass: row.UserImageIconClass || null
+                });
+            }
+        }));
+        // Update raw data and timestamp
+        existing.RawData = freshRows;
+        existing.LoadedAt = new Date();
+        existing.PeripheralDataStale = false;
+        return existing;
+    }
+    /**
+     * Returns cached conversation details (messages only) without hitting the database.
+     * Returns undefined if no cache entry exists for this conversation.
+     *
+     * @param conversationId - The conversation ID
+     * @returns Cached message entities, or undefined if not cached
+     */
+    GetCachedDetails(conversationId) {
+        const key = NormalizeUUID(conversationId);
+        return this._detailCache.get(key)?.Details;
+    }
+    /**
+     * Returns the full cache entry for a conversation, including all peripheral data
+     * (agent runs, artifacts, ratings, user avatars). Returns undefined if not cached.
+     *
+     * This is the primary read method for UI components — returns instant cached data
+     * without any database round-trip.
+     *
+     * @param conversationId - The conversation ID
+     * @returns The full cache entry, or undefined
+     */
+    GetCachedDetailEntry(conversationId) {
+        const key = NormalizeUUID(conversationId);
+        return this._detailCache.get(key);
+    }
+    /**
+     * Returns true if conversation details are cached for the given conversation.
+     */
+    HasCachedDetails(conversationId) {
+        const key = NormalizeUUID(conversationId);
+        return this._detailCache.has(key);
+    }
+    /**
+     * Adds a detail (message) to the cached list for a conversation.
+     * If no cache entry exists, this is a no-op (caller should LoadConversationDetails first).
+     *
+     * @param conversationId - The conversation this detail belongs to
+     * @param detail - The detail entity to add
+     */
+    AddDetailToCache(conversationId, detail) {
+        const key = NormalizeUUID(conversationId);
+        const cached = this._detailCache.get(key);
+        if (cached) {
+            cached.Details.push(detail);
+        }
+    }
+    /**
+     * Updates a detail entity in the cache. Finds by ID and replaces.
+     * If the detail is not in cache, this is a no-op.
+     *
+     * @param conversationId - The conversation this detail belongs to
+     * @param detail - The updated detail entity
+     */
+    UpdateDetailInCache(conversationId, detail) {
+        const key = NormalizeUUID(conversationId);
+        const cached = this._detailCache.get(key);
+        if (cached) {
+            const idx = cached.Details.findIndex(d => UUIDsEqual(d.ID, detail.ID));
+            if (idx >= 0) {
+                cached.Details[idx] = detail;
+            }
+        }
+    }
+    // ========================================================================
+    // PERIPHERAL DATA (Agent Runs)
+    // ========================================================================
+    /**
+     * Gets the cached agent run for a specific conversation detail.
+     *
+     * @param conversationId - The conversation ID
+     * @param detailId - The conversation detail ID
+     * @returns The agent run entity, or undefined if not cached
+     */
+    GetAgentRunForDetail(conversationId, detailId) {
+        const key = NormalizeUUID(conversationId);
+        const cached = this._detailCache.get(key);
+        if (!cached)
+            return undefined;
+        // Search by detail ID (agent runs are keyed by the detail they belong to)
+        for (const [cachedDetailId, agentRun] of cached.AgentRunsByDetailId) {
+            if (UUIDsEqual(cachedDetailId, detailId)) {
+                return agentRun;
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Gets all cached agent runs for a conversation, keyed by detail ID.
+     *
+     * @param conversationId - The conversation ID
+     * @returns Map of detail ID to agent run, or empty map if not cached
+     */
+    GetAgentRunsMap(conversationId) {
+        const key = NormalizeUUID(conversationId);
+        return this._detailCache.get(key)?.AgentRunsByDetailId ?? new Map();
+    }
+    /**
+     * Adds or updates an agent run in the cache for a specific detail.
+     *
+     * @param conversationId - The conversation ID
+     * @param detailId - The detail ID the agent run is associated with
+     * @param agentRun - The agent run entity
+     */
+    SetAgentRunForDetail(conversationId, detailId, agentRun) {
+        const key = NormalizeUUID(conversationId);
+        const cached = this._detailCache.get(key);
+        if (cached) {
+            cached.AgentRunsByDetailId.set(detailId, agentRun);
+        }
+    }
+    // ========================================================================
+    // CACHE MANAGEMENT
+    // ========================================================================
+    /**
+     * Invalidates (removes) the cached details for a specific conversation.
+     * The next call to LoadConversationDetails will fetch fresh data.
+     *
+     * @param conversationId - The conversation ID to invalidate
+     */
+    InvalidateConversation(conversationId) {
+        this.removeDetailCache(conversationId);
+    }
+    /**
+     * Clears all cached data: conversations, details, and peripheral data.
+     * Typically called on logout or environment switch.
+     */
+    ClearCache() {
+        this._conversations$.next([]);
+        this._detailCache.clear();
+        this._lastEnvironmentId = null;
+    }
+    // ========================================================================
+    // CONVERSATION DETAIL CRUD
+    // ========================================================================
+    /**
+     * Creates a new conversation detail (message), saves it, and adds it to the cache.
+     *
+     * @param conversationId - The conversation this detail belongs to
+     * @param role - The message role ('User', 'AI', 'System')
+     * @param message - The message content
+     * @param contextUser - The current user context
+     * @param additionalFields - Optional extra fields to set on the entity
+     * @returns The saved conversation detail entity
+     */
+    async CreateConversationDetail(conversationId, role, message, contextUser, additionalFields) {
+        const md = new Metadata();
+        const detail = await md.GetEntityObject('MJ: Conversation Details', contextUser);
+        detail.ConversationID = conversationId;
+        detail.Role = role;
+        detail.Message = message;
+        if (additionalFields) {
+            this.mergeDataOntoRecord(detail, additionalFields);
+        }
+        this._selfMutating = true;
+        try {
+            const saved = await detail.Save();
+            if (!saved) {
+                throw new Error(detail.LatestResult?.Message || 'Failed to create conversation detail');
+            }
+        }
+        finally {
+            this._selfMutating = false;
+        }
+        // Add to cache if this conversation's details are cached
+        this.AddDetailToCache(conversationId, detail);
+        return detail;
+    }
+    /**
+     * Saves an existing conversation detail entity and updates the cache.
+     * Use this instead of calling detail.Save() directly to keep the engine cache in sync.
+     *
+     * @param detail - The conversation detail entity to save (must already be loaded)
+     * @returns true if saved successfully
+     */
+    async SaveConversationDetail(detail) {
+        this._selfMutating = true;
+        try {
+            const saved = await detail.Save();
+            if (!saved) {
+                throw new Error(detail.LatestResult?.Message || 'Failed to save conversation detail');
+            }
+        }
+        finally {
+            this._selfMutating = false;
+        }
+        // Update in cache
+        this.UpdateDetailInCache(detail.ConversationID, detail);
+        return true;
+    }
+    /**
+     * Deletes a conversation detail and removes it from the cache.
+     *
+     * @param conversationId - The conversation this detail belongs to
+     * @param detailId - The detail ID to delete
+     * @param contextUser - The current user context
+     * @returns true if deleted successfully
+     */
+    async DeleteConversationDetail(conversationId, detailId, contextUser) {
+        // Try to use the cached detail entity to avoid a DB round-trip
+        const key = NormalizeUUID(conversationId);
+        const cachedEntry = this._detailCache.get(key);
+        let detail = cachedEntry?.Details.find(d => UUIDsEqual(d.ID, detailId));
+        if (!detail) {
+            // Not in cache — load from DB as fallback
+            const md = new Metadata();
+            detail = await md.GetEntityObject('MJ: Conversation Details', contextUser);
+            const loaded = await detail.Load(detailId);
+            if (!loaded) {
+                throw new Error('Conversation detail not found');
+            }
+        }
+        this._selfMutating = true;
+        try {
+            const deleted = await detail.Delete();
+            if (!deleted) {
+                throw new Error(detail.LatestResult?.Message || 'Failed to delete conversation detail');
+            }
+        }
+        finally {
+            this._selfMutating = false;
+        }
+        // Remove from cache
+        if (cachedEntry) {
+            cachedEntry.Details = cachedEntry.Details.filter(d => !UUIDsEqual(d.ID, detailId));
+            cachedEntry.AgentRunsByDetailId.delete(detailId);
+        }
+        return true;
+    }
+    // ========================================================================
+    // ENTITY EVENT HANDLING (External Mutation Sync)
+    // ========================================================================
+    /**
+     * Overrides BaseEngine's entity event handler to watch for external mutations
+     * to Conversations and Conversation Details. When another piece of code (outside
+     * this engine) saves or deletes these entities, we sync our cache.
+     *
+     * The _selfMutating guard prevents processing events from our own mutations.
+     */
+    async HandleIndividualBaseEntityEvent(event) {
+        // Skip events from our own mutations to avoid redundant cache updates
+        if (this._selfMutating) {
+            return true;
+        }
+        // Entity name comes from baseEntity for local events, or event.entityName for remote-invalidate
+        const entityName = event.baseEntity?.EntityInfo?.Name || event.entityName;
+        if (!entityName) {
+            return await super.HandleIndividualBaseEntityEvent(event);
+        }
+        const normalizedName = entityName.toLowerCase().trim();
+        // For remote-invalidate events, resolve the action to save/delete for our handlers
+        const effectiveType = event.type === 'remote-invalidate'
+            ? event.payload?.action || 'save'
+            : event.type;
+        if (normalizedName === 'mj: conversations') {
+            return this.handleConversationEntityEvent(event, effectiveType);
+        }
+        if (normalizedName === 'mj: conversation details') {
+            return this.handleConversationDetailEntityEvent(event, effectiveType);
+        }
+        if (normalizedName === 'mj: ai agent runs') {
+            return this.handleAgentRunEntityEvent(event, effectiveType);
+        }
+        if (normalizedName === 'mj: conversation detail artifacts' || normalizedName === 'mj: conversation detail ratings') {
+            return this.handlePeripheralJunctionEntityEvent(event);
+        }
+        // Not a conversation entity — let BaseEngine handle it
+        return await super.HandleIndividualBaseEntityEvent(event);
+    }
+    /**
+     * Extracts record data from a BaseEntityEvent.
+     * For local events: uses baseEntity directly.
+     * For remote-invalidate events: parses recordData JSON from the payload.
+     * Returns null if no data is available.
+     */
+    extractRecordData(event) {
+        // Local event — entity is available directly
+        if (event.baseEntity) {
+            return event.baseEntity.GetAll();
+        }
+        // Remote event — parse from payload
+        const payload = event.payload;
+        if (payload?.recordData) {
+            try {
+                return JSON.parse(payload.recordData);
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    }
+    /**
+     * Safely merges data onto a target object that may or may not be a BaseEntity.
+     * If the target has SetMany (i.e., it's a BaseEntity), uses that to properly handle
+     * read-only fields like __mj_CreatedAt. Otherwise falls back to Object.assign.
+     */
+    mergeDataOntoRecord(target, data) {
+        const t = target;
+        if (typeof t.SetMany === 'function') {
+            t.SetMany(data, true);
+        }
+        else {
+            Object.assign(target, data);
+        }
+    }
+    /**
+     * Handles save/delete events on Conversation entities from local or remote code.
+     */
+    handleConversationEntityEvent(event, action) {
+        const data = this.extractRecordData(event);
+        const id = data?.['ID'];
+        if (!id)
+            return true;
+        if (action === 'save') {
+            const existing = this.GetConversation(id);
+            if (existing) {
+                this.mergeDataOntoRecord(existing, data);
+                this._conversations$.next([...this._conversations$.value]);
+            }
+        }
+        else if (action === 'delete') {
+            const existing = this.GetConversation(id);
+            if (existing) {
+                this.removeFromList(id);
+                this.removeDetailCache(id);
+            }
+        }
+        return true;
+    }
+    /**
+     * Handles save/delete events on ConversationDetail entities from local or remote code.
+     */
+    handleConversationDetailEntityEvent(event, action) {
+        const entity = event.baseEntity;
+        const data = this.extractRecordData(event);
+        const id = data?.['ID'];
+        const conversationId = data?.['ConversationID'];
+        if (!id || !conversationId)
+            return true;
+        const key = NormalizeUUID(conversationId);
+        const cached = this._detailCache.get(key);
+        if (!cached)
+            return true;
+        if (action === 'save') {
+            const existingIdx = cached.Details.findIndex(d => UUIDsEqual(d.ID, id));
+            if (existingIdx >= 0) {
+                // For local events, use the entity directly; for remote, update fields in place
+                if (entity) {
+                    cached.Details[existingIdx] = entity;
+                }
+                else {
+                    this.mergeDataOntoRecord(cached.Details[existingIdx], data);
+                }
+            }
+            else if (entity) {
+                // New detail from local event — append the entity
+                cached.Details.push(entity);
+            }
+            // For new details from remote events, we can't construct a full entity here
+            // — the next loadMessages will pick it up from the engine cache
+        }
+        else if (action === 'delete') {
+            cached.Details = cached.Details.filter(d => !UUIDsEqual(d.ID, id));
+            cached.AgentRunsByDetailId.delete(id);
+        }
+        return true;
+    }
+    /**
+     * Handles save/delete events on AI Agent Run entities from local or remote code.
+     * Updates the AgentRunsByDetailId map so timers and status reflect reality.
+     */
+    handleAgentRunEntityEvent(event, action) {
+        const data = this.extractRecordData(event);
+        const id = data?.['ID'];
+        const detailId = data?.['ConversationDetailID'];
+        if (!id || !detailId)
+            return true;
+        // Find which conversation cache entry contains this detail ID
+        for (const [_key, cached] of this._detailCache) {
+            const detail = cached.Details.find(d => UUIDsEqual(d.ID, detailId));
+            if (detail) {
+                if (action === 'save') {
+                    // For local events, use the entity directly
+                    if (event.baseEntity) {
+                        cached.AgentRunsByDetailId.set(detailId, event.baseEntity);
+                    }
+                    else {
+                        // Remote event — update existing agent run in place, or skip if not cached
+                        const existing = cached.AgentRunsByDetailId.get(detailId);
+                        if (existing) {
+                            this.mergeDataOntoRecord(existing, data);
+                        }
+                    }
+                }
+                else if (action === 'delete') {
+                    cached.AgentRunsByDetailId.delete(detailId);
+                }
+                break;
+            }
+        }
+        return true;
+    }
+    /**
+     * Handles save/delete events on junction entities (Conversation Detail Artifacts,
+     * Conversation Detail Ratings) from local or remote code.
+     *
+     * These entities have joined fields (ArtifactName, UserName, etc.) that can't be
+     * reconstructed from the entity event alone, so we flag the cache as stale.
+     * The UI component checks PeripheralDataStale and force-refreshes when needed.
+     */
+    handlePeripheralJunctionEntityEvent(event) {
+        const data = this.extractRecordData(event);
+        const detailId = data?.['ConversationDetailID'];
+        if (!detailId)
+            return true;
+        for (const [_key, cached] of this._detailCache) {
+            const detail = cached.Details.find(d => UUIDsEqual(d.ID, detailId));
+            if (detail) {
+                cached.PeripheralDataStale = true;
+                break;
+            }
+        }
+        return true;
+    }
+    // ========================================================================
+    // PRIVATE HELPERS
+    // ========================================================================
+    /**
+     * Saves a partial update to a conversation entity.
+     */
+    async saveConversationField(id, updates, contextUser) {
+        const md = new Metadata();
+        const conversation = await md.GetEntityObject('MJ: Conversations', contextUser);
+        const loaded = await conversation.Load(id);
+        if (!loaded) {
+            throw new Error('Conversation not found');
+        }
+        if (updates.IsArchived !== undefined)
+            conversation.IsArchived = updates.IsArchived;
+        if (updates.IsPinned !== undefined)
+            conversation.IsPinned = updates.IsPinned;
+        if (updates.Name !== undefined)
+            conversation.Name = updates.Name;
+        if (updates.Description !== undefined)
+            conversation.Description = updates.Description;
+        const saved = await conversation.Save();
+        if (!saved) {
+            throw new Error(conversation.LatestResult?.Message || 'Failed to update conversation');
+        }
+        return true;
+    }
+    /**
+     * Removes a conversation from the in-memory list and emits the updated list.
+     */
+    removeFromList(id) {
+        const filtered = this._conversations$.value.filter(c => !UUIDsEqual(c.ID, id));
+        this._conversations$.next(filtered);
+    }
+    /**
+     * Removes multiple IDs from the cached list in a single emission.
+     * Used by DeleteMultipleConversations for a smooth batch UI update.
+     */
+    removeMultipleFromList(ids) {
+        const idSet = new Set(ids.map(id => NormalizeUUID(id)));
+        const filtered = this._conversations$.value.filter(c => !idSet.has(NormalizeUUID(c.ID)));
+        this._conversations$.next(filtered);
+    }
+    /**
+     * Removes the detail cache entry for a conversation.
+     */
+    removeDetailCache(conversationId) {
+        const key = NormalizeUUID(conversationId);
+        this._detailCache.delete(key);
+    }
+    /**
+     * Sorts conversations: pinned first, then by updated date descending.
+     */
+    sortConversations(conversations) {
+        return [...conversations].sort((a, b) => {
+            // Pinned conversations first
+            if (a.IsPinned && !b.IsPinned)
+                return -1;
+            if (!a.IsPinned && b.IsPinned)
+                return 1;
+            // Then by updated date descending
+            const aTime = a.__mj_UpdatedAt?.getTime() ?? 0;
+            const bTime = b.__mj_UpdatedAt?.getTime() ?? 0;
+            return bTime - aTime;
+        });
+    }
+}
+//# sourceMappingURL=conversations.js.map