@yahyahammad/venastine 0.2.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 (129) hide show
  1. package/.env.example +19 -14
  2. package/CONFIG_ARCHITECTURE.md +2002 -0
  3. package/NOTICE +1 -1
  4. package/README.md +233 -94
  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 +277 -43
  12. package/agents/tui_commands.py +7 -12
  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 +158 -20
  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 +1238 -82
  29. package/core/commands.py +454 -0
  30. package/core/compaction.py +830 -66
  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 +1516 -440
  38. package/core/memory.py +120 -8
  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 +158 -26
  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 +1671 -199
  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 +7 -12
  70. package/package.json +234 -4
  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 +51 -2
  80. package/requirements.txt +252 -29
  81. package/safety/policy_enforcement.py +353 -17
  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 +368 -35
  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 +347 -30
  118. package/tui/app.py +4645 -438
  119. package/tui/app.tcss +185 -2
  120. package/tui/commands.py +10 -154
  121. package/tui/diffs.py +286 -265
  122. package/tui/hosted_driver.py +102 -0
  123. package/tui/markdown.py +60 -10
  124. package/tui/meters.py +103 -7
  125. package/tui/screens.py +346 -92
  126. package/tui/themes.py +59 -19
  127. package/tui/widgets.py +1575 -111
  128. package/SECURITY.md +0 -88
  129. package/THIRD_PARTY_NOTICES.md +0 -100
