@aj-archipelago/cortex 1.4.22 → 1.4.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aj-archipelago/cortex",
-  "version": "1.4.22",
+  "version": "1.4.24",
   "description": "Cortex is a GraphQL API for AI. It provides a simple, extensible interface for using AI services from OpenAI, Azure and others.",
   "private": false,
   "repository": {

package/pathways/system/entity/files/sys_read_file_collection.js

@@ -3,39 +3,50 @@
 // File collections are stored in Redis hash maps (FileStoreMap:ctx:<contextId>
 // Returns file collection as JSON array string for backward compatibility with Labeeb
 
-import { loadFileCollection } from '../../../../lib/fileUtils.js';
+import { loadMergedFileCollection } from '../../../../lib/fileUtils.js';
 
 export default {
     inputParameters: {
-        contextId: ``,
-        contextKey: ``,
+        agentContext: [
+            { contextId: ``, contextKey: ``, default: true }
+        ],
         useCache: true
     },
     // No format field - returns String directly (like sys_read_memory)
     model: 'oai-gpt4o',
 
     resolver: async (_parent, args, _contextValue, _info) => {
-        const { contextId, contextKey = null, useCache = true } = args;
+        let { agentContext } = args;
         
-        // Validate that contextId is provided
-        if (!contextId) {
+        // Backward compatibility: if contextId is provided without agentContext, create agentContext
+        if ((!agentContext || !Array.isArray(agentContext) || agentContext.length === 0) && args.contextId) {
+            agentContext = [{ 
+                contextId: args.contextId, 
+                contextKey: args.contextKey || null, 
+                default: true 
+            }];
+        }
+        
+        // Validate that agentContext is provided
+        if (!agentContext || !Array.isArray(agentContext) || agentContext.length === 0) {
             return JSON.stringify({ error: 'Context error' }, null, 2);
         }
         
         try {
-            // Load file collection from Redis hash maps
-            const collection = await loadFileCollection(contextId, contextKey, useCache);
+            // Load file collection from Redis hash maps (merged from all agentContext contexts)
+            const collection = await loadMergedFileCollection(agentContext);
             
             // Return as JSON array string for backward compatibility with Labeeb
             // Labeeb expects either: [] or { version: "...", files: [...] }
             // Since we removed versioning, we just return the array directly
-            // Ensure we always return a valid JSON array (empty if no files)
-            const result = Array.isArray(collection) ? collection : [];
+            // Strip internal _contextId before returning
+            const result = (Array.isArray(collection) ? collection : [])
+                .map(({ _contextId, ...file }) => file);
             return JSON.stringify(result);
         } catch (e) {
             // Log error for debugging
             const logger = (await import('../../../../lib/logger.js')).default;
-            logger.warn(`Error loading file collection for contextId ${contextId}: ${e.message}`);
+            logger.warn(`Error loading file collection: ${e.message}`);
             // Return empty array on error for backward compatibility
             return "[]";
         }

package/pathways/system/entity/files/sys_update_file_metadata.js

@@ -2,31 +2,40 @@
 // GraphQL pathway for updating file metadata (replaces sys_save_memory for renames and metadata updates)
 // Only updates Cortex-managed fields (displayFilename, tags, notes, etc.), not CFH fields (url, gcs, hash, filename)
 
-import { updateFileMetadata } from '../../../../lib/fileUtils.js';
+import { updateFileMetadata, getDefaultContext } from '../../../../lib/fileUtils.js';
 
 export default {
     inputParameters: {
-        contextId: ``,
+        agentContext: [{ contextId: ``, contextKey: ``, default: true }],
         hash: ``,
         displayFilename: { type: 'string' }, // Optional - no default
         tags: { type: 'array', items: { type: 'string' } }, // Optional - no default
         notes: { type: 'string' }, // Optional - no default
         mimeType: { type: 'string' }, // Optional - no default
         permanent: { type: 'boolean' }, // Optional - no default
-        inCollection: { type: 'array', items: { type: 'string' } }, // Optional - array of chat IDs, or can be boolean true/false (normalized to ['*'] or removed)
-        contextKey: `` // Optional - context key for encryption
+        inCollection: { type: 'array', items: { type: 'string' } } // Optional - array of chat IDs, or can be boolean true/false (normalized to ['*'] or removed)
     },
     model: 'oai-gpt4o',
     isMutation: true, // Declaratively mark this as a Mutation
 
     resolver: async (_parent, args, _contextValue, _info) => {
-        const { contextId, hash, displayFilename, tags, notes, mimeType, permanent, inCollection, contextKey } = args;
+        const { agentContext, hash, displayFilename, tags, notes, mimeType, permanent, inCollection, chatId } = args;
+        
+        const defaultCtx = getDefaultContext(agentContext);
+        if (!defaultCtx) {
+            return JSON.stringify({ 
+                success: false, 
+                error: 'agentContext with at least one default context is required' 
+            });
+        }
+        const contextId = defaultCtx.contextId;
+        const contextKey = defaultCtx.contextKey || null;
         
         // Validate required parameters
-        if (!contextId || !hash) {
+        if (!hash) {
             return JSON.stringify({ 
                 success: false, 
-                error: 'contextId and hash are required' 
+                error: 'hash is required' 
             });
         }
         
@@ -50,12 +59,13 @@ export default {
             }
             // inCollection can be: boolean true/false, or array of chat IDs (e.g., ['*'] for global, ['chat-123'] for specific chat)
             // Will be normalized by updateFileMetadata: true -> ['*'], false -> undefined (removed), array -> as-is
+            // If not provided, will default based on chatId
             if (inCollection !== undefined && inCollection !== null) {
                 metadata.inCollection = inCollection;
             }
             
             // Update metadata (only Cortex-managed fields)
-            const success = await updateFileMetadata(contextId, hash, metadata, contextKey);
+            const success = await updateFileMetadata(contextId, hash, metadata, contextKey, chatId);
             
             if (success) {
                 return JSON.stringify({ 

package/pathways/system/entity/sys_entity_agent.js

@@ -63,7 +63,9 @@ export default {
     inputParameters: {
         privateData: false,    
         chatHistory: [{role: '', content: []}],
-        contextId: ``,
+        agentContext: [
+            { contextId: ``, contextKey: ``, default: true }
+        ],
         chatId: ``,
         language: "English",
         aiName: "Jarvis",
@@ -76,8 +78,7 @@ export default {
         entityId: ``,
         researchMode: false,
         userInfo: '',
-        model: 'oai-gpt41',
-        contextKey: ``
+        model: 'oai-gpt41'
     },
     timeout: 600,
 
@@ -547,10 +548,11 @@ export default {
             args.chatHistory = args.chatHistory.slice(-20);
         }
 
-        // Sync files from chat history to collection and strip file content
-        // Files are accessible via tools (AnalyzeFile, ReadTextFile, etc.)
+        // Process files in chat history:
+        // - Files in collection (all agentContext contexts): stripped, accessible via tools
+        // - Files not in collection: left in message for model to see directly
         const { chatHistory: strippedHistory, availableFiles } = await syncAndStripFilesFromChatHistory(
-            args.chatHistory, args.contextId, args.contextKey
+            args.chatHistory, args.agentContext, chatId
         );
         args.chatHistory = strippedHistory;
 

package/pathways/system/entity/tools/sys_tool_codingagent.js

@@ -81,12 +81,12 @@ export default {
 
     executePathway: async ({args, resolver}) => {
         try {
-            const { codingTask, userMessage, inputFiles, codingTaskKeywords, contextId, contextKey } = args;
+            const { codingTask, userMessage, inputFiles, codingTaskKeywords } = args;
 
             let taskSuffix = "";
             if (inputFiles) {
-                if (!contextId) {
-                    throw new Error("contextId is required when using the 'inputFiles' parameter. Use ListFileCollection or SearchFileCollection to find available files.");
+                if (!args.agentContext || !Array.isArray(args.agentContext) || args.agentContext.length === 0) {
+                    throw new Error("agentContext is required when using the 'inputFiles' parameter. Use ListFileCollection or SearchFileCollection to find available files.");
                 }
                 
                 // Resolve file parameters to URLs
@@ -100,7 +100,7 @@ export default {
                 
                 for (const fileRef of fileReferences) {
                     // Try to resolve each file reference
-                    const resolvedUrl = await resolveFileParameter(fileRef, contextId, contextKey);
+                    const resolvedUrl = await resolveFileParameter(fileRef, args.agentContext);
                     if (resolvedUrl) {
                         resolvedUrls.push(resolvedUrl);
                     } else {

package/pathways/system/entity/tools/sys_tool_editfile.js

@@ -2,7 +2,7 @@
 // Entity tool that modifies existing files by replacing line ranges or exact string matches
 import logger from '../../../../lib/logger.js';
 import { axios } from '../../../../lib/requestExecutor.js';
-import { uploadFileToCloud, findFileInCollection, loadFileCollection, getMimeTypeFromFilename, deleteFileByHash, isTextMimeType, updateFileMetadata, writeFileDataToRedis, invalidateFileCollectionCache, getActualContentMimeType } from '../../../../lib/fileUtils.js';
+import { uploadFileToCloud, findFileInCollection, loadMergedFileCollection, getDefaultContext, getMimeTypeFromFilename, deleteFileByHash, isTextMimeType, updateFileMetadata, writeFileDataToRedis, invalidateFileCollectionCache, getActualContentMimeType } from '../../../../lib/fileUtils.js';
 
 // Maximum file size for editing (50MB) - prevents memory blowup on huge files
 const MAX_EDITABLE_FILE_SIZE = 50 * 1024 * 1024;
@@ -145,7 +145,19 @@ export default {
     ],
 
     executePathway: async ({args, runAllPrompts, resolver}) => {
-        const { file, startLine, endLine, content, oldString, newString, replaceAll = false, contextId, contextKey } = args;
+        const { file, startLine, endLine, content, oldString, newString, replaceAll = false, agentContext, chatId } = args;
+        
+        const defaultCtx = getDefaultContext(agentContext);
+        if (!defaultCtx) {
+            const errorResult = {
+                success: false,
+                error: "agentContext with at least one default context is required"
+            };
+            resolver.tool = JSON.stringify({ toolUsed: "EditFile" });
+            return JSON.stringify(errorResult);
+        }
+        const contextId = defaultCtx.contextId;
+        const contextKey = defaultCtx.contextKey || null;
         
         // Determine which tool was called based on parameters
         const isSearchReplace = oldString !== undefined && newString !== undefined;
@@ -162,14 +174,6 @@ export default {
             return JSON.stringify(errorResult);
         }
 
-        if (!contextId) {
-            const errorResult = {
-                success: false,
-                error: "contextId is required for file modification"
-            };
-            resolver.tool = JSON.stringify({ toolUsed: toolName });
-            return JSON.stringify(errorResult);
-        }
 
         // Validate that we have the right parameters for the tool being used
         if (!isSearchReplace && !isEditByLine) {
@@ -243,7 +247,7 @@ export default {
 
         try {
             // Resolve file ID first (needed for serialization)
-            const collection = await loadFileCollection(contextId, contextKey, false);
+            const collection = await loadMergedFileCollection(agentContext);
             const foundFile = findFileInCollection(file, collection);
             
             if (!foundFile) {
@@ -281,7 +285,7 @@ export default {
                     logger.info(`Using cached content for: ${currentFile.displayFilename || file}`);
                 } else {
                     // First edit in session: load collection and download file
-                    const currentCollection = await loadFileCollection(contextId, contextKey, false);
+                    const currentCollection = await loadMergedFileCollection(agentContext);
                     currentFile = findFileInCollection(file, currentCollection);
 
                     if (!currentFile) {
@@ -467,7 +471,7 @@ export default {
             if (editResult._isLastOperation) {
                 // Flush: upload the final content and update metadata
                 const { modifiedContent, currentFile, fileIdToUpdate: initialFileId, filename, mimeType, 
-                        modificationInfo, message, contextId: ctxId, contextKey: ctxKey, resolver: res,
+                        modificationInfo, message, resolver: res,
                         file: fileParam, isEditByLine: isByLine, isSearchReplace: isSR, replaceAll: repAll,
                         startLine: sLine, endLine: eLine } = editResult;
                 
@@ -482,7 +486,7 @@ export default {
                     mimeType,
                     filename,
                     res,
-                    ctxId
+                    contextId
                 );
 
                 if (!uploadResult || !uploadResult.url) {
@@ -490,7 +494,8 @@ export default {
                 }
 
                 // Update the file collection entry directly (atomic operation)
-                const latestCollection = await loadFileCollection(ctxId, ctxKey, false);
+                // Use default context from agentContext for consistency
+                const latestCollection = await loadMergedFileCollection(agentContext);
                 let fileToUpdate = latestCollection.find(f => f.id === fileIdToUpdate);
                 
                 // If not found by ID, try to find by the original file parameter
@@ -509,10 +514,10 @@ export default {
                 
                 // Write new entry with CFH data (url, gcs, hash) + Cortex metadata
                 if (uploadResult.hash) {
-                    const { getRedisClient } = await import('../../../../lib/fileUtils.js');
+                    const { getRedisClient, addChatIdToInCollection, getInCollectionValue } = await import('../../../../lib/fileUtils.js');
                     const redisClient = await getRedisClient();
                     if (redisClient) {
-                        const contextMapKey = `FileStoreMap:ctx:${ctxId}`;
+                        const contextMapKey = `FileStoreMap:ctx:${contextId}`;
                         
                         const existingDataStr = await redisClient.hget(contextMapKey, uploadResult.hash);
                         let existingData = {};
@@ -524,6 +529,12 @@ export default {
                             }
                         }
                         
+                        // Merge chatId into existing inCollection (reference counting)
+                        const existingInCollection = fileToUpdate.inCollection || existingData.inCollection;
+                        const updatedInCollection = existingInCollection 
+                            ? addChatIdToInCollection(existingInCollection, chatId)
+                            : getInCollectionValue(chatId);
+                        
                         const fileData = {
                             ...existingData,
                             url: uploadResult.url,
@@ -535,27 +546,27 @@ export default {
                             tags: fileToUpdate.tags || [],
                             notes: fileToUpdate.notes || '',
                             mimeType: fileToUpdate.mimeType || mimeType || null,
-                            inCollection: ['*'],
+                            inCollection: updatedInCollection,
                             addedDate: fileToUpdate.addedDate,
                             lastAccessed: new Date().toISOString(),
                             permanent: fileToUpdate.permanent || false
                         };
                         
-                        await writeFileDataToRedis(redisClient, contextMapKey, uploadResult.hash, fileData, ctxKey);
+                        await writeFileDataToRedis(redisClient, contextMapKey, uploadResult.hash, fileData, contextKey);
                         
                         if (oldHashToDelete && oldHashToDelete !== uploadResult.hash) {
                             await redisClient.hdel(contextMapKey, oldHashToDelete);
                         }
                         
-                        invalidateFileCollectionCache(ctxId, ctxKey);
+                        invalidateFileCollectionCache(contextId, contextKey);
                     }
                 } else if (fileToUpdate.hash) {
-                    await updateFileMetadata(ctxId, fileToUpdate.hash, {
+                    await updateFileMetadata(contextId, fileToUpdate.hash, {
                         filename: filename,
                         lastAccessed: new Date().toISOString()
-                    }, ctxKey);
+                    }, contextKey);
                     
-                    invalidateFileCollectionCache(ctxId, ctxKey);
+                    invalidateFileCollectionCache(contextId, contextKey);
                 }
 
                 // Delete old file version (fire-and-forget)
@@ -563,7 +574,7 @@ export default {
                     (async () => {
                         try {
                             logger.info(`Deleting old file version with hash ${oldHashToDelete} (background task)`);
-                            await deleteFileByHash(oldHashToDelete, res, ctxId);
+                            await deleteFileByHash(oldHashToDelete, res, contextId);
                         } catch (cleanupError) {
                             logger.warn(`Failed to cleanup old file version: ${cleanupError.message}`);
                         }

package/pathways/system/entity/tools/sys_tool_file_collection.js

@@ -3,7 +3,7 @@
 // Uses Redis hash maps (FileStoreMap:ctx:<contextId>) for storage
 // Supports atomic rename/tag/notes updates via UpdateFileMetadata
 import logger from '../../../../lib/logger.js';
-import { addFileToCollection, loadFileCollection, findFileInCollection, deleteFileByHash, updateFileMetadata, invalidateFileCollectionCache } from '../../../../lib/fileUtils.js';
+import { addFileToCollection, loadFileCollection, loadMergedFileCollection, findFileInCollection, deleteFileByHash, updateFileMetadata, invalidateFileCollectionCache, getDefaultContext } from '../../../../lib/fileUtils.js';
 
 export default {
     prompt: [],
@@ -198,7 +198,13 @@ export default {
     ],
 
     executePathway: async ({args, runAllPrompts, resolver}) => {
-        const { contextId, contextKey } = args;
+        const defaultCtx = getDefaultContext(args.agentContext);
+        if (!defaultCtx) {
+            throw new Error("agentContext with at least one default context is required");
+        }
+        const contextId = defaultCtx.contextId;
+        const contextKey = defaultCtx.contextKey || null;
+        const chatId = args.chatId || null;
 
         // Determine which function was called based on which parameters are present
         // Order matters: check most specific operations first
@@ -288,7 +294,7 @@ export default {
                 metadataUpdate.lastAccessed = new Date().toISOString();
 
                 // Perform the atomic update
-                const success = await updateFileMetadata(contextId, foundFile.hash, metadataUpdate, contextKey);
+                const success = await updateFileMetadata(contextId, foundFile.hash, metadataUpdate, contextKey, chatId);
                 
                 if (!success) {
                     throw new Error(`Failed to update file metadata for "${file}"`);
@@ -337,7 +343,8 @@ export default {
                     hash,
                     fileUrl,
                     resolver,
-                    permanent
+                    permanent,
+                    chatId
                 );
 
                 resolver.tool = JSON.stringify({ toolUsed: "AddFileToCollection" });
@@ -359,12 +366,12 @@ export default {
                 const safeFilterTags = Array.isArray(filterTags) ? filterTags : [];
                 const queryLower = query.toLowerCase();
                 
-                // Update lastAccessed for matching files directly (atomic operations)
-                const allFiles = await loadFileCollection(contextId, contextKey, false);
+                // Load primary collection for lastAccessed updates (only update files in primary context)
+                const primaryFiles = await loadFileCollection(contextId, contextKey, false);
                 const now = new Date().toISOString();
                 
-                // Find matching files and update lastAccessed directly
-                for (const file of allFiles) {
+                // Find matching files in primary collection and update lastAccessed directly
+                for (const file of primaryFiles) {
                     if (!file.hash) continue;
                     
                     // Fallback to filename if displayFilename is not set (for files uploaded before displayFilename was added)
@@ -381,14 +388,15 @@ export default {
                     
                     if (matchesQuery && matchesTags) {
                         // Update lastAccessed directly (atomic operation)
+                        // Don't pass chatId - we're only updating access time, not changing inCollection
                         await updateFileMetadata(contextId, file.hash, {
                             lastAccessed: now
                         }, contextKey);
                     }
                 }
                 
-                // Reload collection to get results (after update)
-                const updatedFiles = await loadFileCollection(contextId, contextKey, false);
+                // Load merged collection for search results (includes all agentContext files)
+                const updatedFiles = await loadMergedFileCollection(args.agentContext);
                 
                 // Filter and sort results (for display only, not modifying)
                 let results = updatedFiles.filter(file => {
@@ -444,7 +452,8 @@ export default {
                 });
 
             } else if (isRemove) {
-                // Remove file(s) from collection and delete from cloud storage
+                // Remove file(s) from this chat's collection (reference counting)
+                // Only delete from cloud if no other chats reference the file
                 const { fileIds, fileId } = args;
                 
                 // Normalize input to array
@@ -460,9 +469,9 @@ export default {
                 }
 
                 let notFoundFiles = [];
-                let filesToRemove = [];
+                let filesToProcess = [];
 
-                // Load collection ONCE to find all files and their hashes
+                // Load collection ONCE to find all files and their data
                 // Use useCache: false to get fresh data
                 const collection = await loadFileCollection(contextId, contextKey, false);
                 
@@ -474,12 +483,13 @@ export default {
                     
                     if (foundFile) {
                         // Avoid duplicates (by hash since that's the unique key in Redis)
-                        if (!filesToRemove.some(f => f.hash === foundFile.hash)) {
-                            filesToRemove.push({
+                        if (!filesToProcess.some(f => f.hash === foundFile.hash)) {
+                            filesToProcess.push({
                                 id: foundFile.id,
                                 displayFilename: foundFile.displayFilename || foundFile.filename || null,
                                 hash: foundFile.hash || null,
-                                permanent: foundFile.permanent ?? false
+                                permanent: foundFile.permanent ?? false,
+                                inCollection: foundFile.inCollection || []
                             });
                         }
                     } else {
@@ -487,34 +497,76 @@ export default {
                     }
                 }
 
-                if (filesToRemove.length === 0 && notFoundFiles.length > 0) {
+                if (filesToProcess.length === 0 && notFoundFiles.length > 0) {
                     throw new Error(`No files found matching: ${notFoundFiles.join(', ')}`);
                 }
 
-                // Use the hashes collected from the single collection load
-                // No need to reload - we already have all the info we need
-                const hashesToDelete = filesToRemove.filter(f => f.hash);
-                
-                // Delete entries directly from hash map (atomic operations)
-                const { getRedisClient } = await import('../../../../lib/fileUtils.js');
+                // Import helpers for reference counting
+                const { getRedisClient, removeChatIdFromInCollection } = await import('../../../../lib/fileUtils.js');
                 const redisClient = await getRedisClient();
+                const contextMapKey = `FileStoreMap:ctx:${contextId}`;
+                
+                // Track files that will be fully deleted vs just updated
+                const filesToFullyDelete = [];
+                const filesToUpdate = [];
+                
+                for (const fileInfo of filesToProcess) {
+                    if (!fileInfo.hash) continue;
+                    
+                    // Check if file is global ('*') - global files can't be removed per-chat
+                    const isGlobal = Array.isArray(fileInfo.inCollection) && fileInfo.inCollection.includes('*');
+                    
+                    if (isGlobal) {
+                        // Global file - fully remove it (no reference counting for global files)
+                        filesToFullyDelete.push(fileInfo);
+                    } else if (!chatId) {
+                        // No chatId context - fully remove
+                        filesToFullyDelete.push(fileInfo);
+                    } else {
+                        // Remove this chatId from inCollection
+                        const updatedInCollection = removeChatIdFromInCollection(fileInfo.inCollection, chatId);
+                        
+                        if (updatedInCollection.length === 0) {
+                            // No more references - fully delete
+                            filesToFullyDelete.push(fileInfo);
+                        } else {
+                            // Still has references from other chats - just update inCollection
+                            filesToUpdate.push({ ...fileInfo, updatedInCollection });
+                        }
+                    }
+                }
+                
+                // Update files that still have references (remove this chatId only)
+                for (const fileInfo of filesToUpdate) {
+                    if (redisClient) {
+                        try {
+                            const existingDataStr = await redisClient.hget(contextMapKey, fileInfo.hash);
+                            if (existingDataStr) {
+                                const existingData = JSON.parse(existingDataStr);
+                                existingData.inCollection = fileInfo.updatedInCollection;
+                                await redisClient.hset(contextMapKey, fileInfo.hash, JSON.stringify(existingData));
+                                logger.info(`Removed chatId ${chatId} from file: ${fileInfo.displayFilename} (still referenced by: ${fileInfo.updatedInCollection.join(', ')})`);
+                            }
+                        } catch (e) {
+                            logger.warn(`Failed to update inCollection for file ${fileInfo.hash}: ${e.message}`);
+                        }
+                    }
+                }
+                
+                // Fully delete files with no remaining references
                 if (redisClient) {
-                    const contextMapKey = `FileStoreMap:ctx:${contextId}`;
-                    for (const fileInfo of hashesToDelete) {
+                    for (const fileInfo of filesToFullyDelete) {
                         await redisClient.hdel(contextMapKey, fileInfo.hash);
                     }
                 }
                 
-                // Always invalidate cache immediately so list operations reflect removals
-                // (even if Redis operations failed, cache might be stale)
+                // Always invalidate cache immediately so list operations reflect changes
                 invalidateFileCollectionCache(contextId, contextKey);
 
-                // Delete files from cloud storage ASYNC (fire and forget, but log errors)
-                // We do this after updating collection so user gets fast response and files are "gone" from UI immediately
-                // Use hashes captured inside the lock to ensure we delete the correct files
+                // Delete files from cloud storage ASYNC (only for files with no remaining references)
                 // IMPORTANT: Don't delete permanent files from cloud storage - they should persist
                 (async () => {
-                    for (const fileInfo of hashesToDelete) {
+                    for (const fileInfo of filesToFullyDelete) {
                         // Skip deletion if file is marked as permanent
                         if (fileInfo.permanent) {
                             logger.info(`Skipping cloud deletion for permanent file: ${fileInfo.displayFilename} (hash: ${fileInfo.hash})`);
@@ -522,7 +574,7 @@ export default {
                         }
                         
                         try {
-                            logger.info(`Deleting file from cloud storage: ${fileInfo.displayFilename} (hash: ${fileInfo.hash})`);
+                            logger.info(`Deleting file from cloud storage (no remaining references): ${fileInfo.displayFilename} (hash: ${fileInfo.hash})`);
                             await deleteFileByHash(fileInfo.hash, resolver, contextId);
                         } catch (error) {
                             logger.warn(`Failed to delete file ${fileInfo.displayFilename} (hash: ${fileInfo.hash}) from cloud storage: ${error?.message || String(error)}`);
@@ -530,8 +582,13 @@ export default {
                     }
                 })().catch(err => logger.error(`Async cloud deletion error: ${err}`));
 
-                const removedCount = filesToRemove.length;
-                const removedFiles = filesToRemove;
+                const removedCount = filesToProcess.length;
+                const removedFiles = filesToProcess.map(f => ({
+                    id: f.id,
+                    displayFilename: f.displayFilename,
+                    hash: f.hash,
+                    fullyDeleted: filesToFullyDelete.some(fd => fd.hash === f.hash)
+                }));
 
                 // Get remaining files count after deletion
                 const remainingCollection = await loadFileCollection(contextId, contextKey, false);
@@ -560,8 +617,8 @@ export default {
                 // List collection (read-only, no locking needed)
                 const { tags: filterTags = [], sortBy = 'date', limit = 50 } = args;
                 
-                // Use useCache: false to ensure we get the latest file data (important after edits)
-                const collection = await loadFileCollection(contextId, contextKey, false);
+                // Use merged collection to include files from all agentContext contexts
+                const collection = await loadMergedFileCollection(args.agentContext);
                 let results = collection;
 
                 // Filter by tags if provided

package/pathways/system/entity/tools/sys_tool_image.js

@@ -113,7 +113,7 @@ export default {
                 
                 for (let i = 0; i < imagesToProcess.length; i++) {
                     const imageRef = imagesToProcess[i];
-                    const resolved = await resolveFileParameter(imageRef, args.contextId, args.contextKey);
+                    const resolved = await resolveFileParameter(imageRef, args.agentContext);
                     if (!resolved) {
                         throw new Error(`File not found: "${imageRef}". Use ListFileCollection or SearchFileCollection to find available files.`);
                     }

package/pathways/system/entity/tools/sys_tool_image_gemini.js

@@ -109,7 +109,7 @@ export default {
                 
                 for (let i = 0; i < imagesToProcess.length; i++) {
                     const imageRef = imagesToProcess[i];
-                    const resolved = await resolveFileParameter(imageRef, args.contextId, args.contextKey, { preferGcs: true });
+                    const resolved = await resolveFileParameter(imageRef, args.agentContext, { preferGcs: true });
                     if (!resolved) {
                         throw new Error(`File not found: "${imageRef}". Use ListFileCollection or SearchFileCollection to find available files.`);
                     }

package/pathways/system/entity/tools/sys_tool_readfile.js

@@ -135,20 +135,20 @@ export default {
             const MAX_CHARS = 100000;
             const MAX_LINES = 1000;
             
-            let { cloudUrl, file, startChar, endChar, startLine, endLine, contextId, contextKey } = args;
+            let { cloudUrl, file, startChar, endChar, startLine, endLine } = args;
             
             // If file parameter is provided, resolve it to a URL using the common utility
             if (file) {
-                if (!contextId) {
+                if (!args.agentContext || !Array.isArray(args.agentContext) || args.agentContext.length === 0) {
                     const errorResult = {
                         success: false,
-                        error: "contextId is required when using the 'file' parameter. Use ListFileCollection or SearchFileCollection to find available files."
+                        error: "agentContext is required when using the 'file' parameter. Use ListFileCollection or SearchFileCollection to find available files."
                     };
                     resolver.tool = JSON.stringify({ toolUsed: "ReadFile" });
                     return JSON.stringify(errorResult);
                 }
                 // Use useCache: false to ensure we get the latest file data (important after edits)
-                const resolvedUrl = await resolveFileParameter(file, contextId, contextKey, { useCache: false });
+                const resolvedUrl = await resolveFileParameter(file, args.agentContext, { useCache: false });
                 if (!resolvedUrl) {
                     const errorResult = {
                         success: false,