# 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)