manual_slop/conductor/tracks/manual_slop_headless_20260225/plan.md

Implementation Plan: Manual Slop Headless Backend

Phase 1: Project Setup & Headless Scaffold [checkpoint: d5f056c]

• 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) d5f056c

Phase 2: Core API Routes & Authentication [checkpoint: 4e0bcd5]

• 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) 4e0bcd5

Phase 3: Remote Tool Confirmation Mechanism [checkpoint: a6e184e]

• 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) a6e184e

Phase 4: Session & Context Management via API [checkpoint: 7f3a1e2]

• 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) 7f3a1e2

Phase 5: Dockerization [checkpoint: 5176b8d]

• 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) 5176b8d

Phase: Review Fixes

• Task: Apply review suggestions (docstrings and security fix) 9b50bfa