Docstrings: SSDL + ASCII Layout Map for all Operations Monitor region functions

src/gui_2.py

@@ -5371,6 +5371,23 @@ def render_discussion_tab(app: App) -> None:
 #region: Operations Monitor
 
 def render_operations_hub(app: App) -> None:
+ """
+ Top-level Operations Monitor hub. Houses pop-out checkboxes for Tool Calls, Usage Analytics,
+ and External Tools, then a tab-bar for all ops sub-panels.
+
+ SSDL Shape:
+   `[B:popout_toggles] -> [I:tab_bar] => [I:active_tab_content]`
+
+ ASCII Layout Map:
+   +---------------------------------------------------------+
+   | [ ] Pop Out Tool Calls  [ ] Pop Out Usage  [ ] Ext Tools|
+   | [Comms History] [Tool Calls] [Usage Analytics]          |
+   | [External Tools] [Workspace Layouts] [Vendor State]     |
+   | +-----------------------------------------------------+ |
+   | | <active tab content>                                | |
+   | +-----------------------------------------------------+ |
+   +---------------------------------------------------------+
+ """
  imgui.push_style_var(imgui.StyleVar_.item_spacing, imgui.ImVec2(10, 4))
  ch1, app.ui_separate_tool_calls_panel = imgui.checkbox("Pop Out Tool Calls", app.ui_separate_tool_calls_panel)
  if ch1: app.show_windows["Tool Calls"] = app.ui_separate_tool_calls_panel
@@ -5412,8 +5429,24 @@ def render_operations_hub(app: App) -> None:
   with imscope.tab_item("Vendor State") as (exp, _):
    if exp: render_vendor_state(app)
 
-def render_vendor_state(app: App) -> None: # TODO(Ed): Shouldn't this just be a part of usage analytics? We can show all used vendors at once...
+def render_vendor_state(app: App) -> None:
- """Render the Operations Hub > Vendor State panel."""
+ """
+ Renders the Operations Hub > Vendor State panel. Displays per-vendor health metrics
+ (model name, cache state, token budget, connection status) in a colour-coded table.
+
+ SSDL Shape:
+   `[I:metrics_table] => [I:state_column]`
+
+ ASCII Layout Map:
+   +---------------------------------------------------------+
+   | Metric                   | Value           | State      |
+   |--------------------------|-----------------|------------|
+   | Provider                 | gemini          | ok         |
+   | Model                    | gemini-2.0-flash| ok         |
+   | Cache Token Budget       | 32000           | warn       |
+   | Last Error               | (none)          | info       |
+   +---------------------------------------------------------+
+ """
  from src.vendor_state import get_vendor_state
  metrics = get_vendor_state(app)
  if imgui.begin_table("vendor_state", 3, imgui.TableFlags_.row_bg | imgui.TableFlags_.borders):
@@ -5437,13 +5470,19 @@ def render_message_panel(app: App) -> None:
  Renders user message text input area, exposing buttons to generate assistant responses,
  inject contextual files, or reset active conversation sessions.
 
- State Mutations:
-   app.ui_ai_input (stores user message content)
-   app.show_inject_modal (triggers inject modal visibility)
-   app.disc_entries (appends user message to history)
-
  SSDL Shape:
    `[I:live_indicator] -> [I:input_textbox] -> [B:gen_send_buttons] -> [B:inject_reset]`
