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.
- agent_command_tab/__init__.py +4 -0
- agent_command_tab/agent_adapters/__init__.py +48 -0
- agent_command_tab/agent_adapters/base.py +162 -0
- agent_command_tab/agent_adapters/claude_code.py +120 -0
- agent_command_tab/agent_adapters/codex.py +102 -0
- agent_command_tab/agent_adapters/generic.py +22 -0
- agent_command_tab/agent_process_tree.py +557 -0
- agent_command_tab/agent_session_pausing.py +254 -0
- agent_command_tab/app_controller.py +947 -0
- agent_command_tab/claude_code_transcript_records.py +75 -0
- agent_command_tab/command_line.py +187 -0
- agent_command_tab/context_window_usage.py +230 -0
- agent_command_tab/dashboard_core_api.py +57 -0
- agent_command_tab/docked_window_frames_store.py +60 -0
- agent_command_tab/global_shortcut_key_filter.py +167 -0
- agent_command_tab/hook_event_forwarder.py +116 -0
- agent_command_tab/hook_event_tracking.py +129 -0
- agent_command_tab/hook_states_store.py +60 -0
- agent_command_tab/hooks_installer.py +300 -0
- agent_command_tab/installed_copy_paths.py +41 -0
- agent_command_tab/iterm2_actions.py +325 -0
- agent_command_tab/iterm2_connection_thread.py +2299 -0
- agent_command_tab/iterm2_snapshot_builder.py +403 -0
- agent_command_tab/list_sorting.py +117 -0
- agent_command_tab/messages_between_agent_sessions.py +78 -0
- agent_command_tab/monitor_assignment.py +109 -0
- agent_command_tab/pause_records_store.py +61 -0
- agent_command_tab/screen_readings.py +108 -0
- agent_command_tab/session_preview_computation.py +228 -0
- agent_command_tab/session_status_computation.py +235 -0
- agent_command_tab/settings_store.py +292 -0
- agent_command_tab/snapshot_data_classes.py +145 -0
- agent_command_tab/start_with_iterm2.py +138 -0
- agent_command_tab/tab_order_computation.py +26 -0
- agent_command_tab/user_interface/__init__.py +1 -0
- agent_command_tab/user_interface/agent_session_outline_view.py +2120 -0
- agent_command_tab/user_interface/agent_tool_icons.py +124 -0
- agent_command_tab/user_interface/app_icon.py +75 -0
- agent_command_tab/user_interface/control_helpers.py +38 -0
- agent_command_tab/user_interface/list_window.py +116 -0
- agent_command_tab/user_interface/menu_bar_status_item.py +193 -0
- agent_command_tab/user_interface/named_colors.py +58 -0
- agent_command_tab/user_interface/pointing_hand_button.py +42 -0
- agent_command_tab/user_interface/popover_container.py +461 -0
- agent_command_tab/user_interface/row_text_rendering.py +342 -0
- agent_command_tab/user_interface/screen_layout.py +91 -0
- agent_command_tab/user_interface/settings_window.py +530 -0
- agent_command_tab/user_interface/sidebar_panel.py +486 -0
- agent_command_tab/user_interface/sidebar_placement.py +105 -0
- agent_command_tab/user_interface/talk_to_each_other_alert.py +130 -0
- agent_command_tab/window_list_ordering.py +44 -0
- agent_command_tab-0.1.0.dist-info/METADATA +85 -0
- agent_command_tab-0.1.0.dist-info/RECORD +57 -0
- agent_command_tab-0.1.0.dist-info/WHEEL +5 -0
- agent_command_tab-0.1.0.dist-info/entry_points.txt +2 -0
- agent_command_tab-0.1.0.dist-info/licenses/LICENSE +21 -0
- 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)
|