@yahyahammad/venastine 0.1.0 → 0.3.8

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 (130) hide show
  1. package/.env.example +19 -14
  2. package/CONFIG_ARCHITECTURE.md +2002 -0
  3. package/NOTICE +1 -1
  4. package/README.md +249 -93
  5. package/agents/builtin/build.md +73 -0
  6. package/agents/builtin/general.md +80 -0
  7. package/agents/builtin/plan.md +23 -5
  8. package/agents/builtin/test.md +65 -0
  9. package/agents/builtin/writer.md +67 -0
  10. package/agents/manager.py +261 -195
  11. package/agents/subagent_tool.py +280 -23
  12. package/agents/tui_commands.py +31 -21
  13. package/bin/venastine.mjs +528 -382
  14. package/bin/venastine.py +71 -0
  15. package/cli_commands.py +835 -0
  16. package/config.py +95 -1198
  17. package/config.yaml +1090 -0
  18. package/config_edit.py +1301 -0
  19. package/config_schema.py +966 -0
  20. package/config_update.py +749 -0
  21. package/core/agent_activity.py +256 -0
  22. package/core/ansi.py +452 -0
  23. package/core/approval.py +27 -5
  24. package/core/call_view.py +364 -0
  25. package/core/cancel.py +121 -0
  26. package/core/chatgpt_auth.py +747 -0
  27. package/core/claims_view.py +107 -0
  28. package/core/client.py +1249 -82
  29. package/core/commands.py +454 -0
  30. package/core/compaction.py +1735 -959
  31. package/core/config_loader.py +516 -97
  32. package/core/connect.py +686 -0
  33. package/core/events.py +68 -6
  34. package/core/file_mentions.py +280 -0
  35. package/core/interaction.py +87 -4
  36. package/core/line_pattern.py +128 -0
  37. package/core/loop.py +2566 -1353
  38. package/core/memory.py +482 -370
  39. package/core/pipeline_models.py +23 -9
  40. package/core/provider_errors.py +234 -0
  41. package/core/reasoning/confidence_scoring.py +70 -54
  42. package/core/reasoning/json_retry.py +19 -1
  43. package/core/reasoning/orchestrator.py +232 -53
  44. package/core/reasoning/output_writer.py +90 -31
  45. package/core/reasoning/payload_validation.py +133 -7
  46. package/core/reasoning/pipeline_storage.py +427 -361
  47. package/core/reasoning/review.py +659 -615
  48. package/core/reasoning/scholar.py +38 -14
  49. package/core/reasoning/source_corpus.py +110 -4
  50. package/core/replay.py +315 -167
  51. package/core/session.py +36 -12
  52. package/core/session_view.py +259 -0
  53. package/core/session_wake.py +259 -0
  54. package/core/shell_sessions.py +1553 -0
  55. package/core/workspace_trust.py +1 -1
  56. package/credentials.py +308 -180
  57. package/database.py +82 -1
  58. package/{PRIVACY.md → docs/PRIVACY.md} +19 -7
  59. package/docs/SECURITY.md +108 -0
  60. package/docs/THIRD_PARTY_NOTICES.md +148 -0
  61. package/env_secrets.py +118 -77
  62. package/json_store.py +236 -16
  63. package/logging_setup.py +121 -11
  64. package/main.py +1672 -198
  65. package/mcp_client/client.py +257 -23
  66. package/mcp_client/config.py +484 -379
  67. package/mcp_client/registration.py +163 -2
  68. package/memories/manager.py +15 -0
  69. package/memories/tui_commands.py +21 -14
  70. package/package.json +303 -73
  71. package/project_init/config_files.py +4 -0
  72. package/project_init/generator.py +201 -37
  73. package/project_init/manifest.py +418 -406
  74. package/project_init/tui_commands.py +7 -4
  75. package/prompts/revalidate.md +1 -1
  76. package/prompts/revise.md +17 -15
  77. package/prompts/system_prompts.py +64 -10
  78. package/providers.json.example +94 -92
  79. package/pyproject.toml +149 -100
  80. package/requirements.txt +252 -29
  81. package/safety/policy_enforcement.py +1082 -682
  82. package/security/askpass.py +419 -0
  83. package/security/capability.py +37 -7
  84. package/security/confine.py +484 -0
  85. package/security/hosted.py +182 -0
  86. package/security/permissions.py +54 -7
  87. package/security/posture.py +124 -12
  88. package/security/protected_paths.py +198 -6
  89. package/security/sandbox.py +3262 -139
  90. package/security/secrets.py +855 -0
  91. package/skills/tui_commands.py +3 -4
  92. package/storage.py +1338 -1005
  93. package/tools/base.py +465 -305
  94. package/tools/builtin/_math_common.py +306 -16
  95. package/tools/builtin/_net_common.py +267 -61
  96. package/tools/builtin/arxiv.py +681 -223
  97. package/tools/builtin/ask_user.py +231 -213
  98. package/tools/builtin/discrete_math.py +35 -4
  99. package/tools/builtin/fetch_url.py +239 -21
  100. package/tools/builtin/file_ops.py +341 -33
  101. package/tools/builtin/geometry.py +184 -148
  102. package/tools/builtin/get_time.py +2 -2
  103. package/tools/builtin/linear_algebra.py +66 -23
  104. package/tools/builtin/load_skill.py +10 -0
  105. package/tools/builtin/logic.py +171 -12
  106. package/tools/builtin/pin.py +46 -12
  107. package/tools/builtin/probability_stats.py +224 -228
  108. package/tools/builtin/project_docs.py +80 -21
  109. package/tools/builtin/remember.py +21 -4
  110. package/tools/builtin/shell.py +586 -67
  111. package/tools/builtin/shell_sessions.py +613 -0
  112. package/tools/builtin/symbolic_math.py +80 -10
  113. package/tools/builtin/todo.py +5 -3
  114. package/tools/builtin/web_search.py +329 -151
  115. package/tools/context.py +23 -0
  116. package/tools/isolation.py +387 -314
  117. package/tools/registry.py +374 -29
  118. package/tui/app.py +5281 -397
  119. package/tui/app.tcss +290 -9
  120. package/tui/commands.py +26 -61
  121. package/tui/diffs.py +286 -265
  122. package/tui/history.py +128 -0
  123. package/tui/hosted_driver.py +102 -0
  124. package/tui/markdown.py +1329 -0
  125. package/tui/meters.py +364 -0
  126. package/tui/screens.py +346 -92
  127. package/tui/themes.py +599 -366
  128. package/tui/widgets.py +2673 -116
  129. package/SECURITY.md +0 -88
  130. package/THIRD_PARTY_NOTICES.md +0 -100