+
+ ASCII Layout Map:
+   +---------------------------------------------------------+
+   | LIVE (blinking green when tool is executing)            |
+   | +-----------------------------------------------------+ |
+   | | Type your message here...               (Ctrl+Enter)| |
+   | |                                                     | |
+   | +-----------------------------------------------------+ |
+   | [Gen + Send] [MD Only] [Inject File] [-> History]       |
+   | [Reset]                                                 |
+   +---------------------------------------------------------+
  """
  if app.perf_profiling_enabled: app.perf_monitor.start_component("_render_message_panel")
 # LIVE indicator
@@ -5487,12 +5526,19 @@ def render_response_panel(app: App) -> None:
  Renders assistant stream output panel. Renders thinking traces, markdown segments,
  and exports active responses to history entries.
 
- State Mutations:
-   app._trigger_blink, app._is_blinking, app._blink_start_time (visual transition indicators)
-   app.disc_entries (appends generated responses to history)
-
  SSDL Shape:
    `[I:response_text] -> [I:thinking_trace] -> [I:markdown_view] => [B:export_to_history]`
+
+ ASCII Layout Map:
+   +---------------------------------------------------------+
+   | +-----------------------------------------------------+ |
+   | | > Monologue (collapsible thinking trace)            | |
+   | |                                                     | |
+   | | ## AI Response Heading                              | |
+   | | Rendered markdown text...                           | |
+   | +-----------------------------------------------------+ |
+   | [-> History]                                            |
+   +---------------------------------------------------------+
  """
  if app.perf_profiling_enabled: app.perf_monitor.start_component("_render_response_panel")
  if app._trigger_blink:
@@ -5536,17 +5582,21 @@ def render_response_panel(app: App) -> None:
 def render_tool_calls_panel(app: App) -> None:
  """
  Renders tool call execution log. Displays script execution details, status codes,
- and outputs in a table.
+ and outputs in a scrollable table. Clicking a row opens the full call in the Text Viewer.
-
- State Mutations:
-   app._tool_log (clears tool log)
-   app._tool_log_dirty (marks tool log for reload)
-   app.text_viewer_title, app.text_viewer_content, app.text_viewer_type (triggers text viewer)
-   app.show_windows["Text Viewer"]
-   app._scroll_tool_calls_to_bottom
 
  SSDL Shape:
    `[I:tool_log] -> [B:clear_button] => [I:calls_table]`
+
+ ASCII Layout Map:
+   +---------------------------------------------------------+
+   | Tool call history  [Clear]                              |
+   | +----+------+---------------------------+-----------+   |
+   | | #  | Tier | Script                    | Result    |   |
+   | +----+------+---------------------------+-----------+   |
+   | | #1 | main | uv run pytest tests/...   | passed... |   |
+   | | #2 | T3   | git commit -m "fix: ..." | done      |   |
+   | +----+------+---------------------------+-----------+   |
+   +---------------------------------------------------------+
  """
  if app.perf_profiling_enabled: app.perf_monitor.start_component("_render_tool_calls_panel")
  imgui.text("Tool call history")
@@ -5604,6 +5654,24 @@ def render_tool_calls_panel(app: App) -> None:
  if app.perf_profiling_enabled: app.perf_monitor.end_component("_render_tool_calls_panel")
 
 def render_external_tools_panel(app: App) -> None:
+ """
+ Renders the External MCPs panel. Shows server health indicators, a [Refresh] button,
+ and a table of all registered external MCP tool names, servers, and descriptions.
+
+ SSDL Shape:
+   `[B:refresh] -> [I:server_status_badges] -> [I:tools_table]`
+
+ ASCII Layout Map:
+   +---------------------------------------------------------+
+   | [Refresh External MCPs]                                 |
+   | Servers: [●] my-mcp-server  [●] another-server          |
+   | +----------------------+------------+-----------------+ |
+   | | Name                 | Server     | Description     | |
+   | +----------------------+------------+-----------------+ |
+   | | py_get_definition    | manual-slop| Get Python def  | |
+   | +----------------------+------------+-----------------+ |
+   +---------------------------------------------------------+
+ """
  if app.perf_profiling_enabled:           app.perf_monitor.start_component("_render_external_tools_panel")
  if imgui.button("Refresh External MCPs"): app.event_queue.put("refresh_external_mcps", None)
  
