@yahyahammad/venastine 0.2.0 → 0.3.9

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 (152) hide show
  1. package/.env.example +9 -4
  2. package/CONFIG_ARCHITECTURE.md +2030 -0
  3. package/LICENSE +201 -201
  4. package/NOTICE +1 -1
  5. package/README.md +1034 -895
  6. package/agents/builtin/build.md +73 -0
  7. package/agents/builtin/compactor.md +75 -75
  8. package/agents/builtin/explore.md +77 -77
  9. package/agents/builtin/general.md +80 -0
  10. package/agents/builtin/pipeline-reviewer.md +100 -100
  11. package/agents/builtin/plan.md +106 -88
  12. package/agents/builtin/review.md +74 -74
  13. package/agents/builtin/test.md +65 -0
  14. package/agents/builtin/writer.md +67 -0
  15. package/agents/manager.py +68 -2
  16. package/agents/subagent_tool.py +472 -238
  17. package/agents/tui_commands.py +238 -151
  18. package/bin/venastine.mjs +150 -4
  19. package/bin/venastine.py +71 -0
  20. package/cli_commands.py +838 -0
  21. package/config.py +95 -1198
  22. package/config.yaml +1103 -0
  23. package/config_edit.py +1301 -0
  24. package/config_schema.py +971 -0
  25. package/config_update.py +749 -0
  26. package/core/agent_activity.py +256 -118
  27. package/core/ansi.py +452 -0
  28. package/core/approval.py +137 -115
  29. package/core/call_view.py +364 -0
  30. package/core/cancel.py +121 -0
  31. package/core/chatgpt_auth.py +747 -0
  32. package/core/claims_view.py +107 -0
  33. package/core/client.py +2715 -1559
  34. package/core/commands.py +460 -0
  35. package/core/compaction.py +1735 -971
  36. package/core/config_loader.py +1982 -1563
  37. package/core/connect.py +686 -0
  38. package/core/events.py +123 -61
  39. package/core/file_mentions.py +280 -0
  40. package/core/interaction.py +411 -328
  41. package/core/line_pattern.py +128 -0
  42. package/core/loop.py +2566 -1490
  43. package/core/memory.py +482 -370
  44. package/core/pipeline_models.py +190 -176
  45. package/core/provider_errors.py +234 -0
  46. package/core/reasoning/authorization.py +130 -130
  47. package/core/reasoning/base.py +219 -219
  48. package/core/reasoning/confidence_scoring.py +484 -468
  49. package/core/reasoning/events.py +149 -149
  50. package/core/reasoning/json_retry.py +19 -1
  51. package/core/reasoning/orchestrator.py +1561 -1382
  52. package/core/reasoning/output_writer.py +345 -286
  53. package/core/reasoning/payload_validation.py +524 -398
  54. package/core/reasoning/pipeline_storage.py +88 -22
  55. package/core/reasoning/review.py +659 -615
  56. package/core/reasoning/scholar.py +458 -434
  57. package/core/reasoning/source_corpus.py +433 -327
  58. package/core/reasoning/source_scoring.py +855 -855
  59. package/core/replay.py +315 -183
  60. package/core/session.py +36 -12
  61. package/core/session_view.py +259 -0
  62. package/core/session_wake.py +259 -0
  63. package/core/shell_sessions.py +1553 -0
  64. package/core/workspace_trust.py +1 -1
  65. package/credentials.py +148 -20
  66. package/database.py +333 -252
  67. package/{PRIVACY.md → docs/PRIVACY.md} +78 -66
  68. package/docs/SECURITY.md +108 -0
  69. package/docs/THIRD_PARTY_NOTICES.md +148 -0
  70. package/env_secrets.py +50 -9
  71. package/json_store.py +343 -123
  72. package/logging_setup.py +295 -185
  73. package/main.py +3433 -1961
  74. package/mcp_client/client.py +733 -499
  75. package/mcp_client/config.py +126 -21
  76. package/mcp_client/registration.py +343 -182
  77. package/memories/manager.py +147 -132
  78. package/memories/tui_commands.py +319 -244
  79. package/package.json +303 -73
  80. package/project_init/config_files.py +282 -278
  81. package/project_init/generator.py +728 -564
  82. package/project_init/manifest.py +18 -6
  83. package/project_init/tui_commands.py +147 -144
  84. package/prompts/critic_pass.md +24 -24
  85. package/prompts/revalidate.md +25 -25
  86. package/prompts/revise.md +2 -0
  87. package/prompts/source_grounding.md +66 -66
  88. package/prompts/system_prompts.py +316 -262
  89. package/providers.json.example +4 -2
  90. package/pyproject.toml +149 -100
  91. package/requirements.txt +295 -72
  92. package/safety/policy_enforcement.py +1082 -746
  93. package/security/askpass.py +419 -0
  94. package/security/capability.py +207 -177
  95. package/security/confine.py +484 -0
  96. package/security/hosted.py +182 -0
  97. package/security/permissions.py +237 -190
  98. package/security/posture.py +124 -12
  99. package/security/protected_paths.py +501 -309
  100. package/security/sandbox.py +4108 -985
  101. package/security/secrets.py +855 -0
  102. package/skills/builtin/math/formal-specification.md +67 -67
  103. package/skills/builtin/math/numerical-methods.md +66 -66
  104. package/skills/builtin/research/experiment-design.md +62 -62
  105. package/skills/builtin/research/reproducibility.md +55 -55
  106. package/skills/builtin/research/source-evaluation.md +70 -70
  107. package/skills/builtin/research/statistical-inference.md +63 -63
  108. package/skills/builtin/research/technical-writing.md +59 -59
  109. package/skills/builtin/software/code-review.md +61 -61
  110. package/skills/builtin/software/debugging.md +61 -61
  111. package/skills/builtin/software/test-design.md +67 -67
  112. package/skills/tui_commands.py +110 -111
  113. package/storage.py +1338 -1005
  114. package/tools/base.py +161 -1
  115. package/tools/builtin/_math_common.py +667 -377
  116. package/tools/builtin/_net_common.py +225 -19
  117. package/tools/builtin/arxiv.py +497 -39
  118. package/tools/builtin/ask_user.py +231 -213
  119. package/tools/builtin/discrete_math.py +35 -4
  120. package/tools/builtin/fetch_url.py +371 -153
  121. package/tools/builtin/file_ops.py +720 -412
  122. package/tools/builtin/geometry.py +48 -12
  123. package/tools/builtin/get_time.py +2 -2
  124. package/tools/builtin/linear_algebra.py +66 -23
  125. package/tools/builtin/load_skill.py +76 -66
  126. package/tools/builtin/logic.py +171 -12
  127. package/tools/builtin/pin.py +227 -193
  128. package/tools/builtin/probability_stats.py +12 -16
  129. package/tools/builtin/project_docs.py +464 -405
  130. package/tools/builtin/remember.py +175 -158
  131. package/tools/builtin/shell.py +980 -461
  132. package/tools/builtin/shell_sessions.py +613 -0
  133. package/tools/builtin/symbolic_math.py +80 -10
  134. package/tools/builtin/todo.py +149 -147
  135. package/tools/builtin/web_search.py +191 -13
  136. package/tools/context.py +159 -136
  137. package/tools/isolation.py +107 -34
  138. package/tools/registry.py +1242 -925
  139. package/tui/app.py +8318 -4100
  140. package/tui/app.tcss +747 -556
  141. package/tui/commands.py +26 -170
  142. package/tui/diffs.py +34 -13
  143. package/tui/history.py +128 -128
  144. package/tui/hosted_driver.py +102 -0
  145. package/tui/markdown.py +1329 -1279
  146. package/tui/meters.py +364 -268
  147. package/tui/ravens.py +146 -146
  148. package/tui/screens.py +1255 -943
  149. package/tui/themes.py +599 -559
  150. package/tui/widgets.py +3813 -2332
  151. package/SECURITY.md +0 -88
  152. package/THIRD_PARTY_NOTICES.md +0 -100
