refactor(project_manager,aggregate,api_hook_client): replace weak type sites with aliases

src/api_hook_client.py

@@ -9,7 +9,7 @@ This module provides a Python client for interacting with the Hook API exposed b
 
 Architecture:
  - Uses requests library for HTTP communication
- - All methods return dict[str, Any] or None
+ - All methods return Metadata or None
  - Handles connection errors gracefully (returns None on failure)
 
 Key Method Categories:
@@ -37,6 +37,19 @@ import requests # type: ignore[import-untyped]
 import sys
 import time
 
+from src.type_aliases import (
+ CommsLog,
+ CommsLogCallback,
+ CommsLogEntry,
+ FileItem,
+ FileItems,
+ History,
+ HistoryMessage,
+ Metadata,
+ ToolCall,
+ ToolDefinition,
+)
+
 from typing import Any
 
 
@@ -49,7 +62,7 @@ class ApiHookClient:
   self.base_url = base_url.rstrip('/')
   self.api_key  = api_key
 
- def _make_request(self, method: str, path: str, data: dict | None = None, timeout: float = 5.0) -> dict[str, Any] | None:
+ def _make_request(self, method: str, path: str, data: dict | None = None, timeout: float = 5.0) -> Metadata | None:
   """
   Helper to make HTTP requests to the hook server.
   [C: tests/test_api_hook_client.py:test_unsupported_method_error]
@@ -89,7 +102,7 @@ class ApiHookClient:
    time.sleep(0.5)
   return False
 
- def get_status(self) -> dict[str, Any]:
+ def get_status(self) -> Metadata:
   """
   Checks the health of the hook server.
   [C: tests/test_api_hook_client.py:test_get_status_success, tests/test_headless_simulation.py:test_mma_track_lifecycle_simulation, tests/test_hooks.py:test_live_hook_server_responses, tests/test_mma_concurrent_tracks_stress_sim.py:test_mma_concurrent_tracks_stress, tests/test_phase6_simulation.py:test_ast_inspector_modal_opens, tests/test_phase6_simulation.py:test_batch_operations_shift_click, tests/test_phase6_simulation.py:test_slice_editor_add_remove, tests/test_preset_windows_layout.py:make_request, tests/test_preset_windows_layout.py:test_preset_windows_opening, tests/test_ui_cache_controls_sim.py:test_ui_cache_controls]
@@ -101,26 +114,26 @@ class ApiHookClient:
    return {}
   return res
 
- def post_session(self, session_entries: list[dict]) -> dict[str, Any]:
+ def post_session(self, session_entries: list[dict]) -> Metadata:
   """
   Updates the session history.
   [C: tests/test_gui_stress_performance.py:test_comms_volume_stress_performance, tests/test_live_workflow.py:test_full_live_workflow]
   """
   return self._make_request('POST', '/api/session', data={"session": {"entries": session_entries}}) or {}
 
- def get_events(self) -> list[dict[str, Any]]:
+ def get_events(self) -> list[Metadata]:
   """Retrieves any pending events from the API event queue."""
   res = self._make_request('GET', '/api/events')
   return res.get("events", []) if res else []
 
- def clear_events(self) -> list[dict[str, Any]]:
+ def clear_events(self) -> list[Metadata]:
   """
   Retrieves and clears the event queue.
   [C: simulation/sim_base.py:BaseSimulation.setup]
   """
   return self.get_events()
 
- def wait_for_event(self, event_type: str, timeout: int = 5) -> dict[str, Any] | None:
+ def wait_for_event(self, event_type: str, timeout: int = 5) -> Metadata | None:
   """
   [C: simulation/sim_base.py:BaseSimulation.wait_for_event, simulation/sim_execution.py:ExecutionSimulation.run, tests/test_z_negative_flows.py:test_mock_error_result, tests/test_z_negative_flows.py:test_mock_malformed_json, tests/test_z_negative_flows.py:test_mock_timeout]
   """