@@ -5648,7 +5716,28 @@ def render_external_tools_panel(app: App) -> None:
  if app.perf_profiling_enabled: app.perf_monitor.end_component("_render_external_tools_panel")
 
 def render_text_viewer_window(app: App) -> None:
- """Renders the standalone text/code/markdown viewer window."""
+ """
+ Renders the standalone text/code/markdown viewer window. Supports four rendering modes
+ based on content type: markdown (rendered), slice editor (line-click range selection),
+ syntax-highlighted code (CodeEditor widget), and plain text (scrollable).
+
+ SSDL Shape:
+   `[I:mode_dispatch] => [I:markdown] | [I:slice_editor] | [I:code_editor] | [I:plain_text]`
+
+ ASCII Layout Map:
+   +---------------------------------------------------------+
+   | src/gui_2.py - Text Viewer                 [x]          |
+   | --- (slice mode only) ---                               |
+   | [Add Selection as Slice] [Clear Selection]              |
+   | [Auto-Populate AST Slices] [Edit Tags]                  |
+   | Slice 1: L10-L42  [tag v] [comment________] [X]         |
+   | ---                                                     |
+   | [Copy]  [ ] Word Wrap                                   |
+   | +-----------------------------------------------------+ |
+   | | <markdown / slice-editor / CodeEditor / plain text> | |
+   | +-----------------------------------------------------+ |
+   +---------------------------------------------------------+
+ """
  if not app.show_windows.get("Text Viewer", False): return
  imgui.set_next_window_size(imgui.ImVec2(900, 700), imgui.Cond_.first_use_ever)
  # Force a unique ID to clear legacy docking corruption
@@ -5753,6 +5842,30 @@ def render_text_viewer_window(app: App) -> None:
  imgui.end()
 
 def render_patch_modal(app: App) -> None:
+ """
+ Renders the Apply Patch? modal. Shows files to be modified, a syntax-highlighted
+ diff preview, and action buttons to open in an external editor, apply, or reject.
+
+ SSDL Shape:
+   `[I:files_list] -> [I:diff_preview] => [B:open_external | B:apply | B:reject]`
+
+ ASCII Layout Map:
+   +---------------------------------------------------------+
+   | ⚠ Tier 4 QA Generated a Patch                           |
+   | Files to modify:                                        |
+   |   - src/gui_2.py                                        |
+   | ---                                                     |
+   | Diff Preview:                                           |
+   | +-----------------------------------------------------+ |
+   | | --- a/src/gui_2.py                                  | |
+   | | +++ b/src/gui_2.py                                  | |
+   | | @@ -100,7 +100,7 @@                                 | |
+   | | -old line                                           | |
+   | | +new line                                           | |
+   | +-----------------------------------------------------+ |
+   | [Open in External Editor] [Apply Patch] [Reject]        |
+   +---------------------------------------------------------+
+ """
  if not app._show_patch_modal:
   return
  imgui.open_popup("Apply Patch?")
@@ -5797,6 +5910,25 @@ def render_patch_modal(app: App) -> None:
     imgui.close_current_popup()
 
 def render_external_editor_panel(app: App) -> None:
+ """
+ Renders the External Editor configuration panel. Lists configured editors
+ from config.toml, shows the current default, and allows setting a new default.
+
+ SSDL Shape:
+   `[I:editors_list] -> [B:set_default] => [I:config_hint?]`
+
+ ASCII Layout Map:
+   +---------------------------------------------------------+
+   | External Editor for Diff Viewing                        |
+   | (no editors configured)                                 |
+   | Add editors in config.toml:                             |
+   |   [tools.text_editors.vscode]                           |
+   |   path = "C:\\path\\to\\code.exe"                       |
+   | ---  OR when editors exist ---                          |
+   | Default: vscode                                         |
+   | [vscode] [notepad++]                [Set as Default]    |
+   +---------------------------------------------------------+
+ """
  from src.external_editor import get_default_launcher
  imgui.text("External Editor for Diff Viewing")
  imgui.separator()