package/core/ansi.py ADDED
@@ -0,0 +1,452 @@
1
+ """
2
+ core/ansi.py
3
+
4
+ ROADMAP_v3 §49, slice 2 (SS27, SS34). The two transforms a pty's output
5
+ needs before anything else sees it: escape sequences removed, and the
6
+ harness's own prompt token taken back out of the stream it marks.
7
+
8
+ WHY IN core/. `core/shell_sessions.py` reads the stream and the tools read
9
+ the buffer; both need the same text, and a second stripper anywhere else
10
+ would be the two-copies-of-one-decision shape §46 (EP6) and #157 are about.
11
+ Nothing here imports a widget, a tool or a sandbox.
12
+
13
+ WHY STATEFUL. The reader gets whatever the pipe hands it. Measured (batch
14
+ 100, probe): 128 KB of output arrived in 74 chunks whose boundaries fall
15
+ wherever the kernel put them, so a sequence split across two reads is the
16
+ ORDINARY case, not the corner. Every class here holds its partial across
17
+ `feed` calls and gives it up on `flush`, mirroring the incremental UTF-8
18
+ decoder the reader already wraps the same stream in.
19
+
20
+ WHAT THIS IS NOT. Not a terminal emulator (SS27). A sequence is REMOVED,
21
+ never interpreted: nothing here moves a cursor, tracks a scroll region or
22
+ maintains a screen. So a program that paints -- `vim`, `htop`, `less` --
23
+ is not supported in an interactive session, and the tool description says
24
+ so rather than leaving it to be found. A bare CR is left in the text for
25
+ the same reason: making `working\rdone` read as `done` is emulation, and
26
+ guessing is worse than showing what arrived.
27
+
28
+ BOTH ENCODINGS OF A CONTROL, since batch 145. Every sequence here has two
29
+ forms: `ESC [` and the single character U+009B are the SAME introducer, and
30
+ a terminal in UTF-8 mode decodes the two bytes `\xc2\x9b` back into one.
31
+ Until batch 145 only the ESC form was removed, which was not a judgement --
32
+ `_sequence_end` keyed on ESC and the 8-bit forms were never considered.
33
+ Measured, all seven introducers survived (CSI, OSC, DCS, SOS, PM, APC, and
34
+ ST as a terminator), so `x\x9b2Jy` came through whole while `x\x1b[2Jy`
35
+ became `xy`. The asymmetry is the argument on its own: this module exists
36
+ because a control must not reach a terminal, and which of two spellings
37
+ the sender chose was never part of that decision. The whole Unicode C1 range
38
+ 0x80-0x9F goes, not only the introducers, for the same symmetry -- `ESC D`
39
+ and `ESC E` already went through the two-character fallback below, and
40
+ U+0084 and U+0085 are those same two controls.
41
+
42
+ The cost, stated because it is real: text that was decoded as latin-1
43
+ where it was written as cp1252 carries Unicode C1 characters where its curly
44
+ quotes belong, and those characters are now DELETED rather than drawn
45
+ as something odd. A Unicode C1 character cannot be drawn meaningfully either
46
+ way -- the alternative is handing it to the terminal as a control --
47
+ so the choice is between losing it and acting on it.
48
+
49
+ THE UNTERMINATED CARRY IS THE ONE THING THE CONSUMERS DISAGREE ABOUT, which
50
+ is why it is a flag and not a rule (batch 145). For the pty, a carry that
51
+ never completes is text: a program's output cut off mid-sequence is still
52
+ the output the agent asked for, and holding it back forever would lose it.
53
+ For a TRANSCRIPT the same release is a leak, because the text there is
54
+ handed to a terminal, and `ESC [` with no final byte consumes whatever is
55
+ printed after it as its final byte. `release_unterminated` names the two,
56
+ and the pty's answer stays the default so nothing about SS27 moves.
57
+
58
+ A THIRD CONSUMER SINCE BATCH 152, AND IT IS NOT A STREAM. `main.py` prints
59
+ model- and third-party text to a terminal one whole string at a time -- an
60
+ approval headline, a notice, the agent's own stated reason, a question, a
61
+ reviewer's proposed correction, an MCP server's description of what its
62
+ tool does. None of those is a pty's output and none is a transcript's
63
+ deltas, but the hazard is the transcript's exactly: the text is handed to
64
+ a terminal. Measured before the fix (batch 152), through the real channel --
65
+ a headline of `cat README.md`, CSI `2K`, a carriage return and a second
66
+ `$ cat .venastine/settings.json` reached stdout with the introducer
67
+ intact, and CSI `2K` erases the row the approved command was drawn on. So
68
+ `for_display` below takes the transcript's answer to the carry, for the
69
+ transcript's reason, and it lives here so that the CLI composes nothing of
70
+ its own.
71
+
72
+ WHAT `for_display` REMOVES AND WHAT IT KEEPS, since a display filter
73
+ cannot inherit the pty's answer to either. A LONE CARRIAGE RETURN GOES.
74
+ This module leaves one in a pty's text because interpreting it would be
75
+ emulation -- and that argument inverts at a terminal, where a carriage
76
+ return is not ambiguous at all: it returns the cursor to column 0 and
77
+ whatever prints next overwrites the line the user is reading. The other
78
+ other controls below U+0020 go with it, and DEL, for the same reason
79
+ rather than for tidiness: backspace, vertical tab and form feed move a
80
+ cursor too.
81
+ A newline and a tab stay, because they are the only two a caller means.
82
+ The per-line `$ ` prefix in `main.py`'s headline loop keeps doing its own
83
+ job: measured, `str.splitlines()` splits on a carriage return as well as a
84
+ newline, so one inside a headline already became a second prefixed line
85
+ rather than an overwrite, and the forged line wears a doubled prefix.
86
+
87
+ NOT A BIDI OR ZERO-WIDTH FILTER, and that boundary is deliberate. U+202E
88
+ and its family can make a terminal draw text in an order the bytes do not
89
+ have, which is the same class of problem -- but removing them is not the
90
+ same kind of answer, because a bidi mark is legitimate content in Arabic
91
+ and Hebrew text while a control character is never legitimate content at
92
+ all. TECHNICAL_DEBT 104 carried it, and batch 160 answered it where the
93
+ answer is different: `reveal_invisible_counted` shows them as `<U+202E>`
94
+ in the two approval prompts, and nowhere else.
95
+ """
96
+
97
+ from __future__ import annotations
98
+
99
+ _ESC = "\x1b"
100
+ _BEL = "\x07"
101
+
102
+ # A partial sequence is held until it completes. A stream that opens one and
103
+ # never closes it would otherwise hold text forever, so a carry this long is
104
+ # declared malformed and released as ordinary text. Longer than any real
105
+ # sequence: an OSC title is the longest thing that legitimately gets here.
106
+ _MAX_CARRY = 4096
107
+
108
+ # CSI runs ESC [ , parameter and intermediate bytes, then ONE final byte in
109
+ # this range. Splitting the ranges out is what keeps this a scanner rather
110
+ # than a parser (G2's line): it finds where a sequence ENDS and never asks
111
+ # what it meant.
112
+ _CSI_FINAL = frozenset(chr(c) for c in range(0x40, 0x7F))
113
+ # ESC ( B and friends: one intermediate, then one final byte.
114
+ _CHARSET = frozenset("()*+-./")
115
+ # Sequences that run until a String Terminator (ESC \) or, for OSC, a BEL.
116
+ _STRING_OPENERS = frozenset("]P^_X")
117
+
118
+ # The 8-bit forms. Each is one character where the ESC form is two, and
119
+ # means exactly the same thing to a terminal that decodes it -- so the
120
+ # scanner below reaches the SAME two helpers for either spelling, which is
121
+ # what keeps there being one answer per sequence shape rather than two.
122
+ _C1_CSI = "\x9b" # ESC [
123
+ _C1_ST = "\x9c" # ESC \ , a terminator rather than an opener
124
+ # DCS, SOS, OSC, PM, APC: ESC P, ESC X, ESC ], ESC ^, ESC _
125
+ _C1_STRING_OPENERS = frozenset("\x90\x98\x9d\x9e\x9f")
126
+ # Every Unicode C1 control. The ones that are not introducers are single-character
127
+ # controls a terminal still ACTS on (U+0084 is IND, U+0085 is NEL), and
128
+ # their ESC spellings were already removed by the fallback at the end of
129
+ # `_sequence_end`, so removing these is the symmetry and not a widening.
130
+ _C1 = frozenset(chr(c) for c in range(0x80, 0xA0))
131
+
132
+
133
+ class AnsiStripper:
134
+ """Escape sequences out, CRLF to LF, everything else untouched.
135
+
136
+ CRLF is folded because it is the PTY's artifact and not the program's
137
+ text: the same command run by `shell` returns LF, and a session whose
138
+ output differed from a one-shot run's by a carriage return per line
139
+ would be the drift EP6 names, in the only place the agent can see it.
140
+ A LONE CR is left exactly where it was -- see the module docstring.
141
+
142
+ `release_unterminated` is the pty's answer by default and the module
143
+ docstring argues both; `False` is the transcript's, where a carry that
144
+ never completed must not become text. It governs BOTH releases -- the
145
+ `_MAX_CARRY` overflow and `flush` -- because they are the same event
146
+ reached by two routes, and covering one would leave the other as the
147
+ way out.
148
+
149
+ `sequences_removed` counts what this object took out, so a caller can
150
+ say that something was removed without rescanning the text to find out.
151
+ Nothing here decides what to do with that count; the only thing that
152
+ could is the layer that knows who is reading.
153
+ """
154
+
155
+ def __init__(self, *, release_unterminated: bool = True) -> None:
156
+ self._carry = ""
157
+ self._release = release_unterminated
158
+ self.sequences_removed = 0
159
+
160
+ def feed(self, text: str) -> str:
161
+ if not text:
162
+ return ""
163
+ s = self._carry + text
164
+ self._carry = ""
165
+ out: list[str] = []
166
+ i, n = 0, len(s)
167
+ while i < n:
168
+ ch = s[i]
169
+ if ch == _ESC or ch in _C1:
170
+ end = _sequence_end(s, i)
171
+ if end is None:
172
+ self._carry = s[i:]
173
+ break
174
+ self.sequences_removed += 1
175
+ i = end
176
+ continue
177
+ if ch == "\r":
178
+ if i + 1 == n:
179
+ # It may be the CR of a CRLF whose LF is in the next
180
+ # read. Held rather than emitted, because deciding now
181
+ # is deciding without the evidence.
182
+ self._carry = "\r"
183
+ break
184
+ if s[i + 1] == "\n":
185
+ out.append("\n")
186
+ i += 2
187
+ continue
188
+ out.append(ch)
189
+ i += 1
190
+ if len(self._carry) > _MAX_CARRY:
191
+ # The declared-malformed release. For the pty it is text (see
192
+ # _MAX_CARRY's own comment); for a transcript it is the leak
193
+ # this flag exists to close, and dropping it costs at most
194
+ # _MAX_CARRY characters of a sequence nobody ever closed.
195
+ if self._release:
196
+ out.append(self._carry)
197
+ else:
198
+ self.sequences_removed += 1
199
+ self._carry = ""
200
+ return "".join(out)
201
+
202
+ def flush(self) -> str:
203
+ """The end of the stream: an unterminated carry was never a
204
+ sequence, so it is text after all -- unless the caller said it is
205
+ not, in which case it is dropped and nothing is returned. See the
206
+ class docstring for which consumer wants which."""
207
+ held, self._carry = self._carry, ""
208
+ if not self._release:
209
+ if held:
210
+ self.sequences_removed += 1
211
+ return ""
212
+ return held
213
+
214
+
215
+ # What `for_display` will not hand to a terminal. The 8-bit controls at
216
+ # U+0080-U+009F are already gone by the time this applies --
217
+ # `_sequence_end` removes every one of them -- so this is U+0000-U+001F
218
+ # plus DEL, less the two a caller means.
219
+ _DISPLAY_KEEPS = frozenset("\n\t")
220
+ _NOT_PRINTABLE = (frozenset(chr(c) for c in range(0x20)) - _DISPLAY_KEEPS
221
+ | frozenset("\x7f"))
222
+
223
+
224
+ def for_display_counted(text) -> tuple[str, int]:
225
+ """*text* as it may be PRINTED to a terminal, and what that cost.
226
+
227
+ The count is sequences-and-controls REMOVED, and that is why this form
228
+ exists at all: `main.py`'s consent prompts say so out loud, because a
229
+ tool call whose headline tries to move the cursor is evidence about the
230
+ decision being asked rather than a rendering detail. Folding CRLF to
231
+ LF is NOT counted -- it is a normalisation, and counting it would put
232
+ the warning on ordinary text that arrived with Windows line endings.
233
+
234
+ Takes anything rather than only a str, so a call site can hand it the
235
+ same `payload.get(...)` an f-string would have interpolated, None
236
+ included. The alternative is twenty call sites each deciding how to
237
+ coerce, which is the shape this module exists to prevent.
238
+ """
239
+ stripper = AnsiStripper(release_unterminated=False)
240
+ scanned = stripper.feed(str(text)) + stripper.flush()
241
+ kept = "".join(ch for ch in scanned if ch not in _NOT_PRINTABLE)
242
+ return kept, stripper.sequences_removed + len(scanned) - len(kept)
243
+
244
+
245
+ def for_display(text) -> str:
246
+ """`for_display_counted` without the count, for the callers printing
247
+ untrusted text where nothing is being decided -- a replayed thread, a
248
+ research pass's progress lines. Defined in terms of it rather than
249
+ beside it, so there is one scanner and one answer.
250
+ """
251
+ return for_display_counted(text)[0]
252
+
253
+
254
+ #: Characters that change how text is DRAWN without being drawn
255
+ #: (TECHNICAL_DEBT 104, batch 160): the bidirectional embeddings, overrides
256
+ #: and isolates, the marks, the zero-width characters and the byte-order
257
+ #: mark, the invisible operators, and the TAG block -- which is ASCII
258
+ #: spelled invisibly, and the published way to smuggle text past a reader.
259
+ _INVISIBLE = frozenset(
260
+ [0x061C, 0x180E, 0xFEFF]
261
+ + list(range(0x200B, 0x2010))
262
+ + list(range(0x202A, 0x202F))
263
+ + list(range(0x2060, 0x2065))
264
+ + list(range(0x2066, 0x206A))
265
+ + list(range(0xE0000, 0xE0080)))
266
+ _REVEALED = {code: f"<U+{code:04X}>" for code in _INVISIBLE}
267
+
268
+
269
+ def reveal_invisible_counted(text) -> tuple[str, int]:
270
+ """*text* with each character in `_INVISIBLE` shown as `<U+XXXX>`, and
271
+ how many there were.
272
+
273
+ FOR CONSENT PROMPTS ONLY, by owner ruling (batch 160), and that scope
274
+ is the module docstring's reason applied rather than set aside. A bidi
275
+ mark is ordinary content in Arabic and Hebrew, a zero-width joiner
276
+ builds every family emoji, a non-joiner spells Persian -- so revealing
277
+ them in a transcript corrupts correct text. In an approval the trade
278
+ reverses: the text is a command a person is about to authorise, a
279
+ U+202E can draw it in an order its bytes do not have (the Trojan Source
280
+ class), and the reader needs the bytes. Revealed rather than removed,
281
+ because removing one is the corruption, and a reader shown
282
+ `<U+202E>` can see both what is there and that something was.
283
+
284
+ Takes anything, as `for_display_counted` does; meant to run on its
285
+ output, since a control character is removed and an invisible one is
286
+ shown, and the two never overlap.
287
+ """
288
+ text = str(text)
289
+ count = sum(1 for ch in text if ord(ch) in _INVISIBLE)
290
+ if not count:
291
+ return text, 0
292
+ return text.translate(_REVEALED), count
293
+
294
+
295
+ def _sequence_end(s: str, i: int) -> int | None:
296
+ """Index just past the escape sequence at *i*, or None if it is not all
297
+ here yet. *s[i]* is ESC or a Unicode C1 control (batch 145).
298
+
299
+ The two spellings reach the SAME two scanners -- a CSI ends at its final
300
+ byte, a string sequence ends at its terminator -- and differ only in
301
+ where the body starts, one character in for a Unicode C1 introducer and two for
302
+ ESC. That is the whole of the difference, which is why it is expressed
303
+ as an offset rather than as a second branch per shape.
304
+ """
305
+ n = len(s)
306
+ ch = s[i]
307
+ if ch != _ESC:
308
+ if ch == _C1_CSI:
309
+ return _csi_end(s, i + 1)
310
+ if ch in _C1_STRING_OPENERS:
311
+ return _string_end(s, i + 1)
312
+ # Every other Unicode C1 is a single-character control, ST included: it
313
+ # terminates a string sequence, and a bare one outside any
314
+ # sequence is still a control the terminal would act on.
315
+ return i + 1
316
+ if i + 1 >= n:
317
+ return None
318
+ opener = s[i + 1]
319
+ if opener == "[":
320
+ return _csi_end(s, i + 2)
321
+ if opener in _STRING_OPENERS:
322
+ return _string_end(s, i + 2)
323
+ if opener in _CHARSET:
324
+ return i + 3 if i + 2 < n else None
325
+ return i + 2
326
+
327
+
328
+ def _csi_end(s: str, j: int) -> int | None:
329
+ """Index just past the CSI sequence whose BODY starts at *j*."""
330
+ n = len(s)
331
+ while j < n:
332
+ if s[j] in _CSI_FINAL:
333
+ return j + 1
334
+ j += 1
335
+ return None
336
+
337
+
338
+ def _string_end(s: str, j: int) -> int | None:
339
+ """Index just past the string sequence whose BODY starts at *j*.
340
+
341
+ Three terminators, because a sender may mix the spellings freely: BEL
342
+ (OSC's traditional one), `ESC \\`, and the 8-bit ST U+009C. An OSC
343
+ opened with ESC and closed with the 8-bit ST is legal and was not
344
+ recognised before batch 145, which left the ESC consumed and the
345
+ terminator standing.
346
+ """
347
+ n = len(s)
348
+ while j < n:
349
+ if s[j] == _BEL or s[j] == _C1_ST:
350
+ return j + 1
351
+ if s[j] == _ESC:
352
+ if j + 1 >= n:
353
+ return None
354
+ if s[j + 1] == "\\":
355
+ return j + 2
356
+ j += 1
357
+ return None
358
+
359
+
360
+ class PromptSplitter:
361
+ """Takes the harness's prompt token back out, and says when it landed.
362
+
363
+ SS34's sentinel is machinery, not output: the agent asked for a command's
364
+ result and a token this process minted is not part of it. It is removed
365
+ from what the buffer keeps, and what it MEANT is kept as a count.
366
+
367
+ TWO facts, because one cannot answer it. `ready_count` counts how many
368
+ times the shell has PRINTED its prompt, and `at_prompt` says whether the
369
+ stream is resting on one right now. A caller marks the count, writes,
370
+ and waits for both (SS26): the count alone would miss the ordinary case
371
+ where a command's output and the prompt that follows it arrive in a
372
+ SINGLE read -- a transition never happens because the shell was already
373
+ at a prompt when the call began -- and `at_prompt` alone would answer
374
+ yes to that same pre-existing prompt before the command had even run.
375
+
376
+ Together they also hold the only case where the token could lie: a
377
+ command that PRINTS it. That raises the count, but the output which
378
+ follows clears `at_prompt`, so no false ready is left standing.
379
+ """
380
+
381
+ def __init__(self, token: str) -> None:
382
+ self._token = token
383
+ self._carry = ""
384
+ self.ready_count = 0
385
+ self.at_prompt = False
386
+
387
+ def feed(self, text: str) -> str:
388
+ if not text:
389
+ return ""
390
+ s = self._carry + text
391
+ self._carry = ""
392
+ if not self._token:
393
+ return s
394
+ hits = s.count(self._token)
395
+ # Read BEFORE the removal, and off the carry-joined text, so a token
396
+ # split across two reads is still seen to end the stream.
397
+ self.at_prompt = s.endswith(self._token)
398
+ if hits:
399
+ self.ready_count += hits
400
+ s = s.replace(self._token, "")
401
+ # Hold back only what could still BECOME the token, so at most
402
+ # len(token)-1 characters are ever delayed, and only when they
403
+ # already look like its beginning.
404
+ keep = _prefix_held(s, self._token)
405
+ if keep:
406
+ s, self._carry = s[:-keep], s[-keep:]
407
+ return s
408
+
409
+ def flush(self) -> str:
410
+ held, self._carry = self._carry, ""
411
+ return held
412
+
413
+
414
+ def _prefix_held(s: str, token: str) -> int:
415
+ """How many trailing characters of *s* are a proper prefix of *token*."""
416
+ longest = min(len(token) - 1, len(s))
417
+ for size in range(longest, 0, -1):
418
+ if token.startswith(s[-size:]):
419
+ return size
420
+ return 0
421
+
422
+
423
+ class PtyStream:
424
+ """Both transforms, in the one order they can go in.
425
+
426
+ Escapes first: the token is looked for in TEXT, and a sequence sitting
427
+ between the prompt and the end of the stream would hide it. One object,
428
+ so a caller cannot hold them in the other order or forget one.
429
+ """
430
+
431
+ def __init__(self, token: str) -> None:
432
+ # Required, with no default. A stream with no token to look for
433
+ # would report a prompt that never comes, which is the shape of
434
+ # every one of SS26's bounds answering wrongly -- and nothing
435
+ # builds one: an interactive session always has a minted token,
436
+ # and no other kind builds a PtyStream at all.
437
+ self._ansi = AnsiStripper()
438
+ self._prompt = PromptSplitter(token)
439
+
440
+ @property
441
+ def ready_count(self) -> int:
442
+ return self._prompt.ready_count
443
+
444
+ @property
445
+ def at_prompt(self) -> bool:
446
+ return self._prompt.at_prompt
447
+
448
+ def feed(self, text: str) -> str:
449
+ return self._prompt.feed(self._ansi.feed(text))
450
+
451
+ def flush(self) -> str:
452
+ return self._prompt.feed(self._ansi.flush()) + self._prompt.flush()