manual_slop/conductor/tracks/hook_api_expansion_20260308/plan.md

Implementation Plan: Expanded Hook API & Headless Orchestration

Phase 1: WebSocket Infrastructure & Event Streaming

• Task: Implement the WebSocket gateway.
  • Integrate a lightweight WebSocket library (e.g., websockets or simple-websocket).
  • Create a dedicated WebSocketServer class in src/api_hooks.py that runs on a separate port (e.g., 9000).
  • Implement a basic subscription mechanism for different event channels.
• Task: Connect the event queue to the WebSocket stream.
  • Update AsyncEventQueue to broadcast events to connected WebSocket clients.
  • Add high-frequency telemetry (FPS, CPU) to the event stream.
• Task: Write unit tests for WebSocket connection and event broadcasting.
• Task: Conductor - User Manual Verification 'Phase 1: WebSocket Infrastructure' (Protocol in workflow.md)

Phase 2: Expanded Read Endpoints (GET)

• Task: Implement detailed state exposure endpoints.
  • Add /api/mma/workers to return the status, logs, and traces of all active sub-agents.
  • Add /api/context/state to expose AST cache metadata and file aggregation status.
  • Add /api/metrics/financial to return track-specific token usage and cost data.
  • Add /api/system/telemetry to expose internal thread and queue metrics.
• Task: Enhance /api/gui/state to provide a truly exhaustive JSON dump of all internal managers.
• Task: Update api_hook_client.py with corresponding methods for all new GET endpoints.
• Task: Write integration tests for all new GET endpoints using live_gui.
• Task: Conductor - User Manual Verification 'Phase 2: Expanded Read Endpoints' (Protocol in workflow.md)

Phase 3: Comprehensive Control Endpoints (POST)

• Task: Implement worker and pipeline control.
  • Add /api/mma/workers/spawn to manually initiate sub-agent execution via the API.
  • Add /api/mma/workers/kill to programmatically abort running workers.
  • Add /api/mma/pipeline/pause and /api/mma/pipeline/resume to control the global MMA loop.
• Task: Implement context and DAG mutation.
  • Add /api/context/inject to allow programmatic context injection (files/skeletons).
  • Add /api/mma/dag/mutate to allow modifying task dependencies through the API.
• Task: Update api_hook_client.py with corresponding methods for all new POST endpoints.
• Task: Write integration tests for all new control endpoints using live_gui.
• Task: Conductor - User Manual Verification 'Phase 3: Comprehensive Control Endpoints' (Protocol in workflow.md)

Phase 4: Headless Refinement & Verification

• Task: Improve error reporting.
  • Refactor HookHandler to catch and wrap all internal exceptions in JSON error responses.
• Task: Conduct a full headless simulation.
  • Create a specialized simulation script that replicates a full MMA track lifecycle (planning, worker spawn, DAG mutation, completion) using ONLY the Hook API.
• Task: Final performance audit.
  • Ensure that active WebSocket clients and large state dumps do not cause GUI frame drops.
• Task: Conductor - User Manual Verification 'Phase 4: Headless Refinement & Verification' (Protocol in workflow.md)