@@ -0,0 +1,1553 @@
1
+ """
2
+ core/shell_sessions.py
3
+
4
+ ROADMAP_v3 §49, slices 1 and 2. Shell sessions: commands that keep running
5
+ after the tool call that started them has been answered, and the one object
6
+ that knows about all of them.
7
+
8
+ THREE KINDS. `background` and `monitor` are slice 1's -- started, watched,
9
+ reported when they end. `interactive` is slice 2's: a shell held open with
10
+ a pty that the agent TYPES INTO, whose state survives across its own turns.
11
+ It differs in four places and nowhere else: its stdin is a pipe, its output
12
+ passes through `core/ansi.py` first, it does not block the user's prompt
13
+ (SS25), and its end is HELD rather than woken for (SS31).
14
+
15
+ WHY IN core/. The TUI, the CLI and a sleeping subagent all consume what a
16
+ session produces, and D12 keeps the CLI a permanent fallback -- so the
17
+ lifecycle cannot live in tui/, and it is not a tool's to own either: three
18
+ tools read and write the same sessions. Nothing here imports storage or a
19
+ widget.
20
+
21
+ WHAT THIS OWNS: lifecycle (start, supervise, time out, kill, close); the
22
+ process-wide cap (SS12); each session's output, head and tail, in memory
23
+ only; monitor matching on the live stream (SS8); and each owning thread's
24
+ INBOX of results waiting to wake it (SS2, SS5, SS7, SS19, SS20).
25
+
26
+ WHAT IT DOES NOT: write rows or build the wake text (core/session_wake.py
27
+ does both, through the real output policy), or decide to start a turn. The
28
+ consumers -- the TUI, the CLI chat loop, a subagent asleep in its spawn --
29
+ take what is waiting and decide.
30
+
31
+ THREADS, NOT ASYNCIO (NA10). Each session has a SUPERVISOR (waits for the
32
+ process, kills it at its timeout, finalises the state) and a READER (reads
33
+ merged output, feeds the buffer, matches lines). A monitor pattern is matched
34
+ on the reader thread and outside every lock; re2 releases the GIL.
35
+
36
+ LOCKING, NA16's SHAPE. One lock guards the session table, the inboxes and
37
+ the closing flag, with a Condition over it for waiters. Each output buffer
38
+ has its own lock, and the order is always manager then buffer. The sink is
39
+ called with a SNAPSHOT and OUTSIDE the lock, so a sink that reads back into
40
+ the manager cannot deadlock it and the UI thread never holds a list a
41
+ supervisor is still writing.
42
+ """
43
+
44
+ from __future__ import annotations
45
+
46
+ import codecs
47
+ import contextvars
48
+ import itertools
49
+ import logging
50
+ import threading
51
+ import time
52
+ from collections import deque
53
+ from collections.abc import Callable
54
+ from contextlib import contextmanager
55
+ from dataclasses import dataclass, field
56
+ from typing import Optional
57
+
58
+ import config
59
+ from core import agent_activity
60
+ from core.ansi import PtyStream
61
+ from core.line_pattern import compile_pattern, validate
62
+ from safety.policy_enforcement import (
63
+ TOKEN_CHARS,
64
+ fragment_end,
65
+ fragment_start,
66
+ redact_output_text,
67
+ )
68
+
69
+ logger = logging.getLogger(__name__)
70
+
71
+ KIND_BACKGROUND = "background"
72
+ KIND_MONITOR = "monitor"
73
+ KIND_INTERACTIVE = "interactive"
74
+
75
+ # The kinds whose being live BLOCKS the user's prompt (SS2). Not the same
76
+ # question as which kinds occupy the 4-live cap, which is all of them: the
77
+ # cap is about resources, which an idle shell does hold, and the block is
78
+ # about whether the agent is waiting on work it cannot proceed without,
79
+ # which for an idle REPL it is not (SS25). One list, two questions, and
80
+ # `_live_locked` takes the kinds so neither caller can drift into the
81
+ # other's answer.
82
+ BLOCKING_KINDS = frozenset({KIND_BACKGROUND, KIND_MONITOR})
83
+
84
+ STARTING = "starting"
85
+ RUNNING = "running"
86
+ EXITED = "exited"
87
+ TIMED_OUT = "timed_out"
88
+ KILLED = "killed"
89
+ FAILED = "failed"
90
+ LIVE_STATES = frozenset({STARTING, RUNNING})
91
+
92
+ # The one wake shape that is not a terminal state: a monitor line matched and
93
+ # the session is still running (SS7). The other shapes are the states above.
94
+ SHAPE_MATCHED = "matched"
95
+
96
+ KILL_MODEL = "model"
97
+ KILL_USER = "user"
98
+ KILL_QUIT = "quit"
99
+ KILL_OWNER_FAILED = "owner_failed"
100
+ KILL_WAKE_LIMIT = "wake_limit"
101
+ KILL_IDLE = "idle"
102
+ KILL_OPEN_FAILED = "open_failed"
103
+
104
+
105
+ class _AnyOwner:
106
+ """The type of ANY_OWNER, for a legible repr in a traceback."""
107
+
108
+ __slots__ = ()
109
+
110
+ def __repr__(self) -> str: # pragma: no cover - repr
111
+ return "ANY_OWNER"
112
+
113
+
114
+ #: "Do not check ownership" -- the AUTHORITY OF THE USER OR THE HARNESS, said
115
+ #: out loud (TECHNICAL_DEBT 29, batch 110).
116
+ #:
117
+ #: This used to be spelled `None`, which is the value a thread id takes when
118
+ #: something forgot to supply one. `_owned_locked` read it as "any session
119
+ #: matches" and `list_for` eleven lines below read the same value as "no
120
+ #: session matches" -- one value, two opposite readings, in two functions
121
+ #: that answer the same question. Both are now the second reading, and a
122
+ #: caller that means to skip the check has to say so.
123
+ #:
124
+ #: Nothing reachable from the tools can pass this: `shell_input`,
125
+ #: `shell_output` and `shell_kill` all hand over `memory.thread_id`, and the
126
+ #: whole ownership story in tools/builtin/shell_sessions.py is that a model
127
+ #: which could NAME a thread could reach another conversation's sessions.
128
+ #: That story rested on `memory.thread_id` never being None, which is a
129
+ #: property of another module and was asserted nowhere.
130
+ ANY_OWNER = _AnyOwner()
131
+
132
+ # What an interactive session may be typed at, and how it is waited on.
133
+ # The control names are the agent's vocabulary; the bytes are the pty's.
134
+ CONTROLS = {"interrupt": "\x03", "eof": "\x04"}
135
+
136
+ # Measured, batch 100. A pty in canonical mode accepts 4095 bytes on one
137
+ # line and SILENTLY DROPS the rest -- the shell then runs a truncated
138
+ # command and reports success. So a longer input is REFUSED here rather
139
+ # than half-executed: a command the user approved must not be edited by a
140
+ # terminal driver on its way in.
141
+ MAX_INPUT_BYTES = 4000
142
+
143
+ # What each of SS26's four bounds MEANS, carried in the result beside the
144
+ # name. The distinction the agent has to act on is that only `ready` says a
145
+ # command finished -- `quiet` is silence, which a running command produces
146
+ # just as well as a finished one, and that ambiguity is why SS34 exists.
147
+ _ENDED_MEANING = {
148
+ "ready": ("the shell returned to its prompt, so the command finished; "
149
+ "anything you sent has run"),
150
+ "matched": ("a line matched wait_for; the command may still be running, "
151
+ "so send again with no text to keep reading"),
152
+ "quiet": ("output stopped arriving, which does NOT mean the command "
153
+ "finished -- send again with no text to keep waiting"),
154
+ "bound": ("wait_s ran out without the shell coming back to its prompt. "
155
+ "Whatever you sent is still running and its output is still "
156
+ "being collected -- send again with no text to keep reading, "
157
+ "or control \"interrupt\" to stop it"),
158
+ "ended": "the session itself ended while waiting",
159
+ }
160
+
161
+ # A pty in canonical mode holds this many bytes on one line, measured.
162
+ _PTY_LINE_LIMIT = 4095
163
+ # How much new output one poll pulls back to run a wait_for pattern over.
164
+ _MATCH_SLICE = 65_536
165
+
166
+ # The round trip through the container was measured at about 50 ms, so a
167
+ # third of a second of silence is quiet rather than slow.
168
+ _INPUT_QUIET_S = 0.3
169
+ _INPUT_POLL_S = 0.02
170
+ # How long a shell gets to reach its first prompt before the open fails.
171
+ # Measured at 0.43 s; this is that with room for a cold image.
172
+ _OPEN_BOUND_S = 30.0
173
+
174
+ MAX_MATCHED_LINES = 50
175
+ _MAX_LINE_CHARS = 16_000
176
+ _READ_CHUNK = 65_536
177
+ _FINISHED_KEPT = 20
178
+ _KILL_SETTLE_S = 15
179
+ # How much of a finished session's output the sandbox's credential
180
+ # quarantine is shown (`SessionProcess.note_exit`). A refused login or
181
+ # sudo password is the first thing a session prints, because nothing
182
+ # else has run yet; this is that with room for an SSH banner.
183
+ _AUTH_SCAN_CHARS = 4096
184
+
185
+
186
+ class SessionRefused(Exception):
187
+ """A start the manager will not make. The message is what the agent is
188
+ told, so it says what to do next."""
189
+
190
+
191
+ # ---------------------------------------------------------------------------
192
+ # ---- Who can be woken (SS17) -----------------------------------------------
193
+ # ---------------------------------------------------------------------------
194
+
195
+ # Set around a run that something will WAKE when its sessions finish: the TUI
196
+ # chat turn, the CLI chat loop, a subagent run. A ContextVar rather than a
197
+ # registry of thread ids, because the question is asked by a tool's
198
+ # refusal_check, which is handed params and a ToolContext and never learns
199
+ # which thread it runs on -- and a ContextVar follows the run into the NA10
200
+ # pool, which submits through copy_context().
201
+ _CONSUMING: contextvars.ContextVar[bool] = contextvars.ContextVar(
202
+ "shell_session_consumer", default=False)
203
+
204
+
205
+ @contextmanager
206
+ def consuming():
207
+ """Mark the code inside as a run whose sessions will be woken for."""
208
+ token = _CONSUMING.set(True)
209
+ try:
210
+ yield
211
+ finally:
212
+ _CONSUMING.reset(token)
213
+
214
+
215
+ def has_consumer() -> bool:
216
+ """Whether the current run can be woken. A research pass cannot, and
217
+ under `shell_approval_mode: never` nothing else would stop it starting a
218
+ session that no one would ever report (ROADMAP_v3 §49, SS17)."""
219
+ return _CONSUMING.get()
220
+
221
+
222
+ # ---------------------------------------------------------------------------
223
+ # ---- Output ------------------------------------------------------------------
224
+ # ---------------------------------------------------------------------------
225
+
226
+
227
+ class OutputBuffer:
228
+ """A session's output: the first `head_chars` and the most recent
229
+ `tail_chars`, in memory only (SS12). Offsets are ABSOLUTE character
230
+ positions in everything the program wrote, so a page that falls in the
231
+ dropped middle can say exactly which span is gone."""
232
+
233
+ def __init__(self, head_chars: int, tail_chars: int) -> None:
234
+ self._head_chars = head_chars
235
+ self._tail_chars = tail_chars
236
+ self._lock = threading.Lock()
237
+ self._head: list[str] = []
238
+ self._head_len = 0
239
+ self._tail: deque[str] = deque()
240
+ self._tail_len = 0
241
+ self.total = 0
242
+ # The character on the FAR side of each cut the dropped middle
243
+ # makes: the first one the head had no room for, and the last one
244
+ # evicted from the tail. One character each, because all a reader
245
+ # needs to know is whether the cut fell inside a word -- see
246
+ # `_cut_fragments` (TECHNICAL_DEBT 95, batch 160).
247
+ self._after_head = ""
248
+ self._before_tail = ""
249
+
250
+ def append(self, text: str) -> None:
251
+ if not text:
252
+ return
253
+ with self._lock:
254
+ self.total += len(text)
255
+ room = self._head_chars - self._head_len
256
+ if room > 0:
257
+ part = text[:room]
258
+ self._head.append(part)
259
+ self._head_len += len(part)
260
+ text = text[room:]
261
+ if not text:
262
+ return
263
+ if not self._after_head:
264
+ self._after_head = text[0]
265
+ self._tail.append(text)
266
+ self._tail_len += len(text)
267
+ excess = self._tail_len - self._tail_chars
268
+ while excess > 0 and self._tail:
269
+ first = self._tail[0]
270
+ if len(first) <= excess:
271
+ self._tail.popleft()
272
+ self._tail_len -= len(first)
273
+ excess -= len(first)
274
+ self._before_tail = first[-1]
275
+ else:
276
+ self._tail[0] = first[excess:]
277
+ self._tail_len -= excess
278
+ self._before_tail = first[excess - 1]
279
+ excess = 0
280
+
281
+ def _parts(self) -> tuple[str, str, int]:
282
+ with self._lock:
283
+ return "".join(self._head), "".join(self._tail), self.total
284
+
285
+ def _cut_parts(self) -> tuple[str, str, int]:
286
+ """`_parts()`, with the word each side of a dropped middle moved
287
+ into it (TECHNICAL_DEBT 95, batch 160).
288
+
289
+ THE ONE CUT THE REDACTOR CANNOT BE PUT ABOVE. The middle is
290
+ discarded as it arrives, so a credential that straddled the
291
+ eviction point has one half at the end of the head and the other
292
+ at the start of the tail, with nothing between them this process
293
+ ever kept -- each page clean on its own, the pair a leak, and the
294
+ model can ask for both. So the fragments go: the token-character
295
+ run at the head's end, if the character after it is one too, and
296
+ the run at the tail's start, if the character before it was. A cut
297
+ that fell between two words moves nothing.
298
+
299
+ THE GAP GROWS BY WHAT MOVED, and its arithmetic stays the reader's:
300
+ `total` is unchanged, so `page()`'s gap runs from where the shown
301
+ head ends to where the shown tail starts. Raw characters, like the
302
+ rest of the gap -- this runs before any redaction.
303
+
304
+ For the model and the display only. The MONITOR's raw view keeps
305
+ every character it was given, since it matches on raw output by
306
+ design.
307
+ """
308
+ with self._lock:
309
+ head, tail = "".join(self._head), "".join(self._tail)
310
+ total, after, before = (self.total, self._after_head,
311
+ self._before_tail)
312
+ if total - len(tail) <= len(head):
313
+ return head, tail, total
314
+ return (head[:fragment_end(head) if after in TOKEN_CHARS
315
+ else len(head)],
316
+ tail[fragment_start(tail) if before in TOKEN_CHARS
317
+ else 0:],
318
+ total)
319
+
320
+ def page(self, offset: int, limit: int, clean=None) -> dict:
321
+ """Up to *limit* characters from *offset*, never across the gap.
322
+
323
+ `clean` is a text redactor, and passing one is how a caller that
324
+ shows a page TO THE MODEL obeys A23: the parts are redacted before
325
+ the page is cut out of them, so a credential straddling a page
326
+ boundary is replaced while it is still one string. Measured, with
327
+ the redactor running after the cut instead: all seven credential
328
+ shapes this deployment knows arrive whole across two adjacent pages,
329
+ because the model asks for the second one itself and holds both
330
+ halves -- including the fixed-length vendor tokens, which every
331
+ other cut site survives. Omitting `clean` gives the raw text, which
332
+ is what the MONITOR's own search wants (it matches on raw output by
333
+ design) and what the buffer's tests read.
334
+
335
+ THE OFFSETS THEN DESCRIBE THE REDACTED DOCUMENT, which is RB3's rule
336
+ rather than a compromise: every offset a surface speaks is a position
337
+ in the text the reader was given. `[REDACTED]` is shorter than what
338
+ it replaces, so the two coordinate systems genuinely differ -- 210
339
+ characters apart on a measured 120,000-character buffer.
340
+ """
341
+ head, tail, total = (self._parts() if clean is None
342
+ else self._cleaned_parts(clean))
343
+ tail_start = total - len(tail)
344
+ gap = ({"from": len(head), "to": tail_start}
345
+ if tail_start > len(head) else None)
346
+ offset = max(0, int(offset))
347
+ page: dict = {"total_chars": total}
348
+ if offset < len(head):
349
+ text = head[offset:offset + limit]
350
+ end = offset + len(text)
351
+ next_offset = tail_start if (gap and end >= len(head)) else end
352
+ if gap and end >= len(head):
353
+ page["gap"] = gap
354
+ elif gap and offset < tail_start:
355
+ page["gap"] = gap
356
+ text = tail[:limit]
357
+ offset = tail_start
358
+ next_offset = tail_start + len(text)
359
+ else:
360
+ start = offset - tail_start
361
+ text = tail[start:start + limit]
362
+ next_offset = offset + len(text)
363
+ page.update(offset=offset, text=text, next_offset=next_offset,
364
+ more=next_offset < total)
365
+ return page
366
+
367
+ def _cleaned_parts(self, clean) -> tuple[str, str, int]:
368
+ """The three facts page() pages over, with the redactor run FIRST.
369
+
370
+ ONE STRING WHEREVER THIS BUFFER HOLDS ONE. With nothing evicted the
371
+ head and the tail are adjacent, so they are redacted JOINED --
372
+ otherwise the head/tail seam is one more cut the redactor cannot see
373
+ across, and that seam sits at 10,000 characters on every session,
374
+ which is inside the first page of every read.
375
+
376
+ THE DROPPED MIDDLE IS THE CUT NOTHING CAN REPAIR, and it is the
377
+ honest limit of A23 here: half of a credential that straddled it was
378
+ never kept by this process, so no later pass can rejoin it. A stream
379
+ has no "whole document" to redact exactly once; what a layer can do
380
+ is redact the largest string it holds before making its own cut, and
381
+ say where the one it cannot cross is. So the two halves are not
382
+ SHOWN instead (batch 160): `_cut_parts` moves the word each side of
383
+ the gap into it, and what remains is two strings that each begin and
384
+ end at a word. The gap's own size stays in RAW characters -- it
385
+ counts what the program wrote and we do not have.
386
+
387
+ AND IT RUNS OUTSIDE THE LOCK. `_parts()` copies and returns, so the
388
+ redaction happens on strings nothing else holds -- which matters
389
+ because the pty reader thread is appending to this buffer while a
390
+ model-facing read is being built, and 6.5ms (measured, on a full
391
+ 200,000-character buffer) under the lock would stall it for exactly
392
+ that long on every `shell_output` call.
393
+ """
394
+ head, tail, total = self._cut_parts()
395
+ dropped = total - len(head) - len(tail)
396
+ if dropped > 0:
397
+ head, tail = clean(head), clean(tail)
398
+ return head, tail, len(head) + dropped + len(tail)
399
+ joined = clean(head + tail)
400
+ return joined, "", len(joined)
401
+
402
+ def last(self, chars: Optional[int] = None) -> tuple[str, bool]:
403
+ """The most recent *chars* characters kept, and whether anything the
404
+ program wrote before them is missing from what is returned.
405
+
406
+ NO ARGUMENT MEANS EVERY CONTIGUOUS CHARACTER THIS BUFFER HOLDS,
407
+ which is what a caller needs when the redactor has to see the text
408
+ before anything cuts it (ROADMAP_v3 §65 A23). The selection is the
409
+ same either way: with a dropped middle only the tail is returned,
410
+ because head + tail would splice two spans that are not adjacent
411
+ and present the join as continuous output.
412
+
413
+ AND THE TAIL STARTS AT A WORD (TECHNICAL_DEBT 95, batch 160): every
414
+ caller shows this to the model or draws it, so the fragment a
415
+ dropped middle leaves at the tail's start is moved into what is
416
+ missing, as `page()` does -- see `_cut_parts`.
417
+ """
418
+ head, tail, total = self._cut_parts()
419
+ kept = tail if total - len(tail) > len(head) else head + tail
420
+ if chars is None:
421
+ text = kept
422
+ else:
423
+ text = kept[-chars:] if chars > 0 else ""
424
+ return text, len(text) < total
425
+
426
+
427
+ # ---------------------------------------------------------------------------
428
+ # ---- Records ---------------------------------------------------------------
429
+ # ---------------------------------------------------------------------------
430
+
431
+
432
+ @dataclass
433
+ class WakeEvent:
434
+ """One session's contribution to one wake. Coalesced per session: a
435
+ monitor that matched ten lines before the wake was taken is ONE event
436
+ with ten lines, and a finish folds any untaken matches into itself."""
437
+
438
+ session_id: str
439
+ call_id: str
440
+ kind: str
441
+ command: str
442
+ shape: str
443
+ lines: list[str] = field(default_factory=list)
444
+ match_count: int = 0
445
+ return_code: Optional[int] = None
446
+ elapsed_s: float = 0.0
447
+ ran_on: str = ""
448
+ tier: str = ""
449
+ kill_reason: str = ""
450
+ output_tail: str = ""
451
+ output_truncated: bool = False
452
+ # What a monitor was watching for, and the timeout it ran under -- so a
453
+ # wake can say "matched `FAILED`" and "stopped at its 600s timeout"
454
+ # without asking the manager for a session it may have pruned.
455
+ pattern: Optional[str] = None
456
+ timeout_s: int = 0
457
+
458
+
459
+ @dataclass(frozen=True)
460
+ class SessionRow:
461
+ """A snapshot of one session, for a panel or a view. Frozen and copied,
462
+ never the live object (NA16)."""
463
+
464
+ id: str
465
+ kind: str
466
+ command: str
467
+ rationale: str
468
+ pattern: Optional[str]
469
+ owner_thread: str
470
+ owner_agent: Optional[str]
471
+ owner_depth: int
472
+ owner_span_id: Optional[str]
473
+ call_id: str
474
+ state: str
475
+ started_wall: float
476
+ timeout_s: int
477
+ match_count: int
478
+ output_chars: int
479
+ ran_on: str
480
+ tier: str
481
+ return_code: Optional[int]
482
+
483
+
484
+ @dataclass
485
+ class _Session:
486
+ id: str
487
+ kind: str
488
+ command: str
489
+ rationale: str
490
+ pattern: Optional[str]
491
+ owner_thread: str
492
+ owner_agent: Optional[str]
493
+ owner_depth: int
494
+ owner_span_id: Optional[str]
495
+ call_id: str
496
+ requested_timeout_s: int
497
+ timeout_s: int
498
+ capped: bool
499
+ output: OutputBuffer
500
+ matcher: object = None
501
+ started_mono: float = 0.0
502
+ started_wall: float = 0.0
503
+ finished_mono: Optional[float] = None
504
+ state: str = STARTING
505
+ process: object = None
506
+ ran_on: str = ""
507
+ tier: str = ""
508
+ return_code: Optional[int] = None
509
+ kill_reason: str = ""
510
+ timed_out: bool = False
511
+ match_count: int = 0
512
+ # Interactive only. `pty` strips escape sequences and takes the
513
+ # prompt token back out (SS27, SS34); `last_input_mono` is what the
514
+ # idle deadline is measured from (SS25).
515
+ prompt_token: str = ""
516
+ pty: object = None
517
+ last_input_mono: float = 0.0
518
+ # The agent's own kill takes the finish as its RESULT instead of a wake
519
+ # (`kill`). Claimed and released under the manager lock, which `_finish`
520
+ # also holds when it reads the claim.
521
+ kill_report_claimed: bool = False
522
+ final_event: Optional[WakeEvent] = None
523
+
524
+ def row(self) -> SessionRow:
525
+ return SessionRow(
526
+ id=self.id, kind=self.kind, command=self.command,
527
+ rationale=self.rationale, pattern=self.pattern,
528
+ owner_thread=self.owner_thread, owner_agent=self.owner_agent,
529
+ owner_depth=self.owner_depth, owner_span_id=self.owner_span_id,
530
+ call_id=self.call_id, state=self.state,
531
+ started_wall=self.started_wall, timeout_s=self.timeout_s,
532
+ match_count=self.match_count, output_chars=self.output.total,
533
+ ran_on=self.ran_on, tier=self.tier, return_code=self.return_code)
534
+
535
+
536
+ @dataclass
537
+ class _Inbox:
538
+ events: list[WakeEvent] = field(default_factory=list)
539
+ held: list[WakeEvent] = field(default_factory=list)
540
+ consecutive_wakes: int = 0
541
+ suspended: bool = False
542
+
543
+
544
+ class SessionActivity:
545
+ """The sink a shell supplies. The base class is the null sink.
546
+
547
+ `changed` receives every session row after anything moved; `wake_ready`
548
+ says a thread has results waiting. Both are called OUTSIDE the manager's
549
+ lock, and a raise inside either is contained: display machinery must not
550
+ fail the session it describes (core/agent_activity.py's rule)."""
551
+
552
+ def changed(self, rows: list[SessionRow]) -> None:
553
+ pass
554
+
555
+ def wake_ready(self, thread_id: str) -> None:
556
+ pass
557
+
558
+
559
+ NULL_SINK = SessionActivity()
560
+
561
+
562
+ # ---------------------------------------------------------------------------
563
+ # ---- The manager -------------------------------------------------------------
564
+ # ---------------------------------------------------------------------------
565
+
566
+
567
+ def _default_starter(*args, **kwargs):
568
+ from security import sandbox
569
+ # An interactive session is the one shape `start_sandboxed` cannot
570
+ # serve: it needs a stdin pipe, the pty wrapper, and the container
571
+ # route or nothing (SS28). The kwarg is only ever passed for that
572
+ # kind, so a slice-1 fake starter sees the call it always saw.
573
+ if kwargs.get("prompt_token"):
574
+ kwargs.pop("command", None)
575
+ args = args[1:] # the command is typed in, not run
576
+ return sandbox.start_interactive(*args, **kwargs)
577
+ return sandbox.start_sandboxed(*args, **kwargs)
578
+
579
+
580
+
581
+ def _new_prompt_token() -> str:
582
+ """One interactive session's prompt token (SS34).
583
+
584
+ Imported lazily for `_default_starter`'s reason: core must not import
585
+ the sandbox at module scope. Minted THERE rather than here because the
586
+ token and the shell string that embeds it are one decision, and the
587
+ character set is what makes that embedding safe.
588
+ """
589
+ from security import sandbox
590
+ return sandbox.new_prompt_token()
591
+
592
+
593
+ class SessionManager:
594
+ """Every background and monitor session in this process."""
595
+
596
+ def __init__(self, starter: Optional[Callable] = None, *,
597
+ clock: Callable[[], float] = time.monotonic,
598
+ wall_clock: Callable[[], float] = time.time,
599
+ poll_s: float = 0.5) -> None:
600
+ self._starter = starter or _default_starter
601
+ self._clock = clock
602
+ self._wall_clock = wall_clock
603
+ self._poll_s = poll_s
604
+ self._lock = threading.Lock()
605
+ self._changed = threading.Condition(self._lock)
606
+ self._sessions: dict[str, _Session] = {}
607
+ self._inboxes: dict[str, _Inbox] = {}
608
+ self._ids = itertools.count(1)
609
+ self._closing = False
610
+ self._sink: SessionActivity = NULL_SINK
611
+
612
+ # -- configuration ---------------------------------------------------------
613
+
614
+ def set_sink(self, sink: Optional[SessionActivity]) -> None:
615
+ self._sink = sink or NULL_SINK
616
+
617
+ @property
618
+ def sink(self) -> SessionActivity:
619
+ """Who is being told, so a shell can drop ITS OWN registration
620
+ without dropping a later one's. The manager is a module
621
+ singleton and a shell is not: an app tearing down unconditionally
622
+ would silence whatever mounted after it."""
623
+ return self._sink
624
+
625
+ @staticmethod
626
+ def effective_timeout(requested: int) -> tuple[int, bool]:
627
+ """(the timeout a session runs with, whether the cap applied) --
628
+ THE clamp (SS13). Nothing else compares against the cap."""
629
+ cap = int(config.SHELL_SESSION_TIMEOUT_CAP_S)
630
+ requested = int(requested)
631
+ return (cap, True) if requested > cap else (requested, False)
632
+
633
+ # -- starting --------------------------------------------------------------
634
+
635
+ def start_refusal(self, kind: str, pattern: Optional[str] = None,
636
+ owner_thread=None) -> Optional[str]:
637
+ """Why a start would be refused, or None. Asked BEFORE approval by
638
+ the tools' refusal_check (§32 A7) and again inside `start`."""
639
+ if not has_consumer():
640
+ return ("Background sessions can only be started from a chat "
641
+ "turn or a subagent -- something that is woken when they "
642
+ "finish. This run cannot be.")
643
+ if kind == KIND_MONITOR:
644
+ reason = validate(pattern)
645
+ if reason is not None:
646
+ return (f"Invalid pattern: {reason}. Patterns use RE2 syntax: "
647
+ f"no backreferences or lookaround.")
648
+ with self._lock:
649
+ return self._capacity_refusal_locked(owner_thread)
650
+
651
+ def _capacity_refusal_locked(self, owner_thread) -> Optional[str]:
652
+ if self._closing:
653
+ return "The harness is quitting; no new sessions can start."
654
+ cap = int(config.SHELL_SESSION_MAX_LIVE)
655
+ live = [s for s in self._sessions.values() if s.state in LIVE_STATES]
656
+ if len(live) < cap:
657
+ return None
658
+ # With no owner -- the tools' pre-approval check, which is handed
659
+ # params and a context and never learns the thread -- say only what
660
+ # is true of every caller.
661
+ yours = [s.id for s in live if s.owner_thread == str(owner_thread)]
662
+ if owner_thread is None:
663
+ mine = (" List yours with shell_sessions and stop one with "
664
+ "shell_kill, or wait for one to finish.")
665
+ elif yours:
666
+ mine = (f" Yours: {', '.join(yours)}; stop one with shell_kill, "
667
+ f"or wait for one to finish.")
668
+ else:
669
+ mine = (" None of them is this conversation's, so wait for one "
670
+ "to finish.")
671
+ return (f"{len(live)} background sessions are already running, which "
672
+ f"is the limit, shared with any subagents.{mine}")
673
+
674
+ def start(self, *, kind: str, command: str, profile, docker_available: bool,
675
+ requested_timeout_s: int, owner_thread, workspace_dir: str,
676
+ call_id: str = "", rationale: str = "",
677
+ pattern: Optional[str] = None,
678
+ open_wait_s: float = 10.0,
679
+ backend: str = "container",
680
+ needs_root: bool = False) -> dict:
681
+ """Start a session and return what the agent is told. Raises
682
+ SessionRefused with the reason, or the backend's SandboxUnavailable."""
683
+ refusal = self.start_refusal(kind, pattern, owner_thread)
684
+ if refusal:
685
+ raise SessionRefused(refusal)
686
+ timeout_s, capped = self.effective_timeout(requested_timeout_s)
687
+ matcher = compile_pattern(pattern) if kind == KIND_MONITOR else None
688
+ interactive = kind == KIND_INTERACTIVE
689
+ token = _new_prompt_token() if interactive else ""
690
+ span = agent_activity.current()
691
+ with self._lock:
692
+ refusal = self._capacity_refusal_locked(owner_thread)
693
+ if refusal:
694
+ raise SessionRefused(refusal)
695
+ session = _Session(
696
+ id=f"s{next(self._ids)}", kind=kind, command=command,
697
+ rationale=rationale or "", pattern=pattern,
698
+ owner_thread=str(owner_thread),
699
+ owner_agent=span.name if span else None,
700
+ owner_depth=span.depth if span else 0,
701
+ owner_span_id=span.id if span else None,
702
+ call_id=call_id or "",
703
+ requested_timeout_s=int(requested_timeout_s),
704
+ timeout_s=timeout_s, capped=capped,
705
+ output=OutputBuffer(int(config.SHELL_SESSION_OUTPUT_HEAD_CHARS),
706
+ int(config.SHELL_SESSION_OUTPUT_TAIL_CHARS)),
707
+ matcher=matcher, started_mono=self._clock(),
708
+ started_wall=self._wall_clock(),
709
+ prompt_token=token,
710
+ pty=PtyStream(token) if interactive else None,
711
+ last_input_mono=self._clock())
712
+ self._sessions[session.id] = session
713
+ # ROADMAP_v3 §49 slice 3. Passed to the backend, not stored on the
714
+ # session: what the session RECORDS about where it ran is
715
+ # `ran_on`, read back off the process below, so a request and an
716
+ # outcome cannot disagree in the record. Interactive never carries
717
+ # one -- `start_interactive` takes no backend from this layer.
718
+ #
719
+ # Passed ONLY when it is not the default, which is `prompt_token`'s
720
+ # rule and keeps its property: a starter written against slice 1 --
721
+ # every fake in the suite -- sees the call it has always seen, and
722
+ # one that wants to observe the backend opts in by accepting it.
723
+ # "container" and "no backend given" are the same request, so there
724
+ # is nothing a caller can express that this drops.
725
+ extra = {"prompt_token": token} if interactive else {}
726
+ if not interactive and backend != "container":
727
+ extra["backend"] = backend
728
+ # Slice 5b, on `backend`'s own terms: passed to the backend, not
729
+ # stored on the session, and only when it is true -- so a slice-1
730
+ # fake starter still sees the call it has always seen.
731
+ if not interactive and needs_root:
732
+ extra["needs_root"] = True
733
+ try:
734
+ process = self._starter(command, workspace_dir, profile=profile,
735
+ docker_available=docker_available,
736
+ timeout_s=timeout_s, **extra)
737
+ except Exception:
738
+ with self._lock:
739
+ session.state = FAILED
740
+ session.finished_mono = self._clock()
741
+ rows = self._rows_locked()
742
+ self._post(rows)
743
+ raise
744
+ with self._lock:
745
+ session.process = process
746
+ session.ran_on = getattr(process, "ran_on", "")
747
+ session.tier = getattr(process, "tier", "") or getattr(
748
+ profile, "tier", "")
749
+ session.state = RUNNING
750
+ killed_early = bool(session.kill_reason)
751
+ rows = self._rows_locked()
752
+ threading.Thread(target=self._supervise, args=(session,),
753
+ name=f"shell-session-{session.id}",
754
+ daemon=True).start()
755
+ if killed_early:
756
+ process.kill()
757
+ self._post(rows)
758
+ if interactive:
759
+ return self._open_interactive(session, command, open_wait_s)
760
+ return self._started_result(session)
761
+
762
+ def _open_interactive(self, session: _Session, command: str,
763
+ wait_s: float) -> dict:
764
+ """Wait for the shell's first prompt, then TYPE the opening command.
765
+
766
+ WAITED FOR, not fired off. The terminal driver echoes what reaches
767
+ it before `stty -echo` has run, and that window is the container's
768
+ whole startup -- so input written the instant Popen returns would
769
+ be echoed back EVERY time, not rarely. Waiting for the prompt also
770
+ turns a shell that never comes up into a clear refusal instead of a
771
+ session that accepts input nothing will ever read.
772
+
773
+ TYPED, not handed to the container (SS32). The text is classified
774
+ and approved exactly as `shell` would classify it, and then it
775
+ lands in the shell that was measured here -- rather than becoming
776
+ the container's command, where whatever it started would be the
777
+ thing holding the pty and the prompt token would never come back.
778
+ """
779
+ if not self._await_prompt(session, _OPEN_BOUND_S):
780
+ self.kill(session.id, owner_thread=session.owner_thread,
781
+ reason=KILL_OPEN_FAILED)
782
+ raise SessionRefused(
783
+ "The shell did not reach a prompt within "
784
+ f"{int(_OPEN_BOUND_S)}s and was stopped. The container "
785
+ "image must provide bash and util-linux's `script`.")
786
+ result = self._started_result(session)
787
+ if command:
788
+ sent = self.send(session.id, session.owner_thread,
789
+ text=command, wait_s=wait_s)
790
+ for key in ("text", "ended", "ended_meaning", "next_offset",
791
+ "total_chars", "more", "gap"):
792
+ if key in sent:
793
+ result[key] = sent[key]
794
+ return result
795
+
796
+ def _await_prompt(self, session: _Session, bound_s: float) -> bool:
797
+ """Whether the shell reached its prompt inside *bound_s*."""
798
+ deadline = self._clock() + bound_s
799
+ while self._clock() < deadline:
800
+ pty = session.pty
801
+ if pty is not None and pty.ready_count > 0 and pty.at_prompt:
802
+ return True
803
+ if session.state not in LIVE_STATES:
804
+ return False
805
+ time.sleep(_INPUT_POLL_S)
806
+ return False
807
+
808
+ def _started_result(self, session: _Session) -> dict:
809
+ cap = int(config.SHELL_SESSION_TIMEOUT_CAP_S)
810
+ if session.kind == KIND_INTERACTIVE:
811
+ idle = int(config.SHELL_SESSION_IDLE_TIMEOUT_S)
812
+ note = (
813
+ "An interactive shell is open. Send it input with "
814
+ "shell_input; what you do in it -- the working directory, "
815
+ "variables, a REPL you started -- survives between your "
816
+ "turns. It does NOT block the user, and nothing wakes you "
817
+ f"when it ends: it closes after {idle}s with no input, or "
818
+ f"at its {session.timeout_s}s cap, whichever comes first. "
819
+ "Full-screen programs (vim, htop, less) are not supported.")
820
+ else:
821
+ woken = ("it finishes, times out, or a line matches your pattern"
822
+ if session.kind == KIND_MONITOR else
823
+ "it finishes or times out")
824
+ note = (f"Runs in the background. You will be woken when "
825
+ f"{woken}; do not poll it.")
826
+ if session.capped:
827
+ note += (f" You asked for {session.requested_timeout_s}s, which is "
828
+ f"above the {cap}s cap, so it runs for {cap}s.")
829
+ result = {"session": session.id, "kind": session.kind,
830
+ "status": RUNNING, "command": session.command,
831
+ "timeout_s": session.timeout_s,
832
+ "timeout_capped": session.capped, "timeout_cap_s": cap,
833
+ "ran_on": session.ran_on, "tier": session.tier,
834
+ "note": note}
835
+ if session.kind == KIND_MONITOR:
836
+ result["pattern"] = session.pattern
837
+ return result
838
+
839
+ # -- the two threads -------------------------------------------------------
840
+
841
+ def _supervise(self, session: _Session) -> None:
842
+ reader = threading.Thread(target=self._read, args=(session,),
843
+ name=f"shell-session-{session.id}-reader",
844
+ daemon=True)
845
+ reader.start()
846
+ process = session.process
847
+ deadline = session.started_mono + session.timeout_s
848
+ # SS25. An interactive session also dies of being IGNORED. Its
849
+ # wall-clock cap is the same one every session has, but a shell
850
+ # nobody is typing into is holding a container for nothing, and
851
+ # because it does not block the user's prompt there is no other
852
+ # pressure to close it.
853
+ idle_s = (int(config.SHELL_SESSION_IDLE_TIMEOUT_S)
854
+ if session.kind == KIND_INTERACTIVE else 0)
855
+ code = None
856
+ while True:
857
+ remaining = deadline - self._clock()
858
+ if idle_s:
859
+ idle_left = session.last_input_mono + idle_s - self._clock()
860
+ if idle_left <= 0:
861
+ with self._lock:
862
+ if not session.kill_reason:
863
+ session.kill_reason = KILL_IDLE
864
+ process.kill()
865
+ break
866
+ remaining = min(remaining, idle_left)
867
+ if remaining <= 0:
868
+ with self._lock:
869
+ if not session.kill_reason:
870
+ session.timed_out = True
871
+ process.kill()
872
+ break
873
+ code = process.wait(min(remaining, self._poll_s))
874
+ if code is not None:
875
+ break
876
+ if code is None:
877
+ code = process.wait(_KILL_SETTLE_S)
878
+ reader.join(timeout=10)
879
+ # BEFORE `_finish`, so the quarantine is set by the time the
880
+ # exit wakes anyone who might start the next session (TECHNICAL_DEBT
881
+ # 51, batch 160). The sandbox does the matching; this hands it the
882
+ # stream it cannot read for itself.
883
+ process.note_exit(
884
+ code, session.output.page(0, _AUTH_SCAN_CHARS)["text"])
885
+ self._finish(session, code)
886
+
887
+ def _read(self, session: _Session) -> None:
888
+ stream = session.process.stdout
889
+ read = getattr(stream, "read1", None) or stream.read
890
+ decoder = codecs.getincrementaldecoder("utf-8")("replace")
891
+ pending = ""
892
+ try:
893
+ while True:
894
+ chunk = read(_READ_CHUNK)
895
+ if not chunk:
896
+ break
897
+ text = decoder.decode(chunk)
898
+ if session.pty is not None:
899
+ # BEFORE the buffer and before every match (SS27), so
900
+ # nothing downstream ever holds a version of this text
901
+ # with the escape sequences still in it.
902
+ text = session.pty.feed(text)
903
+ session.output.append(text)
904
+ if session.matcher is not None:
905
+ pending = self._match_complete_lines(session, pending + text)
906
+ except (OSError, ValueError):
907
+ logger.debug("session %s output stream closed", session.id)
908
+ text = decoder.decode(b"", final=True)
909
+ if session.pty is not None:
910
+ # An unterminated escape sequence at the end of the stream was
911
+ # never a sequence, and held-back text is owed to the reader.
912
+ text = session.pty.feed(text) + session.pty.flush()
913
+ session.output.append(text)
914
+ if session.matcher is not None:
915
+ pending = self._match_complete_lines(session, pending + text)
916
+ if pending:
917
+ self._match(session, pending)
918
+
919
+ def _match_complete_lines(self, session: _Session, text: str) -> str:
920
+ *lines, pending = text.split("\n")
921
+ for line in lines:
922
+ self._match(session, line.rstrip("\r"))
923
+ while len(pending) > _MAX_LINE_CHARS:
924
+ self._match(session, pending[:_MAX_LINE_CHARS])
925
+ pending = pending[_MAX_LINE_CHARS:]
926
+ return pending
927
+
928
+ def _match(self, session: _Session, line: str) -> None:
929
+ # Outside every lock: re2 releases the GIL, and a long line must not
930
+ # hold up a kill or a snapshot.
931
+ if not session.matcher.search(line):
932
+ return
933
+ with self._lock:
934
+ session.match_count += 1
935
+ inbox = self._inboxes.setdefault(session.owner_thread, _Inbox())
936
+ target = inbox.held if inbox.suspended else inbox.events
937
+ event = next((e for e in target if e.session_id == session.id
938
+ and e.shape == SHAPE_MATCHED), None)
939
+ if event is None:
940
+ event = self._event_locked(session, SHAPE_MATCHED)
941
+ target.append(event)
942
+ event.match_count += 1
943
+ if len(event.lines) < MAX_MATCHED_LINES:
944
+ event.lines.append(line)
945
+ wake = not inbox.suspended
946
+ self._changed.notify_all()
947
+ rows = self._rows_locked()
948
+ self._post(rows, session.owner_thread if wake else None)
949
+
950
+ def _finish(self, session: _Session, code: Optional[int]) -> None:
951
+ # REDACTED BEFORE THE CUT, not after it (A23). This read
952
+ # `last(int(config.MAX_READ_CHARS))` and every consumer redacted the
953
+ # slice it was handed -- so a credential straddling character 50,000
954
+ # of a session's output lost the half its pattern anchors on, and the
955
+ # value inside the kept half survived whole. Measured through the
956
+ # real redactor at every interior cut position: three of the seven
957
+ # shapes it knows leak, and they are the field-name-plus-value ones
958
+ # where only the value is the secret.
959
+ #
960
+ # HERE rather than only in the consumers, because this is where the
961
+ # tail becomes a FACT about the session: core/session_wake.py formats
962
+ # it for the model, _kill_report returns it to the model, and
963
+ # core/session_view.py draws it. One redaction at the producer covers
964
+ # all three, and each consumer still redacts what IT cuts -- the
965
+ # command, the matched lines, its own narrower budget.
966
+ whole, truncated = session.output.last()
967
+ clean = redact_output_text(whole)
968
+ tail = clean[-int(config.MAX_READ_CHARS):]
969
+ truncated = truncated or len(tail) < len(clean)
970
+ with self._lock:
971
+ if session.kill_reason:
972
+ session.state = KILLED
973
+ elif session.timed_out:
974
+ session.state = TIMED_OUT
975
+ else:
976
+ session.state = EXITED
977
+ session.return_code = code
978
+ session.finished_mono = self._clock()
979
+ inbox = self._inboxes.setdefault(session.owner_thread, _Inbox())
980
+ event = self._event_locked(session, session.state)
981
+ event.output_tail = tail
982
+ event.output_truncated = truncated
983
+ for queue in (inbox.events, inbox.held):
984
+ for matched in [e for e in queue
985
+ if e.session_id == session.id
986
+ and e.shape == SHAPE_MATCHED]:
987
+ event.lines.extend(matched.lines)
988
+ event.match_count += matched.match_count
989
+ queue.remove(matched)
990
+ del event.lines[MAX_MATCHED_LINES:]
991
+ # SS19. A kill the USER made between turns does not wake the main
992
+ # conversation -- it arrives with their next message. A
993
+ # subagent's session still wakes the subagent, which has no next
994
+ # message.
995
+ # The agent's own kill takes this event as its RESULT, so it is
996
+ # queued for nobody: `kill` is still waiting for it, and a wake
997
+ # turn telling the agent about a session it just stopped is a
998
+ # model call nobody needed. Read under the lock `kill` releases
999
+ # the claim under, so a session that outlives the wait is
1000
+ # reported the ordinary way instead of not at all.
1001
+ # SS31. An interactive session's end is HELD whoever ended it.
1002
+ # It does not block the user's prompt (SS25), so a wake for one
1003
+ # would be a turn starting underneath the user's cursor -- and
1004
+ # there is nothing in it the agent is waiting on, since every
1005
+ # send was already answered when it was made.
1006
+ claimed = session.kill_report_claimed
1007
+ hold = not claimed and (
1008
+ inbox.suspended
1009
+ or session.kind == KIND_INTERACTIVE
1010
+ or (session.kill_reason == KILL_USER
1011
+ and session.owner_depth == 0))
1012
+ if claimed:
1013
+ session.final_event = event
1014
+ else:
1015
+ (inbox.held if hold else inbox.events).append(event)
1016
+ self._prune_locked()
1017
+ self._changed.notify_all()
1018
+ rows = self._rows_locked()
1019
+ self._post(rows, None if (hold or claimed) else session.owner_thread)
1020
+
1021
+ def _event_locked(self, session: _Session, shape: str) -> WakeEvent:
1022
+ return WakeEvent(
1023
+ session_id=session.id, call_id=session.call_id, kind=session.kind,
1024
+ command=session.command, shape=shape,
1025
+ return_code=session.return_code,
1026
+ elapsed_s=round(self._clock() - session.started_mono, 1),
1027
+ ran_on=session.ran_on, tier=session.tier,
1028
+ kill_reason=session.kill_reason, pattern=session.pattern,
1029
+ timeout_s=session.timeout_s)
1030
+
1031
+ def _prune_locked(self) -> None:
1032
+ finished = sorted((s for s in self._sessions.values()
1033
+ if s.state not in LIVE_STATES),
1034
+ key=lambda s: s.finished_mono or 0.0)
1035
+ for old in finished[:-_FINISHED_KEPT]:
1036
+ del self._sessions[old.id]
1037
+
1038
+ # -- what the consumers ask --------------------------------------------------
1039
+
1040
+ def _live_locked(self, owner_thread, kinds=None) -> int:
1041
+ """How many of this thread's sessions are live, of *kinds*.
1042
+
1043
+ The kinds are a parameter because two different questions are
1044
+ asked of this one list and they have different answers (SS25):
1045
+ what is RUNNING, which is every kind, and what the user's prompt
1046
+ is waiting on, which is not. Defaulting to all of them keeps the
1047
+ broad question the cheap one to ask.
1048
+ """
1049
+ owner = str(owner_thread)
1050
+ return sum(1 for s in self._sessions.values()
1051
+ if s.owner_thread == owner and s.state in LIVE_STATES
1052
+ and (kinds is None or s.kind in kinds))
1053
+
1054
+ def live_for(self, owner_thread) -> int:
1055
+ with self._lock:
1056
+ return self._live_locked(owner_thread)
1057
+
1058
+ def blocks(self, owner_thread) -> bool:
1059
+ """Whether this thread's input is blocked (SS2): it has a live
1060
+ BLOCKING session and waking has not been suspended by the
1061
+ consecutive-wake limit.
1062
+
1063
+ An interactive session is deliberately not counted (SS25): the
1064
+ block exists because the agent is waiting on work the user cannot
1065
+ usefully interrupt, and an open shell is not that.
1066
+ """
1067
+ with self._lock:
1068
+ inbox = self._inboxes.get(str(owner_thread))
1069
+ return (self._live_locked(owner_thread, BLOCKING_KINDS) > 0
1070
+ and not (inbox and inbox.suspended))
1071
+
1072
+ def suspended(self, owner_thread) -> bool:
1073
+ with self._lock:
1074
+ inbox = self._inboxes.get(str(owner_thread))
1075
+ return bool(inbox and inbox.suspended)
1076
+
1077
+ def pending(self, owner_thread) -> bool:
1078
+ with self._lock:
1079
+ inbox = self._inboxes.get(str(owner_thread))
1080
+ return bool(inbox and inbox.events and not inbox.suspended)
1081
+
1082
+ def _take_locked(self, owner_thread) -> tuple[Optional[list[WakeEvent]], bool]:
1083
+ """(the batch to wake with, whether waking was just suspended)."""
1084
+ inbox = self._inboxes.get(str(owner_thread))
1085
+ if inbox is None or not inbox.events or inbox.suspended:
1086
+ return None, False
1087
+ if inbox.consecutive_wakes >= int(
1088
+ config.SHELL_SESSION_MAX_CONSECUTIVE_WAKES):
1089
+ inbox.suspended = True
1090
+ inbox.held.extend(inbox.events)
1091
+ inbox.events = []
1092
+ self._changed.notify_all()
1093
+ return None, True
1094
+ batch, inbox.events = inbox.events, []
1095
+ inbox.consecutive_wakes += 1
1096
+ return batch, False
1097
+
1098
+ def take_wake(self, owner_thread) -> Optional[list[WakeEvent]]:
1099
+ """Everything waiting to wake this thread, taken atomically -- or None
1100
+ when nothing is, or when the consecutive-wake limit just stopped
1101
+ waking (SS2), in which case the results move to `held`."""
1102
+ with self._lock:
1103
+ batch, suspended_now = self._take_locked(owner_thread)
1104
+ rows = self._rows_locked() if suspended_now else None
1105
+ if rows is not None:
1106
+ self._post(rows)
1107
+ return batch
1108
+
1109
+ def wait_for_wake(self, owner_thread,
1110
+ timeout: Optional[float] = None
1111
+ ) -> Optional[list[WakeEvent]]:
1112
+ """Block until there is a batch to wake this thread with. None when
1113
+ there is nothing left to wait for: no live session and nothing
1114
+ pending, waking suspended, the harness quitting, or *timeout* gone.
1115
+ Waits in `poll_s` slices, so a KeyboardInterrupt still lands."""
1116
+ deadline = None if timeout is None else self._clock() + timeout
1117
+ rows = None
1118
+ with self._changed:
1119
+ while True:
1120
+ batch, suspended_now = self._take_locked(owner_thread)
1121
+ if batch is not None:
1122
+ return batch
1123
+ if suspended_now:
1124
+ rows = self._rows_locked()
1125
+ break
1126
+ inbox = self._inboxes.get(str(owner_thread))
1127
+ # BLOCKING_KINDS for SS25's reason, and here it is load
1128
+ # bearing: this loop keeps a turn alive while something is
1129
+ # still running, and an idle interactive shell would hold
1130
+ # the turn open exactly as a hung read would.
1131
+ if (self._closing or (inbox and inbox.suspended)
1132
+ or not self._live_locked(owner_thread,
1133
+ BLOCKING_KINDS)):
1134
+ break
1135
+ if deadline is not None and self._clock() >= deadline:
1136
+ break
1137
+ self._changed.wait(self._poll_s)
1138
+ if rows is not None:
1139
+ self._post(rows)
1140
+ return None
1141
+
1142
+ def note_user_input(self, owner_thread) -> None:
1143
+ """A message from the user resets the consecutive-wake count and
1144
+ resumes waking (SS2). Held results stay held until `take_held`."""
1145
+ with self._lock:
1146
+ inbox = self._inboxes.setdefault(str(owner_thread), _Inbox())
1147
+ inbox.consecutive_wakes = 0
1148
+ inbox.suspended = False
1149
+ rows = self._rows_locked()
1150
+ self._post(rows)
1151
+
1152
+ def take_held(self, owner_thread) -> list[WakeEvent]:
1153
+ """Results held for the user's next message: past the wake limit, or
1154
+ from a kill the user made (SS2, SS19)."""
1155
+ with self._lock:
1156
+ inbox = self._inboxes.get(str(owner_thread))
1157
+ if inbox is None or not inbox.held:
1158
+ return []
1159
+ held, inbox.held = inbox.held, []
1160
+ return held
1161
+
1162
+ # -- what the tools ask --------------------------------------------------------
1163
+
1164
+ def _owned_locked(self, session_id: str, owner_thread) -> Optional[_Session]:
1165
+ """This thread's session of that id, or None.
1166
+
1167
+ `ANY_OWNER` is the only way past the check, and it is a value a
1168
+ caller has to name (see its comment above). Everything else is
1169
+ compared, `None` INCLUDED -- a missing thread id owns nothing, which
1170
+ is the same answer `list_for` gives it one function down.
1171
+ """
1172
+ session = self._sessions.get(str(session_id))
1173
+ if session is None:
1174
+ return None
1175
+ if owner_thread is ANY_OWNER:
1176
+ return session
1177
+ if owner_thread is None or session.owner_thread != str(owner_thread):
1178
+ return None
1179
+ return session
1180
+
1181
+ def list_for(self, owner_thread) -> list[dict]:
1182
+ now = self._clock()
1183
+ with self._lock:
1184
+ sessions = [s for s in self._sessions.values()
1185
+ if s.owner_thread == str(owner_thread)]
1186
+ return [{"session": s.id, "kind": s.kind, "command": s.command,
1187
+ "status": s.state,
1188
+ "elapsed_s": round((s.finished_mono or now)
1189
+ - s.started_mono, 1),
1190
+ "timeout_s": s.timeout_s, "return_code": s.return_code,
1191
+ "output_chars": s.output.total,
1192
+ "match_count": s.match_count}
1193
+ for s in sessions]
1194
+
1195
+ def output(self, session_id: str, owner_thread, offset: int = 0,
1196
+ limit: Optional[int] = None) -> dict:
1197
+ limit = int(limit or config.MAX_READ_CHARS)
1198
+ with self._lock:
1199
+ session = self._owned_locked(session_id, owner_thread)
1200
+ if session is None:
1201
+ return {"error": f"No session {session_id} in this "
1202
+ f"conversation."}
1203
+ state = session.state
1204
+ buffer = session.output
1205
+ # A23: the redactor sees the buffer before this page is cut out
1206
+ # of it. dispatch()'s own check_output_policy still runs after the
1207
+ # return -- it covers the other keys and is the backstop -- but it
1208
+ # cannot put back a pattern this cut would have split.
1209
+ page = buffer.page(offset, limit, clean=redact_output_text)
1210
+ page.update(session=str(session_id), status=state)
1211
+ return page
1212
+
1213
+ def send(self, session_id: str, owner_thread, *, text: str = "",
1214
+ control: str = "", wait_s: float = 10.0,
1215
+ wait_for: Optional[str] = None) -> dict:
1216
+ """Type into an interactive session and wait for it, BOUNDED (SS26).
1217
+
1218
+ Returns everything the session wrote since this call began, and
1219
+ `ended`, naming which of the four bounds ended the wait. Every one of
1220
+ them returns: a send cannot wait forever, because the turn it is in
1221
+ cannot either -- that is the whole reason the gap register called a
1222
+ hung read a wedge.
1223
+
1224
+ An empty *text* with no *control* writes nothing and only waits,
1225
+ which is how a caller reads more of something still running.
1226
+ """
1227
+ if control and control not in CONTROLS:
1228
+ return {"error": f"Unknown control {control!r}. Use one of: "
1229
+ f"{', '.join(sorted(CONTROLS))}."}
1230
+ matcher = None
1231
+ if wait_for:
1232
+ reason = validate(wait_for)
1233
+ if reason is not None:
1234
+ return {"error": f"Invalid pattern: {reason}. Patterns use "
1235
+ f"RE2 syntax: no backreferences or "
1236
+ f"lookaround."}
1237
+ matcher = compile_pattern(wait_for)
1238
+ if control:
1239
+ payload = CONTROLS[control]
1240
+ elif text:
1241
+ # The newline is added rather than demanded: a line the shell
1242
+ # never sees because its terminator was forgotten looks exactly
1243
+ # like a command that produced no output.
1244
+ payload = text if text.endswith("\n") else text + "\n"
1245
+ else:
1246
+ payload = ""
1247
+ size = len(payload.encode("utf-8"))
1248
+ if size > MAX_INPUT_BYTES:
1249
+ return {"error": (
1250
+ f"That input is {size} bytes. A pty accepts "
1251
+ f"{_PTY_LINE_LIMIT} on one line and silently drops the rest, "
1252
+ f"so the shell would run a TRUNCATED command and report "
1253
+ f"success -- it is refused here instead. Write it to a file "
1254
+ f"with `write` and run the file.")}
1255
+ with self._lock:
1256
+ session = self._owned_locked(session_id, owner_thread)
1257
+ if session is None:
1258
+ return {"error": f"No session {session_id} in this "
1259
+ f"conversation."}
1260
+ if session.kind != KIND_INTERACTIVE:
1261
+ return {"error": f"Session {session.id} is a {session.kind} "
1262
+ f"session and cannot be typed into. Only an "
1263
+ f"interactive session takes input."}
1264
+ if session.state not in LIVE_STATES:
1265
+ return {"error": f"Session {session.id} has already finished "
1266
+ f"({session.state})."}
1267
+ process, pty = session.process, session.pty
1268
+ mark = session.output.total
1269
+ # ONE rule: a prompt that arrives AFTER this write, with the
1270
+ # stream then at rest on it. Three cheaper rules were measured
1271
+ # first and each was wrong somewhere.
1272
+ #
1273
+ # `at_prompt` alone says the stream ENDS with a prompt, which is
1274
+ # not the same as the shell being idle -- with the echo off
1275
+ # (SS33) a command produces nothing at all when it starts, so
1276
+ # the last prompt stands on the stream for as long as a silent
1277
+ # command runs. Measured: a wait issued while `sleep 2` ran read
1278
+ # that stale prompt and returned `ready` before the command had
1279
+ # finished. Nothing observable distinguishes the two; only this
1280
+ # side knows a line was written.
1281
+ #
1282
+ # Counting two prompts when the shell looked busy fixed the
1283
+ # queued case and broke leaving a REPL, where `exit()` is eaten
1284
+ # by python and one prompt follows. Those two are identical from
1285
+ # out here, and telling them apart means emulating the terminal.
1286
+ #
1287
+ # So: always the NEXT prompt, and always let it settle. A prompt
1288
+ # that is merely passed through on the way to running a queued
1289
+ # line is followed by that line's output within milliseconds, so
1290
+ # it never settles; the prompt that ends the work does. The cost
1291
+ # is the quiet interval on every send, which is a third of a
1292
+ # second against a model round trip.
1293
+ ready_target = pty.ready_count + 1
1294
+ # Reset the idle clock on the INPUT, not on the output: a session
1295
+ # printing to itself forever is still one nobody is using (SS25).
1296
+ session.last_input_mono = self._clock()
1297
+ if payload:
1298
+ stdin = getattr(process, "stdin", None)
1299
+ if stdin is None:
1300
+ return {"error": f"Session {session.id} has no input stream."}
1301
+ try:
1302
+ stdin.write(payload.encode("utf-8"))
1303
+ stdin.flush()
1304
+ except (OSError, ValueError) as e:
1305
+ return {"error": f"Could not reach session {session.id}: {e}."}
1306
+ return self._wait_after_input(session, mark, ready_target, wait_s,
1307
+ matcher)
1308
+
1309
+ def _wait_after_input(self, session: _Session, mark: int,
1310
+ ready_target: int, wait_s: float, matcher) -> dict:
1311
+ """SS26's four bounds, in the order they can be believed.
1312
+
1313
+ `ready` is checked first because it is the only one that is a FACT
1314
+ about the shell rather than an observation about silence, and it
1315
+ ends a wait for a pattern that is never coming.
1316
+ """
1317
+ pty = session.pty
1318
+ deadline = self._clock() + max(0.0, float(wait_s))
1319
+ last_total, last_change = mark, self._clock()
1320
+ searched, carry = mark, ""
1321
+ while True:
1322
+ total = session.output.total
1323
+ if (pty.ready_count >= ready_target and pty.at_prompt
1324
+ and self._clock() - last_change >= _INPUT_QUIET_S):
1325
+ ended = "ready"
1326
+ break
1327
+ if matcher is not None and total > searched:
1328
+ page = session.output.page(searched, _MATCH_SLICE)
1329
+ searched = int(page.get("next_offset", searched))
1330
+ *lines, carry = (carry + page.get("text", "")).split("\n")
1331
+ if len(carry) > _MAX_LINE_CHARS:
1332
+ lines.append(carry[:_MAX_LINE_CHARS])
1333
+ carry = carry[_MAX_LINE_CHARS:]
1334
+ if any(matcher.search(line.rstrip("\r")) for line in lines):
1335
+ ended = "matched"
1336
+ break
1337
+ now = self._clock()
1338
+ if total != last_total:
1339
+ last_total, last_change = total, now
1340
+ elif (matcher is None and total > mark
1341
+ and now - last_change >= _INPUT_QUIET_S):
1342
+ # Two conditions, each measured into existence.
1343
+ #
1344
+ # Only once something HAS arrived: a command that prints
1345
+ # nothing while it works -- which is most of them, now that
1346
+ # the echo is off -- would otherwise report `quiet` after a
1347
+ # third of a second and read as finished.
1348
+ #
1349
+ # And NEVER when a pattern was given. A caller passing
1350
+ # `wait_for` has said what it is waiting for, and silence is
1351
+ # not it: measured, `wait_for="line2"` against a loop
1352
+ # printing a line a second returned `quiet` after line1 --
1353
+ # answering a question nobody asked, and leaving the loop
1354
+ # running to desynchronize every later call.
1355
+ ended = "quiet"
1356
+ break
1357
+ if session.state not in LIVE_STATES:
1358
+ ended = "ended"
1359
+ break
1360
+ if now >= deadline:
1361
+ ended = "bound"
1362
+ break
1363
+ time.sleep(_INPUT_POLL_S)
1364
+ # A23, as in output() above: this page is returned to the model.
1365
+ # The MATCH slice a few lines up is deliberately raw -- the monitor
1366
+ # matches on raw output by design, and redacting what is searched
1367
+ # would stop a credential-shaped line waking the agent at all.
1368
+ page = session.output.page(mark, int(config.MAX_READ_CHARS),
1369
+ clean=redact_output_text)
1370
+ page.update(session=session.id, status=session.state, ended=ended,
1371
+ ended_meaning=_ENDED_MEANING[ended])
1372
+ return page
1373
+
1374
+ def kill(self, session_id: str, *, owner_thread,
1375
+ reason: str = KILL_MODEL) -> dict:
1376
+ """Stop a session and report its terminal state. *owner_thread*
1377
+ `ANY_OWNER` is the user's or the harness's kill, which may name any
1378
+ session; a thread id is the model's, which may name only its own.
1379
+
1380
+ REQUIRED, with no default, since batch 110. The default was `None`
1381
+ and `None` meant "skip the ownership check", so the safe call was
1382
+ the one a caller had to remember to make. There are four call sites
1383
+ and each of them now says which authority it is exercising.
1384
+
1385
+ A kill the MODEL makes is its own report: this returns what the wake
1386
+ would have said -- the final state, the end of the output, and any
1387
+ matched lines nobody had taken yet -- and no wake follows, because
1388
+ the agent is the one that asked. The claim belongs to the call that
1389
+ SET the reason, so a second killer of the same session does not take
1390
+ a report out from under the first, and it is given back if the
1391
+ session outlives the wait, which puts the finish back on the
1392
+ ordinary wake path rather than dropping it."""
1393
+ with self._lock:
1394
+ session = self._owned_locked(session_id, owner_thread)
1395
+ if session is None:
1396
+ return {"error": f"No session {session_id} in this "
1397
+ f"conversation."}
1398
+ if session.state not in LIVE_STATES:
1399
+ return {"session": session.id, "status": session.state,
1400
+ "return_code": session.return_code,
1401
+ "note": "already finished"}
1402
+ claimed = False
1403
+ if not session.kill_reason:
1404
+ session.kill_reason = reason
1405
+ claimed = reason == KILL_MODEL
1406
+ session.kill_report_claimed = claimed
1407
+ process = session.process
1408
+ if process is not None:
1409
+ process.kill()
1410
+ with self._changed:
1411
+ self._changed.wait_for(lambda: session.state not in LIVE_STATES,
1412
+ timeout=_KILL_SETTLE_S)
1413
+ if claimed and session.state in LIVE_STATES:
1414
+ session.kill_report_claimed = False
1415
+ elif claimed and session.final_event is not None:
1416
+ return self._kill_report(session.final_event)
1417
+ return {"session": session.id, "status": session.state,
1418
+ "return_code": session.return_code}
1419
+
1420
+ @staticmethod
1421
+ def _kill_report(event: WakeEvent) -> dict:
1422
+ """What the agent is told about the session it just stopped."""
1423
+ report = {"session": event.session_id, "status": event.shape,
1424
+ "return_code": event.return_code,
1425
+ "elapsed_s": event.elapsed_s, "ran_on": event.ran_on,
1426
+ "output_tail": event.output_tail,
1427
+ "output_truncated": event.output_truncated,
1428
+ "note": "Stopped. This is its final report; you will not "
1429
+ "be woken for it."}
1430
+ if event.match_count:
1431
+ report["unreported_matches"] = {"count": event.match_count,
1432
+ "lines": list(event.lines)}
1433
+ return report
1434
+
1435
+ def kill_owned(self, owner_thread, reason: str) -> list[str]:
1436
+ """Kill every live session this thread owns -- a subagent that ran
1437
+ out of wakes (KILL_WAKE_LIMIT).
1438
+
1439
+ `ANY_OWNER` below because the ownership question was already asked,
1440
+ two lines up and by this function: re-asking it per id would either
1441
+ repeat the filter or, if the thread were None, quietly widen it."""
1442
+ with self._lock:
1443
+ ids = [s.id for s in self._sessions.values()
1444
+ if s.owner_thread == str(owner_thread)
1445
+ and s.state in LIVE_STATES]
1446
+ for session_id in ids:
1447
+ self.kill(session_id, owner_thread=ANY_OWNER, reason=reason)
1448
+ return ids
1449
+
1450
+ def kill_by_span(self, owner_span_id: str, reason: str) -> list[str]:
1451
+ """Kill every live session started inside one agent-shaped run.
1452
+
1453
+ The failure path's answer to a question the thread id cannot be
1454
+ asked: a subagent whose run RAISES never returns its thread, and
1455
+ `agent_activity`'s span is frozen and carries no address (the
1456
+ binding belongs to the sink). The span id is on the session from
1457
+ the moment it started, so what a failed run left behind is
1458
+ identifiable even though its conversation is not.
1459
+
1460
+ `ANY_OWNER` for the same reason as `kill_owned`, and here it is the
1461
+ point rather than an economy: this sweep exists precisely because
1462
+ the thread id is not available, so there is nothing to check by."""
1463
+ if not owner_span_id:
1464
+ return []
1465
+ with self._lock:
1466
+ ids = [s.id for s in self._sessions.values()
1467
+ if s.owner_span_id == owner_span_id
1468
+ and s.state in LIVE_STATES]
1469
+ for session_id in ids:
1470
+ self.kill(session_id, owner_thread=ANY_OWNER, reason=reason)
1471
+ return ids
1472
+
1473
+ # -- snapshots and shutdown ----------------------------------------------------
1474
+
1475
+ def _rows_locked(self) -> list[SessionRow]:
1476
+ return [s.row() for s in self._sessions.values()]
1477
+
1478
+ def rows(self) -> list[SessionRow]:
1479
+ with self._lock:
1480
+ return self._rows_locked()
1481
+
1482
+ def live_rows(self) -> list[SessionRow]:
1483
+ with self._lock:
1484
+ return [s.row() for s in self._sessions.values()
1485
+ if s.state in LIVE_STATES]
1486
+
1487
+ def row(self, session_id: str) -> Optional[SessionRow]:
1488
+ with self._lock:
1489
+ session = self._sessions.get(str(session_id))
1490
+ return session.row() if session else None
1491
+
1492
+ def buffer(self, session_id: str) -> Optional[OutputBuffer]:
1493
+ """A session's output buffer, for a shell's read-only view."""
1494
+ with self._lock:
1495
+ session = self._sessions.get(str(session_id))
1496
+ return session.output if session else None
1497
+
1498
+ def close(self, reason: str = KILL_QUIT,
1499
+ budget_s: Optional[float] = None) -> dict[str, list[SessionRow]]:
1500
+ """Kill every live session, within one shared budget, and stop
1501
+ accepting new ones. Returns {owner thread: the rows killed}, for the
1502
+ caller to record (SS6). Idempotent: a second call finds nothing live.
1503
+ Releases every waiter."""
1504
+ budget = float(config.TEARDOWN_BUDGET_S if budget_s is None
1505
+ else budget_s)
1506
+ with self._lock:
1507
+ self._closing = True
1508
+ live = [s for s in self._sessions.values()
1509
+ if s.state in LIVE_STATES]
1510
+ for session in live:
1511
+ if not session.kill_reason:
1512
+ session.kill_reason = reason
1513
+ self._changed.notify_all()
1514
+ killers = [threading.Thread(target=s.process.kill, daemon=True)
1515
+ for s in live if s.process is not None]
1516
+ for killer in killers:
1517
+ killer.start()
1518
+ deadline = self._clock() + budget
1519
+ for killer in killers:
1520
+ killer.join(max(0.0, deadline - self._clock()))
1521
+ with self._changed:
1522
+ self._changed.wait_for(
1523
+ lambda: all(s.state not in LIVE_STATES for s in live),
1524
+ timeout=max(0.0, deadline - self._clock()))
1525
+ closed: dict[str, list[SessionRow]] = {}
1526
+ for session in live:
1527
+ closed.setdefault(session.owner_thread, []).append(
1528
+ session.row())
1529
+ rows = self._rows_locked()
1530
+ self._post(rows)
1531
+ return closed
1532
+
1533
+ @property
1534
+ def closing(self) -> bool:
1535
+ return self._closing
1536
+
1537
+ def _post(self, rows: Optional[list[SessionRow]],
1538
+ wake_thread: Optional[str] = None) -> None:
1539
+ sink = self._sink
1540
+ if rows is not None:
1541
+ try:
1542
+ sink.changed(list(rows))
1543
+ except Exception: # noqa: BLE001 -- contained
1544
+ logger.exception("session sink raised on changed")
1545
+ if wake_thread is not None:
1546
+ try:
1547
+ sink.wake_ready(wake_thread)
1548
+ except Exception: # noqa: BLE001 -- contained
1549
+ logger.exception("session sink raised on wake_ready")
1550
+
1551
+
1552
+ sessions = SessionManager()
1553
+ """The process's one session manager."""