Simplify File Handling, Tune Agentic

[jmacAJ]

An extensive overall of the file handling system provides a more scalable, secure, and performant architecture for managing files in Cortex. This update also introduces dynamic generation of REST endpoints directly from model configurations and adds several new agent tools.

🚀 File System Architecture Overhaul

The file system has been completely refactored to improve scalability, security, and concurrency. This introduces a single-container architecture, atomic file collection management, and context-scoping for multi-tenancy.

• Single Container Architecture: The system now uses a single Azure Blob Storage container. The AZURE_STORAGE_CONTAINER_NAME environment variable now accepts only one container name. Files are distinguished using blob index tags (retention=temporary or retention=permanent) instead of separate containers.
• Atomic File Collections: File collections are now stored in Redis hash maps (FileStoreMap:ctx:<contextId>), and all modifications are performed using atomic Redis operations (e.g., HSET, HDEL). This eliminates race conditions and the need for version-based locking, significantly improving reliability and performance.
• Context Scoping (contextId): All file operations now support an optional contextId to provide per-user or per-context file isolation, which is critical for multi-tenant applications.
• File Retention Management: A new setRetention operation allows files to be marked as permanent. By default, all uploaded files are temporary and are automatically deleted after 30 days. This is managed via blob index tags, requiring no file movement.
• Secure, Short-Lived URLs: All file retrieval operations now generate and return a shortLivedUrl (with a default 5-minute expiration) for secure, time-limited access, which is the preferred method for providing files to LLMs.
• New System Pathways:
  • sys_read_file_collection: A new GraphQL query to read the file collection for a given context.
  • sys_update_file_metadata: A new GraphQL mutation for atomically updating a file's metadata (e.g., filename, tags, notes).
• Comprehensive Documentation: A new detailed document, FILE_SYSTEM_DOCUMENTATION.md, has been added to cover the entire file system architecture, including data flows, API endpoints, and best practices.

✨ Dynamic REST Endpoint Generation

Cortex can now automatically generate OpenAI-compatible REST endpoints for any configured model, eliminating the need to create individual sys_rest_streaming_* pathway files.

• Automatic Endpoint Exposure: To expose a model, simply add emulateOpenAIChatModel: "your-model-name" or emulateOpenAICompletionModel: "your-model-name" to its definition in config.js.
• Customization: An optional restStreaming block can be added to the model configuration to customize the generated pathway's timeout, inputParameters, and other settings.
• Example Configuration:

  "my-custom-model": {
      "type": "OPENAI-CHAT",
      "emulateOpenAIChatModel": "my-model-v1",
      "restStreaming": {
          "timeout": 180
      },
      "url": "https://api.example.com/v1/chat/completions",
      ...
  }

📚 Documentation & Tooling Improvements

• Model Override Documentation: The README.md has been updated with a comprehensive guide on using model for static model selection and modelOverride for dynamic, runtime model switching.
• New Agent Tools:
  • CreatePlan: A new planning tool that uses a high-reasoning model to generate detailed, step-by-step plans for complex tasks.
  • ViewImages: Allows the agent to view image files from its file collection, injecting them into the conversation for analysis.
• Agent Enhancements:
  • The sys_entity_agent can now process image objects returned by the ViewImages tool in addition to base64-encoded screenshots.
  • System messages for task completion have been improved to better "challenge" the model to ensure tasks are fully completed before responding.
• Infrastructure: Redis clients now use an exponential backoff retry strategy, making connections more resilient to temporary network issues.

[Copilot]

Pull request overview

This pull request modernizes the Cortex File Handler's storage architecture by consolidating to a single Azure Blob Storage container with blob index tags for lifecycle management, introducing context-scoped file isolation via Redis hash maps, and adding support for short-lived URLs. The changes also include new pathways for file metadata management, a new Gemini 3 reasoning plugin, removal of legacy OpenAI pathway stubs, and updates to entity constants for improved agentic behavior.

Key changes:

• Simplified Azure storage from multiple containers to a single container with retention tags (temporary/permanent)
• Introduced contextId parameter for per-user/tenant file isolation using Redis keys in format <hash>:ctx:<contextId>
• Added short-lived URL support (5-minute expiration) for secure file access across all file handler responses
• New GraphQL pathways: sys_read_file_collection, sys_update_file_metadata with mutation support
• Added Gemini3ReasoningVisionPlugin for reasoning-enabled vision models
• Removed legacy OpenAI pathway stubs (o3, gpt-5, gpt-4.1, grok-4, ollama, gemini-2.5)

Reviewed changes

Copilot reviewed 86 out of 86 changed files in this pull request and generated 15 comments.

Show a summary per file

File	Description
tests/unit/core/*.test.js	Updated unit tests for file collection and short-lived URL functionality
tests/integration/features/tools/*.test.js	Updated integration tests to use direct Redis access instead of memory system
pathways/system/entity/tools/*.js	Updated file collection tools to use Redis hash maps and context scoping
pathways/system/entity/files/*.js	New pathways for file collection and metadata management
pathways/system/entity/memory/*.js	Removed memoryFiles from memory system (now separate in Redis)
pathways/system/rest_streaming/*.js	Removed legacy pathway stubs for unreleased models
server/typeDef.js	Added mutation support with isMutation flag
server/graphql.js	Updated resolvers to support mutations
server/plugins/*.js	New Gemini3ReasoningVisionPlugin and updates for contextId support
lib/fileUtils.js	Major refactor for Redis hash maps, context scoping, and short-lived URLs
lib/entityConstants.js	Updated entity prompts for improved agentic behavior
helper-apps/cortex-file-handler/tests/*.test.js	Comprehensive test updates for single-container architecture
helper-apps/cortex-file-handler/src/*.js	Storage service updates for retention tags and context scoping

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 94 out of 95 changed files in this pull request and generated 2 comments.

Files not reviewed (1)

• helper-apps/cortex-file-handler/package-lock.json: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.