@@ -133,14 +146,14 @@ class ApiHookClient:
    time.sleep(0.2)
   return None
 
- def post_gui(self, payload: dict) -> dict[str, Any]:
+ def post_gui(self, payload: dict) -> Metadata:
   """
   Pushes an event to the GUI's AsyncEventQueue via the /api/gui endpoint.
   [C: tests/test_ai_settings_layout.py:test_set_params_via_custom_callback, tests/test_api_hook_client.py:test_post_gui_success, tests/test_gui2_parity.py:test_gui2_custom_callback_hook_works, tests/test_gui2_parity.py:test_gui2_set_value_hook_works]
   """
   return self._make_request('POST', '/api/gui', data=payload) or {}
 
- def push_event(self, action: str, payload: dict) -> dict[str, Any]:
+ def push_event(self, action: str, payload: dict) -> Metadata:
   """
   Convenience to push a GUI task.
   [C: tests/test_auto_switch_sim.py:test_auto_switch_sim, tests/test_auto_switch_sim.py:trigger_tier, tests/test_external_editor_gui.py:test_button_click_is_received, tests/test_external_editor_gui.py:test_patch_modal_shows_with_configured_editor, tests/test_external_editor_gui.py:test_vscode_launches_with_diff_view, tests/test_gui_context_presets.py:test_gui_context_preset_save_load, tests/test_gui_text_viewer.py:test_text_viewer_state_update, tests/test_patch_modal_gui.py:test_patch_apply_modal_workflow, tests/test_patch_modal_gui.py:test_patch_modal_appears_on_trigger, tests/test_preset_windows_layout.py:test_preset_windows_opening, tests/test_saved_presets_sim.py:test_preset_manager_modal, tests/test_saved_presets_sim.py:test_preset_switching, tests/test_tool_management_layout.py:test_tool_management_state_updates, tests/test_tool_presets_sim.py:test_tool_preset_switching, tests/test_visual_mma.py:test_visual_mma_components, tests/test_visual_sim_gui_ux.py:test_gui_track_creation, tests/test_visual_sim_gui_ux.py:test_gui_ux_event_routing, tests/test_workspace_profiles_sim.py:test_workspace_profiles_restoration, tests/test_z_negative_flows.py:test_mock_error_result, tests/test_z_negative_flows.py:test_mock_malformed_json, tests/test_z_negative_flows.py:test_mock_timeout]
@@ -149,7 +162,7 @@ class ApiHookClient:
 
 #region: Data
 
- def get_gui_state(self) -> dict[str, Any]:
+ def get_gui_state(self) -> Metadata:
   """
   Returns the full GUI state available via the hook API.
   [C: tests/test_ai_settings_layout.py:test_change_provider_via_hook, tests/test_ai_settings_layout.py:test_set_params_via_custom_callback, tests/test_conductor_api_hook_integration.py:simulate_conductor_phase_completion, tests/test_external_editor_gui.py:test_button_click_is_received, tests/test_external_editor_gui.py:test_patch_modal_shows_with_configured_editor, tests/test_external_editor_gui.py:test_vscode_launches_with_diff_view, tests/test_gui_text_viewer.py:test_text_viewer_state_update, tests/test_hooks.py:test_live_hook_server_responses, tests/test_live_gui_integration_v2.py:test_api_gui_state_live, tests/test_live_workflow.py:test_full_live_workflow, tests/test_live_workflow.py:wait_for_value, tests/test_patch_modal_gui.py:test_patch_apply_modal_workflow, tests/test_patch_modal_gui.py:test_patch_modal_appears_on_trigger, tests/test_rag_phase4_final_verify.py:test_phase4_final_verify, tests/test_rag_phase4_stress.py:test_rag_large_codebase_verification_sim, tests/test_saved_presets_sim.py:test_preset_manager_modal, tests/test_saved_presets_sim.py:test_preset_switching, tests/test_task_dag_popout_sim.py:test_task_dag_popout, tests/test_tool_management_layout.py:test_tool_management_gettable_fields, tests/test_tool_management_layout.py:test_tool_management_state_updates, tests/test_tool_presets_sim.py:test_tool_preset_switching, tests/test_usage_analytics_popout_sim.py:test_usage_analytics_popout, tests/test_visual_mma.py:test_visual_mma_components]
