@aj-archipelago/cortex 1.4.22 → 1.4.24

package/lib/fileUtils.js

@@ -702,23 +702,21 @@ function parseRawFileData(allFiles, contextKey = null) {
  * Filter and format file collection based on inCollection and chatId
  * @param {Array} rawFiles - Array of parsed file data objects
  * @param {string|null} chatId - Optional chat ID to filter by
- * @returns {Array} Filtered and sorted file collection
+ * @returns {Array} Filtered and sorted file collection (includes inCollection for reference counting)
  */
 function filterAndFormatFileCollection(rawFiles, chatId = null) {
     // Filter by inCollection and optional chatId
     const filtered = rawFiles.filter(file => isFileInCollection(file.inCollection, chatId));
     
-    // Remove inCollection from output (internal metadata)
-    const formatted = filtered.map(({ inCollection, ...file }) => file);
-    
+    // Keep inCollection in output (needed for reference counting display)
     // Sort by lastAccessed (most recent first)
-    formatted.sort((a, b) => {
+    filtered.sort((a, b) => {
         const aDate = new Date(a.lastAccessed || a.addedDate || 0);
         const bDate = new Date(b.lastAccessed || b.addedDate || 0);
         return bDate - aDate;
     });
     
-    return formatted;
+    return filtered;
 }
 
 async function loadFileCollection(contextId, contextKey = null, useCache = true, chatId = null) {
@@ -768,6 +766,45 @@ async function loadFileCollection(contextId, contextKey = null, useCache = true,
     return filterAndFormatFileCollection(rawFiles, chatId);
 }
 
+/**
+ * Load ALL files from a context's file collection, bypassing inCollection filtering.
+ * Used when merging alt contexts where we want all files regardless of chat scope.
+ * @param {string} contextId - Context ID
+ * @param {string|null} contextKey - Optional encryption key
+ * @returns {Promise<Array>} All files in the collection
+ */
+async function loadFileCollectionAll(contextId, contextKey = null) {
+    if (!contextId) {
+        return [];
+    }
+
+    try {
+        const redisClient = await getRedisClient();
+        
+        if (redisClient) {
+            const contextMapKey = `FileStoreMap:ctx:${contextId}`;
+            const allFiles = await redisClient.hgetall(contextMapKey);
+            
+            // Parse raw file data
+            const rawFiles = parseRawFileData(allFiles, contextKey);
+            
+            // Return all files without inCollection filtering (keep inCollection for reference counting)
+            // Sort by lastAccessed (most recent first)
+            rawFiles.sort((a, b) => {
+                const aDate = new Date(a.lastAccessed || a.addedDate || 0);
+                const bDate = new Date(b.lastAccessed || b.addedDate || 0);
+                return bDate - aDate;
+            });
+            
+            return rawFiles;
+        }
+    } catch (e) {
+        // Collection doesn't exist yet or error reading
+    }
+    
+    return [];
+}
+
 /**
  * Normalize inCollection value to array format
  * @param {boolean|Array<string>|undefined} inCollection - inCollection value to normalize
@@ -798,16 +835,94 @@ function normalizeInCollection(inCollection) {
     return ['*'];
 }
 
+/**
+ * Get the appropriate inCollection value based on chatId
+ * Centralized function to ensure consistent behavior across all file operations
+ * @param {string|null|undefined} chatId - Optional chat ID
+ * @returns {Array<string>} Array with chatId if provided, otherwise ['*'] for global
+ */
+function getInCollectionValue(chatId = null) {
+    if (chatId && typeof chatId === 'string' && chatId.trim() !== '') {
+        return [chatId];
+    }
+    return ['*'];
+}
+
+/**
+ * Add a chatId to an existing inCollection array (reference counting)
+ * If the chatId is already present, returns the array unchanged.
+ * 
+ * IMPORTANT: inCollection is either ['*'] (global) OR [chatId, ...] (chat-scoped), never mixed.
+ * If inCollection contains '*' (global), it stays global - no chatIds are added.
+ * 
+ * @param {Array<string>|undefined} existingInCollection - Current inCollection value
+ * @param {string|null} chatId - Chat ID to add
+ * @returns {Array<string>} Updated inCollection array
+ */
+function addChatIdToInCollection(existingInCollection, chatId) {
+    // Normalize existing to array
+    const existing = Array.isArray(existingInCollection) ? existingInCollection : [];
+    
+    // If already global, stay global
+    if (existing.includes('*')) {
+        return existing;
+    }
+    
+    // If no chatId provided, return existing or default to global
+    if (!chatId || typeof chatId !== 'string' || chatId.trim() === '') {
+        return existing.length > 0 ? existing : ['*'];
+    }
+    
+    // Add chatId if not already present
+    if (!existing.includes(chatId)) {
+        return [...existing, chatId];
+    }
+    
+    return existing;
+}
+
+/**
+ * Remove a chatId from an inCollection array (reference counting)
+ * Returns the updated array without the chatId.
+ * 
+ * IMPORTANT: Global files (['*']) are not reference-counted - they return unchanged.
+ * Only chat-scoped files have chatIds removed. When removing from collection,
+ * global files should be fully deleted, not reference-counted.
+ * 
+ * @param {Array<string>|undefined} existingInCollection - Current inCollection value
+ * @param {string|null} chatId - Chat ID to remove
+ * @returns {Array<string>} Updated inCollection array (may be empty for chat-scoped files)
+ */
+function removeChatIdFromInCollection(existingInCollection, chatId) {
+    // Normalize existing to array
+    const existing = Array.isArray(existingInCollection) ? existingInCollection : [];
+    
+    // If no chatId provided, can't remove anything
+    if (!chatId || typeof chatId !== 'string' || chatId.trim() === '') {
+        return existing;
+    }
+    
+    // If global, removing a specific chatId doesn't make sense - return as-is
+    // (global files aren't scoped to chats)
+    if (existing.includes('*')) {
+        return existing;
+    }
+    
+    // Remove the chatId
+    return existing.filter(id => id !== chatId);
+}
+
 /**
  * Update file metadata in Redis hash map (direct atomic operation)
  * @param {string} contextId - Context ID
  * @param {string} hash - File hash
  * @param {Object} metadata - Metadata to update (displayFilename, id, tags, notes, mimeType, addedDate, lastAccessed, permanent, inCollection)
  * @param {string} contextKey - Optional context key for encryption
+ * @param {string|null} chatId - Optional chat ID, used as default for inCollection if not provided in metadata and not already set
  * Note: Does NOT update CFH core fields (url, gcs, hash, filename) - those are managed by CFH
  * @returns {Promise<boolean>} True if successful
  */
-async function updateFileMetadata(contextId, hash, metadata, contextKey = null) {
+async function updateFileMetadata(contextId, hash, metadata, contextKey = null, chatId = null) {
     if (!contextId || !hash) {
         return false;
     }
@@ -819,20 +934,24 @@ async function updateFileMetadata(contextId, hash, metadata, contextKey = null)
         }
         
         const contextMapKey = `FileStoreMap:ctx:${contextId}`;
-        // Get existing file data from CFH (if any)
+        // Get existing file data - must exist to update
         const existingDataStr = await redisClient.hget(contextMapKey, hash);
+        if (!existingDataStr) {
+            // File doesn't exist in this context - don't create new entries
+            return false;
+        }
         const existingData = readFileDataFromRedis(existingDataStr, contextKey) || {};
         
         // Merge CFH data with Cortex metadata
         // Only update Cortex-managed fields, preserve CFH fields (url, gcs, hash, filename)
         const fileData = {
             ...existingData, // Preserve all CFH data (url, gcs, hash, filename, etc.)
-            // Handle inCollection: normalize if provided, otherwise preserve existing or default to global
+            // Handle inCollection: normalize if provided, otherwise preserve existing or default based on chatId
             inCollection: metadata.inCollection !== undefined
                 ? normalizeInCollection(metadata.inCollection)
                 : (existingData.inCollection !== undefined
                     ? normalizeInCollection(existingData.inCollection)
-                    : ['*']),
+                    : getInCollectionValue(chatId)),
             // Update only Cortex-managed metadata fields
             ...(metadata.displayFilename !== undefined && { displayFilename: metadata.displayFilename }),
             ...(metadata.id !== undefined && { id: metadata.id }),
@@ -869,9 +988,10 @@ async function updateFileMetadata(contextId, hash, metadata, contextKey = null)
  * @param {string} contextId - Context ID for the file collection
  * @param {string} contextKey - Optional context key for encryption (unused with hash maps)
  * @param {Array} collection - File collection array
+ * @param {string|null} chatId - Optional chat ID, used for inCollection value (chat-scoped if provided, global if not)
  * @returns {Promise<boolean>} True if successful
  */
-async function saveFileCollection(contextId, contextKey, collection) {
+async function saveFileCollection(contextId, contextKey, collection, chatId = null) {
     const cacheKey = getCollectionCacheKey(contextId, contextKey);
 
     try {
@@ -932,7 +1052,10 @@ async function saveFileCollection(contextId, contextKey, collection) {
                     addedDate: file.addedDate || existingData.timestamp || new Date().toISOString(),
                     lastAccessed: file.lastAccessed || new Date().toISOString(),
                     permanent: file.permanent !== undefined ? file.permanent : (existingData.permanent || false),
-                    inCollection: ['*'] // Mark as global chat file (available to all chats)
+                    // Add chatId to existing inCollection (reference counting) - file may be used in multiple chats
+                    inCollection: existingData.inCollection 
+                        ? addChatIdToInCollection(existingData.inCollection, chatId)
+                        : getInCollectionValue(chatId)
                 };
                 
                 // Write back to hash map (atomic operation) - encryption happens in helper
@@ -968,9 +1091,11 @@ async function saveFileCollection(contextId, contextKey, collection) {
  * @param {string} hash - Optional file hash
  * @param {string} fileUrl - Optional: URL of file to upload (if not already in cloud storage)
  * @param {pathwayResolver} pathwayResolver - Optional pathway resolver for logging
+ * @param {boolean} permanent - If true, file is stored with permanent retention
+ * @param {string|null} chatId - Optional chat ID, used for inCollection value (chat-scoped if provided, global if not)
  * @returns {Promise<Object>} File entry object with id
  */
-async function addFileToCollection(contextId, contextKey, url, gcs, filename, tags = [], notes = '', hash = null, fileUrl = null, pathwayResolver = null, permanent = false) {
+async function addFileToCollection(contextId, contextKey, url, gcs, filename, tags = [], notes = '', hash = null, fileUrl = null, pathwayResolver = null, permanent = false, chatId = null) {
     if (!contextId || !filename) {
         throw new Error("contextId and filename are required");
     }
@@ -1078,7 +1203,10 @@ async function addFileToCollection(contextId, contextKey, url, gcs, filename, ta
                     tags: fileEntry.tags.length > 0 ? fileEntry.tags : (existingData.tags || []), // Merge tags if new ones provided
                     notes: fileEntry.notes || existingData.notes || '', // Keep existing notes if new ones empty
                     mimeType: fileEntry.mimeType || existingData.mimeType || null, // MIME type from URL (actual content type)
-                    inCollection: ['*'], // Mark as global chat file (available to all chats)
+                    // Add chatId to existing inCollection (reference counting) - file may be used in multiple chats
+                    inCollection: existingData.inCollection 
+                        ? addChatIdToInCollection(existingData.inCollection, chatId)
+                        : getInCollectionValue(chatId),
                     addedDate: existingData.addedDate || fileEntry.addedDate, // Keep earliest addedDate
                     lastAccessed: new Date().toISOString(), // Always update lastAccessed
                     permanent: fileEntry.permanent !== undefined ? fileEntry.permanent : (existingData.permanent || false),
@@ -1238,135 +1366,6 @@ function getActualContentMimeType(file) {
     return determineMimeTypeFromUrl(file.url, file.gcs, null);
 }
 
-/**
- * Sync files from chat history to file collection
- * @param {Array} chatHistory - Chat history to scan
- * @param {string} contextId - Context ID for the file collection
- * @param {string} contextKey - Optional context key for encryption
- * @returns {Promise<Array>} Array of file metadata objects
- */
-async function syncFilesToCollection(chatHistory, contextId, contextKey = null) {
-    if (!chatHistory || !Array.isArray(chatHistory) || !contextId) {
-        return [];
-    }
-
-    // Extract all files from chat history
-    const extractedFiles = extractFilesFromChatHistory(chatHistory);
-
-    if (extractedFiles.length === 0) {
-        // No new files to add, return existing collection
-        return await loadFileCollection(contextId, contextKey, true);
-    }
-
-    // Sync files - check individually and update only what's needed (atomic operations)
-    try {
-        const redisClient = await getRedisClient();
-        if (!redisClient) {
-            // No Redis, return existing collection
-            return await loadFileCollection(contextId, contextKey, true);
-        }
-        
-        const contextMapKey = `FileStoreMap:ctx:${contextId}`;
-        const existingFiles = await redisClient.hgetall(contextMapKey);
-        const existingByUrl = new Map();
-        const existingByGcs = new Map();
-        const existingByHash = new Map();
-        
-        // Build lookup maps from existing files
-        for (const [hash, dataStr] of Object.entries(existingFiles)) {
-            try {
-                const data = JSON.parse(dataStr);
-                if (data.url) existingByUrl.set(data.url, hash);
-                if (data.gcs) existingByGcs.set(data.gcs, hash);
-                if (hash) existingByHash.set(hash, hash);
-            } catch (e) {
-                // Skip invalid entries
-            }
-        }
-        
-        // Add/update files individually (atomic operations)
-        for (const file of extractedFiles) {
-            const existsByUrl = file.url && existingByUrl.has(file.url);
-            const existsByGcs = file.gcs && existingByGcs.has(file.gcs);
-            const existsByHash = file.hash && existingByHash.has(file.hash);
-            
-            if (!existsByUrl && !existsByGcs && !existsByHash && file.hash) {
-                // File not found in context-scoped map - check if CFH has it (context-scoped or unscoped)
-                // This handles the case where file was uploaded but not yet in this context's collection
-                const existingDataStr = await redisClient.hget(contextMapKey, file.hash);
-                let existingData = readFileDataFromRedis(existingDataStr, contextKey);
-                
-                // Also check unscoped map (CFH might have written it there)
-                if (!existingData) {
-                    const unscopedDataStr = await redisClient.hget("FileStoreMap", file.hash);
-                    existingData = readFileDataFromRedis(unscopedDataStr, contextKey);
-                }
-                
-                if (existingData) {
-                    // CFH already has this file - merge CFH data with Cortex metadata
-                    // Only set Cortex-managed fields (tags, notes, id, dates), preserve all CFH data
-                    // Ensure mimeType is set (CFH doesn't store it, so we need to determine it)
-                    // IMPORTANT: Determine MIME type from URL (actual content), not displayFilename
-                    // displayFilename may have original extension (e.g., .docx) while URL points to converted content (e.g., .md)
-                    const mimeType = existingData.mimeType || determineMimeTypeFromUrl(existingData.url, existingData.gcs, null);
-                    
-                    const fileData = {
-                        ...existingData, // Preserve all CFH data (url, gcs, filename, displayFilename, permanent, etc.)
-                        mimeType: mimeType, // Ensure mimeType is set
-                        id: existingData.id || `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`,
-                        tags: existingData.tags || [],
-                        notes: existingData.notes || '',
-                        addedDate: existingData.addedDate || existingData.timestamp || new Date().toISOString(),
-                        lastAccessed: new Date().toISOString(),
-                        inCollection: ['*'] // Mark as global chat file (available to all chats)
-                    };
-                    
-                    // Write to Redis - encryption happens in helper
-                    await writeFileDataToRedis(redisClient, contextMapKey, file.hash, fileData, contextKey);
-                } else {
-                    // File doesn't exist in CFH - create minimal entry (file referenced in chat but not uploaded)
-                    const mimeType = determineMimeTypeFromUrl(file.url, file.gcs, null);
-                    
-                    const fileData = {
-                        url: file.url,
-                        gcs: file.gcs || null,
-                        mimeType: mimeType,
-                        id: `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`,
-                        tags: [],
-                        notes: '',
-                        hash: file.hash,
-                        permanent: false,
-                        addedDate: new Date().toISOString(),
-                        lastAccessed: new Date().toISOString(),
-                        inCollection: ['*'] // Mark as global chat file (available to all chats)
-                    };
-                    
-                    // Write to Redis - encryption happens in helper
-                    await writeFileDataToRedis(redisClient, contextMapKey, file.hash, fileData, contextKey);
-                }
-            } else if (file.hash) {
-                // File exists - update lastAccessed directly
-                await updateFileMetadata(contextId, file.hash, {
-                    lastAccessed: new Date().toISOString()
-                }, contextKey);
-            }
-        }
-        
-        // Invalidate cache
-        const cacheKey = getCollectionCacheKey(contextId, contextKey);
-        fileCollectionCache.delete(cacheKey);
-    } catch (e) {
-        // Fallback: log error and return existing collection
-        const logger = (await import('./logger.js')).default;
-        logger.warn(`Failed to sync files individually: ${e.message}`);
-        // Return existing collection on error
-        return await loadFileCollection(contextId, contextKey, true);
-    }
-
-    // Return updated collection
-    return await loadFileCollection(contextId, contextKey, false);
-}
-
 /**
  * Get available files from file collection and format for template
  * @param {string} contextId - Context ID for the file collection
@@ -1430,69 +1429,164 @@ function formatFilesForTemplate(collection) {
 }
 
 /**
- * Get available files - now async and works with file collection
- * @param {Array} chatHistory - Chat history to scan
- * @param {string} contextId - Context ID for the file collection
- * @param {string} contextKey - Optional context key for encryption
- * @returns {Promise<string>} Formatted string of available files
+ * Extract default context from agentContext array (for writes/updates)
+ * @param {Array} agentContext - Array of context objects { contextId, contextKey, default }
+ * @returns {Object|null} Default context object or null if not found
  */
-async function getAvailableFiles(chatHistory, contextId, contextKey = null) {
-    if (!contextId) {
-        // Fallback to old behavior if no contextId
-        const files = extractFilesFromChatHistory(chatHistory);
-        return files.map(f => f.url).filter(Boolean).join('\n') || 'No files available.';
+function getDefaultContext(agentContext) {
+    if (!agentContext || !Array.isArray(agentContext) || agentContext.length === 0) {
+        return null;
     }
+    return agentContext.find(ctx => ctx.default === true) || agentContext[0] || null;
+}
 
-    // Sync files from chat history to collection
-    await syncFilesToCollection(chatHistory, contextId, contextKey);
+/**
+ * Load merged file collection from agentContext array
+ * Merges all contexts in the array for read operations
+ * @param {Array} agentContext - Array of context objects { contextId, contextKey, default }
+ * @returns {Promise<Array>} Merged file collection
+ */
+async function loadMergedFileCollection(agentContext) {
+    if (!agentContext || !Array.isArray(agentContext) || agentContext.length === 0) {
+        return [];
+    }
     
-    // Return formatted files from collection
-    return await getAvailableFilesFromCollection(contextId, contextKey);
+    // Load first context as primary - use loadFileCollectionAll to get all files (not filtered by inCollection)
+    const primaryCtx = agentContext[0];
+    const primaryCollection = await loadFileCollectionAll(primaryCtx.contextId, primaryCtx.contextKey || null);
+    
+    // Tag primary files with their source context
+    const collection = primaryCollection.map(f => ({ ...f, _contextId: primaryCtx.contextId }));
+    
+    // If only one context, return early
+    if (agentContext.length === 1) {
+        return collection;
+    }
+    
+    // Load and merge additional contexts
+    for (let i = 1; i < agentContext.length; i++) {
+        const ctx = agentContext[i];
+        if (!ctx.contextId) continue;
+        
+        // Load alternate collection - use loadFileCollectionAll to bypass inCollection filtering
+        // (we want ALL files from the alt context, not just global ones)
+        const altCollection = await loadFileCollectionAll(ctx.contextId, ctx.contextKey || null);
+        
+        // Build set of existing identifiers from current collection
+        const existingHashes = new Set(collection.map(f => f.hash).filter(Boolean));
+        const existingUrls = new Set(collection.map(f => f.url).filter(Boolean));
+        const existingGcs = new Set(collection.map(f => f.gcs).filter(Boolean));
+        
+        // Add files from alt collection that aren't already in collection, tagged with alt context
+        for (const file of altCollection) {
+            const isDupe = (file.hash && existingHashes.has(file.hash)) ||
+                           (file.url && existingUrls.has(file.url)) ||
+                           (file.gcs && existingGcs.has(file.gcs));
+            if (!isDupe) {
+                collection.push({ ...file, _contextId: ctx.contextId });
+            }
+        }
+    }
+    
+    return collection;
 }
 
 /**
- * Sync files from chat history to collection and strip file content from messages.
- * Files are synced to the collection where they can be accessed via tools (AnalyzeFile, ReadTextFile, etc.)
- * File content is replaced with placeholders to avoid sending large files to the model.
+ * Get available files from file collection (no syncing from chat history)
+ * @param {Array} chatHistory - Unused, kept for API compatibility
+ * @param {Array} agentContext - Array of context objects { contextId, contextKey, default }
+ * @returns {Promise<string>} Formatted string of available files
+ */
+async function getAvailableFiles(chatHistory, agentContext) {
+    if (!agentContext || !Array.isArray(agentContext) || agentContext.length === 0) {
+        return 'No files available.';
+    }
+    const collection = await loadMergedFileCollection(agentContext);
+    // Strip internal _contextId before formatting
+    const cleanCollection = collection.map(({ _contextId, ...file }) => file);
+    return formatFilesForTemplate(cleanCollection);
+}
+
+/**
+ * Process files in chat history:
+ * - Files IN collection (all agentContext contexts): update lastAccessed, add chatId to inCollection (reference counting), strip from message (tools can access)
+ * - Files NOT in collection: leave in message (model sees directly)
+ * 
  * @param {Array} chatHistory - Chat history array
- * @param {string} contextId - Context ID for file collection
- * @param {string|null} contextKey - Optional encryption key
- * @returns {Promise<{chatHistory: Array, availableFiles: string}>} Modified chat history and available files string
+ * @param {Array} agentContext - Array of context objects { contextId, contextKey, default }
+ * @param {string|null} chatId - Optional chat ID, added to inCollection for reference counting when files are accessed
+ * @returns {Promise<{chatHistory: Array, availableFiles: string}>}
  */
-async function syncAndStripFilesFromChatHistory(chatHistory, contextId, contextKey = null) {
+async function syncAndStripFilesFromChatHistory(chatHistory, agentContext, chatId = null) {
     if (!chatHistory || !Array.isArray(chatHistory)) {
         return { chatHistory: chatHistory || [], availableFiles: 'No files available.' };
     }
 
-    if (!contextId) {
-        // No contextId - can't sync to collection, just strip files
-        const strippedHistory = stripAllFilesFromChatHistory(chatHistory);
-        return { chatHistory: strippedHistory, availableFiles: 'No files available.' };
+    if (!agentContext || !Array.isArray(agentContext) || agentContext.length === 0) {
+        // No agentContext - no collection to check, leave all files in messages
+        return { chatHistory, availableFiles: 'No files available.' };
     }
 
-    // Sync files to collection first
-    await syncFilesToCollection(chatHistory, contextId, contextKey);
+    // Load merged collection once
+    const collection = await loadMergedFileCollection(agentContext);
     
-    // Get available files string
-    const availableFiles = await getAvailableFilesFromCollection(contextId, contextKey);
+    // Build lookup map from contextId to contextKey for updates
+    const contextKeyMap = new Map(agentContext.map(ctx => [ctx.contextId, ctx.contextKey || null]));
     
-    // Strip all file content from chat history
-    const strippedHistory = stripAllFilesFromChatHistory(chatHistory);
-    
-    return { chatHistory: strippedHistory, availableFiles };
-}
+    // Build lookup maps for fast matching and context lookup (need Maps, not Sets, to get full file object)
+    const collectionByHash = new Map(collection.filter(f => f.hash).map(f => [f.hash, f]));
+    const collectionByUrl = new Map(collection.filter(f => f.url).map(f => [f.url, f]));
+    const collectionByGcs = new Map(collection.filter(f => f.gcs).map(f => [f.gcs, f]));
 
-/**
- * Strip all file and image content from chat history, replacing with placeholders.
- * @param {Array} chatHistory - Chat history array
- * @returns {Array} Chat history with file content replaced by placeholders
- */
-function stripAllFilesFromChatHistory(chatHistory) {
-    if (!chatHistory || !Array.isArray(chatHistory)) {
-        return chatHistory || [];
-    }
+    // Helper to get file from collection (by hash, URL, or GCS) to find _contextId
+    const getFileFromCollection = (contentObj) => {
+        const fileHash = contentObj.hash;
+        const fileUrl = contentObj.url || contentObj.image_url?.url;
+        const fileGcs = contentObj.gcs;
+        
+        if (fileHash && collectionByHash.has(fileHash)) {
+            return collectionByHash.get(fileHash);
+        }
+        if (fileUrl && collectionByUrl.has(fileUrl)) {
+            return collectionByUrl.get(fileUrl);
+        }
+        if (fileGcs && collectionByGcs.has(fileGcs)) {
+            return collectionByGcs.get(fileGcs);
+        }
+        return null;
+    };
 
-    return chatHistory.map(message => {
+    // Helper to check if a file content object is in the collection
+    const isInCollection = (contentObj) => {
+        return getFileFromCollection(contentObj) !== null;
+    };
+    
+    // Helper to update file when stripped - use _contextId from collection to know which context to update
+    const updateStrippedFile = (contentObj) => {
+        const file = getFileFromCollection(contentObj);
+        if (!file || !file._contextId) return;
+        
+        // Use hash from the found file (may not be in contentObj)
+        const hash = file.hash;
+        if (!hash) return;
+        
+        // Get the correct contextKey for this file's context
+        const fileContextKey = contextKeyMap.get(file._contextId) || null;
+        
+        const now = new Date().toISOString();
+        // Update lastAccessed and add chatId to inCollection (reference counting)
+        // If this file is being used in a new chat, add that chat to the list
+        const updatedInCollection = addChatIdToInCollection(file.inCollection, chatId);
+        updateFileMetadata(file._contextId, hash, {
+            lastAccessed: now,
+            inCollection: updatedInCollection
+        }, fileContextKey).catch((err) => {
+            logger.warn(`Failed to update metadata for stripped file (hash=${hash}): ${err?.message || err}`);
+        });
+    };
+
+    // Process chat history - only strip files that are in collection
+    const processedHistory = chatHistory.map(message => {
         if (!message || message.role !== 'user' || !message.content) {
             return message;
         }
@@ -1502,9 +1596,14 @@ function stripAllFilesFromChatHistory(chatHistory) {
             const newContent = message.content.map(item => {
                 const contentObj = typeof item === 'string' ? tryParseJson(item) : item;
                 if (contentObj && (contentObj.type === 'image_url' || contentObj.type === 'file')) {
-                    // Extract filename for placeholder
-                    const filename = extractFilenameFromFileContent(contentObj);
-                    return { type: 'text', text: `[File: ${filename} - available via file tools]` };
+                    if (isInCollection(contentObj)) {
+                        // In collection - strip and update metadata
+                        updateStrippedFile(contentObj); // fire and forget
+                        const filename = extractFilenameFromFileContent(contentObj);
+                        return { type: 'text', text: `[File: ${filename} - available via file tools]` };
+                    }
+                    // Not in collection - leave as-is
+                    return item;
                 }
                 return item;
             });
@@ -1514,8 +1613,11 @@ function stripAllFilesFromChatHistory(chatHistory) {
         // Handle object content
         if (typeof message.content === 'object' && message.content !== null) {
             if (message.content.type === 'image_url' || message.content.type === 'file') {
-                const filename = extractFilenameFromFileContent(message.content);
-                return { ...message, content: `[File: ${filename} - available via file tools]` };
+                if (isInCollection(message.content)) {
+                    updateStrippedFile(message.content); // fire and forget
+                    const filename = extractFilenameFromFileContent(message.content);
+                    return { ...message, content: `[File: ${filename} - available via file tools]` };
+                }
             }
         }
 
@@ -1523,13 +1625,21 @@ function stripAllFilesFromChatHistory(chatHistory) {
         if (typeof message.content === 'string') {
             const contentObj = tryParseJson(message.content);
             if (contentObj && (contentObj.type === 'image_url' || contentObj.type === 'file')) {
-                const filename = extractFilenameFromFileContent(contentObj);
-                return { ...message, content: `[File: ${filename} - available via file tools]` };
+                if (isInCollection(contentObj)) {
+                    updateStrippedFile(contentObj); // fire and forget
+                    const filename = extractFilenameFromFileContent(contentObj);
+                    return { ...message, content: `[File: ${filename} - available via file tools]` };
+                }
             }
         }
 
         return message;
     });
+
+    // Strip internal _contextId before formatting (it's only needed for updates)
+    const cleanCollection = collection.map(({ _contextId, ...file }) => file);
+    const availableFiles = formatFilesForTemplate(cleanCollection);
+    return { chatHistory: processedHistory, availableFiles };
 }
 
 /**
@@ -1661,15 +1771,15 @@ function findFileInCollection(fileParam, collection) {
 /**
  * Resolve a file parameter to a URL by looking it up in the file collection
  * If the parameter is already a URL (starts with http:// or https://), returns it as-is
- * If contextId is provided, looks up the file in the collection and returns its URL
+ * If agentContext is provided, looks up the file in the merged collection and returns its URL
  * @param {string} fileParam - File ID, URL (Azure or GCS), hash, or filename from collection
- * @param {string} contextId - Context ID for the file collection
- * @param {string} contextKey - Optional context key for encryption
+ * @param {Array} agentContext - Array of context objects { contextId, contextKey, default }
  * @param {Object} options - Optional configuration
  * @param {boolean} options.preferGcs - If true, prefer GCS URL over Azure URL when available
+ * @param {boolean} options.useCache - If false, bypass cache (default: true, only used for single context)
  * @returns {Promise<string|null>} Resolved file URL, or null if not found
  */
-export async function resolveFileParameter(fileParam, contextId, contextKey = null, options = {}) {
+export async function resolveFileParameter(fileParam, agentContext, options = {}) {
     if (!fileParam || typeof fileParam !== 'string') {
         return null;
     }
@@ -1677,15 +1787,16 @@ export async function resolveFileParameter(fileParam, contextId, contextKey = nu
     const trimmed = fileParam.trim();
     const { preferGcs = false, useCache = true } = options;
 
-    // If no contextId, can't look up in collection - return null
-    if (!contextId) {
+    // If no agentContext, can't look up in collection - return null
+    if (!agentContext || !Array.isArray(agentContext) || agentContext.length === 0) {
         return null;
     }
 
     try {
-        // Load file collection and find the file
-        // useCache can be set to false to bypass cache (e.g., after file edits)
-        const collection = await loadFileCollection(contextId, contextKey, useCache);
+        // Load merged file collection (always use merged to get all files, not just global ones)
+        // Note: useCache option is ignored for merged collections (they always load fresh)
+        const collection = await loadMergedFileCollection(agentContext);
+        
         const foundFile = findFileInCollection(trimmed, collection);
         
         if (foundFile) {
@@ -1711,11 +1822,10 @@ export async function resolveFileParameter(fileParam, contextId, contextKey = nu
 /**
  * Generate file message content by looking up a file parameter in the file collection
  * @param {string} fileParam - File URL (Azure or GCS), file ID from collection, or file hash
- * @param {string} contextId - Context ID for the file collection
- * @param {string} contextKey - Optional context key for encryption
+ * @param {Array} agentContext - Array of context objects { contextId, contextKey, default }
  * @returns {Promise<Object|null>} Content object in the format for chat history, or null if not found
  */
-async function generateFileMessageContent(fileParam, contextId, contextKey = null) {
+async function generateFileMessageContent(fileParam, agentContext) {
     if (!fileParam || typeof fileParam !== 'string') {
         return null;
     }
@@ -1736,14 +1846,13 @@ async function generateFileMessageContent(fileParam, contextId, contextKey = nul
         logger.debug(`YouTube URL check failed for "${fileParam}": ${error.message}`);
     }
 
-    if (!contextId) {
-        // Without contextId, we can't look up in collection
-        // Return a basic content object from the URL
+    if (!agentContext || !Array.isArray(agentContext) || agentContext.length === 0) {
+        // Without agentContext, we can't look up in collection
         return null;
     }
 
-    // Load file collection
-    const collection = await loadFileCollection(contextId, contextKey, true);
+    // Load merged file collection
+    const collection = await loadMergedFileCollection(agentContext);
 
     // Find the file using shared matching logic
     const foundFile = findFileInCollection(fileParam, collection);
@@ -1754,8 +1863,9 @@ async function generateFileMessageContent(fileParam, contextId, contextKey = nul
     }
 
     // Resolve to short-lived URL if possible
-    // Pass contextId to ensure files are found in the correct context scope
-    const fileWithShortLivedUrl = await ensureShortLivedUrl(foundFile, MEDIA_API_URL, contextId);
+    // Use default context for ensureShortLivedUrl
+    const defaultCtx = getDefaultContext(agentContext);
+    const fileWithShortLivedUrl = await ensureShortLivedUrl(foundFile, MEDIA_API_URL, defaultCtx?.contextId || null);
 
     return {
         type: 'image_url',
@@ -2393,8 +2503,9 @@ export {
     markCompletedForCleanUp,
     extractFileMetadataFromContent,
     extractFilesFromChatHistory,
-    syncFilesToCollection,
     getAvailableFilesFromCollection,
+    getDefaultContext,
+    loadMergedFileCollection,
     formatFilesForTemplate,
     getAvailableFiles,
     syncAndStripFilesFromChatHistory,
@@ -2404,6 +2515,7 @@ export {
     injectFileIntoChatHistory,
     addFileToCollection,
     loadFileCollection,
+    loadFileCollectionAll,
     saveFileCollection,
     updateFileMetadata,
     getCollectionCacheKey,
@@ -2413,6 +2525,9 @@ export {
     uploadFileToCloud,
     uploadImageToCloud,
     resolveFileHashesToContent,
+    getInCollectionValue,
+    addChatIdToInCollection,
+    removeChatIdFromInCollection,
     getMimeTypeFromFilename,
     getMimeTypeFromExtension,
     isTextMimeType,