chore(conductor): Archive track 'event_driven_metrics_20260223'

conductor/archive/event_driven_metrics_20260223/spec.md

@@ -0,0 +1,29 @@
+# Specification: Event-Driven API Metrics Updates
+
+## Overview
+Refactor the API metrics update mechanism to be event-driven. Currently, the UI likely polls or recalculates metrics on every frame. This track will implement a signal/event system where `ai_client.py` broadcasts updates only when significant API activities (requests, responses, tool calls, or stream chunks) occur.
+
+## Functional Requirements
+- **Event System:** Implement a robust event/signal mechanism (e.g., using a queue or a simple observer pattern) to communicate API lifecycle events.
+- **Client Instrumentation:** Update `ai_client.py` to emit events at key points:
+    - **Request Start:** When a call is sent to the provider.
+    - **Response Received:** When a full or final response is received.
+    - **Tool Execution:** When a tool call is processed or a result is returned.
+    - **Stream Update:** When a chunk of a streaming response is processed.
+- **UI Listener:** Update the GUI components (in `gui.py` or associated panels) to subscribe to these events and update metrics displays only when notified.
+- **Decoupling:** Remove any metrics calculation or display logic that is triggered by the UI's main graphical update loop (per-frame).
+
+## Non-Functional Requirements
+- **Efficiency:** Significant reduction in UI main thread CPU usage related to metrics.
+- **Integrity:** Maintain 100% accuracy of token counts and usage data.
+- **Responsiveness:** Metrics should update immediately following the corresponding API event.
+
+## Acceptance Criteria
+- [ ] UI metrics for token usage, costs, and session state do NOT recalculate on every frame (can be verified by adding logging to the recalculation logic).
+- [ ] Metrics update precisely when API calls are made or responses are received.
+- [ ] Automated tests confirm that events are emitted correctly by the `ai_client`.
+- [ ] The application remains stable and metrics accuracy is verified against the existing polling implementation.
+
+## Out of Scope
+- Adding new metrics or visual components.
+- Refactoring the core AI logic beyond the event/metrics hook.