# Matrx AI: Pi-Mono Integration Master Plan

Based on your direct feedback, we have fully aligned our objectives. The "Conversation Node Branching" initiative has been dropped since your system handles forking cleanly via full duplication. 

The remaining four initiatives have been meticulously expanded and categorized by their safety/risk profile into a concrete execution plan. 

---

## 🟢 TOTALLY SAFE (Greenfield & Refactors)
*These modifications are exceptionally safe to proceed with immediately. They either involve completely refactoring isolated components you intend to rebuild anyway, or adding new modular systems that log out quietly without touching critical orchestrator state.*

### 1. Sandbox Tool Resiliency & Overhaul (HIGH PRIORITY)
**Risk Profile:** Null. We have the green light to completely break and rebuild the command implementations. 
**Objective:** Bring Matrx AI's coding and shell execution tools up to the standard of a robust autonomous agent.
*   **The Code Tool (`code.py`):** Completely rewrite the edit mechanic to use unified diff string targeting with AST/Fuzzy-matching. It will require the LLM to output precise `old_text` contexts, verify exact/fuzzy alignment, and perform clean replacements, practically eliminating destructive file mangling loops.
*   **The Shell Tool (`shell.py`):** Implement a continuous stream-state mechanism. Instead of blocking and catching standard output linearly, it will enforce a strict byte-limit rolling tail buffer. If a command generates massive logs (e.g., `npm install`), it will redirect the bulk seamlessly into a sandbox `/tmp/` file and yield only the final truncated tail and the file path back to the LLM. 

### 2. The 5-Tier Context Compaction Engine (Stubbing & Scaffolding)
**Risk Profile:** Very Low. We will build the robust class architecture and hook it into the per-turn loop, structurally declaring all 5 tiers immediately. We will fully implement Tiers 1, 4, and 5 over time, while safely stubbing Tiers 2 and 3 with "coming soon" logging that immediately passes through unharmed.
**Objective:** Ensure agents can run infinitely without context-window overflow.
*   **Tier 1 (Targeted Removal):** Integrating existing logic to strip unnecessary system artifacts or resolved UI properties out of the payload dynamically on each turn. 
*   **Tier 2 (Minimal Assessment [Stubbed]):** Every turn runs a quick validation passing. Scans for duplicated blocks or giant chunks of historically dead context that can be pruned silently without losing chain-of-thought.
*   **Tier 3 (Context-to-Retrieval Conversion [Stubbed]):** Identify large payloads (e.g., massive file reads injected into history early on) and convert them dynamically into storage objects, replacing the explicit tokens with a retrieval reference pointer for the agent tools.
*   **Tier 4 (Aggressive Trimming):** Pre-emptive cost/quality threshold guard. If approaching expensive or hallucination-prone token bounds (e.g., 75% capacity), begin aggressively dropping older semantic tool results from the context window.
*   **Tier 5 (Hard Compression):** The final safety net. When hitting an absolute overflow failure, run an isolated sub-LLM call to lossily summarize the first 50% of the conversation into an injected context block, preserving the exact state of the last 10 messages flawlessly to securely recover the agent.

### 3. Broad Context File Detection & Review Pipeline
**Risk Profile:** Low. We are parsing files to an interface layer, not violently modifying the system context directly.
**Objective:** Sniff out environment configurations gracefully.
*   **The Sniffer:** Create a utility that scans the repository for `CLAUDE.md`, `.cursorrules`, `.antigravity/` configurations, `AGENTS.md`, and any agent-specific templates.
*   **The Review Layer:** Instead of auto-injecting these found contexts into the active config silently, format the payload and map it to an API endpoint / payload state that the Cloud UI can display as "Detected Contexts". This lets the human operator easily review and toggle which instructions to initialize the agent with.

---

## 🟡 REQUIRES CARE / DEBUGGING 
*These changes involve modifying the core execution loop and the structural mapping of the orchestrator API. They carry a risk of introducing race conditions or breaking existing active run-turn processing if not perfectly aligned.*

### 4. Asynchronous Steering & Follow-up Injection
**Risk Profile:** Medium-High. Messing with the synchronous flow of `execute_until_complete` means we must be absolutely certain that queue-interrupts do not break the active AI generation stream or database persistence mechanisms.
**Objective:** Allow human interrupts to inject cleanly into an executing agent.
*   **Queue States:** Establish `steering_queue` and `follow_up_queue` inside the active `AIMatrixRequest` object in memory. 
*   **API Endpoints:** Create corresponding generic POST endpoints `/api/orchestrator/steer` and `/api/orchestrator/follow-up` that safely locate the active request and drop messages into the respective asyncio queues.
*   **Orchestrator Injection (The Tricky Part):** 
    *   Hook into the orchestrator strictly at the boundary line *between* a tool result completing and the subsequent recursive LLM call. 
    *   Await a check against the `steering_queue`. If a user instruction (like *"Actually, use Python 3.10 for this script instead"*) is present, append it as a standard `user` message into the request stream cleanly. 
    *   This ensures the agent receives the interrupt text immediately *before* it gets a chance to evaluate the tool output, drastically altering its subsequent action.
    *   Follow-up messages will trigger cleanly after the finish reason evaluates to complete. 

---

### Suggested Execution Priority:
1. **Tool Resiliency** (Allows you to start running complex local node tasks fearlessly).
2. **5-Tier Compaction Scaffolding** (Immediate stability for large processes). 
3. **Context Detection** (Adds deep environmental awareness).
4. **Steering APIs** (Surgical iteration to bridge your frontend dashboards seamlessly). 