@@ -196,7 +209,7 @@ class ApiHookClient:
   val = self.get_value(item_tag)
   return str(val) if val is not None else None
 
- def set_value(self, item: str, value: Any) -> dict[str, Any]:
+ def set_value(self, item: str, value: Any) -> Metadata:
   """
   Sets the value of a GUI widget.
   [C: simulation/live_walkthrough.py:main, simulation/ping_pong.py:main, simulation/sim_ai_settings.py:AISettingsSimulation.run, simulation/sim_base.py:BaseSimulation.setup, simulation/workflow_sim.py:WorkflowSimulator.create_discussion, simulation/workflow_sim.py:WorkflowSimulator.run_discussion_turn_async, simulation/workflow_sim.py:WorkflowSimulator.setup_new_project, simulation/workflow_sim.py:WorkflowSimulator.truncate_history, tests/smoke_status_hook.py:test_status_hook, tests/test_ai_settings_layout.py:test_change_provider_via_hook, tests/test_auto_switch_sim.py:test_auto_switch_sim, tests/test_deepseek_infra.py:test_gui_provider_list_via_hooks, tests/test_extended_sims.py:test_ai_settings_sim_live, tests/test_extended_sims.py:test_context_sim_live, tests/test_extended_sims.py:test_execution_sim_live, tests/test_extended_sims.py:test_tools_sim_live, tests/test_gui2_parity.py:test_gui2_click_hook_works, tests/test_gui2_performance.py:test_performance_benchmarking, tests/test_live_gui_integration_v2.py:test_api_gui_state_live, tests/test_live_workflow.py:test_full_live_workflow, tests/test_mma_concurrent_tracks_sim.py:test_mma_concurrent_tracks_execution, tests/test_mma_concurrent_tracks_stress_sim.py:test_mma_concurrent_tracks_stress, tests/test_mma_step_mode_sim.py:test_mma_step_mode_approval_flow, tests/test_rag_phase4_final_verify.py:test_phase4_final_verify, tests/test_rag_phase4_stress.py:test_rag_large_codebase_verification_sim, tests/test_rag_visual_sim.py:test_rag_full_lifecycle_sim, tests/test_rag_visual_sim.py:test_rag_settings_persistence_sim, tests/test_saved_presets_sim.py:test_preset_manager_modal, tests/test_selectable_ui.py:test_selectable_label_stability, tests/test_system_prompt_sim.py:test_system_prompt_sim, tests/test_task_dag_popout_sim.py:test_task_dag_popout, tests/test_tool_presets_sim.py:test_tool_preset_switching, tests/test_undo_redo_sim.py:test_undo_redo_context_mutation, tests/test_undo_redo_sim.py:test_undo_redo_discussion_mutation, tests/test_undo_redo_sim.py:test_undo_redo_lifecycle, tests/test_usage_analytics_popout_sim.py:test_usage_analytics_popout, tests/test_visual_mma.py:test_visual_mma_components, tests/test_visual_orchestration.py:test_mma_epic_lifecycle, tests/test_visual_sim_mma_v2.py:test_mma_complete_lifecycle, tests/test_workspace_profiles_sim.py:test_workspace_profiles_restoration, tests/test_z_negative_flows.py:test_mock_error_result, tests/test_z_negative_flows.py:test_mock_malformed_json, tests/test_z_negative_flows.py:test_mock_timeout]
@@ -207,21 +220,21 @@ class ApiHookClient:
 
 #region: Input
 
- def click(self, item: str, user_data: Any = None) -> dict[str, Any]:
+ def click(self, item: str, user_data: Any = None) -> Metadata:
   """
   Simulates a button click.
   [C: simulation/live_walkthrough.py:main, simulation/ping_pong.py:main, simulation/sim_base.py:BaseSimulation.setup, simulation/sim_context.py:ContextSimulation.run, simulation/sim_execution.py:ExecutionSimulation.run, simulation/workflow_sim.py:WorkflowSimulator.create_discussion, simulation/workflow_sim.py:WorkflowSimulator.load_prior_log, simulation/workflow_sim.py:WorkflowSimulator.run_discussion_turn_async, simulation/workflow_sim.py:WorkflowSimulator.setup_new_project, simulation/workflow_sim.py:WorkflowSimulator.truncate_history, simulation/workflow_sim.py:WorkflowSimulator.wait_for_ai_response, tests/test_external_editor_gui.py:test_button_click_is_received, tests/test_external_editor_gui.py:test_vscode_launches_with_diff_view, tests/test_gui2_parity.py:test_gui2_click_hook_works, tests/test_gui_text_viewer.py:test_text_viewer_state_update, tests/test_live_workflow.py:test_full_live_workflow, tests/test_mma_concurrent_tracks_sim.py:test_mma_concurrent_tracks_execution, tests/test_mma_concurrent_tracks_stress_sim.py:test_mma_concurrent_tracks_stress, tests/test_mma_step_mode_sim.py:test_mma_step_mode_approval_flow, tests/test_rag_phase4_final_verify.py:test_phase4_final_verify, tests/test_rag_phase4_stress.py:test_rag_large_codebase_verification_sim, tests/test_rag_visual_sim.py:test_rag_full_lifecycle_sim, tests/test_saved_presets_sim.py:test_preset_manager_modal, tests/test_saved_presets_sim.py:test_preset_switching, tests/test_system_prompt_sim.py:test_system_prompt_sim, tests/test_ui_cache_controls_sim.py:test_ui_cache_controls, tests/test_undo_redo_sim.py:test_undo_redo_context_mutation, tests/test_undo_redo_sim.py:test_undo_redo_discussion_mutation, tests/test_undo_redo_sim.py:test_undo_redo_lifecycle, tests/test_visual_mma.py:test_visual_mma_components, tests/test_visual_orchestration.py:test_mma_epic_lifecycle, tests/test_visual_sim_gui_ux.py:test_gui_track_creation, tests/test_visual_sim_gui_ux.py:test_gui_ux_event_routing, tests/test_visual_sim_mma_v2.py:_drain_approvals, tests/test_visual_sim_mma_v2.py:test_mma_complete_lifecycle, tests/test_z_negative_flows.py:test_mock_error_result, tests/test_z_negative_flows.py:test_mock_malformed_json, tests/test_z_negative_flows.py:test_mock_timeout]
   """
   return self.post_gui({"action": "click", "item": item, "user_data": user_data})
 
- def drag(self, src_item: str, dst_item: str) -> dict[str, Any]:
+ def drag(self, src_item: str, dst_item: str) -> Metadata:
   """
   Simulates a drag and drop operation.
   [C: tests/test_api_hook_client.py:test_drag_success]
   """
   return self.push_event("drag", {"src_item": src_item, "dst_item": dst_item})
 
- def right_click(self, item: str) -> dict[str, Any]:
+ def right_click(self, item: str) -> Metadata:
   """
   Simulates a right-click on an item.
   [C: tests/test_api_hook_client.py:test_right_click_success]
