Track Specification: Enhanced Context Control & Cache Awareness (enhanced_context_control_20260307)

Overview

Give developers granular control over how files are included in the AI context and provide visibility into the active Gemini cache state. This involves moving away from a simple list of files to a structured format with per-file flags (auto_aggregate, force_full), revamping the UI to display this state, and updating the context builders and API clients to respect and expose these details.

Core Requirements

1. `project.toml` Schema Update

Migrate the tracked_files list to a more structured format (or preserve list for compatibility but support dictionaries/objects per file).
Support per-file flags:
- auto_aggregate (bool, default true): Whether to automatically include this file in context aggregation.
- force_full (bool, default false): Whether to send the full file content, overriding skeleton extraction.

2. Files & Media Panel Refactoring

Replace the existing simple list/checkboxes in the GUI (src/gui_2.py) with a structured table.
Columns should include: File Name, Auto-Aggregate (checkbox), Force Full (checkbox), and a 'Cached' indicator (e.g., a green dot).
The GUI must reflect real-time updates from the background threads using the established event queue (_process_pending_gui_tasks).

3. 'Context' Role for Manual Injections

Implement a 'Context' role that allows manual file injections into discussions.
Context amnesia needs to respect these manual inclusions or properly categorize them.

4. `aggregate.py` Updates

build_file_items() and tier-specific context builders must respect the auto_aggregate and force_full flags.
If auto_aggregate is false, the file is omitted unless manually injected.
If force_full is true, bypass skeleton extraction (like ASTParser.get_skeleton()) and include the full file content.

5. `ai_client.py` Cache Tracking

Add state tracking for the active Gemini cache (e.g., tracking which file hashes/paths are currently embedded in the CachedContent).
Expose this state back to the UI (via AsyncEventQueue and mma_state_update or a dedicated "refresh_api_metrics" action) so the GUI can render the 'Cached' indicator dots.
Ensure thread safety (_send_lock and appropriate variable locks) when updating and reading cache state.

Architectural Constraints

Follow the 1-space indentation rule for Python.
Obey the decoupling of GUI (main thread) and asyncio background workers. All UI state mutations must occur via _process_pending_gui_tasks.
No new third-party dependencies unless strictly necessary.

Key Integration Points

src/project_manager.py: TOML serialization/deserialization for tracked files.
src/gui_2.py: The "Files & Media" panel and _process_pending_gui_tasks.
src/aggregate.py: Context building logic.
src/ai_client.py: Gemini API cache tracking.

2.9 KiB Raw Blame History