checkpoint, mma condcutor pain

.gemini/skills/mma-orchestrator/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: mma-orchestrator
+description: Enforces the 4-Tier Hierarchical Multi-Model Architecture (MMA) within Gemini CLI using Token Firewalling and sub-agent task delegation.
+---
+
+# MMA Token Firewall & Tiered Delegation Protocol
+
+You are operating as a Tier 1 Product Manager or Tier 2 Tech Lead within the MMA Framework. Your context window is extremely valuable and must be protected from token bloat (such as raw, repetitive code edits, trial-and-error histories, or massive stack traces).
+
+To accomplish this, you MUST delegate token-heavy or stateless tasks to "Tier 3 Contributors" or "Tier 4 QA Agents" by spawning secondary Gemini CLI instances via `run_shell_command`.
+
+**CRITICAL Prerequisite:**
+To avoid hanging the CLI and ensure proper environment authentication, you MUST NOT call the `gemini` command directly. Instead, you MUST use the wrapper script:
+`.\scripts\run_subagent.ps1 -Role <Role> -Prompt "..."`
+
+## 1. The Tier 3 Worker (Heads-Down Coding)
+When you need to perform a significant code modification (e.g., refactoring a 50-line+ script, writing a massive class, or implementing a predefined spec):
+1. **DO NOT** attempt to write or use `replace`/`write_file` yourself. Your history will bloat.
+2. **DO** construct a single, highly specific prompt.
+3. **DO** spawn a sub-agent using `run_shell_command` pointing to the target file.
+   *Command:* `.\scripts\run_subagent.ps1 -Role Worker -Prompt "Read [FILE_PATH] and modify it to implement [SPECIFIC_INSTRUCTION]. Only write the code, no pleasantries."`
+4. The Tier 3 Worker is stateless and has no tool access. You must take the clean code it returns and apply it to the file system using your own `replace` or `write_file` tools.
+
+## 2. The Tier 4 QA Agent (Error Translation)
+If you run a local test (e.g., `npm test`, `pytest`, `go run`) via `run_shell_command` and it fails with a massive traceback (e.g., 100+ lines of `stderr`):
+1. **DO NOT** analyze the raw `stderr` in your own context window.
+2. **DO** immediately spawn a stateless Tier 4 agent to compress the error.
+3. *Command:* `.\scripts\run_subagent.ps1 -Role QA -Prompt "Summarize this stack trace into a 20-word fix: [PASTE_SNIPPET_OF_STDERR_HERE]"`
+4. Use the 20-word fix returned by the Tier 4 agent to inform your next architectural decision or pass it to the Tier 3 worker.
+
+## 3. Context Amnesia (Phase Checkpoints)
+When you complete a major Phase or Track within the `conductor` workflow:
+1. Stage your changes and commit them.
+2. Draft a comprehensive summary of the state changes in a Git Note attached to the commit.
+3. Treat the checkpoint as a "Memory Wipe." Actively disregard previous conversational turns and trial-and-error histories. Rely exclusively on the newly generated Git Note and the physical state of the files on disk for your next Phase.
+
+<examples>
+### Example 1: Spawning a Tier 4 QA Agent
+**User / System:** `pytest tests/test_gui.py` failed with 400 lines of output.
+**Agent (You):** 
+```json
+{
+  "command": ".\\scripts\\run_subagent.ps1 -Role QA -Prompt \"Summarize this stack trace into a 20-word fix: [snip first 30 lines...]\"",
+  "description": "Spawning Tier 4 QA to compress error trace statelessly."
+}
+```
+
+### Example 2: Spawning a Tier 3 Worker
+**User:** Please implement the `ASTParser` class in `file_cache.py` as defined in Track 1.
+**Agent (You):**
+```json
+{
+  "command": ".\\scripts\\run_subagent.ps1 -Role Worker -Prompt \"Read file_cache.py and implement the ASTParser class using tree-sitter. Ensure you preserve docstrings but strip function bodies. Output the updated code.\"",
+  "description": "Delegating implementation to a Tier 3 Worker."
+}
+```
+</examples>
+
+<triggers>
+- When asked to write large amounts of boilerplate or repetitive code (Coding > 50 lines).
+- When encountering a large error trace from a shell execution (Errors > 100 lines).
+- When explicitly instructed to act as a "Tech Lead" or "Orchestrator".
+- When managing complex, multi-file Track implementations.
+</triggers>

conductor/tracks.md

@@ -38,3 +38,9 @@ This file tracks all major tracks for the project. Each track has its own detail
 - [ ] **Track: Support gemini cli headless as an alternative to the raw client_api route. So that they user may use their gemini subscription and gemini cli features within manual slop for a more discliplined and visually enriched UX.**
 *Link: [./tracks/gemini_cli_headless_20260224/](./tracks/gemini_cli_headless_20260224/)*
 
+
+---
+
+- [~] **Track: Support headless manual_slop for making an unraid gui docker frontend and a unraid server backend down the line.**
+*Link: [./tracks/manual_slop_headless_20260225/](./tracks/manual_slop_headless_20260225/)*
+