@@ -240,14 +253,14 @@ class ApiHookClient:
    timeout=60.0)
   return res.get('response') if res else None
 
- def select_list_item(self, item: str, value: str) -> dict[str, Any]:
+ def select_list_item(self, item: str, value: str) -> Metadata:
   """
   Selects an item in a listbox or combo.
   [C: simulation/workflow_sim.py:WorkflowSimulator.create_discussion, simulation/workflow_sim.py:WorkflowSimulator.switch_discussion, tests/test_api_hook_extensions.py:test_select_list_item_integration, tests/test_live_workflow.py:test_full_live_workflow]
   """
   return self.set_value(item, value)
 
- def select_tab(self, item: str, value: str) -> dict[str, Any]:
+ def select_tab(self, item: str, value: str) -> Metadata:
   """
   Selects a specific tab in a tab bar.
   [C: simulation/live_walkthrough.py:main, tests/test_api_hook_extensions.py:test_select_tab_integration]
@@ -258,28 +271,28 @@ class ApiHookClient:
 
 #region: Patching
 
- def trigger_patch(self, patch_text: str, file_paths: list[str]) -> dict[str, Any]:
+ def trigger_patch(self, patch_text: str, file_paths: list[str]) -> Metadata:
   """Triggers the patch modal to show in the GUI."""
   return self._make_request('POST', '/api/patch/trigger', data={
    "patch_text": patch_text,
    "file_paths": file_paths
   }) or {}
 
- def apply_patch(self) -> dict[str, Any]:
+ def apply_patch(self) -> Metadata:
   """
   Applies the pending patch.
   [C: tests/test_patch_modal.py:test_apply_callback]
   """
   return self._make_request('POST', '/api/patch/apply') or {}
 
- def reject_patch(self) -> dict[str, Any]:
+ def reject_patch(self) -> Metadata:
   """
   Rejects the pending patch.
   [C: tests/test_patch_modal.py:test_reject_callback, tests/test_patch_modal.py:test_reject_patch]
   """
   return self._make_request('POST', '/api/patch/reject') or {}
 
- def get_patch_status(self) -> dict[str, Any]:
+ def get_patch_status(self) -> Metadata:
   """Gets the current patch modal status."""
   return self._make_request('GET', '/api/patch/status') or {}
 
@@ -295,28 +308,28 @@ class ApiHookClient:
   val = self.get_value(item_tag)
   return {"shown": bool(val)}
 
- def get_gui_diagnostics(self) -> dict[str, Any]:
+ def get_gui_diagnostics(self) -> Metadata:
   """
   Retrieves performance and diagnostic metrics.
   [C: tests/test_api_hook_client.py:test_get_performance_success, tests/test_hooks.py:test_live_hook_server_responses, tests/test_selectable_ui.py:test_selectable_label_stability, tests/test_visual_sim_gui_ux.py:test_gui_ux_event_routing]
   """
   return self._make_request('GET', '/api/gui/diagnostics') or {}
 
- def get_performance(self) -> dict[str, Any]:
+ def get_performance(self) -> Metadata:
   """
   Retrieves performance metrics from the dedicated endpoint.
   [C: tests/test_gui2_performance.py:test_performance_benchmarking, tests/test_gui_performance_requirements.py:test_idle_performance_requirements, tests/test_gui_stress_performance.py:test_comms_volume_stress_performance, tests/test_selectable_ui.py:test_selectable_label_stability]
   """
   return self._make_request('GET', '/api/performance') or {}
 
- def get_warmup_status(self) -> dict[str, Any]:
+ def get_warmup_status(self) -> Metadata:
   """
   Returns the current warmup status: {pending, completed, failed}.
   [C: tests/test_api_hooks_warmup.py:test_get_warmup_status_calls_correct_endpoint, tests/test_api_hooks_warmup.py:test_get_warmup_status_handles_empty_response, tests/test_api_hooks_warmup.py:test_live_warmup_status_endpoint]
   """
   return self._make_request('GET', '/api/warmup_status') or {}
 
- def get_warmup_wait(self, timeout: float = 30.0) -> dict[str, Any]:
+ def get_warmup_wait(self, timeout: float = 30.0) -> Metadata:
   """
   Blocks server-side up to `timeout` seconds waiting for the warmup to
   complete, then returns the final status. Useful for external clients
