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,254 @@
1
+ """Pausing and resuming an agent session: the agent and every process below it (user request, 2026-10-20).
2
+
3
+ Pause before going offline, resume once back online. Checked with real Claude Code and Codex
4
+ sessions on 2026-10-20: paused for 2 minutes mid-answer and mid-command, both carried on.
5
+
6
+ A plain SIGSTOP is not enough. The shell notices its job stopped and takes the terminal back, so
7
+ after a plain SIGCONT the agent runs as a background job and stops again at its next key read.
8
+ So a pause presses Ctrl+Z, as you would (Claude Code and Codex then tidy up their screen and
9
+ suspend), and stops every process below the agent, which may run in their own process groups
10
+ (Bash commands, MCP servers) that Ctrl+Z alone leaves running; not the dashboard itself, when it
11
+ was started from the agent's commands. A resume types `fg` at the shell's
12
+ prompt, which gives the agent the terminal back, then continues the processes below it.
13
+
14
+ `fg` is typed only when that is safe: the shell that runs the agent must be in front (not a
15
+ shell or tmux started at its prompt meanwhile, whose prompt may look the same), its cursor line
16
+ must look exactly as it did right after the pause (so nothing was typed there since, which `fg`
17
+ would join and run), and no other job may be suspended in that shell (a bare `fg` could bring
18
+ back that one instead). Ctrl+U goes
19
+ first, clearing what the shell's line held already right after the pause, so `fg` runs alone:
20
+ keys typed while the pause ran, or a reply the terminal sent to the agent's question about the
21
+ cursor position that reached the shell instead (seen live on 2026-10-20 as "22;3;1R").
22
+ """
23
+
24
+ import asyncio
25
+ import collections
26
+ import os
27
+ import signal
28
+
29
+ import iterm2
30
+
31
+ from agent_command_tab.agent_process_tree import (find_the_shell_running_the_agent,
32
+ list_descendant_processes_and_other_users_process_ids,
33
+ list_other_stopped_jobs_of_the_agents_shell,
34
+ list_the_process_and_its_ancestor_ids, process_has_its_terminal,
35
+ process_is_stopped, read_name_of_any_process, read_process_info)
36
+ from agent_command_tab.dashboard_core_api import ActionResult
37
+
38
+ CONTROL_Z = "\x1a"
39
+ CONTROL_U = "\x15" # clears the shell's input line (bash, zsh, fish)
40
+ SECONDS_TO_WAIT_FOR_CONTROL_Z = 2
41
+ SECONDS_TO_WAIT_FOR_SIGTSTP = 1
42
+ SECONDS_TO_WAIT_FOR_THE_SHELL_PROMPT = 2
43
+ SECONDS_TO_WAIT_FOR_FG = 3
44
+ SECONDS_BETWEEN_CHECKS = 0.1
45
+
46
+ PauseRecord = collections.namedtuple(
47
+ "PauseRecord", ["agent_process", "agent_tool_name", "text_around_the_cursor", "stopped_processes"])
48
+ PauseRecord.__doc__ = ("What a pause left behind (kept across restarts by pause_records_store): the agent's (process "
49
+ "ID, start time) and tool name (\"Codex\"), to list it again after a restart; the shell's "
50
+ "cursor line right after the pause, as (text before the cursor, "
51
+ "text after it, which holds a right-side prompt), or None when no prompt showed or the agent "
52
+ "had been suspended by hand; and the (process ID, start time) of each process it stopped "
53
+ "below the agent.")
54
+
55
+
56
+ def send_signal_to_processes(process_ids, signal_number):
57
+ """Sends a signal to each process, skipping those that have ended meanwhile and those this
58
+ user may not signal (a command the agent ran with sudo); returns the IDs of those it reached."""
59
+ signaled_process_ids = []
60
+ for process_id in process_ids:
61
+ try:
62
+ os.kill(process_id, signal_number)
63
+ except (ProcessLookupError, PermissionError):
64
+ continue
65
+ signaled_process_ids.append(process_id)
66
+ return signaled_process_ids
67
+
68
+
69
+ def pause_has_ended(pause_record):
70
+ """Returns whether the paused agent runs again (fg typed by hand) or is gone (its tab
71
+ closed), judged by its own process, also after the dashboard restarted."""
72
+ agent_process_id, started_at = pause_record.agent_process
73
+ agent = read_process_info(agent_process_id)
74
+ return agent is None or agent.started_at != started_at or not process_is_stopped(agent_process_id)
75
+
76
+
77
+ def continue_processes_stopped_at_pause(stopped_processes):
78
+ """Sends SIGCONT to each process a pause stopped that is still stopped, unless its process
79
+ ID now belongs to another process (a different start time).
80
+
81
+ Args:
82
+ stopped_processes: A PauseRecord's stopped_processes.
83
+ """
84
+ process_ids_to_continue = []
85
+ for process_id, started_at in stopped_processes:
86
+ process = read_process_info(process_id)
87
+ if process is not None and process.started_at == started_at and process_is_stopped(process_id):
88
+ process_ids_to_continue.append(process_id)
89
+ send_signal_to_processes(process_ids_to_continue, signal.SIGCONT)
90
+
91
+
92
+ async def wait_until(condition, seconds):
93
+ """Returns whether condition() became true within seconds, checking every SECONDS_BETWEEN_CHECKS."""
94
+ for _ in range(round(seconds / SECONDS_BETWEEN_CHECKS)):
95
+ if condition():
96
+ return True
97
+ await asyncio.sleep(SECONDS_BETWEEN_CHECKS)
98
+ return condition()
99
+
100
+
101
+ async def read_text_around_the_cursor(session):
102
+ """Returns (text before the cursor, text after it) on the cursor's line, joining the screen
103
+ rows a long line wraps over and leaving out empty cells, or None when the cursor isn't on screen."""
104
+ contents = await session.async_get_screen_contents()
105
+ cursor = contents.cursor_coord
106
+ cursor_row = cursor.y - contents.windowed_coord_range.coordRange.start.y
107
+ if not 0 <= cursor_row < contents.number_of_lines:
108
+ return None
109
+ first_row = cursor_row
110
+ while first_row > 0 and not contents.line(first_row - 1).hard_eol:
111
+ first_row -= 1
112
+ cursor_line = contents.line(cursor_row)
113
+ cells_before_the_cursor = []
114
+ for x in range(cursor.x):
115
+ try:
116
+ cells_before_the_cursor.append(cursor_line.string_at(x))
117
+ except IndexError: # past the cells written on this row
118
+ break
119
+ text_on_the_row_before_the_cursor = "".join(cells_before_the_cursor)
120
+ text_before = "".join(contents.line(row).string for row in range(first_row, cursor_row)) + text_on_the_row_before_the_cursor
121
+ text_after = cursor_line.string[len(text_on_the_row_before_the_cursor):]
122
+ row = cursor_row
123
+ while not contents.line(row).hard_eol and row + 1 < contents.number_of_lines:
124
+ row += 1
125
+ text_after += contents.line(row).string
126
+ return text_before.replace("\x00", ""), text_after.replace("\x00", "")
127
+
128
+
129
+ async def read_the_shell_prompt(session, agent_process_id):
130
+ """Returns the cursor line once the shell has drawn its prompt, waiting up to
131
+ SECONDS_TO_WAIT_FOR_THE_SHELL_PROMPT for a slow prompt, or None. The prompt counts as drawn
132
+ once the shell has taken the terminal back from the agent and the cursor line, not empty,
133
+ reads the same twice in a row (until then the agent's own input line may still show)."""
134
+ previous_text_around_the_cursor = None
135
+ for _ in range(round(SECONDS_TO_WAIT_FOR_THE_SHELL_PROMPT / SECONDS_BETWEEN_CHECKS)):
136
+ await asyncio.sleep(SECONDS_BETWEEN_CHECKS)
137
+ if process_has_its_terminal(agent_process_id):
138
+ continue
139
+ try:
140
+ text_around_the_cursor = await read_text_around_the_cursor(session)
141
+ except iterm2.RPCException:
142
+ return None # the tab closed meanwhile; the pause's record still lists what it stopped
143
+ if (text_around_the_cursor is not None and text_around_the_cursor[0].strip()
144
+ and text_around_the_cursor == previous_text_around_the_cursor):
145
+ return text_around_the_cursor
146
+ previous_text_around_the_cursor = text_around_the_cursor
147
+ return None
148
+
149
+
150
+ def list_processes_below_the_agent_to_stop(agent_process_id):
151
+ """Returns ({process ID: ProcessInfo} of the processes below the agent a pause stops, the IDs
152
+ of those below it that belong to another user, which it can't stop: a command run with sudo).
153
+ Leaves out the dashboard's own process, those it runs in and those it started, so a
154
+ dashboard started from the agent's own commands keeps running."""
155
+ dashboard_process_ids = set(list_the_process_and_its_ancestor_ids(os.getpid())) | {
156
+ process.process_id
157
+ for process in list_descendant_processes_and_other_users_process_ids(os.getpid(), maximum_depth=None)[0]}
158
+ processes_below, other_users_process_ids_below = list_descendant_processes_and_other_users_process_ids(
159
+ agent_process_id, maximum_depth=None)
160
+ return ({process.process_id: process for process in processes_below if process.process_id not in dashboard_process_ids},
161
+ other_users_process_ids_below)
162
+
163
+
164
+ async def pause_agent_session(session, agent_process_id, agent_tool_name):
165
+ """Suspends the agent like Ctrl+Z, then stops every process below it.
166
+
167
+ An agent that doesn't take Ctrl+Z as "suspend" (an older Claude Code took it as undo) gets
168
+ SIGTSTP, the signal Ctrl+Z sends in an ordinary terminal, and SIGSTOP, which nothing can
169
+ ignore, if that doesn't stop it either. An agent suspended by hand already only gets the
170
+ processes below it stopped (Ctrl+Z leaves those in their own process groups running); its
171
+ record then holds no prompt, since something may have been typed at the shell meanwhile.
172
+
173
+ Args:
174
+ session: The tab's iterm2.Session.
175
+ agent_process_id: The agent's process.
176
+ agent_tool_name: The agent's tool, as its row names it.
177
+
178
+ Returns:
179
+ (ActionResult, PauseRecord), or (a failed ActionResult, None) when the agent is gone. The
180
+ ActionResult also fails, saying which, when processes below the agent run as another user
181
+ (with sudo) and keep running; the record then lists the others.
182
+ """
183
+ agent = read_process_info(agent_process_id)
184
+ if agent is None:
185
+ return ActionResult(False, "the agent's process has ended"), None
186
+ was_suspended_by_hand = process_is_stopped(agent_process_id)
187
+ processes_below, other_users_process_ids_below = list_processes_below_the_agent_to_stop(agent_process_id)
188
+ if not was_suspended_by_hand:
189
+ await session.async_send_text(CONTROL_Z, suppress_broadcast=True)
190
+ if not await wait_until(lambda: process_is_stopped(agent_process_id), SECONDS_TO_WAIT_FOR_CONTROL_Z):
191
+ send_signal_to_processes([agent_process_id], signal.SIGTSTP)
192
+ if not await wait_until(lambda: process_is_stopped(agent_process_id), SECONDS_TO_WAIT_FOR_SIGTSTP):
193
+ send_signal_to_processes([agent_process_id], signal.SIGSTOP)
194
+ processes_started_meanwhile, other_users_process_ids_started_meanwhile = list_processes_below_the_agent_to_stop(
195
+ agent_process_id)
196
+ processes_below.update(processes_started_meanwhile)
197
+ other_users_process_ids_below = sorted(set(other_users_process_ids_below) | set(other_users_process_ids_started_meanwhile))
198
+ stopped_process_ids = set(send_signal_to_processes(sorted(processes_below), signal.SIGSTOP))
199
+ names_of_processes_left_running = sorted( # not those that ended meanwhile
200
+ [process.name for process_id, process in processes_below.items()
201
+ if process_id not in stopped_process_ids and read_process_info(process_id) is not None]
202
+ + [name for name in map(read_name_of_any_process, other_users_process_ids_below) if name])
203
+ text_around_the_cursor = None if was_suspended_by_hand else await read_the_shell_prompt(session, agent_process_id)
204
+ pause_record = PauseRecord((agent_process_id, agent.started_at), agent_tool_name, text_around_the_cursor, sorted(
205
+ (process_id, process.started_at) for process_id, process in processes_below.items() if process_id in stopped_process_ids))
206
+ if names_of_processes_left_running:
207
+ return ActionResult(False, "paused, but these processes below the agent run as another user (with sudo), so they "
208
+ "keep running: " + ", ".join(names_of_processes_left_running)), pause_record
209
+ return ActionResult(True), pause_record
210
+
211
+
212
+ async def find_reason_not_to_type_fg(session, agent_process_id, pause_record):
213
+ """Returns why typing `fg` into the tab isn't safe now, or "" when it is (module docstring).
214
+ Checked while everything is still stopped, so no output moves the prompt meanwhile."""
215
+ if pause_record is None or pause_record.text_around_the_cursor is None:
216
+ return ("the dashboard didn't see the shell's prompt after a pause (the agent was suspended with Ctrl+Z by "
217
+ "hand, or no prompt showed), so it can't tell whether something is typed there; type fg in the tab")
218
+ shell_process_id = find_the_shell_running_the_agent(agent_process_id)
219
+ if shell_process_id is None or not process_has_its_terminal(shell_process_id):
220
+ return ("another program is in front of the shell that runs the agent (a shell or tmux started in the tab, say), "
221
+ "so fg would go to it; leave that program and resume again")
222
+ if list_other_stopped_jobs_of_the_agents_shell(agent_process_id):
223
+ return "another job is suspended in the tab's shell, so fg might bring back that one; type jobs, then fg %N, in the tab"
224
+ if await read_text_around_the_cursor(session) != pause_record.text_around_the_cursor:
225
+ return ("the tab's shell line has changed since the pause (something typed there, or the prompt redrawn), "
226
+ "so typing fg could run something else; check the line and type fg there")
227
+ return ""
228
+
229
+
230
+ async def resume_agent_session(session, agent_process_id, pause_record):
231
+ """Types `fg` at the shell's prompt, after Ctrl+U (module docstring), which continues the
232
+ agent with the terminal back, then continues the processes the pause stopped below it. Types
233
+ nothing unless that is safe (find_reason_not_to_type_fg).
234
+
235
+ Args:
236
+ session: The tab's iterm2.Session.
237
+ agent_process_id: The agent's process.
238
+ pause_record: The PauseRecord of the agent's pause (kept across dashboard restarts), or
239
+ None for an agent suspended with Ctrl+Z by hand and never paused from the list.
240
+ """
241
+ if process_is_stopped(agent_process_id):
242
+ if process_has_its_terminal(agent_process_id):
243
+ # The shell didn't take the terminal back (a SIGSTOP it didn't notice): a SIGCONT is enough.
244
+ send_signal_to_processes([agent_process_id], signal.SIGCONT)
245
+ else:
246
+ reason_not_to_type_fg = await find_reason_not_to_type_fg(session, agent_process_id, pause_record)
247
+ if reason_not_to_type_fg:
248
+ return ActionResult(False, reason_not_to_type_fg)
249
+ await session.async_send_text(CONTROL_U + "fg\r", suppress_broadcast=True)
250
+ if not await wait_until(lambda: not process_is_stopped(agent_process_id), SECONDS_TO_WAIT_FOR_FG):
251
+ return ActionResult(False, "fg didn't bring the agent back; type jobs, then fg %N, in the tab")
252
+ if pause_record is not None:
253
+ continue_processes_stopped_at_pause(pause_record.stopped_processes)
254
+ return ActionResult(True)