Add SSDL-style docstrings to History and Telemetry functions and fix missing rendering/profiling in session insights panel

2026-06-12 21:54:16 -04:00
parent 924d720c76
commit 06b6d4794f
2 changed files with 66 additions and 18 deletions
@@ -9,5 +9,5 @@ active = "main"

 [discussions.main]
 git_commit = ""
-last_updated = "2026-06-12T21:52:43"
+last_updated = "2026-06-12T21:54:11"
 history = []
@@ -344,25 +344,24 @@ class App:
   self.disc_entries       = self.controller.disc_entries
   self.disc_roles         = self.controller.disc_roles
   self.workspace_profiles = self.workspace_manager.load_all_profiles()
-  with startup_profiler.phase("app_init_start_services"):
-   self.controller.start_services(self)
+  with startup_profiler.phase("app_init_start_services"): self.controller.start_services(self)
  # --- Controller Callbacks & Actions ---
-  self.controller._predefined_callbacks['save_context_preset'] = self.save_context_preset
-  self.controller._predefined_callbacks['load_context_preset'] = self.load_context_preset
-  self.controller._predefined_callbacks['delete_context_preset'] = self.delete_context_preset
-  self.controller._predefined_callbacks['set_ui_file_paths'] = lambda p: setattr(self, 'ui_file_paths', p)
-  self.controller._predefined_callbacks['set_ui_screenshot_paths'] = lambda p: setattr(self, 'ui_screenshot_paths', p)
+  self.controller._predefined_callbacks['save_context_preset']        = self.save_context_preset
+  self.controller._predefined_callbacks['load_context_preset']        = self.load_context_preset
+  self.controller._predefined_callbacks['delete_context_preset']      = self.delete_context_preset
+  self.controller._predefined_callbacks['set_ui_file_paths']          = lambda p: setattr(self, 'ui_file_paths', p)
+  self.controller._predefined_callbacks['set_ui_screenshot_paths']    = lambda p: setattr(self, 'ui_screenshot_paths', p)
  self.controller._predefined_callbacks['set_context_files_for_test'] = lambda files: setattr(self, 'context_files', [models.FileItem(path=f) for f in files])
-  self.controller._predefined_callbacks['set_screenshots_for_test'] = lambda ss: setattr(self, 'screenshots', ss)
-  self.controller._predefined_callbacks['_toggle_command_palette'] = self._toggle_command_palette
-  self.controller._gettable_fields['show_command_palette'] = 'show_command_palette'
+  self.controller._predefined_callbacks['set_screenshots_for_test']   = lambda ss: setattr(self, 'screenshots', ss)
+  self.controller._predefined_callbacks['_toggle_command_palette']    = self._toggle_command_palette
+  self.controller._gettable_fields['show_command_palette']            = 'show_command_palette'
  
  def _save_context_preset_force(name: str):
   if not name: return
   preset_files = []
   for f in self.context_files:
-    p = f.path if hasattr(f, 'path') else str(f)
-    vm = f.view_mode if hasattr(f, 'view_mode') else 'summary'
+    p   = f.path if hasattr(f, 'path') else str(f)
+    vm  = f.view_mode if hasattr(f, 'view_mode') else 'summary'
    slc = copy.deepcopy(f.custom_slices) if hasattr(f, 'custom_slices') else []
    msk = copy.deepcopy(f.ast_mask) if hasattr(f, 'ast_mask') else {}
    sig = f.ast_signatures if hasattr(f, 'ast_signatures') else False
@@ -4392,6 +4391,17 @@ def render_discussion_entry_read_mode(app: App, entry: dict, index: int) -> None
  imgui.end_group()

 def render_history_window(app: App) -> None:
