docs update (wip)

src/events.py

@@ -1,5 +1,33 @@
 """
-Decoupled event emission system for cross-module communication.
+Events - Decoupled event emission and queuing for cross-thread communication.
+
+This module provides three complementary patterns for thread-safe communication
+between the GUI main thread and background workers:
+
+1. EventEmitter: Pub/sub pattern for synchronous event broadcast
+   - Used for: API lifecycle events (request_start, response_received, tool_execution)
+   - Thread-safe: Callbacks execute on emitter's thread
+   - Example: ai_client.py emits 'request_start' and 'response_received' events
+
+2. SyncEventQueue: Producer-consumer pattern via queue.Queue
+   - Used for: Decoupled task submission where consumer polls at its own pace
+   - Thread-safe: Built on Python's thread-safe queue.Queue
+   - Example: Background workers submit tasks, main thread drains queue
+
+3. UserRequestEvent: Structured payload for AI request data
+   - Used for: Bundling prompt, context, files, and base_dir into single object
+   - Immutable data transfer object for cross-thread handoff
+
+Integration Points:
+ - ai_client.py: EventEmitter for API lifecycle events
+ - gui_2.py: Consumes events via _process_event_queue()
+ - multi_agent_conductor.py: Uses SyncEventQueue for state updates
+ - api_hooks.py: Pushes events to _api_event_queue for external visibility
+
+Thread Safety:
+ - EventEmitter: NOT thread-safe for concurrent on/emit (use from single thread)
+ - SyncEventQueue: FULLY thread-safe (built on queue.Queue)
+ - UserRequestEvent: Immutable, safe for concurrent access
 """
 import queue
 from typing import Callable, Any, Dict, List, Tuple