@@ -326,7 +339,7 @@ class ApiHookClient:
   """
   return self._make_request('GET', f'/api/warmup_wait?timeout={timeout}') or {}
 
- def get_warmup_canaries(self) -> list[dict[str, Any]]:
+ def get_warmup_canaries(self) -> list[Metadata]:
   """
   Returns per-module import canary records: list of dicts with
   canary_id, module, thread_name, thread_id, submit_ts, start_ts,
@@ -337,7 +350,7 @@ class ApiHookClient:
   result = self._make_request('GET', '/api/warmup_canaries') or {}
   return result.get("canaries", []) if isinstance(result, dict) else []
 
- def get_startup_timeline(self) -> dict[str, Any]:
+ def get_startup_timeline(self) -> Metadata:
   """
   Returns the startup timeline: dict with init_start_ts, warmup_done_ts,
   first_frame_ts, warmup_ms, first_frame_after_init_ms,
@@ -351,14 +364,14 @@ class ApiHookClient:
 
 #region: Project
 
- def get_project(self) -> dict[str, Any]:
+ def get_project(self) -> Metadata:
   """
   Retrieves the current project state.
   [C: simulation/sim_context.py:ContextSimulation.run, tests/test_api_hook_client.py:test_get_project_success, tests/test_gui_context_presets.py:test_gui_context_preset_save_load, tests/test_headless_simulation.py:test_mma_track_lifecycle_simulation, tests/test_hooks.py:test_live_hook_server_responses, tests/test_live_workflow.py:test_full_live_workflow]
   """
   return self._make_request('GET', '/api/project') or {}
 
- def get_project_switch_status(self) -> dict[str, Any]:
+ def get_project_switch_status(self) -> Metadata:
   """
   Returns the project switch status: {in_progress, path, error}.
   - in_progress: True when a project switch is currently scheduled or running