conductor/tracks/manual_slop_headless_20260225/index.md

@@ -0,0 +1,5 @@
+# Track manual_slop_headless_20260225 Context
+
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Metadata](./metadata.json)

conductor/tracks/manual_slop_headless_20260225/metadata.json

@@ -0,0 +1,8 @@
+{
+  "track_id": "manual_slop_headless_20260225",
+  "type": "feature",
+  "status": "new",
+  "created_at": "2026-02-25T12:00:00Z",
+  "updated_at": "2026-02-25T12:00:00Z",
+  "description": "Support headless manual_slop for making an unraid gui docker frontend and a unraid server backend down the line."
+}

conductor/tracks/manual_slop_headless_20260225/plan.md

@@ -0,0 +1,49 @@
+# Implementation Plan: Manual Slop Headless Backend
+
+## Phase 1: Project Setup & Headless Scaffold
+- [x] Task: Update dependencies (02fc847)
+    - [ ] Add `fastapi` and `uvicorn` to `pyproject.toml` (and sync `requirements.txt` via `uv`).
+- [~] Task: Implement headless startup
+    - [ ] Modify `gui_2.py` (or create `headless.py`) to parse a `--headless` CLI flag.
+    - [ ] Update config parsing in `config.toml` to support headless configuration sections.
+    - [ ] Bypass Dear PyGui initialization if headless mode is active.
+- [ ] Task: Create foundational API application
+    - [ ] Set up the core FastAPI application instance.
+    - [ ] Implement `/health` and `/status` endpoints for Docker lifecycle checks.
+- [ ] Task: Conductor - User Manual Verification 'Project Setup & Headless Scaffold' (Protocol in workflow.md)
+
+## Phase 2: Core API Routes & Authentication
+- [ ] Task: Implement API Key Security
+    - [ ] Create a dependency/middleware in FastAPI to validate `X-API-KEY`.
+    - [ ] Configure the API key validator to read from environment variables or `manual_slop.toml` (supporting Unraid template secrets).
+    - [ ] Add tests for authorized and unauthorized API access.
+- [ ] Task: Implement AI Generation Endpoint
+    - [ ] Create a `/api/v1/generate` POST endpoint.
+    - [ ] Map request payloads to `ai_client.py` unified wrappers.
+    - [ ] Return standard JSON responses with the generated text and token metrics.
+- [ ] Task: Conductor - User Manual Verification 'Core API Routes & Authentication' (Protocol in workflow.md)
+
+## Phase 3: Remote Tool Confirmation Mechanism
+- [ ] Task: Refactor Execution Engine for Async Wait
+    - [ ] Modify `shell_runner.py` and tool-call loops to support a non-blocking "Pending Confirmation" state instead of launching a GUI modal.
+- [ ] Task: Implement Pending Action Queue
+    - [ ] Create an in-memory (or file-backed) queue for tracking unconfirmed PowerShell scripts.
+- [ ] Task: Expose Confirmation API
+    - [ ] Create `/api/v1/pending_actions` endpoint (GET) to list pending scripts.
+    - [ ] Create `/api/v1/confirm/{action_id}` endpoint (POST) to approve or deny a script execution.
+    - [ ] Ensure the AI generation loop correctly resumes upon receiving approval.
+- [ ] Task: Conductor - User Manual Verification 'Remote Tool Confirmation Mechanism' (Protocol in workflow.md)
+
+## Phase 4: Session & Context Management via API
+- [ ] Task: Expose Session History
+    - [ ] Create endpoints to list, retrieve, and delete session logs from the `project_history.toml`.
+- [ ] Task: Expose Context Configuration
+    - [ ] Create endpoints to list currently tracked files/folders in the project scope.
+- [ ] Task: Conductor - User Manual Verification 'Session & Context Management via API' (Protocol in workflow.md)
+
+## Phase 5: Dockerization
+- [ ] Task: Create Dockerfile
+    - [ ] Write a `Dockerfile` using `python:3.11-slim` as a base.
+    - [ ] Configure `uv` inside the container for fast dependency installation.
+    - [ ] Expose the API port (e.g., 8000) and set the container entrypoint.
+- [ ] Task: Conductor - User Manual Verification 'Dockerization' (Protocol in workflow.md)

conductor/tracks/manual_slop_headless_20260225/spec.md

