plans and docs

src/api_hooks.py

@@ -7,6 +7,35 @@ from http.server import ThreadingHTTPServer, BaseHTTPRequestHandler
 from typing import Any
 import logging
 from src import session_logger
+"""
+API Hooks - REST API for external automation and state inspection.
+
+This module implements the HookServer, which exposes internal application state to external HTTP requests on port 8999 using Python's
+ ThreadingHTTPServer. All endpoints are thread-safe and reads that pass through lock-guarded lists,
+ while stateful reads use the GUI thread trampoline pattern.
+
+Architecture:
+ - HookServer: ThreadingHTTPServer with app reference
+ - HookHandler: BaseHTTPRequestHandler per request
+ - Request handling uses trampoline pattern for GUI state reads
+ - GUI Thread Trampoline: Create threading.Event + result dict
+   - Push callback to `_pending_gui_tasks`
+   - Wait for event (timeout)
+   - Return result as JSON
+
+Thread Safety:
+ - All reads use lock-protected lists
+ - All state mutations happen on the GUI thread
+ - The module does to maintain separation between App and AppController
+
+Configuration:
+ - `--enable-test-hooks`: Required for Hook API to be available
+ - `gemini_cli` provider: Hook API is automatically available for synchronous HITL
+
+See Also:
+ - docs/guide_tools.md for full API reference
+ - api_hook_client.py for the client implementation
+"""
 
 def _get_app_attr(app: Any, name: str, default: Any = None) -> Any:
  if hasattr(app, name):

src/multi_agent_conductor.py

@@ -1,3 +1,60 @@
+"""
+Multi-Agent Conductor - 4-tier MMA orchestration engine.
+
+This module implements the ConductorEngine and WorkerPool for executing
+implementation tracks via the 4-tier Multi-Model Agent (MMA) hierarchy.
+
+Key Components:
+ - WorkerPool: Bounded concurrent worker pool with semaphore gating
+ - ConductorEngine: Main orchestration loop with DAG execution
+ - run_worker_lifecycle: Tier 3 worker execution function
+
+Architecture Integration:
+ - Uses TrackDAG and ExecutionEngine from dag_engine.py
+ - Communicates with GUI via SyncEventQueue
+ - Manages tier-specific token usage via update_usage()
+
+Thread Safety:
+ - WorkerPool uses threading.Lock for all state mutations
+ - ConductorEngine uses _tier_usage_lock for tier usage tracking
+ - Abort events use threading.Event for worker cancellation
+
+Configuration:
+ - max_workers: Loaded from config.toml [mma].max_workers (default: 4)
+
+See Also:
+ - docs/guide_mma.md for full MMA documentation
+ - src/dag_engine.py for TrackDAG and ExecutionEngine
+ - src/models.py for Ticket, Track, WorkerContext
+"""
+"""
+Multi-Agent Conductor - MMA 4-Tier orchestration engine.
+
+This module provides the ConductorEngine and WorkerPool for orchestrating
+ the execution of implementation tickets within a Track using the DAG engine
+and the bounded concurrent worker pool with abort event propagation.
+
+Key Components:
+ - ConductorEngine: Tier 2 orchestrator that owns the execution loop
+ - WorkerPool: Bounded concurrent worker pool with semaphore gating
+ - run_worker_lifecycle: Stateless Tier 3 worker execution with context amnesia
+
+Thread Safety:
+ - All state mutations use locks (_workers_lock, _tier_usage_lock)
+ - Worker threads are daemon threads that clean up on exit
+ - Abort events enable per-ticket cancellation
+
+Integration:
+ - Uses SyncEventQueue for state updates to the GUI
+ - Uses ai_client.send() for LLM communication
+ - Uses mcp_client for tool dispatch
+
+See Also:
+ - docs/guide_mma.md for MMA orchestration documentation
+ - src/dag_engine.py for TrackDAG and ExecutionEngine
+ - src/ai_client.py for multi-provider LLM abstraction
+ - src/models.py for Ticket, Track, WorkerContext data structures
+"""
 from src import ai_client
 import json
 import threading