@@ -373,7 +386,7 @@ class ApiHookClient:
    return {"in_progress": False, "path": None, "error": None}
   return result
 
- def wait_for_project_switch(self, expected_path: str = None, timeout: float = 30.0, poll_interval: float = 0.2) -> dict[str, Any]:
+ def wait_for_project_switch(self, expected_path: str = None, timeout: float = 30.0, poll_interval: float = 0.2) -> Metadata:
    """
    Blocks until the project switch completes (or fails). Returns the
    final status dict. If expected_path is provided, also waits until the
@@ -404,7 +417,7 @@ class ApiHookClient:
    last_status["timeout"] = True
    return last_status
 
- def get_io_pool_status(self) -> dict[str, Any]:
+ def get_io_pool_status(self) -> Metadata:
   """
   Returns the controller's io_pool status: {idle, inflight}.
   - idle: True if no jobs are currently in-flight (running or queued)
@@ -418,7 +431,7 @@ class ApiHookClient:
    return {"idle": True, "inflight": 0}
   return result
 
- def get_gui_health(self) -> dict[str, Any]:
+ def get_gui_health(self) -> Metadata:
   """
   Returns the controller's GUI health: {healthy, degraded_reason,
   last_assert, io_pool_alive}. Tests should call this before starting
@@ -454,10 +467,10 @@ class ApiHookClient:
    time.sleep(poll_interval)
   return False
 
- def post_project(self, project_data: dict) -> dict[str, Any]:
+ def post_project(self, project_data: dict) -> Metadata:
    return last_status
 
- def post_project(self, project_data: dict) -> dict[str, Any]:
+ def post_project(self, project_data: dict) -> Metadata:
   """
   Updates the current project configuration.
   [C: simulation/sim_context.py:ContextSimulation.run]
