agent-command-tab 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. agent_command_tab/__init__.py +4 -0
  2. agent_command_tab/agent_adapters/__init__.py +48 -0
  3. agent_command_tab/agent_adapters/base.py +162 -0
  4. agent_command_tab/agent_adapters/claude_code.py +120 -0
  5. agent_command_tab/agent_adapters/codex.py +102 -0
  6. agent_command_tab/agent_adapters/generic.py +22 -0
  7. agent_command_tab/agent_process_tree.py +557 -0
  8. agent_command_tab/agent_session_pausing.py +254 -0
  9. agent_command_tab/app_controller.py +947 -0
  10. agent_command_tab/claude_code_transcript_records.py +75 -0
  11. agent_command_tab/command_line.py +187 -0
  12. agent_command_tab/context_window_usage.py +230 -0
  13. agent_command_tab/dashboard_core_api.py +57 -0
  14. agent_command_tab/docked_window_frames_store.py +60 -0
  15. agent_command_tab/global_shortcut_key_filter.py +167 -0
  16. agent_command_tab/hook_event_forwarder.py +116 -0
  17. agent_command_tab/hook_event_tracking.py +129 -0
  18. agent_command_tab/hook_states_store.py +60 -0
  19. agent_command_tab/hooks_installer.py +300 -0
  20. agent_command_tab/installed_copy_paths.py +41 -0
  21. agent_command_tab/iterm2_actions.py +325 -0
  22. agent_command_tab/iterm2_connection_thread.py +2299 -0
  23. agent_command_tab/iterm2_snapshot_builder.py +403 -0
  24. agent_command_tab/list_sorting.py +117 -0
  25. agent_command_tab/messages_between_agent_sessions.py +78 -0
  26. agent_command_tab/monitor_assignment.py +109 -0
  27. agent_command_tab/pause_records_store.py +61 -0
  28. agent_command_tab/screen_readings.py +108 -0
  29. agent_command_tab/session_preview_computation.py +228 -0
  30. agent_command_tab/session_status_computation.py +235 -0
  31. agent_command_tab/settings_store.py +292 -0
  32. agent_command_tab/snapshot_data_classes.py +145 -0
  33. agent_command_tab/start_with_iterm2.py +138 -0
  34. agent_command_tab/tab_order_computation.py +26 -0
  35. agent_command_tab/user_interface/__init__.py +1 -0
  36. agent_command_tab/user_interface/agent_session_outline_view.py +2120 -0
  37. agent_command_tab/user_interface/agent_tool_icons.py +124 -0
  38. agent_command_tab/user_interface/app_icon.py +75 -0
  39. agent_command_tab/user_interface/control_helpers.py +38 -0
  40. agent_command_tab/user_interface/list_window.py +116 -0
  41. agent_command_tab/user_interface/menu_bar_status_item.py +193 -0
  42. agent_command_tab/user_interface/named_colors.py +58 -0
  43. agent_command_tab/user_interface/pointing_hand_button.py +42 -0
  44. agent_command_tab/user_interface/popover_container.py +461 -0
  45. agent_command_tab/user_interface/row_text_rendering.py +342 -0
  46. agent_command_tab/user_interface/screen_layout.py +91 -0
  47. agent_command_tab/user_interface/settings_window.py +530 -0
  48. agent_command_tab/user_interface/sidebar_panel.py +486 -0
  49. agent_command_tab/user_interface/sidebar_placement.py +105 -0
  50. agent_command_tab/user_interface/talk_to_each_other_alert.py +130 -0
  51. agent_command_tab/window_list_ordering.py +44 -0
  52. agent_command_tab-0.1.0.dist-info/METADATA +85 -0
  53. agent_command_tab-0.1.0.dist-info/RECORD +57 -0
  54. agent_command_tab-0.1.0.dist-info/WHEEL +5 -0
  55. agent_command_tab-0.1.0.dist-info/entry_points.txt +2 -0
  56. agent_command_tab-0.1.0.dist-info/licenses/LICENSE +21 -0
  57. agent_command_tab-0.1.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,2120 @@