+ """
+ Renders the Undo/Redo History window. Displays past UI snapshots in reverse chronological
+ order and allows reverting to prior states.
+
+ State Mutations:
+   app.show_windows['Undo/Redo History'] (updates visibility)
+   app.history (jumping/traversing history)
+
+ SSDL Shape:
+   `[I:history_list] -> [B:undo_redo_buttons] => [B:selectable_snapshots]`
+ """
 if not app.show_windows.get('Undo/Redo History', False):
  return
 def iterate_history(history: typing.List[typing.Dict[str, typing.Any]]) -> None:
@@ -4416,6 +4426,16 @@ def render_history_window(app: App) -> None:
     else: iterate_history(history)

 def render_session_insights_panel(app: App) -> None:
+ """
+ Renders session productivity insights, displaying total tokens, API call counts,
+ burn rates, total costs, completed ticket counts, and token efficiency.
+
+ State Mutations:
+   None directly.
+
+ SSDL Shape:
+   `[I:insights] -> [I:telemetry_texts]`
+ """
 if app.perf_profiling_enabled: app.perf_monitor.start_component("_render_session_insights_panel")
 imgui.text_colored(C_LBL(), 'Session Insights')
 imgui.separator()
@@ -4426,8 +4446,22 @@ def render_session_insights_panel(app: App) -> None:
 imgui.text(f"Session Cost: ${insights.get('session_cost', 0):.4f}")
 completed  = insights.get('completed_tickets', 0)
 efficiency = insights.get('efficiency', 0)
+ imgui.text(f"Completed: {completed}")
+ imgui.text(f"Tokens/Ticket: {efficiency:.0f}" if efficiency > 0 else "Tokens/Ticket: N/A")
+ if app.perf_profiling_enabled: app.perf_monitor.end_component("_render_session_insights_panel")

 def render_prior_session_view(app: App) -> None:
+ """
+ Renders a historical read-only view of a loaded prior discussion session, complete
+ with collapsing message bubbles and bubble colors.
+
+ State Mutations:
+   app.prior_disc_entries (collapsing/expanding bubbles)
+   app._comms_log_dirty (triggers log reload on exit)
+
+ SSDL Shape:
+   `[I:prior_entries] -> [B:exit_button] -> [I:scroll_list]`
+ """
 with imscope.style_color(imgui.Col_.child_bg, theme.get_color("bubble_vendor")):
  if imgui.button("Exit Prior Session"): app.controller.cb_exit_prior_session(); app._comms_log_dirty = True
  imgui.same_line()
@@ -4453,6 +4487,16 @@ def render_prior_session_view(app: App) -> None:
     imgui.separator()

 def render_thinking_indicator(app: App) -> None:
+ """
+ Renders a blinking red status indicator when the AI is currently executing,
+ sending, streaming, or running shell commands.
+
+ State Mutations:
+   None.
+
+ SSDL Shape:
+   `[I:ai_status] -> [I:blinking_text]`
+ """
 is_thinking = app.ai_status in ['sending...', 'streaming...', 'running powershell...']
 if is_thinking:
  val   = math.sin(time.time() * 10 * math.pi)
@@ -4488,11 +4532,15 @@ def _on_warmup_complete_callback(app: App, status: dict) -> None:

 def render_warmup_status_indicator(app: App) -> None:
 """
- Renders a per-frame warmup status line. Shows the progress of
- AppController's background warmup (Phase 2 of
- startup_speedup_20260606). Hidden when the controller has no warmup
- or warmup is done with no failures. Shows a transient "ready" tag
- for 3 seconds after completion.
+ Renders a transient warmup status indicator in the main interface frame. Shows progress
+ of AppController's background module imports.
+
+ State Mutations:
+   None directly (reads controller warmup state).
+
+ SSDL Shape:
+   `[I:warmup_status] -> [I:status_text]`
+
 [C: src/gui_2.py:App._post_init, src/gui_2.py:render_main_interface, tests/test_gui_warmup_indicator.py:test_render_warmup_indicator_function_exists, tests/test_gui_warmup_indicator.py:test_callback_sets_timestamp]
 """
 controller = getattr(app, "controller", None)