@@ -475,7 +488,7 @@ class ApiHookClient:
   """
   return self._make_request('POST', '/api/context/inject', data=data) or {}
 
- def get_context_state(self) -> dict[str, Any]:
+ def get_context_state(self) -> Metadata:
   """
   Retrieves the current file and screenshot context state.
   [C: tests/test_gui_context_presets.py:test_gui_context_preset_save_load]
@@ -486,7 +499,7 @@ class ApiHookClient:
 
 #region: Discussion
 
- def get_session(self) -> dict[str, Any]:
+ def get_session(self) -> Metadata:
   """
   Retrieves the current discussion session history.
   [C: simulation/ping_pong.py:main, simulation/sim_context.py:ContextSimulation.run, simulation/sim_execution.py:ExecutionSimulation.run, simulation/sim_tools.py:ToolsSimulation.run, simulation/workflow_sim.py:WorkflowSimulator.run_discussion_turn_async, simulation/workflow_sim.py:WorkflowSimulator.wait_for_ai_response, tests/test_api_hook_client.py:test_get_session_success, tests/test_gui_stress_performance.py:test_comms_volume_stress_performance, tests/test_live_workflow.py:test_full_live_workflow, tests/test_rag_phase4_final_verify.py:test_phase4_final_verify, tests/test_rag_phase4_stress.py:test_rag_large_codebase_verification_sim]
@@ -504,11 +517,11 @@ class ApiHookClient:
 
 #region: Analytics
 
- def get_financial_metrics(self) -> dict[str, Any]:
+ def get_financial_metrics(self) -> Metadata:
   """Retrieves token usage and estimated financial cost metrics."""
   return self._make_request('GET', '/api/metrics/financial') or {}
 
- def get_system_telemetry(self) -> dict[str, Any]:
+ def get_system_telemetry(self) -> Metadata:
   """Retrieves system-level telemetry including thread status and event queue size."""
   return self._make_request('GET', '/api/system/telemetry') or {}
 
@@ -516,21 +529,21 @@ class ApiHookClient:
 
 #region: MMA
 
- def get_node_status(self, node_id: str) -> dict[str, Any]:
+ def get_node_status(self, node_id: str) -> Metadata:
   """
   Retrieves status for a specific node in the MMA DAG.
   [C: tests/test_api_hook_client.py:test_get_node_status]
   """
   return self._make_request('GET', f'/api/mma/node/{node_id}') or {}
 
- def get_mma_status(self) -> dict[str, Any]:
+ def get_mma_status(self) -> Metadata:
   """
   Retrieves the dedicated MMA engine status.
   [C: tests/test_headless_simulation.py:test_mma_track_lifecycle_simulation, tests/test_live_workflow.py:test_full_live_workflow, tests/test_mma_concurrent_tracks_sim.py:_poll_mma_status, tests/test_mma_concurrent_tracks_sim.py:test_mma_concurrent_tracks_execution, tests/test_mma_concurrent_tracks_stress_sim.py:test_mma_concurrent_tracks_stress, tests/test_mma_step_mode_sim.py:_poll_mma_status, tests/test_mma_step_mode_sim.py:test_mma_step_mode_approval_flow, tests/test_visual_mma.py:test_visual_mma_components, tests/test_visual_orchestration.py:test_mma_epic_lifecycle, tests/test_visual_sim_gui_ux.py:test_gui_ux_event_routing, tests/test_visual_sim_mma_v2.py:_poll]
   """
   return self._make_request('GET', '/api/gui/mma_status') or {}
 
- def get_mma_workers(self) -> dict[str, Any]:
+ def get_mma_workers(self) -> Metadata:
   """
   Retrieves status for all active MMA workers.
   [C: tests/test_headless_simulation.py:test_mma_track_lifecycle_simulation, tests/test_mma_concurrent_tracks_sim.py:test_mma_concurrent_tracks_execution, tests/test_mma_concurrent_tracks_stress_sim.py:_poll_mma_workers]