@@ -0,0 +1,48 @@
+# Specification: Manual Slop Headless Backend
+
+## Overview
+Transform Manual Slop into a decoupled, container-friendly backend service. This track enables the core AI orchestration and tool execution logic to run without a GUI, exposing its capabilities via a secured REST API optimized for an Unraid Docker environment.
+
+## Goals
+- Decouple the GUI logic (`Dear PyGui`, `ImGui`) from the core AI and Tool logic.
+- Implement a lightweight REST API server (FastAPI) to handle AI interactions.
+- Ensure full compatibility with Unraid Docker networking and configuration patterns.
+- Maintain the "Human-in-the-Loop" safety model through a remote confirmation mechanism.
+
+## Functional Requirements
+
+### 1. Headless Mode Lifecycle
+- **Startup**: Provide a `--headless` flag or `[headless]` section in `manual_slop.toml` to skip GUI initialization.
+- **Dependencies**: Ensure the app can start in environments without an X11/Wayland display or GPU.
+- **Service Mode**: Support running as a persistent background daemon/service.
+
+### 2. REST API (FastAPI)
+- **Status/Health**: `/status` and `/health` endpoints for Docker/Unraid monitoring.
+- **AI Interface**: `/generate` and `/stream` endpoints to interact with configured AI providers.
+- **Tool Management**: Endpoints to list and execute tools (PowerShell/MCP).
+- **Session Support**: Manage conversation history and project context via API.
+
+### 3. Security & Authentication
+- **API Key**: Require a `X-API-KEY` header for all sensitive endpoints.
+- **Unraid Integration**: API keys should be configurable via Environment Variables (standard for Unraid templates).
+
+### 4. Remote Confirmation Mechanism
+- **Challenge/Response**: When a tool requires execution, the API should return a "Pending Confirmation" state.
+- **Webhook/Poll**: Support a mechanism (e.g., a `/confirm/{id}` endpoint) for the future frontend to approve/deny actions.
+
+## Non-Functional Requirements
+- **Performance**: Headless mode should use significantly less memory/CPU than the GUI version.
+- **Logging**: Use standard Python `logging` for Docker-compatible stdout/stderr output.
+- **Portability**: Must run reliably inside a standard `python:3.11-slim` or similar Docker image.
+
+## Acceptance Criteria
+- [ ] Manual Slop starts successfully with `--headless` and no display environment.
+- [ ] API is accessible via a configurable port (e.g., 8000).
+- [ ] All API requests are rejected without a valid API Key.
+- [ ] AI generation works via REST endpoints, returning structured JSON or a stream.
+- [ ] Tool execution is successfully blocked until a separate "Confirm" API call is made.
+
+## Out of Scope
+- Building the actual Unraid GUI frontend (React/Vue/etc.).
+- Multi-user authentication (OIDC/OAuth2).
+- Native Unraid `.plg` plugin development (focusing on Docker).

project_history.toml

@@ -8,5 +8,5 @@ active = "main"
 
 [discussions.main]
 git_commit = ""
-last_updated = "2026-02-25T01:43:02"
+last_updated = "2026-02-25T11:19:43"
 history = []

pyproject.toml

@@ -10,6 +10,8 @@ dependencies = [
     "anthropic",
     "tomli-w",
     "psutil>=7.2.2",
+    "fastapi",
+    "uvicorn",
 ]
 
 [dependency-groups]

tests/temp_liveaisettingssim_history.toml

@@ -9,5 +9,5 @@ auto_add = true
 
 [discussions.main]
 git_commit = ""
-last_updated = "2026-02-25T01:42:16"
+last_updated = "2026-02-25T11:18:59"
 history = []

tests/temp_livecontextsim_history.toml

@@ -5,10 +5,10 @@ roles = [
     "System",
 ]
 history = []
-active = "TestDisc_1772001716"
+active = "TestDisc_1772036318"
 auto_add = true
 
-[discussions.TestDisc_1772001716]
+[discussions.TestDisc_1772036318]
 git_commit = ""
-last_updated = "2026-02-25T01:42:09"
+last_updated = "2026-02-25T11:18:52"
 history = []

tests/temp_liveexecutionsim_history.toml

@@ -9,5 +9,5 @@ auto_add = true
 
 [discussions.main]
 git_commit = ""
-last_updated = "2026-02-25T01:43:05"
+last_updated = "2026-02-25T11:19:46"
 history = []

tests/temp_livetoolssim_history.toml

@@ -9,5 +9,5 @@ auto_add = true
 
 [discussions.main]
 git_commit = ""
-last_updated = "2026-02-25T01:42:35"
+last_updated = "2026-02-25T11:19:16"
 history = []

tests/temp_project_history.toml

@@ -9,5 +9,7 @@ auto_add = true
 
 [discussions.main]
 git_commit = ""
-last_updated = "2026-02-25T01:43:08"
-history = []
+last_updated = "2026-02-25T11:21:27"
+history = [
+    "@2026-02-25T11:21:23\nSystem:\n[PERFORMANCE ALERT] CPU usage high: 82.8%. Please consider optimizing recent changes or reducing load.",
+]

tests/test_headless_dependencies.py

@@ -0,0 +1,16 @@
+import pytest
+import importlib
+
+def test_fastapi_installed():
+    """Verify that fastapi is installed."""
+    try:
+        importlib.import_module("fastapi")
+    except ImportError:
+        pytest.fail("fastapi is not installed")
+
+def test_uvicorn_installed():
+    """Verify that uvicorn is installed."""
+    try:
+        importlib.import_module("uvicorn")
+    except ImportError:
+        pytest.fail("uvicorn is not installed")