@@ -0,0 +1,364 @@
1
+ """
2
+ core/call_view.py
3
+
4
+ ROADMAP_v3 §55 (TR6-TR15). What ONE tool call's view shows: the whole
5
+ command the agent ran, and what it printed.
6
+
7
+ WHY THERE WAS NOTHING TO SHOW. A successful tool's result reached the model
8
+ and no screen. `tui/app.py`'s `tool_result` branch writes a transcript line
9
+ only when the call FAILED, plus an inline diff for `write` and `edit`; the
10
+ command itself is a one-line 140-character `param_digest`. And
11
+ `core/replay.py` skips `role == "tool"` rows outright (T4), because "a
12
+ grounding-heavy thread carries hundreds of kilobytes of fetched page text in
13
+ its tool_result rows; replaying that would bury the conversation in the
14
+ material the conversation was about".
15
+
16
+ T4 IS STILL RIGHT, AND IT IS WHY THIS IS A PANE (TR6). The question §55
17
+ asks is not "should tool output be in the transcript" -- T4 answered that
18
+ and the answer has not changed -- but "can a reader reach it on purpose".
19
+ A pane is reachable and never in the way; an expanding block in the
20
+ transcript would be T4 undone by a feature, and would cost a full
21
+ `rerender()` and the reader's scroll position every time it was toggled.
22
+
23
+ NOTHING IS RETAINED FOR THIS (TR8). Measured before a line was written:
24
+ `core/memory.add_tool_result` persists `str(result)` to the messages table
25
+ keyed by `tool_call_id`, and `core/client.py` hands the provider that SAME
26
+ string. So the archive already holds, byte for byte, what the agent was
27
+ given -- SS18's promise reaching a one-shot call for free. There is no cap
28
+ to choose, no eviction policy, and a restart costs nothing.
29
+
30
+ WHY IT IS HERE AND NOT IN `tui/`. core/session_view.py's reason, one
31
+ subject over: D12 makes the CLI a permanent fallback, so what may be shown
32
+ for a call is a policy decision that must not differ between the two
33
+ shells. Each shell decides how to paint the entries; this decides what they
34
+ are. Both shells paint them since ROADMAP_v3 §89: the TUI on a ctrl+click,
35
+ the CLI on `/call N` (`cli_commands.py`), which closed TECHNICAL_DEBT 45.
36
+
37
+ THE PRICE OF `str(result)` IS READABILITY, AND IT IS PAID HERE (TR9). The
38
+ stored string is a Python repr -- `{'stdout': 'hello\\n', ...}` -- so the
39
+ newlines a reader wants are two characters. `ast.literal_eval` turns it
40
+ back into the dict whenever it round-trips, and the raw string is drawn
41
+ when it does not. The fallback is never WRONG: it is what the model read.
42
+ It is not a security boundary either, because `literal_eval` evaluates
43
+ nothing; and a hostile nesting cannot exhaust the stack here, because
44
+ `check_output_policy`'s `_MAX_SCAN_DEPTH` already failed CLOSED on anything
45
+ deeper than twelve levels before this string was ever written. What the
46
+ fallback is actually for is a repr that was never a literal --
47
+ `<Foo object at 0x7f…>` from a tool returning something exotic.
48
+
49
+ REDACTED FOR DISPLAY, BOTH HALVES, AND THEY ARE NOT SYMMETRIC (TR15). The
50
+ RESULT was redacted inside `registry.dispatch`, so running it through
51
+ `check_output_policy` again is idempotent and costs one walk --
52
+ core/session_wake.py says why a local copy would be the implementation
53
+ that drifts. The PARAMS were never redacted at rest: `param_digest`
54
+ redacts for DISPLAY and the archive keeps what the model sent, so this
55
+ pane is a NEW place a credential could surface, and that is why the params
56
+ go through the real policy rather than being trusted because they are
57
+ "only arguments".
58
+ """
59
+
60
+ from __future__ import annotations
61
+
62
+ import ast
63
+ from typing import Optional
64
+ from uuid import UUID
65
+
66
+ from core.session_view import ViewEntry, output_lines, tail_chars
67
+ from safety.policy_enforcement import check_output_policy
68
+ from storage import archive_history
69
+
70
+ #: Said above a result that is not a Python literal, so a reader knows the
71
+ #: escaped newlines they are looking at are the string itself rather than
72
+ #: this view declining to do its job (TR9).
73
+ UNPARSED = ("This result is not a Python literal, so it is shown exactly "
74
+ "as the model received it.")
75
+
76
+ #: Said when the call has no result row yet (TR11). D20 persists the
77
+ #: assistant turn with its tool_use blocks BEFORE anything runs, so the
78
+ #: command is readable the instant the line is drawn and the result
79
+ #: genuinely is not there -- a real state, and one that has to be said
80
+ #: rather than drawn as an empty section. `open_agent_thread`'s rule: a
81
+ #: deliberate click answered with silence reads as a broken feature.
82
+ NOT_FINISHED = ("Its result is not in the archive yet. This is the call, "
83
+ "not what it returned.")
84
+
85
+ #: Said when a call is drawn for a tool whose result row is there but
86
+ #: whose assistant row is not -- a thread hand-edited, or one whose
87
+ #: assistant row was written by something older. The name is unknown
88
+ #: rather than guessed.
89
+ UNNAMED = "tool"
90
+
91
+ #: Params drawn before the rest, in this order, because the shell family
92
+ #: puts the thing a reader came for in `command` and `param_digest`'s own
93
+ #: ordering problem (§42, RA3) was a rationale leading the line. Every
94
+ #: other param keeps the order the model sent it in -- which is a fact
95
+ #: about the call, and sorting it would be this view inventing one.
96
+ _LEADING = ("command", "rationale")
97
+
98
+ #: `rationale` reads as `why:` here, exactly as `core/session_view.py`
99
+ #: spells it. One vocabulary across the two panes: a reader who has opened
100
+ #: a session view already knows what the word means.
101
+ _LABELS = {"rationale": "why"}
102
+
103
+
104
+ class _Budget:
105
+ """How much text one section of one view may draw (TR13).
106
+
107
+ PER SECTION, NOT PER VIEW, and that is the whole reason this is an
108
+ object rather than a slice. One budget shared between the params and
109
+ the result would let a `write` whose `content` is a large file eat
110
+ the allowance before the result -- which is the half a reader opened
111
+ the pane for. Two sections, one NUMBER (`tail_chars()`), so there is
112
+ still a single answer to "how much output is one read".
113
+ """
114
+
115
+ def __init__(self, limit: int) -> None:
116
+ self.left = max(0, int(limit))
117
+
118
+ def take(self, text: str) -> tuple[str, int]:
119
+ """`(what to draw, how many characters were left out)`."""
120
+ if len(text) <= self.left:
121
+ self.left -= len(text)
122
+ return text, 0
123
+ kept = text[:self.left]
124
+ self.left = 0
125
+ return kept, len(text) - len(kept)
126
+
127
+
128
+ def _omitted(count: int) -> ViewEntry:
129
+ """The notice a cut section carries.
130
+
131
+ THE COUNT, not the word "truncated". PG4's complaint about a
132
+ truncated value that says nothing: a reader who knows 180,000
133
+ characters are missing knows to go to the archive, and one told only
134
+ that something was cut does not know whether it was a line or a
135
+ library.
136
+ """
137
+ return ("system", f"… {count:,} more characters, not shown here.")
138
+
139
+
140
+ def _clean_params(name: str, params: dict) -> dict:
141
+ """The call's params through the real output policy (TR15).
142
+
143
+ FLAT, with each value starting at depth 0, which is what a tool
144
+ RESULT's values do -- so the depth cap means here exactly what it
145
+ means where it was designed. Wrapping them under one key to save a
146
+ call would have quietly spent a level of the budget that fails
147
+ closed.
148
+
149
+ THE NAME IS DECORATED, which is a one-word fix to an honest-logging
150
+ problem rather than a flourish. `check_output_policy` logs one
151
+ WARNING naming the tool whenever it replaces something, and its
152
+ sentence says "result" -- so a credential found in a call's ARGUMENTS
153
+ would be reported as having been found in its output. The tool name
154
+ is the only thing that message reads (verified: nothing in that
155
+ function branches on it), so saying which half this was costs
156
+ nothing and keeps the one place a reader learns a secret surfaced
157
+ from pointing at the wrong half of the call.
158
+ """
159
+ return check_output_policy(f"{name} (call params)", dict(params))
160
+
161
+
162
+ def _clean_result(name: str, text: str) -> str:
163
+ """The stored result string, re-run through the policy (TR15).
164
+
165
+ Idempotent by construction -- it was redacted at dispatch -- and run
166
+ anyway, because that is what keeps this function's promise true of
167
+ BOTH sources rather than of one plus an assumption about the other.
168
+ core/session_view.py makes the same choice for the same reason.
169
+ """
170
+ return str(check_output_policy(name, {"result": text})["result"])
171
+
172
+
173
+ def _parse(text: str):
174
+ """`(value, True)` when the stored repr round-trips, `(None, False)`
175
+ when it does not (TR9).
176
+
177
+ CAUGHT BROADLY, and the reason is `_as_text`'s: this feeds a display
178
+ surface, so a stored row that raises must cost its own section rather
179
+ than the whole pane. The fallback is not a degraded answer either --
180
+ it is the exact string the model read -- so there is nothing to gain
181
+ from enumerating which exceptions `ast` can raise for input this
182
+ module did not write.
183
+ """
184
+ try:
185
+ return ast.literal_eval(text), True
186
+ except Exception: # noqa: BLE001
187
+ return None, False
188
+
189
+
190
+ def _status(parsed, parsed_ok: bool, has_result: bool) -> str:
191
+ """The clause after the tool's name in the header.
192
+
193
+ "finished" FOR AN UNPARSED RESULT, rather than a guess. Whether a
194
+ call failed is a fact about a key in its result dict, and a string
195
+ this module could not read is a string it cannot answer that about.
196
+ Searching the raw text for `'error'` would be a guess wearing the
197
+ clothes of a fact, which is the instrument-that-lies shape batches
198
+ 118 and 119 each paid for once.
199
+ """
200
+ if not has_result:
201
+ return "has not finished"
202
+ if not parsed_ok:
203
+ return "finished"
204
+ if isinstance(parsed, dict):
205
+ if "error" in parsed:
206
+ return "failed"
207
+ code = parsed.get("return_code")
208
+ if isinstance(code, int) and not isinstance(code, bool):
209
+ return f"exit code {code}"
210
+ return "succeeded"
211
+
212
+
213
+ def _keyed(key: str, value, budget: _Budget) -> list[ViewEntry]:
214
+ """One key of a params or result dict, as entries.
215
+
216
+ INLINE WHEN IT HAS NO NEWLINE, and there is no length threshold
217
+ beside that test on purpose: a long single-line value is something
218
+ the transcript already wraps, and a second number deciding when a
219
+ row becomes a block would be a number with no measurement behind it.
220
+ A value WITH newlines becomes a labelled block, because that is the
221
+ case §55 exists for -- a heredoc, an inline `python3 - <<EOF` -- and
222
+ one entry holding newlines shears its own left edge (output_lines).
223
+
224
+ AN EMPTY STRING IS DROPPED and a falsy non-string is not. `stderr:
225
+ ''` is noise on a call that succeeded; `return_code: 0` is the fact
226
+ a reader came for, and `if not value` would have eaten it.
227
+ """
228
+ label = _LABELS.get(key, key)
229
+ if isinstance(value, str):
230
+ if not value:
231
+ return []
232
+ text = value
233
+ else:
234
+ # repr, NOT json.dumps. These values are Python literals already
235
+ # -- either straight from `literal_eval` or JSON-decoded out of
236
+ # the archive -- so repr shows what is actually there, where
237
+ # re-encoding would redraw a tuple as a list and tell the reader
238
+ # about a shape the call did not have.
239
+ text = repr(value)
240
+ drawn, left_out = budget.take(text)
241
+ if not drawn:
242
+ return [("system", f"{label}:"), _omitted(left_out)]
243
+ rows: list[ViewEntry] = (
244
+ [("system", f"{label}: {drawn}")] if "\n" not in drawn
245
+ else [("system", f"{label}:")] + output_lines(drawn))
246
+ if left_out:
247
+ rows.append(_omitted(left_out))
248
+ return rows
249
+
250
+
251
+ def _call_rows(name: str, params: dict) -> list[ViewEntry]:
252
+ """The tool, then its params, leading with the ones that matter."""
253
+ rows: list[ViewEntry] = [("tool", f"▸ {name}")]
254
+ budget = _Budget(tail_chars())
255
+ clean = _clean_params(name, params)
256
+ for key in _LEADING:
257
+ if key in clean:
258
+ rows.extend(_keyed(key, clean[key], budget))
259
+ for key, value in clean.items():
260
+ if key not in _LEADING:
261
+ rows.extend(_keyed(key, value, budget))
262
+ return rows
263
+
264
+
265
+ def _result_rows(parsed, parsed_ok: bool, raw: str) -> list[ViewEntry]:
266
+ """What the call returned, as entries."""
267
+ budget = _Budget(tail_chars())
268
+ if not parsed_ok:
269
+ drawn, left_out = budget.take(raw)
270
+ rows: list[ViewEntry] = [("system", UNPARSED), ("system", "result:")]
271
+ rows.extend(output_lines(drawn))
272
+ if left_out:
273
+ rows.append(_omitted(left_out))
274
+ return rows
275
+ if isinstance(parsed, dict):
276
+ rows = []
277
+ for key, value in parsed.items():
278
+ rows.extend(_keyed(key, value, budget))
279
+ # Every key dropped means a dict of empty strings, or an empty
280
+ # dict. Said, for NOT_FINISHED's reason: a section that renders
281
+ # to nothing is indistinguishable from this view failing.
282
+ return rows or [("system", "It returned nothing.")]
283
+ return _keyed("result", parsed, budget)
284
+
285
+
286
+ def _read(thread_id: UUID, call_id: str):
287
+ """One pass over the thread's archive for one call.
288
+
289
+ `(name, params, result text, whether a result row exists)`.
290
+
291
+ ONE PASS, `core/session_view.stored_entries`' shape: the assistant row
292
+ that made the call carries the name and the exact params the model
293
+ sent, and the `tool` row carries the result as the model received it.
294
+ Two reads would be two chances to disagree about which call this is.
295
+
296
+ KEYED BY THE MODEL'S CALL ID, which is unique to the call and is what
297
+ a tool line carries anyway -- the same reason stored_entries refuses
298
+ to key a session by its per-process `s1` counter.
299
+ """
300
+ name: Optional[str] = None
301
+ params: dict = {}
302
+ result_text = ""
303
+ has_result = False
304
+ for message in archive_history(thread_id):
305
+ role = message.get("role")
306
+ if role == "assistant":
307
+ for made in message.get("tool_calls") or []:
308
+ if str(made.get("id") or "") == str(call_id):
309
+ name = str(made.get("name") or "") or None
310
+ found = made.get("input")
311
+ params = found if isinstance(found, dict) else {}
312
+ elif role == "tool":
313
+ if str(message.get("tool_call_id") or "") == str(call_id):
314
+ # LAST WINS, and it cannot happen twice: a tool_call_id is
315
+ # the model's own and M4's pairing is one result per call.
316
+ # Written as an assignment rather than a break because the
317
+ # assistant row can come after the tool row in a thread
318
+ # whose rows were written out of order, and stopping early
319
+ # would then lose the name.
320
+ result_text = _as_text(message.get("content"))
321
+ has_result = True
322
+ return name, params, result_text, has_result
323
+
324
+
325
+ def _as_text(value: object) -> str:
326
+ """core/session_view.py's `_as_text`, for the one shape this file reads.
327
+
328
+ A tool row's content is written as a string by
329
+ `memory.add_tool_result`, so nothing else should arrive -- but a
330
+ stored row is data, and reading it as though its shape were
331
+ guaranteed is how a display surface raises on somebody else's thread.
332
+ """
333
+ if isinstance(value, str):
334
+ return value
335
+ return "" if value is None else str(value)
336
+
337
+
338
+ def call_entries(thread_id: UUID, call_id: str) -> list[ViewEntry]:
339
+ """What one tool call's view shows (§55, TR6-TR15).
340
+
341
+ The header names the tool and how the call ended, then the whole
342
+ command -- un-collapsed, which is the half of TR1 `param_digest`
343
+ cannot answer and must not try to (TR2) -- then what it printed.
344
+
345
+ EMPTY when the call is not in this thread at all, which the caller
346
+ turns into its own refusal. A view of nothing is worse than a
347
+ sentence saying why, and the caller is the only thing that knows
348
+ which pane the reader is looking at.
349
+ """
350
+ name, params, raw, has_result = _read(thread_id, call_id)
351
+ if name is None and not has_result:
352
+ return []
353
+ named = name or UNNAMED
354
+ result_text = _clean_result(named, raw) if has_result else ""
355
+ parsed, parsed_ok = _parse(result_text) if has_result else (None, False)
356
+
357
+ entries: list[ViewEntry] = [
358
+ ("system", f"{named} — {_status(parsed, parsed_ok, has_result)}.")]
359
+ entries.extend(_call_rows(named, params))
360
+ if not has_result:
361
+ entries.append(("system", NOT_FINISHED))
362
+ return entries
363
+ entries.extend(_result_rows(parsed, parsed_ok, result_text))
364
+ return entries
package/core/cancel.py ADDED
@@ -0,0 +1,121 @@
1
+ """
2
+ core/cancel.py
3
+
4
+ ROADMAP_v3 §61 (CN1). How a shell stops a turn that is already running.
5
+
6
+ A turn runs on a worker thread and the key that stops it is pressed on
7
+ another one, so the two cannot touch the same generator: calling close()
8
+ on a generator a second thread is stepping raises "generator already
9
+ executing". What DOES cross a thread boundary safely is a flag, which is
10
+ why this is cooperative rather than pre-emptive -- the loop asks, at the
11
+ four sites CN2 names, and stops itself.
12
+
13
+ A LEAF MODULE with no project imports, deliberately, and for
14
+ core/approval.py's reason: core/loop.py, main.py, tui/app.py and
15
+ agents/subagent_tool.py all depend on it and it depends on none of them.
16
+ It is also why this is an object passed down rather than a ContextVar --
17
+ threads do not inherit their parent's context, which core/loop.py's
18
+ _dispatch_parallel and tui/app.py's _consume both already pay for, and a
19
+ token the tool pool could not see would be a stop switch that silently
20
+ missed the longest part of a turn.
21
+
22
+ CANCELLED IS NOT FAILED, and that distinction is why this object carries
23
+ a reason at all rather than being a bare Event. A failed run is recorded
24
+ with memory.mark_turn_failed and reads as something broken; a cancelled
25
+ one is a person changing their mind. §60's UH6 records the same rule
26
+ arriving from the other direction: UHP requires a cancelled task to end
27
+ `cancelled`, never `failed`, with partial output kept.
28
+
29
+ WHAT THIS CANNOT DO, stated here rather than discovered. A cooperative
30
+ token is read between operations, so it cannot interrupt one already
31
+ blocked inside the SDK -- most visibly the socket read before a model
32
+ call's first token, which on a thinking model is tens of seconds. It
33
+ also does not kill a tool call that is already running (CN6). Both are
34
+ limits of the mechanism and both are things a shell has to SAY while it
35
+ waits, which is the difference between a slow stop and a broken one.
36
+ """
37
+
38
+ import threading
39
+
40
+ #: What a cancellation says when nobody gave a reason. It reaches the
41
+ #: transcript and the thread, so it is phrased for a reader rather than
42
+ #: for a log.
43
+ DEFAULT_REASON = "stopped by the user"
44
+
45
+
46
+ class CancelToken:
47
+ """One run's stop switch: set by a shell, read by the loop.
48
+
49
+ ONE instance per turn, handed down beside the response channel and
50
+ the grant budget -- the shape this project already uses for "an
51
+ out-of-band object a run needs where a LoopEvent cannot reach" -- and
52
+ shared BY REFERENCE with any subagent that turn spawns (CN7), so
53
+ stopping a turn stops the children it started.
54
+
55
+ SET-ONCE. A second caller does not overwrite the first's reason: the
56
+ reason worth keeping is the one that actually stopped the run, and a
57
+ later generic "stopped by the user" landing on top of a specific
58
+ first reason would make the record less true the more often the key
59
+ was pressed.
60
+ """
61
+
62
+ def __init__(self) -> None:
63
+ self._event = threading.Event()
64
+ self._reason = DEFAULT_REASON
65
+ # Not an RLock: nothing under `cancel` re-enters this object, and
66
+ # a plain Lock is what makes that claim checkable. GrantBudget in
67
+ # core/approval.py takes the same line for the same reason.
68
+ self._lock = threading.Lock()
69
+
70
+ def cancel(self, reason: str = DEFAULT_REASON) -> bool:
71
+ """Ask the run to stop. True if THIS call is the one that set it.
72
+
73
+ The return value is what lets a shell tell a first press from a
74
+ second: the first announces that it is stopping, and a second
75
+ must not announce it again over a run that is already winding
76
+ down -- nor read as having done nothing, which is the other wrong
77
+ answer.
78
+
79
+ The test AND the write are inside the lock, for GrantBudget.take's
80
+ reason: the decision to record a reason IS the read, and a
81
+ decision made on a stale read is the defect.
82
+ """
83
+ with self._lock:
84
+ if self._event.is_set():
85
+ return False
86
+ self._reason = reason or DEFAULT_REASON
87
+ self._event.set()
88
+ return True
89
+
90
+ @property
91
+ def cancelled(self) -> bool:
92
+ """Whether the run has been asked to stop.
93
+
94
+ No lock. `threading.Event` is already safe to read from any
95
+ thread, and every caller is asking for a snapshot at a point the
96
+ loop chose. Nothing acts on a stale False except by asking again
97
+ at the next of CN2's four sites, so the only cost of losing a
98
+ race here is one more step, never a missed stop.
99
+ """
100
+ return self._event.is_set()
101
+
102
+ @property
103
+ def reason(self) -> str:
104
+ """Why, in words -- for the transcript, and for the rows a
105
+ cancelled turn leaves in its thread."""
106
+ with self._lock:
107
+ return self._reason
108
+
109
+
110
+ def is_cancelled(token) -> bool:
111
+ """True when `token` is a CancelToken that has been set.
112
+
113
+ A free function because the parameter is optional at every layer it
114
+ passes through -- None means "nothing can stop this run", which is
115
+ every caller that has not opted in, including every test that
116
+ predates §61. Writing `token is not None and token.cancelled` out at
117
+ each of CN2's sites would be four chances to get the None half wrong,
118
+ and the one that got it wrong would be a stop switch that raised
119
+ AttributeError instead of stopping.
120
+ """
121
+ return token is not None and token.cancelled