1
+ """The shared list of monitors, windows and agent session tabs.
2
+
3
+ Three instances exist (dropdown, sidebar and list window), each with its own NSOutlineView,
4
+ expanded rows, open previews and selection, fed the same snapshots. Main thread only.
5
+
6
+ How snapshots are applied without breaking expansion, renames or drags:
7
+ - one OutlineListItem per (kind, ID) lives as long as that ID exists, so expansion and
8
+ selection, which NSOutlineView tracks by item identity, survive updates;
9
+ - when the rows' structure (which rows, in which order, how tall) is unchanged, the items'
10
+ entries are replaced and only the visible rows are redrawn; otherwise the outline view is
11
+ reloaded and the expansion and selection are restored from the controller's own records;
12
+ - while a rename or a drag is in progress, or the button is held down on a row or on a row's
13
+ own button, snapshots are held and the newest is applied when that ends.
14
+ """
15
+
16
+ import time
17
+
18
+ import objc
19
+ from AppKit import (NSAnimationContext, NSApp, NSAttributedString, NSBackgroundStyleNormal, NSBezierPath, NSColor, NSCursor,
20
+ NSDragOperationMove, NSDragOperationNone, NSEventModifierFlagControl, NSFont, NSFontAttributeName,
21
+ NSFontWeightBold, NSFontWeightMedium, NSFontWeightRegular, NSFontWeightSemibold, NSForegroundColorAttributeName,
22
+ NSGraphicsContext,
23
+ NSImageOnly, NSImageScaleNone,
24
+ NSImageView, NSInsetRect, NSLeftArrowFunctionKey, NSLineBreakByTruncatingTail, NSLineBreakByWordWrapping,
25
+ NSMakeRect, NSMenu, NSMenuItem, NSMutableAttributedString, NSMutableParagraphStyle, NSOutlineView,
26
+ NSParagraphStyleAttributeName, NSPasteboardItem, NSRightArrowFunctionKey,
27
+ NSTableCellView, NSTableColumn, NSTableColumnAutoresizingMask, NSTableRowView,
28
+ NSTableViewLastColumnOnlyAutoresizingStyle, NSTableViewSelectionHighlightStyleRegular,
29
+ NSTableViewStylePlain, NSTextAlignmentCenter, NSTextAlignmentLeft, NSTextAlignmentRight, NSTextField,
30
+ NSTrackingActiveAlways, NSTrackingArea, NSTrackingCursorUpdate, NSTrackingInVisibleRect,
31
+ NSTrackingMouseEnteredAndExited, NSTrackingMouseMoved, NSView,
32
+ NSWindowStyleMaskNonactivatingPanel, NSZeroRect)
33
+ from Foundation import NSMutableIndexSet, NSObject, NSRunLoop, NSRunLoopCommonModes, NSTimer
34
+
35
+ from agent_command_tab.agent_adapters import (list_agent_tool_names_whose_sessions_can_talk_to_each_other,
36
+ list_slash_commands_of_the_built_in_agent_tools)
37
+ from agent_command_tab.agent_adapters.base import COMMAND_THAT_STARTS_A_NEW_CONVERSATION
38
+ from agent_command_tab.dashboard_core_api import ActionRequest
39
+ from agent_command_tab.list_sorting import sort_agent_session_entries, sort_window_entries
40
+ from agent_command_tab.session_status_computation import (STATES_OF_AN_AGENT_WAITING_AT_ITS_PROMPT,
41
+ split_agent_sessions_into_pausable_and_resumable)
42
+ from agent_command_tab.settings_store import DEFAULT_SETTINGS
43
+ from agent_command_tab.snapshot_data_classes import iterate_agent_session_entries, replace_title_in_snapshot
44
+ from agent_command_tab.user_interface.agent_tool_icons import build_agent_tool_icons, build_text_image, describe_agent_tool_icon
45
+ from agent_command_tab.user_interface.control_helpers import ROWS_OPEN_SYMBOL_NAMES, show_symbol_on_button
46
+ from agent_command_tab.user_interface.named_colors import build_color_from_name
47
+ from agent_command_tab.user_interface.pointing_hand_button import PointingHandButton
48
+ from agent_command_tab.user_interface.row_text_rendering import (DOT_GLYPH_AND_COLOR_BY_STATE,
49
+ LONGEST_TEXT_BY_COLUMN_FIELD_NAME, RowTextParts,
50
+ build_agent_session_row_text_parts,
51
+ build_child_process_row_text_parts,
52
+ build_dot_text, build_monitor_row_text_parts,
53
+ build_tree_connector_text,
54
+ build_window_row_text_parts)
55
+ from agent_command_tab.user_interface.talk_to_each_other_alert import list_tab_titles_for_alert
56
+
57
+ ROW_HEIGHT = 20
58
+ PREVIEW_LINE_HEIGHT = 16 # the height of a 12-point line, so the tree's lines carry on beside the preview
59
+ PREVIEW_LINE_COUNT = 2
60
+ PREVIEW_AREA_HEIGHT = PREVIEW_LINE_HEIGHT * PREVIEW_LINE_COUNT
61
+ TAB_ROW_HEIGHT_WITH_PREVIEW = ROW_HEIGHT + PREVIEW_AREA_HEIGHT # a tab row whose preview is open
62
+ FONT_SIZE = 12
63
+ PREVIEW_FONT_SIZE = 11
64
+ PREVIEW_BUTTON_SIZE = 16 # an expanded window row's button that opens or closes its tabs' previews
65
+ # Each row's arrow (closed ›, open ⌄) opens or closes just that row (user request, 2026-10-19);
66
+ # every row keeps the arrow's room, so names line up whether or not a row has one.
67
+ DISCLOSURE_ARROW_SLOT_WIDTH = 14
68
+ DISCLOSURE_ARROW_POINT_SIZE = 9
69
+ DISCLOSURE_ARROW_LOOKS = {False: ("chevron.right", ">", "Open"), True: ("chevron.down", "v", "Close")} # by whether the row is open
70
+ # The button's (SF Symbol, text fallback, description), by whether all of the window's previews
71
+ # are open. The symbol shows the current state, as the top bar's expand or collapse button's
72
+ # does; the fallback text and the description say what a click does.
73
+ PREVIEW_BUTTON_LOOKS = {False: (ROWS_OPEN_SYMBOL_NAMES[False], "+", "Show the tabs' previews"),
74
+ True: (ROWS_OPEN_SYMBOL_NAMES[True], "−", "Hide the tabs' previews")}
75
+ ROW_LEFT_MARGIN = 8
76
+ GAP_AFTER_PREFIX = 2
77
+ NAME_FIELD_PADDING = 4
78
+ GAP_BEFORE_DETAILS = 8
79
+ # Between the columns at a tab row's right edge: 16 since 2026-10-28, 6 before, which left about 11
80
+ # points between a column's text and a next column its text fills (user request).
81
+ GAP_BETWEEN_COLUMNS = 16
82
+ ROW_RIGHT_MARGIN = 8
83
+ TEXT_FIELD_INSETS = 5 # a label's text sits a few points inside its field
84
+ # A collapsed window's state counts can grow ("9 idle" becomes "10 idle") without widening the dropdown.
85
+ ROOM_FOR_GROWING_DETAILS = "0000"
86
+ SECONDS_TO_HOLD_BEFORE_PEEKING = 0.15
87
+ SMALLEST_TAB_NAME_WIDTH = 80 # a narrower sidebar or window drops columns (COLUMN_NAMES_IN_DROP_ORDER)
88
+ # The spare room a sidebar's or list window's column keeps beyond its widest text, and how much
89
+ # narrower that text may get before the column shrinks (choose_room_for_a_columns_texts).
90
+ SPARE_CHARACTERS_IN_A_COLUMN = 1
91
+ CHARACTERS_A_COLUMN_MAY_LOSE = 2
92
+ # A tab row's columns at its right edge, left to right: settings_store.LIST_COLUMNS, which the
93
+ # settings can show or hide, and the agent tool's icon, which shows by itself when two or more
94
+ # agent tools run. Each comes with the RowTextParts field it shows (the icon column shows the
95
+ # tool's icon instead). The state is left-aligned in its column; the others are right-aligned.
96
+ # The icon, the state and its duration come first, right after the name, and CPU before memory
97
+ # (user requests, 2026-10-28).
98
+ TAB_ROW_COLUMNS = [
99
+ ("agent_tool_icon", None),
100
+ ("state", "state_text"),
101
+ ("state_duration", "elapsed_time_text"),
102
+ ("context_tokens", "context_text"),
103
+ ("created_time", "created_time_text"),
104
+ ("existence_duration", "existence_duration_text"),
105
+ ("cpu_usage", "cpu_text"),
106
+ ("memory_usage", "memory_text"),
107
+ ]
108
+ LEFT_ALIGNED_COLUMN_NAMES = {"state"}
109
+ # The names shown over the columns, in a row between the top bar and the list (user request,
110
+ # 2026-10-26), with "Name" at the left. A name can be on two lines, "\n" between them, so its
111
+ # column widens only to the longer line; none is since they were shortened (user request,
112
+ # 2026-10-28). The icon column has none.
113
+ COLUMN_TITLES = {
114
+ "context_tokens": "Tokens", "created_time": "Created", "existence_duration": "Age", # "Time Since\nCreated" until 2026-10-28
115
+ "memory_usage": "Memory", "cpu_usage": "CPU", "agent_tool_icon": "", "state": "Status",
116
+ "state_duration": "Status Changed", # "Time Since Last\nStatus Change" until 2026-10-28 (user request)
117
+ }
118
+ NAME_COLUMN_TITLE = "Name"
119
+ # The sort order (list_sorting.py) a click on a title chooses, by the title's column ("name" for
120
+ # Name; user requests, 2026-10-26). Tokens sorts by the share of the context window in use (user
121
+ # request, 2026-10-26); Created and Age both sort by when the agent started.
122
+ LIST_SORT_ORDER_BY_TITLE_NAME = {
123
+ "name": "alphabet", "context_tokens": "context_percent", "created_time": "created_time", "existence_duration": "created_time", "memory_usage": "memory_usage",
124
+ "cpu_usage": "cpu_usage", "state": "activity", "state_duration": "state_duration",
125
+ }
126
+ # The sorted column's title ends in an arrow, as in Finder: up while its values go from the
127
+ # smallest at the top (A, the shortest time) to the largest, down while they go from the largest
128
+ # (the fullest context window, the newest start, the most urgent state). These titles' orders start smallest first.
129
+ TITLE_NAMES_WHOSE_ORDER_STARTS_ASCENDING = {"name", "existence_duration", "state_duration"}
130
+ SORT_ARROWS_BY_IS_ASCENDING = {True: " ▴", False: " ▾"} # a space before the arrow (user request, 2026-10-26)
131
+ COLUMN_TITLE_FONT_SIZE = 11
132
+ COLUMN_TITLE_LINE_HEIGHT = 14
133
+ COLUMN_TITLES_ROW_PADDING = 2 # above and below the titles
134
+ # A narrow sidebar or window drops columns in this order to keep room for names (the dot's color
135
+ # still shows the state). The time since the last status change goes last, since its title makes
136
+ # its column about 114 points wide, which would leave a 200-point sidebar's names unreadable.
137
+ COLUMN_NAMES_IN_DROP_ORDER = ["created_time", "existence_duration", "memory_usage", "cpu_usage", "context_tokens",
138
+ "agent_tool_icon", "state", "state_duration"]
139
+ SLASH_COMMANDS_IN_THE_TAB_MENU = list_slash_commands_of_the_built_in_agent_tools()
140
+ AGENT_TOOL_NAMES_WHOSE_SESSIONS_CAN_TALK_TO_EACH_OTHER = list_agent_tool_names_whose_sessions_can_talk_to_each_other()
141
+ SELECTABLE_ROW_KINDS = ("window", "tab") # not monitor rows or the "+" row (user request, 2026-10-21)
142
+ # The hover text of the greyed-out items in the menu of several selected rows that have all exited.
143
+ AGENTS_HAVE_ENDED_TOOL_TIP = "The agents have ended"
144
+ SELECTION_OUTLINE_WIDTH = 1.5
145
+ SELECTION_OUTLINE_INSET = 1
146
+ SELECTION_OUTLINE_CORNER_RADIUS = 4
147
+ TAB_DRAG_TYPE = "org.agent-command-tab.tab-id"
148
+ WINDOW_DRAG_TYPE = "org.agent-command-tab.window-id"
149
+ COLUMN_IDENTIFIER = "main"
150
+ ROW_VIEW_IDENTIFIER = "agent-list-row"
151
+
152
+
153
+ class OutlineListItem(NSObject):
154
+ """One row's item: kind is "monitor", "window", "tab", "process" for a sub row of an open tab
155
+ row (one per process its agent started; user request, 2026-10-27), or "new_window" for the
156
+ "+" row at the end of the list (it has no entry); entry is its snapshot record; key, (kind,
157
+ item ID), finds it in the controller's records (expansion, open tab rows, items)."""
158
+
159
+ def initWithKind_itemId_(self, kind, item_id):
160
+ self = objc.super(OutlineListItem, self).init()
161
+ if self is None:
162
+ return None
163
+ self.kind = kind
164
+ self.item_id = item_id
165
+ self.key = (kind, item_id)
166
+ self.entry = None
167
+ self.parent_item = None
168
+ self.child_items = []
169
+ return self
170
+
171
+
172
+ class OutlineViewWithoutDisclosureTriangles(NSOutlineView):
173
+ """An NSOutlineView that draws no disclosure triangles of its own (each row has its own arrow
174
+ button), that tells its delegate when the button goes down on a row and comes back up, so
175
+ holding a tab row can show that tab for a moment, and that has its delegate open and close
176
+ selected tab rows with the Right and Left arrow keys."""
177
+
178
+ def frameOfOutlineCellAtRow_(self, row):
179
+ return NSZeroRect
180
+
181
+ def keyDown_(self, event):
182
+ if not self.delegate().open_or_close_selected_tab_rows_for_arrow_key(event.charactersIgnoringModifiers()):
183
+ objc.super(OutlineViewWithoutDisclosureTriangles, self).keyDown_(event)
184
+
185
+ def mouseDown_(self, event):
186
+ is_plain_press = event.clickCount() == 1 and not event.modifierFlags() & NSEventModifierFlagControl
187
+ if is_plain_press:
188
+ self.delegate().row_pressed(self.rowAtPoint_(self.convertPoint_fromView_(event.locationInWindow(), None)))
189
+ try:
190
+ objc.super(OutlineViewWithoutDisclosureTriangles, self).mouseDown_(event) # returns once the button is up
191
+ finally:
192
+ if is_plain_press: # always, or the list would hold back every snapshot from then on
193
+ self.delegate().row_released()
194
+
195
+
196
+ def compute_selection_outline_rect(row_bounds, is_flipped, joins_the_row_above, joins_the_row_below):
197
+ """Returns the NSRect of the rounded rectangle a selected row strokes: its bounds
198
+ inset by SELECTION_OUTLINE_INSET, run on past each edge it shares with a selected row above or
199
+ below, so that the row's clip cuts off that edge and its corners and adjacent selected rows
200
+ show one outline around them all (user request, 2026-10-21).
201
+
202
+ Args:
203
+ row_bounds: The row view's bounds.
204
+ is_flipped: Whether the row view's y axis points down (the row above is then at the smaller y).
205
+ joins_the_row_above: Whether the row above is selected too.
206
+ joins_the_row_below: Whether the row below is selected too.
207
+ """
208
+ (x, y), (width, height) = NSInsetRect(row_bounds, SELECTION_OUTLINE_INSET, SELECTION_OUTLINE_INSET)
209
+ run_on = SELECTION_OUTLINE_INSET + SELECTION_OUTLINE_CORNER_RADIUS + SELECTION_OUTLINE_WIDTH
210
+ joins_at_smaller_y, joins_at_larger_y = ((joins_the_row_above, joins_the_row_below) if is_flipped
211
+ else (joins_the_row_below, joins_the_row_above))
212
+ if joins_at_smaller_y:
213
+ y, height = y - run_on, height + run_on
214
+ if joins_at_larger_y:
215
+ height += run_on
216
+ return NSMakeRect(x, y, width, height)
217
+
218
+
219
+ class RowViewWithSelectionOutline(NSTableRowView):
220
+ """A row that shows it is selected with an outline in the accent color rather than a filled
221
+ background, so its text keeps its colors; adjacent selected rows share one outline (user
222
+ requests, 2026-10-21)."""
223
+
224
+ def drawSelectionInRect_(self, dirty_rect):
225
+ NSGraphicsContext.saveGraphicsState()
226
+ NSBezierPath.clipRect_(self.bounds())
227
+ NSColor.controlAccentColor().setStroke()
228
+ outline = NSBezierPath.bezierPathWithRoundedRect_xRadius_yRadius_(
229
+ compute_selection_outline_rect(self.bounds(), self.isFlipped(), self.isPreviousRowSelected(),
230
+ self.isNextRowSelected()),
231
+ SELECTION_OUTLINE_CORNER_RADIUS, SELECTION_OUTLINE_CORNER_RADIUS)
232
+ outline.setLineWidth_(SELECTION_OUTLINE_WIDTH)
233
+ outline.stroke()
234
+ NSGraphicsContext.restoreGraphicsState()
235
+
236
+ def interiorBackgroundStyle(self):
237
+ return NSBackgroundStyleNormal # the row's labels keep the colors of an unselected row
238
+
239
+
240
+ def describe_session_count(count):
241
+ """Returns "1 session" or "3 sessions", for menu item titles, which are in sentence case (user request, 2026-10-27)."""
242
+ return f"{count} session{'' if count == 1 else 's'}"
243
+
244
+
245
+ def list_agent_sessions_that_take_slash_command(agent_session_entries, command):
246
+ """Returns the agent sessions whose tool takes a slash command, whatever they are doing but
247
+ paused (the menu of several selected rows; user request, 2026-10-21): one in the middle of a
248
+ turn gets it when the turn ends (handle_send_slash_command_to_agent_sessions), while the core
249
+ can't type into a suspended agent."""
250
+ return [entry for entry in agent_session_entries if command in entry.slash_commands and entry.status != "paused"]
251
+
252
+
253
+ def tab_row_is_hidden(agent_session_entry, idle_tabs_are_hidden):
254
+ """Whether "Hide Idle" hides the agent session's tab row (user request, 2026-10-21). It only
255
+ hides rows: a window row still stands for its whole iTerm2 window, so the window's menu and
256
+ the top bar's buttons act on its hidden agent sessions too."""
257
+ return idle_tabs_are_hidden and agent_session_entry.status == "idle"
258
+
259
+
260
+ def window_row_is_hidden(window_entry, idle_tabs_are_hidden):
261
+ """Whether "Hide Idle" hides a window row: every one of its agent sessions' rows is hidden."""
262
+ return bool(window_entry.agent_sessions) and all(tab_row_is_hidden(entry, idle_tabs_are_hidden)
263
+ for entry in window_entry.agent_sessions)
264
+
265
+
266
+ def list_window_and_tab_item_keys(snapshot):
267
+ """Returns the item keys of every window and agent session tab in the snapshot, also those
268
+ whose rows Hide Idle hides, so a hidden window keeps its collapsed state and a hidden tab its
269
+ open preview for when its row shows again."""
270
+ return ({("window", window_entry.window_id) for monitor_entry in snapshot.monitors for window_entry in monitor_entry.windows}
271
+ | {("tab", entry.tab_id) for _, _, entry in iterate_agent_session_entries(snapshot)})
272
+
273
+
274
+ def snapshot_shows_monitor_rows(snapshot):
275
+ """Whether the list groups windows under monitor rows: only with two or more monitors."""
276
+ return len(snapshot.monitors) > 1
277
+
278
+
279
+ def build_index_set(indexes):
280
+ """Returns an NSIndexSet holding the given row indexes."""
281
+ index_set = NSMutableIndexSet.alloc().init()
282
+ for index in indexes:
283
+ index_set.addIndex_(index)
284
+ return index_set
285
+
286
+
287
+ def run_without_animation(change_rows):
288
+ """Calls change_rows (expanding, collapsing or resizing rows) with the outline view's slide
289
+ animation off, so the rows change at once; the animation setting is restored even if it raises."""
290
+ NSAnimationContext.beginGrouping()
291
+ NSAnimationContext.currentContext().setDuration_(0)
292
+ try:
293
+ change_rows()
294
+ finally:
295
+ NSAnimationContext.endGrouping()
296
+
297
+
298
+ def make_label_text_field():
299
+ """Returns a borderless, non-editable, single-line text field."""
300
+ text_field = NSTextField.alloc().initWithFrame_(NSMakeRect(0, 0, 10, ROW_HEIGHT))
301
+ text_field.setBezeled_(False)
302
+ text_field.setDrawsBackground_(False)
303
+ text_field.setEditable_(False)
304
+ text_field.setSelectable_(False)
305
+ text_field.cell().setLineBreakMode_(NSLineBreakByTruncatingTail)
306
+ text_field.cell().setUsesSingleLineMode_(True)
307
+ return text_field
308
+
309
+
310
+ def make_multiline_label_text_field(line_count):
311
+ """Returns a label like make_label_text_field's that wraps onto up to line_count lines, the
312
+ last one ending in "…" when the text doesn't fit."""
313
+ text_field = make_label_text_field()
314
+ text_field.cell().setUsesSingleLineMode_(False)
315
+ text_field.cell().setWraps_(True)
316
+ text_field.cell().setLineBreakMode_(NSLineBreakByWordWrapping)
317
+ text_field.cell().setTruncatesLastVisibleLine_(True)
318
+ text_field.setMaximumNumberOfLines_(line_count)
319
+ return text_field
320
+
321
+
322
+ class RowButton(PointingHandButton):
323
+ """A button inside a row, with the pointing hand. While it is pressed, its target (the list
324
+ controller) holds snapshots, as a press on the row itself does, so a snapshot can't reorder
325
+ or reload the rows under it and leave its click without a row."""
326
+
327
+ def mouseDown_(self, event):
328
+ list_controller = self.target()
329
+ # A double-click that starts here isn't the row's: its second click must not show the row
330
+ # an earlier single click hit.
331
+ list_controller.item_under_first_click = None
332
+ list_controller.row_pressed(-1) # held as a press on a row is, without peeking (no row)
333
+ try:
334
+ objc.super(RowButton, self).mouseDown_(event) # returns once the button is up, after the action
335
+ finally:
336
+ list_controller.row_released()
337
+
338
+
339
+ def make_row_icon_button():
340
+ """Returns a small borderless gray button for a row, without a tooltip, since the list's rows
341
+ have no hover popups (user request, 2026-10-19); show_symbol_on_button gives it its icon."""
342
+ button = RowButton.alloc().initWithFrame_(NSMakeRect(0, 0, PREVIEW_BUTTON_SIZE, PREVIEW_BUTTON_SIZE))
343
+ button.setBordered_(False)
344
+ button.setImagePosition_(NSImageOnly)
345
+ button.setContentTintColor_(NSColor.secondaryLabelColor())
346
+ return button
347
+
348
+
349
+ def choose_room_for_a_columns_texts(widest_text_width, room_before, character_width):
350
+ """Returns the room a column keeps for its texts in the sidebar and the list window, whose width
351
+ the user sets (user request, 2026-10-28): the widest text and SPARE_CHARACTERS_IN_A_COLUMN more,
352
+ kept as it was while the widest text still fits and is at most CHARACTERS_A_COLUMN_MAY_LOSE
353
+ narrower than when it was set, so a number gaining or losing a digit (9 to 10, and back)
354
+ doesn't move the columns, while a wider text widens its column at once.
355
+
356
+ Args:
357
+ widest_text_width: The widest of the column's texts now, in points (0 for none).
358
+ room_before: What this returned last time, or 0.
359
+ character_width: One character's width in the rows' monospaced font.
360
+ """
361
+ if not widest_text_width:
362
+ return 0
363
+ rounding_slack = 0.5 # text widths are sums of character widths, give or take a fraction of a point
364
+ if widest_text_width - rounding_slack <= room_before <= (
365
+ widest_text_width + (SPARE_CHARACTERS_IN_A_COLUMN + CHARACTERS_A_COLUMN_MAY_LOSE) * character_width + rounding_slack):
366
+ return room_before
367
+ return widest_text_width + SPARE_CHARACTERS_IN_A_COLUMN * character_width
368
+
369
+
370
+ def place_columns_from_the_right(right_edge, column_widths):
371
+ """Returns {column name: (x, width)} for the TAB_ROW_COLUMNS with a width (a hidden column's
372
+ is 0), placed right to left from right_edge with GAP_BETWEEN_COLUMNS between them: where a tab
373
+ row shows them, and the row of column titles their titles."""
374
+ placed_columns = {}
375
+ for column_name, _ in reversed(TAB_ROW_COLUMNS):
376
+ if column_widths[column_name] > 0:
377
+ right_edge -= column_widths[column_name]
378
+ placed_columns[column_name] = (right_edge, column_widths[column_name])
379
+ right_edge -= GAP_BETWEEN_COLUMNS
380
+ return placed_columns
381
+
382
+
383
+ class ColumnTitlesRowView(NSView):
384
+ """The row of column titles between the top bar and the list (user request, 2026-10-26):
385
+ "Name" centered over the names (user request, 2026-10-26), and each shown column's title over it, aligned as its texts are, with its
386
+ last line just above the first row. The list controller fills it and sets the columns' widths;
387
+ the columns are placed as a tab row places them, from the outline view's right edge, which is
388
+ left of this row's while the list shows a scroller that takes room. A click on a title, or
389
+ anywhere above its column, reports the title's name ("name", or the column's) to
390
+ on_title_clicked, which sorts the list. The pointer is the pointing hand where a click sorts
391
+ (user request, 2026-10-26), set as PointingHandButton sets it: from a cursor rect in the
392
+ dropdown and the list window, and from a tracking area in the sidebar, which turns cursor
393
+ rects off."""
394
+
395
+ def initWithOutlineView_(self, outline_view):
396
+ self = objc.super(ColumnTitlesRowView, self).initWithFrame_(NSMakeRect(0, 0, 400, 0))
397
+ if self is None:
398
+ return None
399
+ self.addTrackingArea_(NSTrackingArea.alloc().initWithRect_options_owner_userInfo_(
400
+ NSZeroRect, NSTrackingMouseEnteredAndExited | NSTrackingMouseMoved | NSTrackingCursorUpdate
401
+ | NSTrackingActiveAlways | NSTrackingInVisibleRect, self, None))
402
+ self.outline_view = outline_view
403
+ # A wrapping label too, of one line: a single-line field's text sits 2 points lower in the
404
+ # same fixed line height, so "Name" would stand below the other titles (user request, 2026-10-27).
405
+ self.name_title_text_field = make_multiline_label_text_field(1)
406
+ self.column_title_text_fields = {column_name: make_multiline_label_text_field(2) for column_name, _ in TAB_ROW_COLUMNS}
407
+ for subview in (self.name_title_text_field, *self.column_title_text_fields.values()):
408
+ self.addSubview_(subview)
409
+ self.column_widths = {column_name: 0 for column_name, _ in TAB_ROW_COLUMNS} # set by the list controller
410
+ self.room_for_the_previews_button = 0 # set by the list controller; the column at the right edge has no title
411
+ self.on_title_clicked = lambda title_name: None # set by the list controller
412
+ self.title_name_under_press = None
413
+ return self
414
+
415
+ def acceptsFirstMouse_(self, event):
416
+ return True # the sidebar's titles sort from the first click, though the dashboard isn't the active app
417
+
418
+ def hitTest_(self, point):
419
+ # The row takes the clicks on its titles itself, rather than the labels.
420
+ return self if objc.super(ColumnTitlesRowView, self).hitTest_(point) is not None else None
421
+
422
+ def mouseDown_(self, event):
423
+ self.title_name_under_press = self.find_title_name_at(self.convertPoint_fromView_(event.locationInWindow(), None))
424
+
425
+ def mouseUp_(self, event):
426
+ """Reports a click: the button went down and came up above the same title."""
427
+ title_name = self.find_title_name_at(self.convertPoint_fromView_(event.locationInWindow(), None))
428
+ if title_name is not None and title_name == self.title_name_under_press:
429
+ self.on_title_clicked(title_name)
430
+ self.title_name_under_press = None
431
+
432
+ @objc.python_method
433
+ def list_titles_that_sort(self):
434
+ """Returns [(title name, its label's frame)] for the shown titles that sort."""
435
+ return [(title_name, text_field.frame())
436
+ for title_name, text_field in [("name", self.name_title_text_field), *self.column_title_text_fields.items()]
437
+ if title_name in LIST_SORT_ORDER_BY_TITLE_NAME and not text_field.isHidden()]
438
+
439
+ @objc.python_method
440
+ def find_title_name_at(self, point):
441
+ """Returns the name ("name", or the column's) of the shown title that sorts and whose
442
+ column holds point's x, or None."""
443
+ for title_name, frame in self.list_titles_that_sort():
444
+ if frame.origin.x <= point.x < frame.origin.x + frame.size.width:
445
+ return title_name
446
+ return None
447
+
448
+ def resetCursorRects(self):
449
+ if not self.isHiddenOrHasHiddenAncestor():
450
+ for _, frame in self.list_titles_that_sort():
451
+ self.addCursorRect_cursor_(NSMakeRect(frame.origin.x, 0, frame.size.width, self.bounds().size.height),
452
+ NSCursor.pointingHandCursor())
453
+
454
+ @objc.python_method
455
+ def show_the_pointer_at(self, point):
456
+ """Shows the pointing hand above a title that sorts, and the arrow elsewhere in the row."""
457
+ if not self.isHiddenOrHasHiddenAncestor() and self.find_title_name_at(point) is not None:
458
+ NSCursor.pointingHandCursor().set()
459
+ else:
460
+ NSCursor.arrowCursor().set()
461
+
462
+ def cursorUpdate_(self, event):
463
+ self.show_the_pointer_at(self.convertPoint_fromView_(self.window().mouseLocationOutsideOfEventStream(), None))
464
+
465
+ def mouseEntered_(self, event):
466
+ self.show_the_pointer_at(self.convertPoint_fromView_(event.locationInWindow(), None))
467
+
468
+ def mouseMoved_(self, event):
469
+ self.show_the_pointer_at(self.convertPoint_fromView_(event.locationInWindow(), None))
470
+
471
+ def mouseExited_(self, event):
472
+ NSCursor.arrowCursor().set()
473
+
474
+ def layout(self):
475
+ objc.super(ColumnTitlesRowView, self).layout()
476
+ placed_columns = place_columns_from_the_right(
477
+ self.outline_view.frame().size.width - ROW_RIGHT_MARGIN - self.room_for_the_previews_button, self.column_widths)
478
+ # "Name" is centered over the room the rows' names have, up to the columns.
479
+ names_right_edge = min((column_x for column_x, _ in placed_columns.values()), default=ROW_LEFT_MARGIN) - GAP_BEFORE_DETAILS
480
+ name_title_size = self.name_title_text_field.fittingSize()
481
+ self.name_title_text_field.setFrame_(NSMakeRect(ROW_LEFT_MARGIN, COLUMN_TITLES_ROW_PADDING,
482
+ max(names_right_edge - ROW_LEFT_MARGIN, name_title_size.width),
483
+ name_title_size.height))
484
+ for column_name, text_field in self.column_title_text_fields.items():
485
+ text_field.setHidden_(column_name not in placed_columns)
486
+ if column_name in placed_columns:
487
+ column_x, column_width = placed_columns[column_name]
488
+ text_field.setFrame_(NSMakeRect(column_x, COLUMN_TITLES_ROW_PADDING, column_width, text_field.fittingSize().height))
489
+ if self.window() is not None:
490
+ self.window().invalidateCursorRectsForView_(self) # the hand's areas follow the titles
491
+
492
+
493
+ class AgentListRowView(NSTableCellView):
494
+ """A row: [tree connector] [arrow] [dot] [name] [details] ... then, on a tab row and a
495
+ process row, the TAB_ROW_COLUMNS at the right edge. The arrow opens or closes the row (a
496
+ monitor's or window's rows below it, a tab's preview and process rows); rows without one keep its room. The list
497
+ controller sets each column's width, 0 for a hidden column, so the columns line up from row
498
+ to row. A tab row whose preview is open has two more lines, [tree lines] [preview], with the
499
+ preview starting under the name. An expanded window row with previews ends in a button that
500
+ opens or closes them all, in a column of its own at the right edge: the tab rows' columns
501
+ end room_for_the_previews_button before it (user request, 2026-10-26)."""
502
+
503
+ def initWithFrame_(self, frame):
504
+ self = objc.super(AgentListRowView, self).initWithFrame_(frame)
505
+ if self is None:
506
+ return None
507
+ self.prefix_text_field = make_label_text_field() # the tree connector
508
+ self.disclosure_button = make_row_icon_button()
509
+ self.dot_text_field = make_label_text_field()
510
+ self.name_text_field = make_label_text_field()
511
+ self.details_text_field = make_label_text_field()
512
+ icon_image_view = NSImageView.alloc().initWithFrame_(NSMakeRect(0, 0, 10, ROW_HEIGHT))
513
+ icon_image_view.setImageScaling_(NSImageScaleNone)
514
+ self.column_views = {column_name: make_label_text_field() if parts_field_name else icon_image_view
515
+ for column_name, parts_field_name in TAB_ROW_COLUMNS}
516
+ self.column_widths = {column_name: 0 for column_name, _ in TAB_ROW_COLUMNS} # set by the list controller
517
+ self.room_for_the_previews_button = 0 # set by the list controller
518
+ self.preview_connector_text_field = make_multiline_label_text_field(PREVIEW_LINE_COUNT)
519
+ self.preview_text_field = make_multiline_label_text_field(PREVIEW_LINE_COUNT)
520
+ self.preview_toggle_button = make_row_icon_button()
521
+ self.new_window_button = make_row_icon_button() # the "+" row's only content
522
+ show_symbol_on_button(self.new_window_button, "plus", "+", "New window with an agent session")
523
+ for subview in (self.prefix_text_field, self.disclosure_button, self.dot_text_field, self.name_text_field,
524
+ self.details_text_field, *self.column_views.values(), self.preview_connector_text_field,
525
+ self.preview_text_field, self.preview_toggle_button, self.new_window_button):
526
+ self.addSubview_(subview)
527
+ self.setTextField_(self.name_text_field)
528
+ self.has_preview_line = False # a tab row whose preview is open
529
+ self.shows_columns = False # tab and process rows
530
+ self.name_runs_over_empty_columns = False # process rows
531
+ self.details_are_right_aligned = False # window rows
532
+ self.shows_disclosure_button = False # a row that can open or close
533
+ self.shows_preview_toggle_button = False # an expanded window row with a preview to show
534
+ self.tree_line_x = None # set on the "+" row: its button is centered on the tree's vertical line
535
+ self.look = None # what the row shows, set by the list controller's fill_row_view
536
+ return self
537
+
538
+ def layout(self):
539
+ objc.super(AgentListRowView, self).layout()
540
+ bounds = self.bounds()
541
+ preview_area_height = PREVIEW_AREA_HEIGHT if self.has_preview_line else 0 # at the bottom (y grows upward)
542
+ main_line_height = bounds.size.height - preview_area_height
543
+ text_height = self.name_text_field.fittingSize().height
544
+ y = preview_area_height + (main_line_height - text_height) / 2
545
+ prefix_width = self.prefix_text_field.fittingSize().width
546
+ self.prefix_text_field.setFrame_(NSMakeRect(ROW_LEFT_MARGIN, y, prefix_width, text_height))
547
+ arrow_x = ROW_LEFT_MARGIN + prefix_width
548
+ self.disclosure_button.setHidden_(not self.shows_disclosure_button)
549
+ self.disclosure_button.setFrame_(NSMakeRect(arrow_x, preview_area_height, DISCLOSURE_ARROW_SLOT_WIDTH, main_line_height))
550
+ dot_x = arrow_x + DISCLOSURE_ARROW_SLOT_WIDTH
551
+ dot_width = self.dot_text_field.fittingSize().width
552
+ self.dot_text_field.setFrame_(NSMakeRect(dot_x, y, dot_width, text_height))
553
+ name_x = dot_x + dot_width + GAP_AFTER_PREFIX
554
+ text_right_limit = bounds.size.width - ROW_RIGHT_MARGIN # where the name and details end; a window's details are right-aligned there
555
+ self.new_window_button.setHidden_(self.tree_line_x is None)
556
+ if self.tree_line_x is not None:
557
+ self.new_window_button.setFrame_(NSMakeRect(self.tree_line_x - PREVIEW_BUTTON_SIZE / 2,
558
+ (bounds.size.height - PREVIEW_BUTTON_SIZE) / 2,
559
+ PREVIEW_BUTTON_SIZE, PREVIEW_BUTTON_SIZE))
560
+ self.preview_toggle_button.setHidden_(not self.shows_preview_toggle_button)
561
+ if self.shows_preview_toggle_button: # at the right edge
562
+ button_x = bounds.size.width - ROW_RIGHT_MARGIN - PREVIEW_BUTTON_SIZE
563
+ self.preview_toggle_button.setFrame_(NSMakeRect(
564
+ button_x, preview_area_height + (main_line_height - PREVIEW_BUTTON_SIZE) / 2, PREVIEW_BUTTON_SIZE, PREVIEW_BUTTON_SIZE))
565
+ text_right_limit = button_x - GAP_BEFORE_DETAILS
566
+ placed_columns = (place_columns_from_the_right(bounds.size.width - ROW_RIGHT_MARGIN - self.room_for_the_previews_button,
567
+ self.column_widths) if self.shows_columns else {})
568
+ for column_name, parts_field_name in TAB_ROW_COLUMNS:
569
+ column_view = self.column_views[column_name]
570
+ column_view.setHidden_(column_name not in placed_columns)
571
+ if column_name not in placed_columns:
572
+ continue
573
+ column_x, column_width = placed_columns[column_name]
574
+ if parts_field_name is None: # the icon, centered in the row's main line
575
+ column_view.setFrame_(NSMakeRect(column_x, preview_area_height, column_width, main_line_height))
576
+ else:
577
+ column_view.setFrame_(NSMakeRect(column_x, y, column_width, text_height))
578
+ # A process row's command runs on over the columns it leaves empty (Tokens, Status), up to its first one with text.
579
+ columns_that_end_the_text = {column_name: placed_column for column_name, placed_column in placed_columns.items()
580
+ if not self.name_runs_over_empty_columns or self.column_views[column_name].stringValue()}
581
+ if columns_that_end_the_text:
582
+ text_right_limit = min(column_x for column_x, _ in columns_that_end_the_text.values()) - GAP_BEFORE_DETAILS
583
+ available_width = max(text_right_limit - name_x, 0)
584
+ name_fitting_width = self.name_text_field.fittingSize().width + NAME_FIELD_PADDING
585
+ details_fitting_width = self.details_text_field.fittingSize().width
586
+ if self.name_text_field.isEditable():
587
+ name_width = available_width * 0.6
588
+ elif name_fitting_width + GAP_BEFORE_DETAILS + details_fitting_width <= available_width:
589
+ name_width = name_fitting_width # everything fits: never truncate the name
590
+ else:
591
+ name_width = min(name_fitting_width, max(available_width - GAP_BEFORE_DETAILS - details_fitting_width,
592
+ available_width * 0.6))
593
+ self.name_text_field.setFrame_(NSMakeRect(name_x, y, name_width, text_height))
594
+ details_x = name_x + name_width + GAP_BEFORE_DETAILS
595
+ details_width = max(text_right_limit - details_x, 0)
596
+ if not self.details_are_right_aligned: # only as wide as its text, so the lights' hover text shows only over them
597
+ details_width = min(details_fitting_width, details_width)
598
+ self.details_text_field.setFrame_(NSMakeRect(details_x, y, details_width, text_height))
599
+ self.preview_connector_text_field.setHidden_(not self.has_preview_line)
600
+ self.preview_text_field.setHidden_(not self.has_preview_line)
601
+ if self.has_preview_line: # under the columns too, up to the right margin; a label's text starts at its top
602
+ self.preview_connector_text_field.setFrame_(NSMakeRect(
603
+ ROW_LEFT_MARGIN, 0, self.preview_connector_text_field.fittingSize().width, preview_area_height))
604
+ self.preview_text_field.setFrame_(NSMakeRect(
605
+ name_x, 0, max(bounds.size.width - ROW_RIGHT_MARGIN - name_x, 0), preview_area_height))
606
+
607
+
608
+ class AgentSessionListController(NSObject):
609
+ """Data source, delegate and actions for one outline view.
610
+
611
+ The owner (set with initWithOwner_) is a plain Python object with these methods:
612
+ submit_action(action_request): forwards an ActionRequest to the core.
613
+ tab_was_focused(list_controller): a tab row was clicked (the dropdown closes itself).
614
+ rows_changed(list_controller): the shown rows changed outside a snapshot delivery, for
615
+ example when the user expanded or collapsed a row (the container fits its size).
616
+ list_agent_tool_names(): the agent tools that can be started, from the settings.
617
+ start_agent_session_from_menu(window_id, folder, agent_tool_name): start an agent
618
+ session in a new tab of that window, or, with window_id None, in a new window (the
619
+ owner chooses the folder).
620
+ confirm_closing_window(window_entry): asks the user whether to close that window;
621
+ returns True for yes.
622
+ ask_for_confirmation(explanation, action_name): asks "Are you sure?" before the action
623
+ ("clear" or "kill"), unless a remembered Yes lets it run; returns True for yes.
624
+ submit_action_and_report_failure(action_request, failure_title): like submit_action,
625
+ and tells the user if the action failed.
626
+ duplicate_agent_session(tab_id, folder, agent_tool_name): opens a copy of the tab's agent
627
+ session right after it.
628
+ find_launch_command(agent_tool_name): the tool's launch command from the settings, or "".
629
+ start_peek(session_id), end_peek(): a tab row is held (shown for a moment), then released.
630
+ list_sort_order_chosen(list_sort_order, list_sort_order_is_reversed): a column's title
631
+ was clicked; the owner shows the order in every list (set_list_sort_order).
632
+ ask_for_note_asking_agent_sessions_to_talk_to_each_other(agent_session_entries,
633
+ left_out_agent_session_entries): shows the Talk to Each Other window; returns (the
634
+ note the user may have edited, the entries chosen to get it), or None for Cancel.
635
+ """
636
+
637
+ def initWithOwner_(self, owner):
638
+ self = objc.super(AgentSessionListController, self).init()
639
+ if self is None:
640
+ return None
641
+ self.owner = owner
642
+ self.submit_action = owner.submit_action
643
+ self.on_tab_focused = lambda: owner.tab_was_focused(self)
644
+ self.on_row_count_changed = lambda: owner.rows_changed(self)
645
+ # Called after every snapshot and expansion change; the panel sets it so its top bar's
646
+ # buttons (expand or collapse all, pause or resume all) follow along.
647
+ self.on_snapshot_or_expansion_changed = lambda: None
648
+ # Called when the row of column titles needs another height; the panel sets it so the list moves under it.
649
+ self.on_column_titles_row_height_changed = lambda: None
650
+ self.items_by_key = {}
651
+ self.top_level_items = []
652
+ self.new_window_row_item = OutlineListItem.alloc().initWithKind_itemId_("new_window", "new_window")
653
+ self.collapsed_item_keys = set()
654
+ # Tab rows whose preview is open: one more level that opens and closes, closed at first (user request, 2026-10-19).
655
+ self.open_preview_item_keys = set()
656
+ self.row_structure = []
657
+ self.snapshot = None
658
+ self.held_snapshot = None
659
+ self.rename_in_progress = False
660
+ self.drag_in_progress = False
661
+ self.row_press_in_progress = False # the button is down on a row (row_pressed until row_released)
662
+ self.menu_is_open = False
663
+ self.blink_phase_is_dim = False
664
+ self.peek_timer = None
665
+ self.peek_in_progress = False
666
+ self.item_under_first_click = None # the row a single click hit, for a double-click's second click
667
+ self.item_under_press = None # the row the button last went down on: a drag moves only that row
668
+ self.menu_target_item = None
669
+ self.menu_target_agent_session_entries = [] # the agent sessions of the selected rows, for their menu
670
+ self.applying_expansion_state = False
671
+ self.item_whose_expansion_is_changing = None
672
+ self.item_being_renamed = None
673
+ self.title_before_rename = ""
674
+ self.regular_font = NSFont.monospacedSystemFontOfSize_weight_(FONT_SIZE, NSFontWeightRegular)
675
+ self.bold_font = NSFont.monospacedSystemFontOfSize_weight_(FONT_SIZE, NSFontWeightBold)
676
+ # The status text, easier to read and still lighter than the front tab's bold name (user
677
+ # request, 2026-10-28). Every weight of the font is as wide, so columns are measured in the regular one.
678
+ self.semibold_font = NSFont.monospacedSystemFontOfSize_weight_(FONT_SIZE, NSFontWeightSemibold)
679
+ self.preview_font = NSFont.monospacedSystemFontOfSize_weight_(PREVIEW_FONT_SIZE, NSFontWeightRegular)
680
+ self.column_title_font = NSFont.monospacedSystemFontOfSize_weight_(COLUMN_TITLE_FONT_SIZE, NSFontWeightMedium)
681
+ # The longer line of each column's title with a sort arrow after it: a shown column is at
682
+ # least this wide, so sorting by another column doesn't change the columns' widths.
683
+ self.column_title_widths = {column_name: max(self.measure_text_width(line, self.column_title_font)
684
+ for sort_arrow in SORT_ARROWS_BY_IS_ASCENDING.values()
685
+ for line in (COLUMN_TITLES[column_name] + sort_arrow).split("\n"))
686
+ for column_name, _ in TAB_ROW_COLUMNS}
687
+ self.right_aligned_paragraph_style = NSMutableParagraphStyle.alloc().init()
688
+ self.right_aligned_paragraph_style.setAlignment_(NSTextAlignmentRight)
689
+ self.right_aligned_paragraph_style.setLineBreakMode_(NSLineBreakByTruncatingTail)
690
+ # Styled text overrides the field's own line breaking, so a name too long for its room (a
691
+ # process row's command) ends in "…" rather than at the last space that fits, and the
692
+ # preview's wrapping is set in its text too.
693
+ self.truncating_paragraph_style = NSMutableParagraphStyle.alloc().init()
694
+ self.truncating_paragraph_style.setLineBreakMode_(NSLineBreakByTruncatingTail)
695
+ self.wrapping_paragraph_style = NSMutableParagraphStyle.alloc().init()
696
+ self.wrapping_paragraph_style.setLineBreakMode_(NSLineBreakByWordWrapping)
697
+ self.preview_connector_paragraph_style = NSMutableParagraphStyle.alloc().init() # one tree line per preview line
698
+ self.preview_connector_paragraph_style.setMinimumLineHeight_(PREVIEW_LINE_HEIGHT)
699
+ self.preview_connector_paragraph_style.setMaximumLineHeight_(PREVIEW_LINE_HEIGHT)
700
+ self.agent_tool_icons_by_name = build_agent_tool_icons()
701
+ # Each TAB_ROW_COLUMNS column's width, 0 while it is hidden or no row has text for it (measure_right_columns).
702
+ self.column_widths = {column_name: 0 for column_name, _ in TAB_ROW_COLUMNS}
703
+ # In the sidebar and the list window, the room each column keeps for its texts (choose_room_for_a_columns_texts).
704
+ self.room_for_texts_by_column_name = {}
705
+ self.character_width = self.measure_text_width("0", self.regular_font)
706
+ # The room the window rows' previews button takes at the right edge, in a column of its
707
+ # own, while a tab has a preview (measure_right_columns; user request, 2026-10-26).
708
+ self.room_for_the_previews_button = 0
709
+ self.width_is_set_by_the_user = False # True for the sidebar's and the list window's lists; the dropdown fits its width to the rows
710
+ self.list_sort_order = "manual" # set by the Sort pop-up or a column title's click (list_sorting.py)
711
+ self.list_sort_order_is_reversed = False
712
+ self.idle_tabs_are_hidden = False # set by the Hide Idle / Show Idle button
713
+ self.shown_columns = list(DEFAULT_SETTINGS["shown_columns"]) # set from the settings (settings_store.LIST_COLUMNS)
714
+ self.outline_view = self.build_outline_view()
715
+ self.column_titles_row_view = self.build_column_titles_row_view()
716
+ self.fill_column_titles()
717
+ self.refresh_timer = NSTimer.scheduledTimerWithTimeInterval_target_selector_userInfo_repeats_(
718
+ 0.6, self, "refreshTimerFired:", None, True)
719
+ return self
720
+
721
+ # ----- building the view -----
722
+
723
+ @objc.python_method
724
+ def build_outline_view(self):
725
+ outline_view = OutlineViewWithoutDisclosureTriangles.alloc().initWithFrame_(NSMakeRect(0, 0, 400, 300))
726
+ column = NSTableColumn.alloc().initWithIdentifier_(COLUMN_IDENTIFIER)
727
+ column.setResizingMask_(NSTableColumnAutoresizingMask)
728
+ outline_view.addTableColumn_(column)
729
+ outline_view.setOutlineTableColumn_(column)
730
+ outline_view.setHeaderView_(None)
731
+ outline_view.setIndentationPerLevel_(0)
732
+ outline_view.setRowHeight_(ROW_HEIGHT)
733
+ # The plain style has no inset margins or extra row spacing, so the rows take exactly
734
+ # their measured size and the dropdown can be fitted to them.
735
+ outline_view.setStyle_(NSTableViewStylePlain)
736
+ outline_view.setIntercellSpacing_((0, 0))
737
+ outline_view.setBackgroundColor_(build_color_from_name("list_background")) # very light gray in light mode (user request, 2026-10-28)
738
+ # A click selects a window or tab row, Command-click adds or removes one, Shift-click a
739
+ # range (user request, 2026-10-21); RowViewWithSelectionOutline draws the selection.
740
+ outline_view.setAllowsMultipleSelection_(True)
741
+ outline_view.setSelectionHighlightStyle_(NSTableViewSelectionHighlightStyleRegular)
742
+ # The one column follows the outline view's width; its container calls sizeLastColumnToFit once it is embedded.
743
+ outline_view.setColumnAutoresizingStyle_(NSTableViewLastColumnOnlyAutoresizingStyle)
744
+ outline_view.setDataSource_(self)
745
+ outline_view.setDelegate_(self)
746
+ outline_view.setTarget_(self)
747
+ outline_view.setAction_("rowClicked:")
748
+ outline_view.setDoubleAction_("rowDoubleClicked:")
749
+ outline_view.registerForDraggedTypes_([TAB_DRAG_TYPE, WINDOW_DRAG_TYPE])
750
+ outline_view.setDraggingSourceOperationMask_forLocal_(NSDragOperationMove, True)
751
+ menu = NSMenu.alloc().initWithTitle_("")
752
+ menu.setDelegate_(self)
753
+ outline_view.setMenu_(menu)
754
+ return outline_view
755
+
756
+ @objc.python_method
757
+ def build_column_titles_row_view(self):
758
+ """Returns the row of column titles, whose clicks sort the list (column_title_clicked)."""
759
+ row_view = ColumnTitlesRowView.alloc().initWithOutlineView_(self.outline_view)
760
+ row_view.on_title_clicked = self.column_title_clicked
761
+ return row_view
762
+
763
+ @objc.python_method
764
+ def fill_column_titles(self):
765
+ """Puts the titles in the row of column titles, those of the columns the list is sorted by
766
+ ending in an arrow (SORT_ARROWS_BY_IS_ASCENDING); update_column_titles_row sets the widths."""
767
+ row_view = self.column_titles_row_view
768
+ names_titles_alignments_and_text_fields = [("name", NAME_COLUMN_TITLE, NSTextAlignmentCenter, row_view.name_title_text_field)] + [
769
+ (column_name, COLUMN_TITLES[column_name],
770
+ NSTextAlignmentLeft if column_name in LEFT_ALIGNED_COLUMN_NAMES else NSTextAlignmentRight,
771
+ row_view.column_title_text_fields[column_name]) for column_name, _ in TAB_ROW_COLUMNS]
772
+ for title_name, title, alignment, text_field in names_titles_alignments_and_text_fields:
773
+ if self.list_sort_order != "manual" and LIST_SORT_ORDER_BY_TITLE_NAME.get(title_name) == self.list_sort_order:
774
+ title += SORT_ARROWS_BY_IS_ASCENDING[
775
+ (title_name in TITLE_NAMES_WHOSE_ORDER_STARTS_ASCENDING) != self.list_sort_order_is_reversed]
776
+ paragraph_style = NSMutableParagraphStyle.alloc().init()
777
+ paragraph_style.setAlignment_(alignment)
778
+ paragraph_style.setMinimumLineHeight_(COLUMN_TITLE_LINE_HEIGHT)
779
+ paragraph_style.setMaximumLineHeight_(COLUMN_TITLE_LINE_HEIGHT)
780
+ text_field.setAttributedStringValue_(NSAttributedString.alloc().initWithString_attributes_(title, {
781
+ NSFontAttributeName: self.column_title_font, NSForegroundColorAttributeName: NSColor.secondaryLabelColor(),
782
+ NSParagraphStyleAttributeName: paragraph_style}))
783
+
784
+ # ----- applying snapshots -----
785
+
786
+ @objc.python_method
787
+ def apply_snapshot(self, snapshot):
788
+ """Shows a new snapshot (held while a rename or drag is in progress, or the button is down
789
+ on a row: a sorted list could reorder its rows under the held button)."""
790
+ if self.rename_in_progress or self.drag_in_progress or self.row_press_in_progress:
791
+ self.held_snapshot = snapshot
792
+ return
793
+ self.snapshot = snapshot
794
+ self.measure_right_columns()
795
+ show_monitor_rows = snapshot_shows_monitor_rows(snapshot)
796
+ new_top_level_items = []
797
+ live_keys = set()
798
+ for monitor_entry in snapshot.monitors:
799
+ window_items = [self.update_window_item(window_entry, live_keys)
800
+ for window_entry in sort_window_entries(
801
+ monitor_entry.windows, self.list_sort_order,
802
+ list_ranked_agent_sessions=lambda window_entry: [
803
+ entry for entry in window_entry.agent_sessions
804
+ if not tab_row_is_hidden(entry, self.idle_tabs_are_hidden)],
805
+ is_reversed=self.list_sort_order_is_reversed)
806
+ if not window_row_is_hidden(window_entry, self.idle_tabs_are_hidden)]
807
+ if show_monitor_rows:
808
+ monitor_item = self.find_or_make_item("monitor", monitor_entry.monitor_id, monitor_entry, live_keys)
809
+ self.set_child_items(monitor_item, window_items)
810
+ new_top_level_items.append(monitor_item)
811
+ else:
812
+ for window_item in window_items:
813
+ window_item.parent_item = None
814
+ new_top_level_items.extend(window_items)
815
+ for key in set(self.items_by_key) - live_keys:
816
+ removed_item = self.items_by_key.pop(key)
817
+ removed_item.parent_item = None # break the parent-child cycle so the item can be freed
818
+ removed_item.child_items = []
819
+ keys_with_saved_row_state = live_keys | list_window_and_tab_item_keys(snapshot)
820
+ self.collapsed_item_keys &= keys_with_saved_row_state
821
+ self.open_preview_item_keys &= keys_with_saved_row_state
822
+ self.top_level_items = new_top_level_items
823
+ new_row_structure = self.list_row_structure()
824
+ if new_row_structure == self.row_structure:
825
+ self.redraw_visible_rows()
826
+ else:
827
+ self.row_structure = new_row_structure
828
+ self.reload_and_restore_expansion()
829
+ self.on_snapshot_or_expansion_changed() # a closed window may be gone
830
+
831
+ @objc.python_method
832
+ def update_window_item(self, window_entry, live_keys):
833
+ window_item = self.find_or_make_item("window", window_entry.window_id, window_entry, live_keys)
834
+ tab_items = [self.find_or_make_item("tab", agent_session_entry.tab_id, agent_session_entry, live_keys)
835
+ for agent_session_entry in sort_agent_session_entries(
836
+ window_entry.agent_sessions, self.list_sort_order, self.list_sort_order_is_reversed)
837
+ if not tab_row_is_hidden(agent_session_entry, self.idle_tabs_are_hidden)]
838
+ self.set_child_items(window_item, tab_items)
839
+ for tab_item in tab_items:
840
+ # The process rows exist only while the tab row is open, so a closed tab's commands
841
+ # starting and ending don't change the rows (which reloads them).
842
+ self.set_child_items(tab_item, [
843
+ self.find_or_make_item("process", f"{tab_item.item_id}:{child_process.process_id}", child_process, live_keys)
844
+ for child_process in tab_item.entry.child_processes] if self.tab_row_is_open(tab_item) else [])
845
+ return window_item
846
+
847
+ @objc.python_method
848
+ def set_list_sort_order(self, list_sort_order, is_reversed):
849
+ """Shows the rows in this order from now on (one of list_sorting.LIST_SORT_ORDERS), in its
850
+ other direction when is_reversed, with an arrow after the titles of the columns it sorts by."""
851
+ if (list_sort_order, is_reversed) == (self.list_sort_order, self.list_sort_order_is_reversed):
852
+ return
853
+ self.list_sort_order = list_sort_order
854
+ self.list_sort_order_is_reversed = is_reversed
855
+ self.fill_column_titles()
856
+ if self.held_snapshot is None and self.snapshot is not None:
857
+ self.apply_snapshot(self.snapshot) # (a held snapshot is sorted when it is applied)
858
+
859
+ @objc.python_method
860
+ def column_title_clicked(self, title_name):
861
+ """Sorts by the clicked title's column, a click at a time: in its first direction, then
862
+ the other, then back to the manual order (user requests, 2026-10-26)."""
863
+ list_sort_order = LIST_SORT_ORDER_BY_TITLE_NAME[title_name]
864
+ if list_sort_order != self.list_sort_order:
865
+ self.owner.list_sort_order_chosen(list_sort_order, False)
866
+ elif not self.list_sort_order_is_reversed:
867
+ self.owner.list_sort_order_chosen(list_sort_order, True)
868
+ else:
869
+ self.owner.list_sort_order_chosen("manual", False)
870
+
871
+ @objc.python_method
872
+ def set_idle_tabs_are_hidden(self, idle_tabs_are_hidden):
873
+ """Hides or shows the idle tabs' rows from now on (the Hide Idle / Show Idle button; user request, 2026-10-21)."""
874
+ if idle_tabs_are_hidden == self.idle_tabs_are_hidden:
875
+ return
876
+ self.idle_tabs_are_hidden = idle_tabs_are_hidden
877
+ if self.held_snapshot is None and self.snapshot is not None:
878
+ self.apply_snapshot(self.snapshot) # (a held snapshot is filtered when it is applied)
879
+ self.on_row_count_changed() # the dropdown fits its size to the rows again
880
+
881
+ @objc.python_method
882
+ def set_shown_columns(self, shown_columns):
883
+ """Shows these information columns on tab rows from now on (names from settings_store.LIST_COLUMNS)."""
884
+ if list(shown_columns) == self.shown_columns:
885
+ return
886
+ self.shown_columns = list(shown_columns)
887
+ self.measure_right_columns()
888
+ self.redraw_visible_rows() # each row's look includes the column widths
889
+ self.on_row_count_changed() # the dropdown fits its width again
890
+
891
+ @objc.python_method
892
+ def find_or_make_item(self, kind, item_id, entry, live_keys):
893
+ key = (kind, item_id)
894
+ item = self.items_by_key.get(key)
895
+ if item is None:
896
+ item = OutlineListItem.alloc().initWithKind_itemId_(kind, item_id)
897
+ self.items_by_key[key] = item
898
+ item.entry = entry
899
+ live_keys.add(key)
900
+ return item
901
+
902
+ @objc.python_method
903
+ def set_child_items(self, parent_item, child_items):
904
+ parent_item.child_items = child_items
905
+ for child_item in child_items:
906
+ child_item.parent_item = parent_item
907
+
908
+ @objc.python_method
909
+ def list_row_structure(self):
910
+ """Returns the (kind, ID) keys of all items in display order, with each parent's child
911
+ count and each row's height (measure_row_height)."""
912
+ structure = []
913
+
914
+ def visit(items):
915
+ for item in items:
916
+ structure.append((item.kind, item.item_id, len(item.child_items), self.measure_row_height(item)))
917
+ visit(item.child_items)
918
+ visit(self.top_level_items)
919
+ return structure
920
+
921
+ @objc.python_method
922
+ def reload_and_restore_expansion(self):
923
+ """Reloads the rows, then restores each item's expansion and the selection."""
924
+ selected_items = self.list_selected_items()
925
+ self.outline_view.reloadData()
926
+ self.apply_expansion_state(self.top_level_items)
927
+ surviving_rows = [self.outline_view.rowForItem_(item) for item in selected_items
928
+ if item.key in self.items_by_key]
929
+ visible_surviving_rows = [row for row in surviving_rows if row >= 0]
930
+ if visible_surviving_rows:
931
+ self.outline_view.selectRowIndexes_byExtendingSelection_(build_index_set(visible_surviving_rows), False)
932
+
933
+ @objc.python_method
934
+ def apply_expansion_state(self, items):
935
+ """Expands or collapses each item as recorded, parents before children.
936
+
937
+ reloadData keeps the expansion of item objects it already knows, and NSOutlineView
938
+ ignores expanding an item whose parent is collapsed, so both directions are set
939
+ explicitly, top-down.
940
+ """
941
+ was_applying = self.applying_expansion_state
942
+ self.applying_expansion_state = True
943
+ try:
944
+ for item in items:
945
+ if not item.child_items:
946
+ continue
947
+ if item.key in self.collapsed_item_keys:
948
+ self.outline_view.collapseItem_(item)
949
+ else:
950
+ self.outline_view.expandItem_(item)
951
+ self.apply_expansion_state(item.child_items)
952
+ finally:
953
+ self.applying_expansion_state = was_applying
954
+
955
+ # NSOutlineView reports every expansion change here, including its own Left and Right arrow
956
+ # handling, so the controller's record always matches what is on screen. Collapsing a monitor
957
+ # row also reports its windows collapsing; only the row that changed first (the one whose
958
+ # "will" notification came first) is recorded, so its windows keep their own state.
959
+
960
+ def outlineViewItemWillExpand_(self, notification):
961
+ self.note_expansion_change_starting(notification.userInfo()["NSObject"])
962
+
963
+ def outlineViewItemWillCollapse_(self, notification):
964
+ self.note_expansion_change_starting(notification.userInfo()["NSObject"])
965
+
966
+ def outlineViewItemDidExpand_(self, notification):
967
+ self.record_expansion_change(notification.userInfo()["NSObject"], True)
968
+
969
+ def outlineViewItemDidCollapse_(self, notification):
970
+ self.record_expansion_change(notification.userInfo()["NSObject"], False)
971
+
972
+ @objc.python_method
973
+ def note_expansion_change_starting(self, item):
974
+ if self.item_whose_expansion_is_changing is None:
975
+ self.item_whose_expansion_is_changing = item
976
+
977
+ @objc.python_method
978
+ def record_expansion_change(self, item, is_expanded):
979
+ if self.item_whose_expansion_is_changing is not None and item is not self.item_whose_expansion_is_changing:
980
+ return # a descendant reported along with the row that actually changed
981
+ self.item_whose_expansion_is_changing = None
982
+ if item.kind == "tab":
983
+ # A tab row's process rows follow whether it is open (open_preview_item_keys); one the
984
+ # outline view collapses itself (the Left arrow key) closes.
985
+ if not is_expanded and not self.applying_expansion_state:
986
+ self.set_previews_open([item], False)
987
+ return
988
+ key = item.key
989
+ if is_expanded:
990
+ self.collapsed_item_keys.discard(key)
991
+ else:
992
+ self.collapsed_item_keys.add(key)
993
+ if self.applying_expansion_state:
994
+ return
995
+ if is_expanded:
996
+ self.apply_expansion_state(item.child_items) # children come back as they were
997
+ self.redraw_visible_rows()
998
+ self.on_row_count_changed()
999
+ self.on_snapshot_or_expansion_changed()
1000
+
1001
+ @objc.python_method
1002
+ def list_is_on_screen(self):
1003
+ """False for the closed dropdown and the hidden sidebar: their rows are redrawn when they appear."""
1004
+ window = self.outline_view.window()
1005
+ return window is not None and window.isVisible()
1006
+
1007
+ @objc.python_method
1008
+ def redraw_visible_rows(self):
1009
+ """Refills the rows on screen; fill_row_view skips rows whose look didn't change."""
1010
+ if self.list_is_on_screen():
1011
+ self.fill_visible_rows()
1012
+
1013
+ @objc.python_method
1014
+ def fill_visible_rows(self):
1015
+ visible_rows = self.outline_view.rowsInRect_(self.outline_view.visibleRect())
1016
+ for row in range(visible_rows.location, visible_rows.location + visible_rows.length):
1017
+ row_view = self.outline_view.viewAtColumn_row_makeIfNecessary_(0, row, False)
1018
+ item = self.outline_view.itemAtRow_(row)
1019
+ if row_view is not None and item is not None:
1020
+ self.fill_row_view(row_view, item)
1021
+
1022
+ def refreshTimerFired_(self, timer):
1023
+ """Blinks working dots and keeps elapsed times current, redrawing visible rows only."""
1024
+ self.blink_phase_is_dim = not self.blink_phase_is_dim
1025
+ if self.snapshot is not None and not self.rename_in_progress and self.list_is_on_screen():
1026
+ self.measure_right_columns() # elapsed times grow
1027
+ self.redraw_visible_rows()
1028
+
1029
+ @objc.python_method
1030
+ def prepare_to_appear(self):
1031
+ """Brings the rows up to date just before the dropdown or the sidebar is shown."""
1032
+ self.measure_right_columns()
1033
+ self.fill_visible_rows()
1034
+
1035
+ # ----- data source -----
1036
+
1037
+ # The outline view's last row is the "+" row, which starts an agent session in a new window
1038
+ # (user request, 2026-10-19). It isn't one of top_level_items, so the list's ordering,
1039
+ # expansion and drag code never meet it.
1040
+
1041
+ def outlineView_numberOfChildrenOfItem_(self, outline_view, item):
1042
+ return len(self.top_level_items) + 1 if item is None else len(item.child_items)
1043
+
1044
+ def outlineView_child_ofItem_(self, outline_view, index, item):
1045
+ if item is None:
1046
+ return self.top_level_items[index] if index < len(self.top_level_items) else self.new_window_row_item
1047
+ return item.child_items[index]
1048
+
1049
+ def outlineView_isItemExpandable_(self, outline_view, item):
1050
+ return bool(item.child_items)
1051
+
1052
+ # ----- drawing rows -----
1053
+
1054
+ def outlineView_viewForTableColumn_item_(self, outline_view, table_column, item):
1055
+ row_view = outline_view.makeViewWithIdentifier_owner_(ROW_VIEW_IDENTIFIER, self)
1056
+ if row_view is None:
1057
+ row_view = AgentListRowView.alloc().initWithFrame_(NSMakeRect(0, 0, 400, ROW_HEIGHT))
1058
+ row_view.setIdentifier_(ROW_VIEW_IDENTIFIER)
1059
+ row_view.name_text_field.setDelegate_(self)
1060
+ row_view.preview_toggle_button.setTarget_(self)
1061
+ row_view.preview_toggle_button.setAction_("previewToggleButtonClicked:")
1062
+ row_view.disclosure_button.setTarget_(self)
1063
+ row_view.disclosure_button.setAction_("disclosureButtonClicked:")
1064
+ row_view.new_window_button.setTarget_(self)
1065
+ row_view.new_window_button.setAction_("newWindowButtonClicked:")
1066
+ self.fill_row_view(row_view, item)
1067
+ return row_view
1068
+
1069
+ def outlineView_heightOfRowByItem_(self, outline_view, item):
1070
+ return self.measure_row_height(item)
1071
+
1072
+ def outlineView_rowViewForItem_(self, outline_view, item):
1073
+ return RowViewWithSelectionOutline.alloc().initWithFrame_(NSZeroRect)
1074
+
1075
+ # ----- selection (user request, 2026-10-21) -----
1076
+
1077
+ def outlineView_selectionIndexesForProposedSelection_(self, outline_view, proposed_selection_indexes):
1078
+ """Keeps only window and tab rows of a proposed selection (a Shift-click range can span a monitor row)."""
1079
+ return build_index_set(row for row in range(outline_view.numberOfRows())
1080
+ if proposed_selection_indexes.containsIndex_(row)
1081
+ and outline_view.itemAtRow_(row).kind in SELECTABLE_ROW_KINDS)
1082
+
1083
+ @objc.python_method
1084
+ def list_selected_items(self):
1085
+ """Returns the items of the selected rows, top to bottom."""
1086
+ selected_rows = self.outline_view.selectedRowIndexes()
1087
+ return [self.outline_view.itemAtRow_(row) for row in range(self.outline_view.numberOfRows())
1088
+ if selected_rows.containsIndex_(row)]
1089
+
1090
+ @objc.python_method
1091
+ def list_agent_session_entries_of_the_selected_rows(self):
1092
+ """Returns the agent sessions of the selected tab rows and of every tab of the selected
1093
+ window rows (also collapsed ones, and tabs whose rows Hide Idle hides), once each, in list order."""
1094
+ entry_by_session_id = {}
1095
+ for item in self.list_selected_items():
1096
+ agent_session_entries = (sort_agent_session_entries(item.entry.agent_sessions, self.list_sort_order,
1097
+ self.list_sort_order_is_reversed)
1098
+ if item.kind == "window" else [item.entry])
1099
+ for entry in agent_session_entries:
1100
+ entry_by_session_id.setdefault(entry.session_id, entry)
1101
+ return list(entry_by_session_id.values())
1102
+
1103
+ @objc.python_method
1104
+ def row_can_open(self, item):
1105
+ """Whether the row has an arrow: a monitor or window row (it has rows below it), or a tab
1106
+ row with a preview or processes its agent started."""
1107
+ if item.kind == "tab":
1108
+ return bool(item.entry.preview_line or item.entry.child_processes)
1109
+ return item.kind != "process" and bool(item.child_items)
1110
+
1111
+ @objc.python_method
1112
+ def row_is_open(self, item):
1113
+ """Whether the row's arrow points down: an expanded monitor or window row, or an open tab row."""
1114
+ return self.tab_row_is_open(item) if item.kind == "tab" else item.key not in self.collapsed_item_keys
1115
+
1116
+ @objc.python_method
1117
+ def tab_row_is_open(self, item):
1118
+ """Whether a tab row shows its preview and its process rows: it was opened, and has one of them to show."""
1119
+ return item.kind == "tab" and item.key in self.open_preview_item_keys and self.row_can_open(item)
1120
+
1121
+ @objc.python_method
1122
+ def toggle_row(self, item):
1123
+ """Opens or closes just this row: a monitor's or window's rows below it, or a tab's preview and process rows."""
1124
+ if item.kind == "tab":
1125
+ self.set_previews_open([item], not self.tab_row_is_open(item))
1126
+ else:
1127
+ self.toggle_expansion(item)
1128
+
1129
+ @objc.python_method
1130
+ def open_or_close_selected_tab_rows_for_arrow_key(self, characters):
1131
+ """The Right arrow key opens the selected tab rows and the Left arrow key closes them, as
1132
+ their arrow buttons do, when every selected row is a tab row that can open and one of
1133
+ them would change: a closed tab row has no process rows below it, so the outline view's
1134
+ own handling finds nothing to open (code review, 2026-10-28). Returns whether it did;
1135
+ otherwise the outline view handles the key (a window row's rows, say).
1136
+
1137
+ Args:
1138
+ characters: The key event's charactersIgnoringModifiers.
1139
+ """
1140
+ is_open = {NSRightArrowFunctionKey: True, NSLeftArrowFunctionKey: False}.get(characters)
1141
+ selected_items = self.list_selected_items()
1142
+ if (is_open is None or not selected_items
1143
+ or not all(item.kind == "tab" and self.row_can_open(item) for item in selected_items)
1144
+ or all(self.tab_row_is_open(item) == is_open for item in selected_items)):
1145
+ return False
1146
+ self.set_previews_open(selected_items, is_open)
1147
+ return True
1148
+
1149
+ def disclosureButtonClicked_(self, sender):
1150
+ row = self.outline_view.rowForView_(sender)
1151
+ item = self.outline_view.itemAtRow_(row) if row >= 0 else None
1152
+ if item is not None and self.row_can_open(item):
1153
+ self.toggle_row(item)
1154
+
1155
+ @objc.python_method
1156
+ def preview_is_open(self, item):
1157
+ """Whether a tab row shows its preview: it is open, and there is one to show."""
1158
+ return self.tab_row_is_open(item) and bool(item.entry.preview_line)
1159
+
1160
+ @objc.python_method
1161
+ def measure_row_height(self, item):
1162
+ """A tab row whose preview is open is taller; list_row_structure notes each row's height,
1163
+ so a preview appearing or going away in a snapshot reloads the rows."""
1164
+ return TAB_ROW_HEIGHT_WITH_PREVIEW if self.preview_is_open(item) else ROW_HEIGHT
1165
+
1166
+ @objc.python_method
1167
+ def measure_fully_expanded_list_height(self):
1168
+ """Returns the height of the rows the list has with every row expanded (list_all_items),
1169
+ with the previews that are open (counting every preview would leave the dropdown mostly
1170
+ empty while they are closed) and the "+" row."""
1171
+ return sum(self.measure_row_height(item) for item in self.list_all_items()) + ROW_HEIGHT
1172
+
1173
+ @objc.python_method
1174
+ def build_is_last_child_at_each_level(self, item):
1175
+ levels = []
1176
+ while item.parent_item is not None:
1177
+ levels.append(item.parent_item.child_items[-1] is item)
1178
+ item = item.parent_item
1179
+ return list(reversed(levels))
1180
+
1181
+ @objc.python_method
1182
+ def build_row_text_parts(self, item):
1183
+ is_last_child_at_each_level = self.build_is_last_child_at_each_level(item)
1184
+ if item.kind == "tab":
1185
+ return build_agent_session_row_text_parts(item.entry, is_last_child_at_each_level, time.time())
1186
+ if item.kind == "process":
1187
+ return build_child_process_row_text_parts(item.entry, is_last_child_at_each_level, time.time())
1188
+ if item.kind == "window":
1189
+ return build_window_row_text_parts(item.entry, is_last_child_at_each_level, self.row_is_open(item))
1190
+ if item.kind == "new_window": # the "+" row draws only its button
1191
+ return RowTextParts("", "", "gray", False, "", "")
1192
+ return build_monitor_row_text_parts(item.entry)
1193
+
1194
+ @objc.python_method
1195
+ def fill_row_view(self, row_view, item):
1196
+ if row_view.name_text_field.isEditable():
1197
+ return # never overwrite text the user is typing
1198
+ parts = self.build_row_text_parts(item)
1199
+ is_in_front = item.kind == "tab" and item.entry.is_in_front
1200
+ tabs_that_open = self.list_tabs_that_open(item) if item.kind == "window" else []
1201
+ shows_preview_toggle_button = bool(tabs_that_open) and self.row_is_open(item)
1202
+ all_previews_are_open = all(self.tab_row_is_open(tab_item) for tab_item in tabs_that_open)
1203
+ shows_disclosure_button = self.row_can_open(item)
1204
+ # Everything the row's look depends on: an unchanged row is neither refilled nor laid out
1205
+ # again, which keeps the 0.6-second refresh cheap with many rows.
1206
+ look = (parts, item.kind, is_in_front, parts.dot_blinks and self.blink_phase_is_dim, self.preview_is_open(item),
1207
+ shows_disclosure_button, self.row_is_open(item), shows_preview_toggle_button, all_previews_are_open,
1208
+ tuple(self.column_widths.values()), self.room_for_the_previews_button, bool(item.child_items))
1209
+ if look == row_view.look:
1210
+ return
1211
+ row_view.look = look
1212
+ row_view.prefix_text_field.setAttributedStringValue_(NSAttributedString.alloc().initWithString_attributes_(
1213
+ parts.connector_text, {NSFontAttributeName: self.regular_font,
1214
+ NSForegroundColorAttributeName: NSColor.tertiaryLabelColor()}))
1215
+ row_view.shows_disclosure_button = shows_disclosure_button
1216
+ if shows_disclosure_button:
1217
+ show_symbol_on_button(row_view.disclosure_button, *DISCLOSURE_ARROW_LOOKS[self.row_is_open(item)],
1218
+ point_size=DISCLOSURE_ARROW_POINT_SIZE)
1219
+ dot_color = build_color_from_name(parts.dot_color_name)
1220
+ if parts.dot_blinks and self.blink_phase_is_dim:
1221
+ dot_color = dot_color.colorWithAlphaComponent_(0.25)
1222
+ row_view.dot_text_field.setAttributedStringValue_(NSAttributedString.alloc().initWithString_attributes_(
1223
+ build_dot_text(parts.dot_glyph), {NSFontAttributeName: self.regular_font, NSForegroundColorAttributeName: dot_color}))
1224
+ # Only the dot and the lights say what they mean; the row as a whole has no hover text (user requests, 2026-10-19 and 2026-10-27).
1225
+ row_view.dot_text_field.setToolTip_(parts.dot_tool_tip or None)
1226
+ row_view.details_text_field.setToolTip_(parts.details_tool_tip or None)
1227
+ # The tab in front is marked by its bold name only, in the same color as the others (blue
1228
+ # until 2026-10-26, user request). A process row's command is gray, as a preview is.
1229
+ row_view.name_text_field.setAttributedStringValue_(NSAttributedString.alloc().initWithString_attributes_(
1230
+ parts.name_text, {NSFontAttributeName: self.choose_name_font(item), NSForegroundColorAttributeName:
1231
+ NSColor.secondaryLabelColor() if item.kind == "process" else NSColor.labelColor(),
1232
+ NSParagraphStyleAttributeName: self.truncating_paragraph_style}))
1233
+ secondary_text_attributes = {NSFontAttributeName: self.regular_font,
1234
+ NSForegroundColorAttributeName: build_color_from_name(parts.details_color_name)}
1235
+ # Alignment goes in the text itself: styled text overrides a field's own alignment.
1236
+ right_aligned_secondary_text_attributes = dict(
1237
+ secondary_text_attributes, **{NSParagraphStyleAttributeName: self.right_aligned_paragraph_style})
1238
+ row_view.details_text_field.setAttributedStringValue_(NSAttributedString.alloc().initWithString_attributes_(
1239
+ parts.details_text,
1240
+ right_aligned_secondary_text_attributes if item.kind == "window" else secondary_text_attributes))
1241
+ row_view.details_are_right_aligned = item.kind == "window"
1242
+ # The columns' texts in the names' color rather than gray (user request, 2026-10-26).
1243
+ column_text_attributes = {NSFontAttributeName: self.regular_font, NSForegroundColorAttributeName: NSColor.labelColor()}
1244
+ right_aligned_column_text_attributes = dict(
1245
+ column_text_attributes, **{NSParagraphStyleAttributeName: self.right_aligned_paragraph_style})
1246
+ for column_name, parts_field_name in TAB_ROW_COLUMNS:
1247
+ column_view = row_view.column_views[column_name]
1248
+ if parts_field_name is None:
1249
+ column_view.setImage_(self.find_agent_tool_icon(parts.agent_tool_name) if parts.agent_tool_name else None)
1250
+ column_view.setToolTip_(describe_agent_tool_icon(parts.agent_tool_name) if parts.agent_tool_name else None)
1251
+ else:
1252
+ column_text = NSMutableAttributedString.alloc().initWithString_attributes_(
1253
+ getattr(parts, parts_field_name), column_text_attributes if column_name in LEFT_ALIGNED_COLUMN_NAMES
1254
+ else right_aligned_column_text_attributes)
1255
+ if parts_field_name == "context_text" and parts.context_fill_percent_color_name:
1256
+ # Only the share in parentheses is colored, amber from 50% and red from 75% (user request, 2026-10-27).
1257
+ share_start = parts.context_text.index("(")
1258
+ column_text.addAttribute_value_range_(NSForegroundColorAttributeName,
1259
+ build_color_from_name(parts.context_fill_percent_color_name),
1260
+ (share_start, len(parts.context_text) - share_start))
1261
+ if parts_field_name == "state_text" and parts.state_color_name: # user requests, 2026-10-28
1262
+ column_text.addAttributes_range_({
1263
+ NSForegroundColorAttributeName: build_color_from_name(parts.state_color_name),
1264
+ NSFontAttributeName: self.semibold_font if parts.state_text_is_semibold else self.regular_font},
1265
+ (0, len(parts.state_text)))
1266
+ column_view.setAttributedStringValue_(column_text)
1267
+ row_view.column_widths = dict(self.column_widths)
1268
+ row_view.room_for_the_previews_button = self.room_for_the_previews_button
1269
+ row_view.has_preview_line = self.preview_is_open(item)
1270
+ row_view.shows_columns = item.kind in ("tab", "process")
1271
+ row_view.name_runs_over_empty_columns = item.kind == "process"
1272
+ row_view.tree_line_x = self.measure_tree_line_x() if item.kind == "new_window" else None
1273
+ row_view.shows_preview_toggle_button = shows_preview_toggle_button
1274
+ if shows_preview_toggle_button: # it shows whether all are open; a click then closes them all
1275
+ show_symbol_on_button(row_view.preview_toggle_button, *PREVIEW_BUTTON_LOOKS[all_previews_are_open])
1276
+ # Beside the preview, the line down to the tab's process rows under it starts too.
1277
+ preview_connector_text = parts.preview_connector_text + ("│" if item.child_items else "")
1278
+ row_view.preview_connector_text_field.setAttributedStringValue_(NSAttributedString.alloc().initWithString_attributes_(
1279
+ "\n".join([preview_connector_text] * PREVIEW_LINE_COUNT),
1280
+ {NSFontAttributeName: self.regular_font, NSForegroundColorAttributeName: NSColor.tertiaryLabelColor(),
1281
+ NSParagraphStyleAttributeName: self.preview_connector_paragraph_style}))
1282
+ row_view.preview_text_field.setAttributedStringValue_(NSAttributedString.alloc().initWithString_attributes_(
1283
+ parts.preview_text, {NSFontAttributeName: self.preview_font, NSForegroundColorAttributeName: NSColor.secondaryLabelColor(),
1284
+ NSParagraphStyleAttributeName: self.wrapping_paragraph_style}))
1285
+ row_view.setNeedsLayout_(True)
1286
+
1287
+ @objc.python_method
1288
+ def find_agent_tool_icon(self, agent_tool_name):
1289
+ """Returns the tool's drawn icon, or its name as a small image for a tool without one."""
1290
+ if agent_tool_name not in self.agent_tool_icons_by_name:
1291
+ self.agent_tool_icons_by_name[agent_tool_name] = build_text_image(agent_tool_name, self.regular_font)
1292
+ return self.agent_tool_icons_by_name[agent_tool_name]
1293
+
1294
+ @objc.python_method
1295
+ def measure_tree_line_x(self):
1296
+ """Returns the x of the tree's vertical line, the middle of a top-level row's child's
1297
+ connector's first character, "├" (a label's text starts half its insets inside the field)."""
1298
+ return ROW_LEFT_MARGIN + TEXT_FIELD_INSETS / 2 + self.measure_text_width(
1299
+ build_tree_connector_text([False])[0], self.regular_font) / 2
1300
+
1301
+ @objc.python_method
1302
+ def measure_text_width(self, text, font):
1303
+ return NSAttributedString.alloc().initWithString_attributes_(text, {NSFontAttributeName: font}).size().width
1304
+
1305
+ @objc.python_method
1306
+ def measure_name_x(self, connector_text, dot_glyph):
1307
+ """Returns where a row's name starts, as AgentListRowView.layout places it: after the
1308
+ left margin, the tree connector's field, the arrow's room and the dot's field (each field
1309
+ its text and TEXT_FIELD_INSETS, which is up to a point more than AppKit adds, so this
1310
+ never falls short)."""
1311
+ return (ROW_LEFT_MARGIN + self.measure_text_width(connector_text, self.regular_font) + TEXT_FIELD_INSETS
1312
+ + DISCLOSURE_ARROW_SLOT_WIDTH + self.measure_text_width(build_dot_text(dot_glyph), self.regular_font)
1313
+ + TEXT_FIELD_INSETS + GAP_AFTER_PREFIX)
1314
+
1315
+ @objc.python_method
1316
+ def measure_right_columns(self):
1317
+ """Sets each TAB_ROW_COLUMNS column's width to fit its widest text and its title, or 0 when
1318
+ the settings hide it or no row has text for it (no context size known yet). In the dropdown, a shown
1319
+ column is at least as wide as LONGEST_TEXT_BY_COLUMN_FIELD_NAME's text, so the dropdown's
1320
+ width doesn't follow the numbers and states; the sidebar and the list window, whose width
1321
+ the user sets, leave that room to the names, but keep a little spare room in each column
1322
+ and shrink one only when its texts get clearly narrower (choose_room_for_a_columns_texts),
1323
+ so the columns don't move as numbers change by a digit. The icon column's width fits the widest tool
1324
+ icon, or is 0 when all agent sessions use the same tool. A narrow sidebar or window then
1325
+ drops columns in COLUMN_NAMES_IN_DROP_ORDER to keep room for names."""
1326
+ agent_session_entries = [entry for _, _, entry in iterate_agent_session_entries(self.snapshot)
1327
+ if not tab_row_is_hidden(entry, self.idle_tabs_are_hidden)] if self.snapshot else []
1328
+ now = time.time()
1329
+ # Process rows too, also those of closed tab rows, so opening one doesn't widen a column.
1330
+ all_parts = [build_agent_session_row_text_parts(entry, [], now) for entry in agent_session_entries] + [
1331
+ build_child_process_row_text_parts(child_process, [], now)
1332
+ for entry in agent_session_entries for child_process in entry.child_processes]
1333
+ self.room_for_the_previews_button = (PREVIEW_BUTTON_SIZE + GAP_BETWEEN_COLUMNS
1334
+ if any(entry.preview_line or entry.child_processes for entry in agent_session_entries)
1335
+ else 0)
1336
+ for column_name, parts_field_name in TAB_ROW_COLUMNS:
1337
+ if parts_field_name is None:
1338
+ agent_tool_names = {entry.agent_tool_name for entry in agent_session_entries}
1339
+ self.column_widths[column_name] = (max(self.find_agent_tool_icon(name).size().width for name in agent_tool_names)
1340
+ if len(agent_tool_names) >= 2 else 0)
1341
+ continue
1342
+ # Each distinct text is measured once; many sessions share "idle" or "2m".
1343
+ texts = {getattr(parts, parts_field_name) for parts in all_parts} if column_name in self.shown_columns else set()
1344
+ if any(texts) and not self.width_is_set_by_the_user: # the dropdown keeps its width as the texts change
1345
+ texts.add(LONGEST_TEXT_BY_COLUMN_FIELD_NAME[parts_field_name])
1346
+ widest_text_width = max((self.measure_text_width(text, self.regular_font) for text in texts if text), default=0)
1347
+ if self.width_is_set_by_the_user: # spare room, so small changes to the numbers don't move the columns
1348
+ widest_text_width = choose_room_for_a_columns_texts(
1349
+ widest_text_width, self.room_for_texts_by_column_name.get(column_name, 0), self.character_width)
1350
+ self.room_for_texts_by_column_name[column_name] = widest_text_width
1351
+ self.column_widths[column_name] = (TEXT_FIELD_INSETS + max(widest_text_width, self.column_title_widths[column_name])
1352
+ if widest_text_width else 0)
1353
+ if self.width_is_set_by_the_user:
1354
+ for column_name in COLUMN_NAMES_IN_DROP_ORDER:
1355
+ if self.measure_room_left_for_tab_names() < SMALLEST_TAB_NAME_WIDTH:
1356
+ self.column_widths[column_name] = 0
1357
+ self.update_column_titles_row()
1358
+
1359
+ @objc.python_method
1360
+ def update_column_titles_row(self):
1361
+ """Gives the row of column titles the columns' widths, and has the panel fit the list under
1362
+ it when it needs another height."""
1363
+ self.column_titles_row_view.column_widths = dict(self.column_widths)
1364
+ self.column_titles_row_view.room_for_the_previews_button = self.room_for_the_previews_button
1365
+ self.column_titles_row_view.setNeedsLayout_(True)
1366
+ if self.measure_column_titles_row_height() != self.column_titles_row_view.frame().size.height:
1367
+ self.on_column_titles_row_height_changed()
1368
+
1369
+ @objc.python_method
1370
+ def measure_column_titles_row_height(self):
1371
+ """Returns the height of the row of column titles: room for the shown columns' titles, or 0
1372
+ while none shows (no tab rows, or every titled column turned off or dropped)."""
1373
+ line_counts = [COLUMN_TITLES[column_name].count("\n") + 1 for column_name, width in self.column_widths.items()
1374
+ if width and COLUMN_TITLES[column_name]]
1375
+ return max(line_counts) * COLUMN_TITLE_LINE_HEIGHT + 2 * COLUMN_TITLES_ROW_PADDING if line_counts else 0
1376
+
1377
+ @objc.python_method
1378
+ def measure_room_left_for_tab_names(self):
1379
+ """Returns the width left for a tab row's name and details beside the right-hand columns."""
1380
+ # A tab under a window, under a monitor row while there are several monitors.
1381
+ tab_levels_below_the_top = 2 if self.snapshot is not None and snapshot_shows_monitor_rows(self.snapshot) else 1
1382
+ deepest_tab_connector = build_tree_connector_text([False] * tab_levels_below_the_top)
1383
+ return (self.outline_view.bounds().size.width - self.measure_name_x(deepest_tab_connector, "●") - GAP_BEFORE_DETAILS
1384
+ - self.measure_right_columns_width() - ROW_RIGHT_MARGIN)
1385
+
1386
+ @objc.python_method
1387
+ def measure_right_columns_width(self):
1388
+ """Returns the width of a tab row's right-hand columns with the gaps between them (0-width
1389
+ columns are hidden), and the previews button's column after them."""
1390
+ shown_column_widths = [width for width in self.column_widths.values() if width]
1391
+ return (sum(shown_column_widths) + GAP_BETWEEN_COLUMNS * max(len(shown_column_widths) - 1, 0)
1392
+ + self.room_for_the_previews_button)
1393
+
1394
+ @objc.python_method
1395
+ def choose_name_font(self, item):
1396
+ """Window and monitor names, and the tab in front, are bold."""
1397
+ is_in_front = item.kind == "tab" and item.entry.is_in_front
1398
+ return self.bold_font if (is_in_front or item.kind in ("monitor", "window")) else self.regular_font
1399
+
1400
+ @objc.python_method
1401
+ def list_all_items(self):
1402
+ """Returns every item, also those inside collapsed rows: the rows the list has when fully expanded."""
1403
+ all_items = []
1404
+
1405
+ def visit(items):
1406
+ for item in items:
1407
+ all_items.append(item)
1408
+ visit(item.child_items)
1409
+ visit(self.top_level_items)
1410
+ return all_items
1411
+
1412
+ @objc.python_method
1413
+ def measure_widest_row_width(self):
1414
+ """Returns the width, in points, that the widest row needs to show all its text, counting
1415
+ the rows inside collapsed windows and a window's counts as if it were collapsed, so the
1416
+ dropdown keeps one size while rows are expanded and collapsed (user request, milestone 2)."""
1417
+ measure_text_width = self.measure_text_width
1418
+ # The state dots' glyphs come from fonts other than the monospaced one and differ by a
1419
+ # fraction of a point, so each row is measured with the widest, and a state change doesn't
1420
+ # change the dropdown's width.
1421
+ widest_dot_glyph = max((dot_glyph for dot_glyph, _ in DOT_GLYPH_AND_COLOR_BY_STATE.values()),
1422
+ key=lambda dot_glyph: measure_text_width(dot_glyph, self.regular_font))
1423
+ widest_row_width = 0
1424
+ preview_buttons_width = GAP_BEFORE_DETAILS + PREVIEW_BUTTON_SIZE
1425
+ for item in self.list_all_items():
1426
+ if item.kind == "process":
1427
+ continue # a command, often long, is cut short to the room the other rows leave it
1428
+ if item.kind == "window": # expanded, it ends in the preview button
1429
+ last_child_flags = self.build_is_last_child_at_each_level(item)
1430
+ parts_and_button_widths = [(build_window_row_text_parts(item.entry, last_child_flags, is_expanded),
1431
+ preview_buttons_width if is_expanded else 0) for is_expanded in (True, False)]
1432
+ else:
1433
+ parts_and_button_widths = [(self.build_row_text_parts(item), 0)]
1434
+ for parts, button_width in parts_and_button_widths:
1435
+ row_width = (self.measure_name_x(parts.connector_text, widest_dot_glyph if parts.dot_glyph else "")
1436
+ + measure_text_width(parts.name_text, self.choose_name_font(item)) + NAME_FIELD_PADDING
1437
+ + GAP_BEFORE_DETAILS + measure_text_width(parts.details_text + ROOM_FOR_GROWING_DETAILS, self.regular_font)
1438
+ + 2 * TEXT_FIELD_INSETS + ROW_RIGHT_MARGIN + button_width)
1439
+ if parts.state_text: # the columns at the right edge
1440
+ row_width += GAP_BEFORE_DETAILS + self.measure_right_columns_width()
1441
+ widest_row_width = max(widest_row_width, row_width)
1442
+ return widest_row_width
1443
+
1444
+ # ----- clicks -----
1445
+
1446
+ @objc.python_method
1447
+ def find_clicked_item(self):
1448
+ clicked_row = self.outline_view.clickedRow()
1449
+ return self.outline_view.itemAtRow_(clicked_row) if clicked_row >= 0 else None
1450
+
1451
+ def rowClicked_(self, sender):
1452
+ current_event = NSApp.currentEvent()
1453
+ if current_event is not None and current_event.clickCount() > 1:
1454
+ return # the second click of a double-click: rowDoubleClicked_ handles it
1455
+ # A single click only selects the row, which the outline view does itself (user request,
1456
+ # 2026-10-21): a row opens and closes with its arrow (user request, 2026-10-19), and a
1457
+ # double-click shows the window or tab (user request, milestone 2). The row is remembered
1458
+ # for a double-click, should the rows move before its second click.
1459
+ self.item_under_first_click = self.find_clicked_item()
1460
+
1461
+ # Pressing and holding a tab row shows that tab until the button comes up (user request,
1462
+ # milestone 2). The short wait tells a hold from a click.
1463
+
1464
+ @objc.python_method
1465
+ def row_pressed(self, row):
1466
+ self.cancel_peek_timer()
1467
+ self.row_press_in_progress = True
1468
+ item = self.outline_view.itemAtRow_(row) if row >= 0 else None
1469
+ self.item_under_press = item
1470
+ if item is None or item.kind != "tab":
1471
+ return
1472
+ self.peek_timer = NSTimer.timerWithTimeInterval_target_selector_userInfo_repeats_(
1473
+ SECONDS_TO_HOLD_BEFORE_PEEKING, self, "peekTimerFired:", item, False)
1474
+ # Common modes, so it fires while the outline view tracks the held button.
1475
+ NSRunLoop.currentRunLoop().addTimer_forMode_(self.peek_timer, NSRunLoopCommonModes)
1476
+
1477
+ def peekTimerFired_(self, timer):
1478
+ self.peek_timer = None
1479
+ item = timer.userInfo()
1480
+ if self.drag_in_progress or item.entry is None:
1481
+ return
1482
+ self.peek_in_progress = True
1483
+ self.owner.start_peek(item.entry.session_id)
1484
+
1485
+ @objc.python_method
1486
+ def row_released(self):
1487
+ self.cancel_peek_timer()
1488
+ if self.peek_in_progress:
1489
+ self.peek_in_progress = False
1490
+ self.owner.end_peek()
1491
+ self.row_press_in_progress = False
1492
+ self.apply_held_snapshot()
1493
+
1494
+ @objc.python_method
1495
+ def cancel_peek_timer(self):
1496
+ if self.peek_timer is not None:
1497
+ self.peek_timer.invalidate()
1498
+ self.peek_timer = None
1499
+
1500
+ def rowDoubleClicked_(self, sender):
1501
+ # The row under the first click, not the one under the pointer now: a sorted list can
1502
+ # reorder its rows (a held snapshot is applied when the first click's button comes up),
1503
+ # which moves another row under the second click.
1504
+ first_click_item, self.item_under_first_click = self.item_under_first_click, None
1505
+ item = first_click_item or self.find_clicked_item()
1506
+ if item is not None and item.kind == "process":
1507
+ item = item.parent_item # its tab
1508
+ if item is not None and item.kind in ("window", "tab"):
1509
+ self.show_item(item)
1510
+
1511
+ @objc.python_method
1512
+ def toggle_expansion(self, item):
1513
+ """Expands or collapses a row at once, without the outline view's slide animation;
1514
+ record_expansion_change keeps the record and redraws."""
1515
+ self.finish_rename()
1516
+ if self.items_by_key.get(item.key) is not item:
1517
+ return # finishing the rename applied a snapshot without this row
1518
+ run_without_animation(lambda: self.outline_view.collapseItem_(item) if self.outline_view.isItemExpanded_(item)
1519
+ else self.outline_view.expandItem_(item))
1520
+ self.item_whose_expansion_is_changing = None # in case a change was announced but not made
1521
+
1522
+ @objc.python_method
1523
+ def set_all_expanded(self, expanded):
1524
+ """Expands or collapses every monitor and window row, leaving the tabs' previews
1525
+ as they are (user request, 2026-10-19). Collapsing keeps the windows collapsed before,
1526
+ also those whose rows Hide Idle hides."""
1527
+ self.finish_rename()
1528
+ if expanded:
1529
+ self.collapsed_item_keys.clear()
1530
+ else:
1531
+ self.collapsed_item_keys |= {key for key, item in self.items_by_key.items()
1532
+ if item.child_items and item.kind in ("monitor", "window")}
1533
+ # Row by row rather than through reloadData, which would rebuild every row view.
1534
+ run_without_animation(lambda: self.apply_expansion_state(self.top_level_items))
1535
+ self.redraw_visible_rows()
1536
+ self.on_row_count_changed()
1537
+ self.on_snapshot_or_expansion_changed()
1538
+
1539
+ @objc.python_method
1540
+ def is_fully_expanded(self):
1541
+ """Whether every monitor and window row with rows below it is expanded (the previews don't
1542
+ count). A collapsed monitor whose windows all moved away keeps its choice for later but
1543
+ hides nothing now."""
1544
+ return not any(self.items_by_key[key].child_items for key in self.collapsed_item_keys if key in self.items_by_key)
1545
+
1546
+ @objc.python_method
1547
+ def count_window_rows(self):
1548
+ """Returns how many window rows the list has, also inside collapsed monitor rows."""
1549
+ return len(self.list_window_items())
1550
+
1551
+ @objc.python_method
1552
+ def set_previews_open(self, tab_items, is_open):
1553
+ """Opens or closes these tab rows at once: their previews and process rows."""
1554
+ self.finish_rename()
1555
+ for tab_item in tab_items:
1556
+ if is_open:
1557
+ self.open_preview_item_keys.add(tab_item.key)
1558
+ else:
1559
+ self.open_preview_item_keys.discard(tab_item.key)
1560
+ if any(tab_item.entry.child_processes for tab_item in tab_items):
1561
+ # Their process rows come or go: the rows are built again (when the click's button
1562
+ # comes up, should a snapshot be held while it is down).
1563
+ self.apply_snapshot(self.held_snapshot or self.snapshot)
1564
+ else:
1565
+ self.apply_row_heights()
1566
+ self.redraw_visible_rows()
1567
+ self.on_row_count_changed() # the dropdown fits its height again
1568
+
1569
+ @objc.python_method
1570
+ def apply_row_heights(self):
1571
+ """Has the outline view take each row's current height (measure_row_height) at once,
1572
+ without its animation, and records the rows as shown so the next snapshot doesn't reload them."""
1573
+ self.row_structure = self.list_row_structure()
1574
+ run_without_animation(lambda: self.outline_view.noteHeightOfRowsWithIndexesChanged_(
1575
+ build_index_set(range(self.outline_view.numberOfRows()))))
1576
+
1577
+ def previewToggleButtonClicked_(self, sender):
1578
+ """Closes the tab rows (previews and process rows) in the window whose row holds this
1579
+ button when all are open, and otherwise opens them all."""
1580
+ row = self.outline_view.rowForView_(sender)
1581
+ window_item = self.outline_view.itemAtRow_(row) if row >= 0 else None
1582
+ if window_item is not None and window_item.kind == "window":
1583
+ tabs_that_open = self.list_tabs_that_open(window_item)
1584
+ self.set_previews_open(tabs_that_open, not all(self.tab_row_is_open(tab_item) for tab_item in tabs_that_open))
1585
+
1586
+ @objc.python_method
1587
+ def list_tabs_that_open(self, window_item):
1588
+ """Returns the window's tab items that have a preview or process rows to show."""
1589
+ return [tab_item for tab_item in window_item.child_items if self.row_can_open(tab_item)]
1590
+
1591
+ # ----- renaming in place -----
1592
+
1593
+ @objc.python_method
1594
+ def finish_rename(self):
1595
+ """Submits an open rename for its own row, as a click elsewhere in the list does. Called
1596
+ before rows open or close: AppKit raises an exception when a row whose name is being
1597
+ edited is collapsed away, and the list would go on holding back snapshots."""
1598
+ if self.rename_in_progress:
1599
+ self.outline_view.window().makeFirstResponder_(self.outline_view)
1600
+
1601
+ @objc.python_method
1602
+ def begin_rename(self, item):
1603
+ self.finish_rename() # then this row is found again, since finishing can apply a held snapshot
1604
+ if item.key not in self.items_by_key:
1605
+ return
1606
+ item = self.items_by_key[item.key]
1607
+ row = self.outline_view.rowForItem_(item)
1608
+ row_view = self.outline_view.viewAtColumn_row_makeIfNecessary_(0, row, True) if row >= 0 else None
1609
+ if row_view is None:
1610
+ return
1611
+ self.rename_in_progress = True
1612
+ self.item_being_renamed = item
1613
+ self.title_before_rename = item.entry.tab_title if item.kind == "tab" else item.entry.title
1614
+ name_text_field = row_view.name_text_field
1615
+ row_view.look = None # the field is edited directly, so the row is refilled afterwards
1616
+ name_text_field.setStringValue_(self.title_before_rename)
1617
+ name_text_field.setEditable_(True)
1618
+ name_text_field.setSelectable_(True)
1619
+ name_text_field.setDrawsBackground_(True)
1620
+ name_text_field.setBezeled_(True)
1621
+ row_view.setNeedsLayout_(True)
1622
+ window = self.outline_view.window()
1623
+ if not window.styleMask() & NSWindowStyleMaskNonactivatingPanel:
1624
+ # The dropdown takes typing only while the dashboard is the active app, which it may
1625
+ # no longer be (after a peek); otherwise the new name would go to an agent's prompt.
1626
+ NSApp.activateIgnoringOtherApps_(True)
1627
+ window.makeKeyWindow()
1628
+ window.makeFirstResponder_(name_text_field)
1629
+ name_text_field.currentEditor().selectAll_(None)
1630
+
1631
+ @objc.python_method
1632
+ def cancel_rename(self):
1633
+ """Ends an open rename without renaming, as Esc does (the dropdown calls it as it closes,
1634
+ and the sidebar when it loses keyboard focus, or the list would keep holding back snapshots)."""
1635
+ if self.rename_in_progress:
1636
+ self.item_being_renamed = None
1637
+ self.outline_view.window().makeFirstResponder_(self.outline_view)
1638
+
1639
+ def control_textView_doCommandBySelector_(self, control, text_view, command_selector):
1640
+ # Esc cancels the rename. AppKit's calls arrive with the selector as str; direct Python calls may pass bytes.
1641
+ if command_selector in ("cancelOperation:", b"cancelOperation:"):
1642
+ self.item_being_renamed = None
1643
+ self.outline_view.window().makeFirstResponder_(self.outline_view)
1644
+ return True
1645
+ return False
1646
+
1647
+ def controlTextDidEndEditing_(self, notification):
1648
+ name_text_field = notification.object()
1649
+ item = self.item_being_renamed
1650
+ new_title = name_text_field.stringValue()
1651
+ if new_title.strip() == self.title_before_rename.strip():
1652
+ item = None # unchanged: don't turn a default name into a fixed title
1653
+ name_text_field.setEditable_(False)
1654
+ name_text_field.setSelectable_(False)
1655
+ name_text_field.setDrawsBackground_(False)
1656
+ name_text_field.setBezeled_(False)
1657
+ self.rename_in_progress = False
1658
+ self.item_being_renamed = None
1659
+ if item is not None and item.entry is not None:
1660
+ if item.kind == "tab":
1661
+ self.submit_action(ActionRequest("rename_tab", {"tab_id": item.item_id}, {"new_title": new_title}))
1662
+ else:
1663
+ self.submit_action(ActionRequest("rename_window", {"window_id": item.item_id}, {"new_title": new_title}))
1664
+ name_text_field.superview().look = None
1665
+ self.apply_held_snapshot() # first, so a snapshot held during the rename doesn't bring the old name back
1666
+ if item is not None and self.held_snapshot is not None and new_title.strip():
1667
+ # Held again (the rename ended with a click on another row, whose button is still
1668
+ # down): it predates the rename, so it gets the new name, or it would bring the old
1669
+ # one back on release. It is kept rather than dropped, since the core sends another
1670
+ # only when something changes.
1671
+ self.held_snapshot = replace_title_in_snapshot(self.held_snapshot, item.kind, item.item_id, new_title.strip())
1672
+ renamed_item = self.items_by_key.get(item.key) if item is not None else None
1673
+ if renamed_item is not None and renamed_item.entry is not None and new_title.strip():
1674
+ # Shown at once; the next snapshot confirms it (or puts the old name back if iTerm2 refused).
1675
+ renamed_item.entry = renamed_item.entry._replace(
1676
+ **{"tab_title" if renamed_item.kind == "tab" else "title": new_title.strip()})
1677
+ self.redraw_visible_rows()
1678
+
1679
+ @objc.python_method
1680
+ def apply_held_snapshot(self):
1681
+ held_snapshot, self.held_snapshot = self.held_snapshot, None
1682
+ if held_snapshot is not None:
1683
+ self.apply_snapshot(held_snapshot)
1684
+ self.on_row_count_changed() # the dropdown didn't refit while the snapshot was held
1685
+ elif self.snapshot is not None:
1686
+ self.redraw_visible_rows()
1687
+
1688
+ # ----- right-click menu -----
1689
+
1690
+ def menuWillOpen_(self, menu):
1691
+ self.menu_is_open = True # keeps the sidebar from sliding away under the menu
1692
+
1693
+ def menuDidClose_(self, menu):
1694
+ self.menu_is_open = False
1695
+
1696
+ def menuNeedsUpdate_(self, menu):
1697
+ menu.removeAllItems()
1698
+ menu.setAutoenablesItems_(False)
1699
+ item = self.find_clicked_item()
1700
+ if item is not None and item.kind == "process":
1701
+ item = item.parent_item # a process row has its tab's menu
1702
+ self.menu_target_item = item
1703
+ selected_items = self.list_selected_items()
1704
+ if item is not None and len(selected_items) >= 2 and any(selected_item is item for selected_item in selected_items):
1705
+ # A right-click on one of several selected rows; a single row keeps its own menu, selected
1706
+ # or not. An "exited" row has no agent left to act on.
1707
+ self.menu_target_agent_session_entries = [entry for entry in self.list_agent_session_entries_of_the_selected_rows()
1708
+ if entry.status != "exited"]
1709
+ self.add_menu_items_for_the_selected_rows(menu, self.menu_target_agent_session_entries,
1710
+ any(selected_item.kind == "window" for selected_item in selected_items))
1711
+ return
1712
+ if item is None or item.kind == "new_window":
1713
+ self.add_new_window_menu_items(menu) # empty space, or the "+" row
1714
+ return
1715
+ if item.child_items and item.kind in ("monitor", "window"): # (a tab row opens with its arrow)
1716
+ self.add_menu_item(menu, "Collapse" if self.outline_view.isItemExpanded_(item) else "Expand",
1717
+ "menuToggleExpansion:")
1718
+ menu.addItem_(NSMenuItem.separatorItem())
1719
+ if item.kind == "monitor": # also when Hide Idle hides all of its window rows
1720
+ self.add_pause_and_resume_menu_items(menu, self.list_agent_session_entries_below(item))
1721
+ return
1722
+ if item.kind == "window":
1723
+ self.add_menu_item(menu, "Show window", "menuFocus:")
1724
+ self.add_menu_item(menu, "Rename", "menuRename:")
1725
+ menu.addItem_(NSMenuItem.separatorItem())
1726
+ # A new tab in this window, in the folder of its selected tab's agent session.
1727
+ for agent_tool_name in self.owner.list_agent_tool_names():
1728
+ self.add_menu_item(menu, f"New tab with {agent_tool_name} session…", "menuNewAgentSessionInWindow:"
1729
+ ).setRepresentedObject_(agent_tool_name)
1730
+ menu.addItem_(NSMenuItem.separatorItem())
1731
+ self.add_pause_and_resume_menu_items(menu, self.list_agent_session_entries_below(item))
1732
+ if item.parent_item is not None:
1733
+ menu.addItem_(NSMenuItem.separatorItem())
1734
+ other_monitor_items = [monitor_item for monitor_item in self.top_level_items if monitor_item is not item.parent_item]
1735
+ submenu = NSMenu.alloc().initWithTitle_("Move to monitor")
1736
+ for monitor_item in other_monitor_items:
1737
+ self.add_menu_item(submenu, monitor_item.entry.name or "Monitor", "menuMoveToMonitor:"
1738
+ ).setRepresentedObject_(monitor_item.item_id)
1739
+ move_item = NSMenuItem.alloc().initWithTitle_action_keyEquivalent_("Move to monitor", None, "")
1740
+ move_item.setSubmenu_(submenu)
1741
+ menu.addItem_(move_item)
1742
+ menu.addItem_(NSMenuItem.separatorItem())
1743
+ self.add_menu_item(menu, "Close window", "menuCloseWindow:")
1744
+ return
1745
+ if item.kind == "tab":
1746
+ self.add_menu_item(menu, "Show tab", "menuFocus:")
1747
+ self.add_menu_item(menu, "Rename", "menuRename:")
1748
+ duplicate_item = self.add_menu_item(menu, "Duplicate this tab", "menuDuplicate:")
1749
+ if item.entry.status == "exited": # the copy would continue its conversation, found through its process
1750
+ duplicate_item.setEnabled_(False)
1751
+ duplicate_item.setToolTip_("The agent has ended")
1752
+ elif not self.owner.find_launch_command(item.entry.agent_tool_name):
1753
+ duplicate_item.setEnabled_(False)
1754
+ duplicate_item.setToolTip_(f"Settings has no launch command for {item.entry.agent_tool_name}")
1755
+ other_window_items = [window_item for window_item in self.list_window_items() if window_item is not item.parent_item]
1756
+ if other_window_items:
1757
+ submenu = NSMenu.alloc().initWithTitle_("Move to window")
1758
+ for window_item in other_window_items:
1759
+ submenu_item = self.add_menu_item(submenu, window_item.entry.title, "menuMoveToWindow:")
1760
+ submenu_item.setRepresentedObject_(window_item.item_id)
1761
+ move_item = NSMenuItem.alloc().initWithTitle_action_keyEquivalent_("Move to window", None, "")
1762
+ move_item.setSubmenu_(submenu)
1763
+ menu.addItem_(move_item)
1764
+ move_to_new_window_item = self.add_menu_item(menu, "Extract to new window", "menuMoveToNewWindow:")
1765
+ if item.parent_item is not None and item.parent_item.entry.total_tab_count < 2:
1766
+ move_to_new_window_item.setEnabled_(False)
1767
+ move_to_new_window_item.setToolTip_("This tab is its window's only tab")
1768
+ # Typed into the agent only while it waits at its prompt (user request, 2026-10-19).
1769
+ menu.addItem_(NSMenuItem.separatorItem())
1770
+ for command in SLASH_COMMANDS_IN_THE_TAB_MENU:
1771
+ command_item = self.add_menu_item(menu, command, "menuSendSlashCommand:")
1772
+ command_item.setRepresentedObject_(command)
1773
+ if item.entry.status == "exited":
1774
+ command_item.setEnabled_(False)
1775
+ command_item.setToolTip_("The agent has ended")
1776
+ elif command not in item.entry.slash_commands:
1777
+ command_item.setEnabled_(False)
1778
+ # As the menu of several rows says it (code review, 2026-10-28).
1779
+ command_item.setToolTip_(f"AgentCommandTab can't type commands into {item.entry.agent_tool_name or 'this agent'}")
1780
+ elif item.entry.status not in STATES_OF_AN_AGENT_WAITING_AT_ITS_PROMPT:
1781
+ command_item.setEnabled_(False)
1782
+ # The user's wording, 2026-10-28, with the state as the row names it ("thinking", not "working").
1783
+ shown_state = build_agent_session_row_text_parts(item.entry, [], time.time()).state_text
1784
+ command_item.setToolTip_(f"Only available when the agent waits at its prompt (it is currently {shown_state})")
1785
+ kill_item = self.add_menu_item(menu, "Kill session", "menuKillSession:")
1786
+ if item.entry.status == "exited":
1787
+ kill_item.setEnabled_(False)
1788
+ kill_item.setToolTip_("The agent has ended")
1789
+ menu.addItem_(NSMenuItem.separatorItem())
1790
+ self.add_pause_and_resume_menu_items(menu, [item.entry])
1791
+
1792
+ @objc.python_method
1793
+ def list_agent_session_entries_below(self, item):
1794
+ """Returns the agent sessions in a window row, or in all windows of a monitor row (also
1795
+ those whose rows Hide Idle hides)."""
1796
+ if item.kind == "window":
1797
+ return list(item.entry.agent_sessions)
1798
+ return [entry for window_entry in item.entry.windows for entry in window_entry.agent_sessions]
1799
+
1800
+ @objc.python_method
1801
+ def list_agent_session_entries(self):
1802
+ """Returns every agent session in the list, those whose rows Hide Idle hides too (the bottom bar's pause or resume button acts on all of them)."""
1803
+ return [entry for _, _, entry in iterate_agent_session_entries(self.snapshot)] if self.snapshot else []
1804
+
1805
+ @objc.python_method
1806
+ def add_pause_and_resume_menu_items(self, menu, agent_session_entries):
1807
+ """Adds "Pause session" for those of the agent sessions that run and "Resume session" for
1808
+ those that are paused, with the count when the row holds several ("Pause 3 sessions";
1809
+ user request, 2026-10-20)."""
1810
+ sessions_to_pause, sessions_to_resume = split_agent_sessions_into_pausable_and_resumable(agent_session_entries)
1811
+ for verb, entries, action_name in (("Pause", sessions_to_pause, "menuPauseSessions:"),
1812
+ ("Resume", sessions_to_resume, "menuResumeSessions:")):
1813
+ if not entries:
1814
+ continue
1815
+ title = f"{verb} session" if len(agent_session_entries) == 1 else f"{verb} {describe_session_count(len(entries))}"
1816
+ self.add_menu_item(menu, title, action_name).setRepresentedObject_([entry.session_id for entry in entries])
1817
+
1818
+ @objc.python_method
1819
+ def add_menu_items_for_the_selected_rows(self, menu, agent_session_entries, a_window_row_is_selected):
1820
+ """The menu of two or more selected rows, acting on their agent sessions (user request,
1821
+ 2026-10-21): /compact, /clear and Kill; Pause and Resume; Talk to Each Other…, last (user
1822
+ request, 2026-10-27).
1823
+
1824
+ Kill says how many sessions only when a window row is selected, since that row stands for
1825
+ all of its window's tabs, hidden idle ones too; for tab rows alone the selection shows it
1826
+ (user requests, 2026-10-21)."""
1827
+ for command in SLASH_COMMANDS_IN_THE_TAB_MENU:
1828
+ agent_sessions_that_take_it = list_agent_sessions_that_take_slash_command(agent_session_entries, command)
1829
+ command_item = self.add_menu_item(
1830
+ menu, f"{command} {describe_session_count(len(agent_sessions_that_take_it))}" if agent_sessions_that_take_it else command,
1831
+ "menuSendSlashCommandToSelectedSessions:")
1832
+ command_item.setRepresentedObject_(command)
1833
+ if not agent_sessions_that_take_it:
1834
+ agent_tool_names = sorted({entry.agent_tool_name or "these agents" for entry in agent_session_entries})
1835
+ command_item.setEnabled_(False)
1836
+ command_item.setToolTip_(AGENTS_HAVE_ENDED_TOOL_TIP if not agent_session_entries
1837
+ else "Only available after the paused sessions are resumed" # the user's wording, 2026-10-28
1838
+ if any(command in entry.slash_commands for entry in agent_session_entries)
1839
+ else f"AgentCommandTab can't type commands into {' or '.join(agent_tool_names)}")
1840
+ continue
1841
+ tool_tip_lines = []
1842
+ if len(agent_sessions_that_take_it) < len(agent_session_entries):
1843
+ # The user's wording, 2026-10-28 (paused sessions, left out too, are counted as not supported).
1844
+ tool_tip_lines.append(f"Typed only into the {len(agent_sessions_that_take_it)} of "
1845
+ f"{len(agent_session_entries)} where this command is supported.")
1846
+ if any(entry.status not in STATES_OF_AN_AGENT_WAITING_AT_ITS_PROMPT for entry in agent_sessions_that_take_it):
1847
+ tool_tip_lines.append("A session in the middle of a turn will get this command when the turn ends") # the user's wording, 2026-10-28
1848
+ command_item.setToolTip_("\n".join(tool_tip_lines) or None)
1849
+ kill_item = self.add_menu_item(menu, f"Kill {describe_session_count(len(agent_session_entries))}" if a_window_row_is_selected
1850
+ else "Kill sessions", "menuKillSelectedSessions:")
1851
+ if not agent_session_entries: # every selected row has exited (code review, 2026-10-28)
1852
+ kill_item.setEnabled_(False)
1853
+ kill_item.setToolTip_(AGENTS_HAVE_ENDED_TOOL_TIP)
1854
+ menu.addItem_(NSMenuItem.separatorItem())
1855
+ self.add_pause_and_resume_menu_items(menu, agent_session_entries)
1856
+ menu.addItem_(NSMenuItem.separatorItem())
1857
+ talk_item = self.add_menu_item(menu, "Talk to each other…", "menuTalkToEachOther:")
1858
+ if len(self.list_agent_sessions_that_can_talk_to_each_other(agent_session_entries)) < 2:
1859
+ talk_item.setEnabled_(False)
1860
+ talk_item.setToolTip_(f"Select two or more {' or '.join(sorted(AGENT_TOOL_NAMES_WHOSE_SESSIONS_CAN_TALK_TO_EACH_OTHER))} "
1861
+ f"sessions to send a 'Talk to each other...' message.") # the user's wording, 2026-10-28
1862
+
1863
+ @objc.python_method
1864
+ def list_agent_sessions_that_can_talk_to_each_other(self, agent_session_entries):
1865
+ """Returns the agent sessions of tools whose sessions other sessions can send messages to."""
1866
+ return [entry for entry in agent_session_entries
1867
+ if entry.agent_tool_name in AGENT_TOOL_NAMES_WHOSE_SESSIONS_CAN_TALK_TO_EACH_OTHER]
1868
+
1869
+ def menuTalkToEachOther_(self, sender):
1870
+ agent_session_entries = self.list_agent_sessions_that_can_talk_to_each_other(self.menu_target_agent_session_entries)
1871
+ left_out_agent_session_entries = [entry for entry in self.menu_target_agent_session_entries
1872
+ if entry not in agent_session_entries]
1873
+ note_and_recipients = self.owner.ask_for_note_asking_agent_sessions_to_talk_to_each_other(
1874
+ agent_session_entries, left_out_agent_session_entries)
1875
+ if note_and_recipients is None:
1876
+ return
1877
+ note, recipient_entries = note_and_recipients
1878
+ # Every one of them is in the message the recipients get; only the recipients get it.
1879
+ self.owner.submit_action_and_report_failure(
1880
+ ActionRequest("ask_agent_sessions_to_talk_to_each_other",
1881
+ {"session_ids": [entry.session_id for entry in agent_session_entries]},
1882
+ {"note": note, "recipient_session_ids": [entry.session_id for entry in recipient_entries]}),
1883
+ "Not every session got the message")
1884
+
1885
+ def menuSendSlashCommandToSelectedSessions_(self, sender):
1886
+ command = sender.representedObject()
1887
+ agent_session_entries = list_agent_sessions_that_take_slash_command(self.menu_target_agent_session_entries, command)
1888
+ if command == COMMAND_THAT_STARTS_A_NEW_CONVERSATION and not self.owner.ask_for_confirmation(
1889
+ f"Are you sure you want to /clear the {describe_session_count(len(agent_session_entries))} "
1890
+ f"({list_tab_titles_for_alert(agent_session_entries)})?", # as the one-tab question, user request, 2026-10-27
1891
+ "clear"):
1892
+ return
1893
+ self.owner.submit_action_and_report_failure(
1894
+ ActionRequest("send_slash_command_to_agent_sessions",
1895
+ {"session_ids": [entry.session_id for entry in agent_session_entries]}, {"command": command}),
1896
+ f"{command} wasn't sent to every session")
1897
+
1898
+ def menuKillSelectedSessions_(self, sender):
1899
+ agent_session_entries = self.menu_target_agent_session_entries
1900
+ if self.owner.ask_for_confirmation(
1901
+ f"Kill ends the agent processes of {describe_session_count(len(agent_session_entries))} "
1902
+ f"({list_tab_titles_for_alert(agent_session_entries)}) at once, with whatever they were doing; "
1903
+ "their tabs stay open with their shells.", "kill"):
1904
+ self.owner.submit_action_and_report_failure(
1905
+ ActionRequest("end_agent_processes", {"session_ids": [entry.session_id for entry in agent_session_entries]}),
1906
+ "Not every session was ended")
1907
+
1908
+ def menuPauseSessions_(self, sender):
1909
+ self.pause_or_resume_agent_sessions(list(sender.representedObject()), pause=True)
1910
+
1911
+ def menuResumeSessions_(self, sender):
1912
+ self.pause_or_resume_agent_sessions(list(sender.representedObject()), pause=False)
1913
+
1914
+ @objc.python_method
1915
+ def pause_or_resume_agent_sessions(self, session_ids, pause):
1916
+ """Asks the core to pause or resume these agent sessions; an alert names those that failed and why."""
1917
+ # A pause that stopped the agent can still fail for processes below it run with sudo.
1918
+ what_failed = "Not everything was paused" if pause else (
1919
+ "The session wasn't resumed" if len(session_ids) == 1 else "Not every session was resumed")
1920
+ self.owner.submit_action_and_report_failure(
1921
+ ActionRequest("pause_agent_sessions" if pause else "resume_agent_sessions", {"session_ids": session_ids}),
1922
+ what_failed)
1923
+
1924
+ @objc.python_method
1925
+ def add_new_window_menu_items(self, menu):
1926
+ """Adds "New Claude Code window" and the like, one per agent tool the settings include:
1927
+ each starts that tool in a new iTerm2 window."""
1928
+ for agent_tool_name in self.owner.list_agent_tool_names():
1929
+ self.add_menu_item(menu, f"New {agent_tool_name} window", "menuNewWindowWithAgentSession:"
1930
+ ).setRepresentedObject_(agent_tool_name)
1931
+
1932
+ def newWindowButtonClicked_(self, sender):
1933
+ menu = NSMenu.alloc().initWithTitle_("")
1934
+ self.add_new_window_menu_items(menu)
1935
+ menu.popUpMenuPositioningItem_atLocation_inView_(None, (0, sender.frame().size.height), sender)
1936
+
1937
+ @objc.python_method
1938
+ def add_menu_item(self, menu, title, action_name):
1939
+ menu_item = NSMenuItem.alloc().initWithTitle_action_keyEquivalent_(title, action_name, "")
1940
+ menu_item.setTarget_(self)
1941
+ menu.addItem_(menu_item)
1942
+ return menu_item
1943
+
1944
+ @objc.python_method
1945
+ def list_window_items(self):
1946
+ """Returns the window items in the order the list shows them (monitor groups included)."""
1947
+ window_items = []
1948
+ for top_level_item in self.top_level_items:
1949
+ if top_level_item.kind == "window":
1950
+ window_items.append(top_level_item)
1951
+ else:
1952
+ window_items.extend(child_item for child_item in top_level_item.child_items if child_item.kind == "window")
1953
+ return window_items
1954
+
1955
+ @objc.python_method
1956
+ def choose_selected_agent_session_of_window(self, window_item):
1957
+ """Returns the agent session in the window's selected tab, else the window's first one."""
1958
+ agent_session_entries = window_item.entry.agent_sessions
1959
+ return next((entry for entry in agent_session_entries if entry.tab_id == window_item.entry.selected_tab_id),
1960
+ agent_session_entries[0])
1961
+
1962
+ def menuFocus_(self, sender):
1963
+ self.show_item(self.menu_target_item)
1964
+
1965
+ @objc.python_method
1966
+ def show_item(self, item):
1967
+ """Brings a tab to the front, or a window with the tab it already shows (even one without an agent)."""
1968
+ if item.kind == "tab":
1969
+ self.submit_action(ActionRequest("focus_agent_session", {"session_id": item.entry.session_id}))
1970
+ else:
1971
+ self.submit_action(ActionRequest("focus_window", {"window_id": item.item_id}))
1972
+ self.on_tab_focused()
1973
+
1974
+ def menuNewAgentSessionInWindow_(self, sender):
1975
+ window_item = self.menu_target_item
1976
+ folder = self.choose_selected_agent_session_of_window(window_item).working_folder
1977
+ self.owner.start_agent_session_from_menu(window_item.item_id, folder, sender.representedObject())
1978
+
1979
+ def menuNewWindowWithAgentSession_(self, sender):
1980
+ self.owner.start_agent_session_from_menu(None, None, sender.representedObject())
1981
+
1982
+ def menuMoveToMonitor_(self, sender):
1983
+ self.submit_action(ActionRequest("move_window_to_monitor", {"window_id": self.menu_target_item.item_id},
1984
+ {"monitor_id": sender.representedObject()}))
1985
+
1986
+ def menuToggleExpansion_(self, sender):
1987
+ self.toggle_expansion(self.menu_target_item)
1988
+
1989
+ def menuSendSlashCommand_(self, sender):
1990
+ tab_item, command = self.menu_target_item, sender.representedObject()
1991
+ if command == COMMAND_THAT_STARTS_A_NEW_CONVERSATION and not self.owner.ask_for_confirmation(
1992
+ f'Are you sure you want to /clear the "{tab_item.entry.tab_title}" session?', # user's wording, 2026-10-27
1993
+ "clear"):
1994
+ return
1995
+ self.owner.submit_action_and_report_failure(
1996
+ ActionRequest("send_slash_command", {"session_id": tab_item.entry.session_id}, {"command": command}),
1997
+ f"{command} wasn't sent")
1998
+
1999
+ def menuKillSession_(self, sender):
2000
+ tab_item = self.menu_target_item
2001
+ if self.owner.ask_for_confirmation(
2002
+ f'Kill session ends the {tab_item.entry.agent_tool_name} process in "{tab_item.entry.tab_title}" at once, '
2003
+ "with whatever it was doing; the tab stays open with its shell.", "kill"):
2004
+ self.owner.submit_action_and_report_failure(
2005
+ ActionRequest("end_agent_process", {"session_id": tab_item.entry.session_id}), "The session wasn't ended")
2006
+
2007
+ def menuCloseWindow_(self, sender):
2008
+ window_item = self.menu_target_item
2009
+ if self.owner.confirm_closing_window(window_item.entry):
2010
+ self.submit_action(ActionRequest("close_window", {"window_id": window_item.item_id}))
2011
+
2012
+ def menuRename_(self, sender):
2013
+ self.begin_rename(self.menu_target_item)
2014
+
2015
+ def menuMoveToWindow_(self, sender):
2016
+ self.submit_action(ActionRequest("move_tab", {"tab_id": self.menu_target_item.item_id},
2017
+ {"target_window_id": sender.representedObject(), "drop_before_tab_id": None}))
2018
+
2019
+ def menuMoveToNewWindow_(self, sender):
2020
+ self.submit_action(ActionRequest("move_tab_to_new_window", {"tab_id": self.menu_target_item.item_id}))
2021
+
2022
+ def menuDuplicate_(self, sender):
2023
+ tab_entry = self.menu_target_item.entry
2024
+ self.owner.duplicate_agent_session(tab_entry.tab_id, tab_entry.working_folder, tab_entry.agent_tool_name)
2025
+
2026
+ # ----- drag and drop -----
2027
+
2028
+ def outlineView_pasteboardWriterForItem_(self, outline_view, item):
2029
+ # Dragging one of several selected rows would drag them all; only the row under the
2030
+ # pointer moves (None leaves a row out of the drag).
2031
+ if item.kind not in ("tab", "window") or item is not self.item_under_press:
2032
+ return None
2033
+ pasteboard_item = NSPasteboardItem.alloc().init()
2034
+ pasteboard_item.setString_forType_(item.item_id, TAB_DRAG_TYPE if item.kind == "tab" else WINDOW_DRAG_TYPE)
2035
+ return pasteboard_item
2036
+
2037
+ def outlineView_draggingSession_willBeginAtPoint_forItems_(self, outline_view, session, point, items):
2038
+ self.drag_in_progress = True
2039
+ self.dragged_item = items[0] if items else None
2040
+ self.cancel_peek_timer() # a drag, not a hold
2041
+ if self.peek_in_progress: # the drag began after the hold had already shown the tab
2042
+ self.peek_in_progress = False
2043
+ self.owner.end_peek()
2044
+
2045
+ def outlineView_draggingSession_endedAtPoint_operation_(self, outline_view, session, point, operation):
2046
+ self.drag_in_progress = False
2047
+ self.dragged_item = None
2048
+ self.apply_held_snapshot()
2049
+
2050
+ def outlineView_validateDrop_proposedItem_proposedChildIndex_(self, outline_view, drag_info, proposed_item, child_index):
2051
+ dragged_item = getattr(self, "dragged_item", None)
2052
+ if dragged_item is None:
2053
+ return NSDragOperationNone
2054
+ if proposed_item is not None and proposed_item.kind == "process":
2055
+ proposed_item, child_index = proposed_item.parent_item, -1 # a drop on a process row is one on its tab row
2056
+ if dragged_item.kind == "tab" and self.list_sort_order != "manual":
2057
+ # Sorted rows aren't in iTerm2's tab order, so a tab can only go to the end of another window.
2058
+ window_item = proposed_item.parent_item if proposed_item is not None and proposed_item.kind == "tab" else proposed_item
2059
+ if window_item is None or window_item.kind != "window" or window_item is dragged_item.parent_item:
2060
+ return NSDragOperationNone
2061
+ outline_view.setDropItem_dropChildIndex_(window_item, -1)
2062
+ return NSDragOperationMove
2063
+ if dragged_item.kind == "tab":
2064
+ # Tabs drop between the tabs of a window: retarget drops on a tab to its window.
2065
+ if proposed_item is not None and proposed_item.kind == "tab":
2066
+ window_item = proposed_item.parent_item
2067
+ outline_view.setDropItem_dropChildIndex_(window_item, window_item.child_items.index(proposed_item))
2068
+ return NSDragOperationMove
2069
+ if proposed_item is not None and proposed_item.kind == "window":
2070
+ if child_index < 0:
2071
+ outline_view.setDropItem_dropChildIndex_(proposed_item, len(proposed_item.child_items))
2072
+ return NSDragOperationMove
2073
+ return NSDragOperationNone
2074
+ # Windows reorder among the windows of the same group, in the manual order only...
2075
+ parent_item = dragged_item.parent_item
2076
+ if self.list_sort_order == "manual":
2077
+ if proposed_item is parent_item and child_index >= 0:
2078
+ return NSDragOperationMove
2079
+ if proposed_item is not None and proposed_item.kind == "window" and proposed_item.parent_item is parent_item:
2080
+ sibling_items = parent_item.child_items if parent_item is not None else self.top_level_items
2081
+ outline_view.setDropItem_dropChildIndex_(parent_item, sibling_items.index(proposed_item))
2082
+ return NSDragOperationMove
2083
+ # ...or move to another monitor when dropped into that monitor's group.
2084
+ target_monitor_item = None
2085
+ if proposed_item is not None and proposed_item.kind == "monitor":
2086
+ target_monitor_item = proposed_item
2087
+ elif proposed_item is not None and proposed_item.kind in ("window", "tab"):
2088
+ target_monitor_item = proposed_item.parent_item if proposed_item.kind == "window" else proposed_item.parent_item.parent_item
2089
+ if target_monitor_item is not None and target_monitor_item is not parent_item:
2090
+ outline_view.setDropItem_dropChildIndex_(target_monitor_item, -1)
2091
+ return NSDragOperationMove
2092
+ return NSDragOperationNone
2093
+
2094
+ def outlineView_acceptDrop_item_childIndex_(self, outline_view, drag_info, target_item, child_index):
2095
+ dragged_item = getattr(self, "dragged_item", None)
2096
+ if dragged_item is None:
2097
+ return False
2098
+ if dragged_item.kind == "tab":
2099
+ sibling_items = [child_item for child_item in target_item.child_items if child_item is not dragged_item]
2100
+ original_index = target_item.child_items.index(dragged_item) if dragged_item in target_item.child_items else None
2101
+ if original_index is not None and child_index in (original_index, original_index + 1):
2102
+ return True # dropped back where it was: moving it would shift the hidden tabs around it
2103
+ drop_index = child_index - (1 if original_index is not None and original_index < child_index else 0)
2104
+ drop_before_tab_id = sibling_items[drop_index].item_id if 0 <= drop_index < len(sibling_items) else None
2105
+ self.submit_action(ActionRequest("move_tab", {"tab_id": dragged_item.item_id},
2106
+ {"target_window_id": target_item.item_id,
2107
+ "drop_before_tab_id": drop_before_tab_id}))
2108
+ return True
2109
+ if target_item is not None and target_item.kind == "monitor" and target_item is not dragged_item.parent_item:
2110
+ self.submit_action(ActionRequest("move_window_to_monitor", {"window_id": dragged_item.item_id},
2111
+ {"monitor_id": target_item.item_id}))
2112
+ return True
2113
+ sibling_items = target_item.child_items if target_item is not None else self.top_level_items
2114
+ remaining_items = [sibling_item for sibling_item in sibling_items if sibling_item is not dragged_item]
2115
+ original_index = sibling_items.index(dragged_item)
2116
+ drop_index = child_index - (1 if original_index < child_index else 0)
2117
+ drop_before_window_id = remaining_items[drop_index].item_id if 0 <= drop_index < len(remaining_items) else None
2118
+ self.submit_action(ActionRequest("reorder_window_list", {"window_id": dragged_item.item_id},
2119
+ {"drop_before_window_id": drop_before_window_id}))
2120
+ return True