@yahyahammad/venastine 0.3.8 → 0.3.10

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 -19
  2. package/CONFIG_ARCHITECTURE.md +2139 -2002
  3. package/LICENSE +201 -201
  4. package/README.md +1043 -1034
  5. package/agents/builtin/compactor.md +75 -75
  6. package/agents/builtin/explore.md +77 -77
  7. package/agents/builtin/pipeline-reviewer.md +100 -100
  8. package/agents/builtin/plan.md +106 -106
  9. package/agents/builtin/review.md +74 -74
  10. package/agents/manager.py +261 -261
  11. package/agents/subagent_tool.py +472 -472
  12. package/agents/tui_commands.py +238 -146
  13. package/bin/venastine.mjs +584 -528
  14. package/bin/venastine.py +73 -71
  15. package/cli_commands.py +848 -835
  16. package/config.yaml +64 -0
  17. package/config_edit.py +1301 -1301
  18. package/config_schema.py +987 -966
  19. package/config_update.py +749 -749
  20. package/core/agent_activity.py +256 -256
  21. package/core/ansi.py +452 -452
  22. package/core/approval.py +137 -137
  23. package/core/call_view.py +364 -364
  24. package/core/cancel.py +121 -121
  25. package/core/chatgpt_auth.py +747 -747
  26. package/core/claims_view.py +107 -107
  27. package/core/client.py +2756 -2715
  28. package/core/commands.py +464 -454
  29. package/core/compaction.py +1735 -1735
  30. package/core/config_loader.py +1982 -1982
  31. package/core/connect.py +686 -686
  32. package/core/events.py +123 -123
  33. package/core/file_mentions.py +280 -280
  34. package/core/interaction.py +411 -411
  35. package/core/loop.py +2566 -2566
  36. package/core/memory.py +482 -482
  37. package/core/pipeline_models.py +190 -190
  38. package/core/provider_errors.py +274 -234
  39. package/core/reasoning/authorization.py +130 -130
  40. package/core/reasoning/base.py +219 -219
  41. package/core/reasoning/confidence_scoring.py +484 -484
  42. package/core/reasoning/events.py +149 -149
  43. package/core/reasoning/orchestrator.py +1561 -1561
  44. package/core/reasoning/output_writer.py +345 -345
  45. package/core/reasoning/payload_validation.py +524 -524
  46. package/core/reasoning/pipeline_storage.py +427 -427
  47. package/core/reasoning/scholar.py +467 -458
  48. package/core/reasoning/source_corpus.py +433 -433
  49. package/core/reasoning/source_scoring.py +855 -855
  50. package/core/replay.py +315 -315
  51. package/core/shell_sessions.py +1553 -1553
  52. package/credentials.py +307 -307
  53. package/database.py +333 -333
  54. package/docs/PRIVACY.md +78 -78
  55. package/docs/SECURITY.md +114 -108
  56. package/docs/THIRD_PARTY_NOTICES.md +148 -148
  57. package/env_secrets.py +118 -118
  58. package/json_store.py +343 -343
  59. package/logging_setup.py +295 -295
  60. package/main.py +3433 -3433
  61. package/mcp_client/client.py +780 -733
  62. package/mcp_client/config.py +484 -484
  63. package/mcp_client/registration.py +343 -343
  64. package/memories/manager.py +147 -147
  65. package/memories/tui_commands.py +319 -239
  66. package/package.json +303 -303
  67. package/project_init/config_files.py +282 -282
  68. package/project_init/generator.py +728 -728
  69. package/project_init/manifest.py +418 -418
  70. package/project_init/tui_commands.py +147 -147
  71. package/prompts/critic_pass.md +24 -24
  72. package/prompts/revalidate.md +25 -25
  73. package/prompts/revise.md +17 -17
  74. package/prompts/source_grounding.md +66 -66
  75. package/prompts/system_prompts.py +316 -316
  76. package/providers.json.example +94 -94
  77. package/pyproject.toml +149 -149
  78. package/requirements.txt +314 -295
  79. package/safety/policy_enforcement.py +1082 -1082
  80. package/security/askpass.py +419 -419
  81. package/security/capability.py +207 -207
  82. package/security/confine.py +484 -484
  83. package/security/hosted.py +182 -182
  84. package/security/permissions.py +237 -237
  85. package/security/protected_paths.py +501 -501
  86. package/security/sandbox.py +4108 -4108
  87. package/skills/builtin/math/formal-specification.md +67 -67
  88. package/skills/builtin/math/numerical-methods.md +66 -66
  89. package/skills/builtin/research/experiment-design.md +62 -62
  90. package/skills/builtin/research/reproducibility.md +55 -55
  91. package/skills/builtin/research/source-evaluation.md +70 -70
  92. package/skills/builtin/research/statistical-inference.md +63 -63
  93. package/skills/builtin/research/technical-writing.md +59 -59
  94. package/skills/builtin/software/code-review.md +61 -61
  95. package/skills/builtin/software/debugging.md +61 -61
  96. package/skills/builtin/software/test-design.md +67 -67
  97. package/skills/tui_commands.py +110 -110
  98. package/storage.py +1338 -1338
  99. package/tools/base.py +465 -465
  100. package/tools/builtin/_math_common.py +667 -667
  101. package/tools/builtin/_net_common.py +1145 -267
  102. package/tools/builtin/_page_text.py +490 -0
  103. package/tools/builtin/_pdf_text.py +113 -0
  104. package/tools/builtin/arxiv.py +685 -681
  105. package/tools/builtin/fetch_url.py +639 -371
  106. package/tools/builtin/file_ops.py +720 -720
  107. package/tools/builtin/geometry.py +184 -184
  108. package/tools/builtin/load_skill.py +76 -76
  109. package/tools/builtin/pin.py +227 -227
  110. package/tools/builtin/probability_stats.py +224 -224
  111. package/tools/builtin/project_docs.py +464 -464
  112. package/tools/builtin/remember.py +175 -175
  113. package/tools/builtin/shell.py +980 -980
  114. package/tools/builtin/todo.py +149 -149
  115. package/tools/builtin/web_search.py +402 -328
  116. package/tools/context.py +159 -159
  117. package/tools/isolation.py +387 -387
  118. package/tools/registry.py +1252 -1242
  119. package/tui/app.py +8372 -8307
  120. package/tui/app.tcss +754 -739
  121. package/tui/commands.py +26 -26
  122. package/tui/diffs.py +286 -286
  123. package/tui/history.py +128 -128
  124. package/tui/hosted_driver.py +102 -102
  125. package/tui/markdown.py +1329 -1329
  126. package/tui/meters.py +364 -364
  127. package/tui/ravens.py +146 -146
  128. package/tui/screens.py +1255 -1197
  129. package/tui/themes.py +599 -599
  130. package/tui/widgets.py +3861 -3796
@@ -1,256 +1,256 @@
1
- """
2
- core/agent_activity.py
3
-
4
- ROADMAP_v2 §18, batch 59: WHICH agent is running right now, and how deep.
5
-
6
- The harness runs a TREE of agents, and until §47 slice 8 it ran a stack.
7
-
8
- This paragraph used to open "the harness runs exactly one agent at a time",
9
- and that was measured rather than assumed: `core/loop.py` dispatched tool
10
- calls in a plain `for` loop and `spawn_subagent` BLOCKED on the child run,
11
- so there was never a second one alongside. NA9 partitions a response
12
- instead, so several children of one turn are now PEERS, up to
13
- config.SUBAGENT_MAX_PARALLEL of them, each still able to nest to
14
- config.SUBAGENT_MAX_DEPTH. What a shell learns from this module is
15
- therefore the shape of a tree.
16
-
17
- Almost nothing here had to change for that, which is the part worth
18
- knowing: the depth is still ToolContext.subagent_depth, the parent is
19
- still a ContextVar, and a span still brackets one run. The two things that
20
- did are outside this file -- the sink that keeps the stack needs a lock
21
- (NA16), and the panel that draws it needs lineage order rather than
22
- arrival order (NA17), because a stack can only arrive outermost-first and
23
- a tree cannot.
24
-
25
- WHY A CHANNEL AND NOT A LoopEvent, which is the obvious first reach:
26
-
27
- * A generator cannot yield from inside a nested call. spawn_subagent's
28
- handler runs inside registry.dispatch(), which runs inside the loop's
29
- per-call body -- there is no yield point there, so a child's activity
30
- cannot be turned into a parent event however much one would like it
31
- to be.
32
-
33
- STILL TRUE AFTER §47 SLICE 8, and the distinction is worth stating
34
- because NA15 adds a queue that looks like a counter-example. That
35
- conduit carries the PARENT'S own events about its own tool calls, which
36
- it would have yielded itself had it not handed the work to a thread,
37
- and it is drained by a frame that is still inside `_run` and can still
38
- yield. A child's stream reaches nothing: the bullet below is why, and
39
- D6 is unchanged.
40
- * run_agent_conversation drains its OWN _run() through
41
- run_to_completion(), so a child's events are consumed internally and
42
- never reach the parent's stream. That is not an oversight to route
43
- around; §18/D6 returns only the subagent's distilled final text, on
44
- the pipeline's "don't share raw history" principle.
45
-
46
- So this carries LIFECYCLE ONLY -- a name, a depth, an identity, and the
47
- id of the thread the run is writing. Never the child's text, tool calls,
48
- or events. A shell that wanted those would be asking for the thing D6
49
- declines to give it.
50
-
51
- §47 ADDED THE IDENTITY, AND AN IDENTIFIER IS NOT CONTENT. A run already
52
- writes its whole conversation to its own ConversationThread, and a human
53
- can already open one by id (`--ref`, `/resume`). What nobody could do was
54
- find out WHICH thread a row in the sidebar was about. So a span carries
55
- `id` and `parent_id` now, and `bind()` says which thread it opened.
56
- Everything a shell then displays it reads back out of the ARCHIVE --
57
- `core/replay.py`, the same function and the same policy `/resume` uses --
58
- so nothing here forwards a child's stream to its parent, which is what
59
- D6 is about. The distinction is the whole design: the channel gained an
60
- address, not a payload.
61
-
62
- THE PARENT COMES FROM A ContextVar, NOT FROM A PARAMETER. Five call sites
63
- open spans and none of them knows what is above it; threading a parent
64
- through all of them would put the answer in the hands of whoever
65
- remembers to pass it -- the D24/R13 failure shape. The var is set and
66
- reset inside the same context manager whose `finally` already makes
67
- `exit` unforgettable, so the two cannot drift. It is also the shape that
68
- survives concurrency: a ContextVar is per-thread, so a run submitted to
69
- an executor takes `contextvars.copy_context()` with it rather than
70
- reading a variable that would be wrong the moment two children run.
71
-
72
- It rides the same route response_channel already rides (loop -> dispatch
73
- -> handler -> the child's own loop), for the same reason: an out-of-band
74
- object is what crosses a boundary a generator cannot.
75
-
76
- Lives in core/ rather than tui/ because D12 makes the CLI a permanent
77
- fallback -- and because nothing here knows what a widget is.
78
- """
79
-
80
- import logging
81
- from contextlib import contextmanager
82
- from contextvars import ContextVar
83
- from dataclasses import dataclass, field
84
- from typing import Optional
85
- from uuid import uuid4
86
-
87
- logger = logging.getLogger(__name__)
88
-
89
- #: The innermost span open on THIS thread, or None. Read by `span()` to
90
- #: find a new span's parent and by `bind()` to find the run whose thread
91
- #: has just been created. Module-level and private: nothing outside this
92
- #: file sets it, so the context manager below is the only writer.
93
- _CURRENT: ContextVar = ContextVar("venastine_agent_span", default=None)
94
-
95
-
96
- @dataclass(frozen=True)
97
- class AgentSpan:
98
- """One agent-shaped run, while it is running.
99
-
100
- `depth` is ToolContext.subagent_depth -- the value C3 bounds, so a
101
- consumer indenting by it is drawing the same nesting the depth limit
102
- is about. Frozen because a span is posted to another thread and read
103
- later; a mutable one would be a second writer of the stack.
104
-
105
- `id` is minted per span rather than derived from anything, because
106
- the thing it has to distinguish is two runs that agree on every other
107
- field: a goal turn spawning `explore` twice gives two spans with the
108
- same name and the same depth, and a sink that could not tell them
109
- apart had to pop by last match and hope. `parent_id` is the enclosing
110
- span's, or None at the root.
111
-
112
- NEITHER IS THE THREAD ID, and the gap between them is deliberate. A
113
- span opens BEFORE the run it describes creates its thread -- the
114
- handler brackets the call, the thread is made inside it -- so the
115
- address arrives later, through `bind()`. A frozen span cannot be
116
- edited to hold it, which is correct: the binding belongs to the sink,
117
- which is the thing that has to redraw when it arrives.
118
- """
119
- name: str
120
- depth: int
121
- # Defaulted so `AgentSpan("explore", 1)` still constructs -- the
122
- # positional pair is what every existing caller and test writes.
123
- id: str = field(default_factory=lambda: uuid4().hex)
124
- parent_id: Optional[str] = None
125
- # §47. WHICH tool call started this run, when one did. The same
126
- # kind of fact as the name and the depth -- what the run IS --
127
- # rather than a second channel: a shell that knows both this and
128
- # the bound thread can make the CALL LINE in the transcript open
129
- # the run while it is still going, instead of only once its
130
- # result comes back. None for the compactor and the reviewer,
131
- # which no tool call starts.
132
- call_id: Optional[str] = None
133
-
134
-
135
- class AgentActivity:
136
- """A sink for span lifecycle. Override enter/exit; use span().
137
-
138
- The base class is the null sink, so `NULL` below is an instance of
139
- this rather than a separate do-nothing type -- one class, and a
140
- subclass that overrides only what it cares about.
141
- """
142
-
143
- def enter(self, span: AgentSpan) -> None:
144
- """A run began. Called on whatever thread the run is on."""
145
-
146
- def exit(self, span: AgentSpan) -> None:
147
- """That run ended -- successfully or not."""
148
-
149
- def bind(self, span_id: str, thread_id) -> None:
150
- """That run's conversation thread exists, and this is its id.
151
-
152
- Separate from `enter` because it genuinely happens later: the
153
- span brackets the call, and the thread is created inside it. A
154
- sink that wants to make a row openable holds this against the
155
- span id it was given at `enter`.
156
-
157
- Called at most once per span, and not at all for a run that
158
- never gets that far -- a spawn refused before it starts. A run
159
- whose provider fails at the FIRST CALL is bound all the same:
160
- `run_agent_conversation` binds as soon as the thread exists, before
161
- its user message and before any model call, which is what lets a
162
- failed child still be opened from its spawn line. (This docstring
163
- said the opposite until batch 91.)
164
- """
165
-
166
- @contextmanager
167
- def span(self, name: str, depth: int, call_id=None):
168
- """Bracket one agent-shaped run.
169
-
170
- A CONTEXT MANAGER RATHER THAN A PAIR OF CALLS, and that is the
171
- whole reason this module exists as more than a dataclass. `exit`
172
- has to run when the child RAISES -- a subagent whose provider
173
- errors, a compactor that times out -- or its row stays on screen
174
- for the rest of the session, describing a run that is over. A
175
- panel that lies is worse than no panel, and the way to make the
176
- `finally` unforgettable is to make it structural.
177
-
178
- FAILURES IN THE SINK ARE CONTAINED, both halves. A sink is
179
- display machinery; a raise inside one must not take down the run
180
- it is merely describing. Logged rather than swallowed silently,
181
- so a broken sink is findable -- the same posture
182
- tools/registry.dispatch() takes around a tool handler.
183
-
184
- THE ContextVar IS RESET IN THE SAME `finally` AS `exit`, and that
185
- pairing is the point rather than a convenience. A token that
186
- outlived its span would make the NEXT sibling a child of a run
187
- that has finished -- lineage that is wrong rather than missing,
188
- which is the harder kind to notice. `reset(token)` rather than
189
- `set(parent)`, because that is what restores the exact state this
190
- frame found, including "there was nothing".
191
- """
192
- parent = _CURRENT.get()
193
- span = AgentSpan(
194
- name, depth, call_id=call_id,
195
- parent_id=parent.id if parent is not None else None)
196
- token = _CURRENT.set(span)
197
- try:
198
- self.enter(span)
199
- except Exception: # noqa: BLE001 -- contained
200
- logger.exception("agent activity sink raised on enter")
201
- try:
202
- yield span
203
- finally:
204
- _CURRENT.reset(token)
205
- try:
206
- self.exit(span)
207
- except Exception: # noqa: BLE001 -- contained
208
- logger.exception("agent activity sink raised on exit")
209
-
210
-
211
- NULL = AgentActivity()
212
- """The no-op sink. Every non-TUI shell runs on this."""
213
-
214
-
215
- def span(activity, name: str, depth: int, call_id=None):
216
- """Bracket a run against an OPTIONAL sink.
217
-
218
- `activity` is None on every path but the TUI's, and this is what
219
- keeps the call sites unconditional: one `with` statement, no branch,
220
- nothing to get wrong at the five places that open a span. Callers say
221
- `with agent_activity.span(activity, name, depth):` and never have to
222
- ask whether anyone is watching.
223
- """
224
- return (activity or NULL).span(name, depth, call_id)
225
-
226
-
227
- def current() -> Optional[AgentSpan]:
228
- """The innermost span open on this thread, or None.
229
-
230
- Public because two things outside this module need to know which run
231
- is speaking without being handed it: `bind()` below, and the approval
232
- path, which names the asking agent on a modal that would otherwise
233
- say only which TOOL was asked for.
234
- """
235
- return _CURRENT.get()
236
-
237
-
238
- def bind(activity, thread_id) -> None:
239
- """Tell the sink which thread the innermost open run is writing.
240
-
241
- A no-op when nothing is open, which is the ordinary state of a
242
- top-level `run_agent_conversation` -- the CLI's chat, a test calling
243
- it directly. That is why the call site needs no branch, matching
244
- `span()` above.
245
-
246
- CONTAINED like the sink's other two calls, and for the identical
247
- reason: this is display machinery. A sink that raises while learning
248
- an id must not fail the run whose id it was learning.
249
- """
250
- span = _CURRENT.get()
251
- if span is None or thread_id is None:
252
- return
253
- try:
254
- (activity or NULL).bind(span.id, thread_id)
255
- except Exception: # noqa: BLE001 -- contained
256
- logger.exception("agent activity sink raised on bind")
1
+ """
2
+ core/agent_activity.py
3
+
4
+ ROADMAP_v2 §18, batch 59: WHICH agent is running right now, and how deep.
5
+
6
+ The harness runs a TREE of agents, and until §47 slice 8 it ran a stack.
7
+
8
+ This paragraph used to open "the harness runs exactly one agent at a time",
9
+ and that was measured rather than assumed: `core/loop.py` dispatched tool
10
+ calls in a plain `for` loop and `spawn_subagent` BLOCKED on the child run,
11
+ so there was never a second one alongside. NA9 partitions a response
12
+ instead, so several children of one turn are now PEERS, up to
13
+ config.SUBAGENT_MAX_PARALLEL of them, each still able to nest to
14
+ config.SUBAGENT_MAX_DEPTH. What a shell learns from this module is
15
+ therefore the shape of a tree.
16
+
17
+ Almost nothing here had to change for that, which is the part worth
18
+ knowing: the depth is still ToolContext.subagent_depth, the parent is
19
+ still a ContextVar, and a span still brackets one run. The two things that
20
+ did are outside this file -- the sink that keeps the stack needs a lock
21
+ (NA16), and the panel that draws it needs lineage order rather than
22
+ arrival order (NA17), because a stack can only arrive outermost-first and
23
+ a tree cannot.
24
+
25
+ WHY A CHANNEL AND NOT A LoopEvent, which is the obvious first reach:
26
+
27
+ * A generator cannot yield from inside a nested call. spawn_subagent's
28
+ handler runs inside registry.dispatch(), which runs inside the loop's
29
+ per-call body -- there is no yield point there, so a child's activity
30
+ cannot be turned into a parent event however much one would like it
31
+ to be.
32
+
33
+ STILL TRUE AFTER §47 SLICE 8, and the distinction is worth stating
34
+ because NA15 adds a queue that looks like a counter-example. That
35
+ conduit carries the PARENT'S own events about its own tool calls, which
36
+ it would have yielded itself had it not handed the work to a thread,
37
+ and it is drained by a frame that is still inside `_run` and can still
38
+ yield. A child's stream reaches nothing: the bullet below is why, and
39
+ D6 is unchanged.
40
+ * run_agent_conversation drains its OWN _run() through
41
+ run_to_completion(), so a child's events are consumed internally and
42
+ never reach the parent's stream. That is not an oversight to route
43
+ around; §18/D6 returns only the subagent's distilled final text, on
44
+ the pipeline's "don't share raw history" principle.
45
+
46
+ So this carries LIFECYCLE ONLY -- a name, a depth, an identity, and the
47
+ id of the thread the run is writing. Never the child's text, tool calls,
48
+ or events. A shell that wanted those would be asking for the thing D6
49
+ declines to give it.
50
+
51
+ §47 ADDED THE IDENTITY, AND AN IDENTIFIER IS NOT CONTENT. A run already
52
+ writes its whole conversation to its own ConversationThread, and a human
53
+ can already open one by id (`--ref`, `/resume`). What nobody could do was
54
+ find out WHICH thread a row in the sidebar was about. So a span carries
55
+ `id` and `parent_id` now, and `bind()` says which thread it opened.
56
+ Everything a shell then displays it reads back out of the ARCHIVE --
57
+ `core/replay.py`, the same function and the same policy `/resume` uses --
58
+ so nothing here forwards a child's stream to its parent, which is what
59
+ D6 is about. The distinction is the whole design: the channel gained an
60
+ address, not a payload.
61
+
62
+ THE PARENT COMES FROM A ContextVar, NOT FROM A PARAMETER. Five call sites
63
+ open spans and none of them knows what is above it; threading a parent
64
+ through all of them would put the answer in the hands of whoever
65
+ remembers to pass it -- the D24/R13 failure shape. The var is set and
66
+ reset inside the same context manager whose `finally` already makes
67
+ `exit` unforgettable, so the two cannot drift. It is also the shape that
68
+ survives concurrency: a ContextVar is per-thread, so a run submitted to
69
+ an executor takes `contextvars.copy_context()` with it rather than
70
+ reading a variable that would be wrong the moment two children run.
71
+
72
+ It rides the same route response_channel already rides (loop -> dispatch
73
+ -> handler -> the child's own loop), for the same reason: an out-of-band
74
+ object is what crosses a boundary a generator cannot.
75
+
76
+ Lives in core/ rather than tui/ because D12 makes the CLI a permanent
77
+ fallback -- and because nothing here knows what a widget is.
78
+ """
79
+
80
+ import logging
81
+ from contextlib import contextmanager
82
+ from contextvars import ContextVar
83
+ from dataclasses import dataclass, field
84
+ from typing import Optional
85
+ from uuid import uuid4
86
+
87
+ logger = logging.getLogger(__name__)
88
+
89
+ #: The innermost span open on THIS thread, or None. Read by `span()` to
90
+ #: find a new span's parent and by `bind()` to find the run whose thread
91
+ #: has just been created. Module-level and private: nothing outside this
92
+ #: file sets it, so the context manager below is the only writer.
93
+ _CURRENT: ContextVar = ContextVar("venastine_agent_span", default=None)
94
+
95
+
96
+ @dataclass(frozen=True)
97
+ class AgentSpan:
98
+ """One agent-shaped run, while it is running.
99
+
100
+ `depth` is ToolContext.subagent_depth -- the value C3 bounds, so a
101
+ consumer indenting by it is drawing the same nesting the depth limit
102
+ is about. Frozen because a span is posted to another thread and read
103
+ later; a mutable one would be a second writer of the stack.
104
+
105
+ `id` is minted per span rather than derived from anything, because
106
+ the thing it has to distinguish is two runs that agree on every other
107
+ field: a goal turn spawning `explore` twice gives two spans with the
108
+ same name and the same depth, and a sink that could not tell them
109
+ apart had to pop by last match and hope. `parent_id` is the enclosing
110
+ span's, or None at the root.
111
+
112
+ NEITHER IS THE THREAD ID, and the gap between them is deliberate. A
113
+ span opens BEFORE the run it describes creates its thread -- the
114
+ handler brackets the call, the thread is made inside it -- so the
115
+ address arrives later, through `bind()`. A frozen span cannot be
116
+ edited to hold it, which is correct: the binding belongs to the sink,
117
+ which is the thing that has to redraw when it arrives.
118
+ """
119
+ name: str
120
+ depth: int
121
+ # Defaulted so `AgentSpan("explore", 1)` still constructs -- the
122
+ # positional pair is what every existing caller and test writes.
123
+ id: str = field(default_factory=lambda: uuid4().hex)
124
+ parent_id: Optional[str] = None
125
+ # §47. WHICH tool call started this run, when one did. The same
126
+ # kind of fact as the name and the depth -- what the run IS --
127
+ # rather than a second channel: a shell that knows both this and
128
+ # the bound thread can make the CALL LINE in the transcript open
129
+ # the run while it is still going, instead of only once its
130
+ # result comes back. None for the compactor and the reviewer,
131
+ # which no tool call starts.
132
+ call_id: Optional[str] = None
133
+
134
+
135
+ class AgentActivity:
136
+ """A sink for span lifecycle. Override enter/exit; use span().
137
+
138
+ The base class is the null sink, so `NULL` below is an instance of
139
+ this rather than a separate do-nothing type -- one class, and a
140
+ subclass that overrides only what it cares about.
141
+ """
142
+
143
+ def enter(self, span: AgentSpan) -> None:
144
+ """A run began. Called on whatever thread the run is on."""
145
+
146
+ def exit(self, span: AgentSpan) -> None:
147
+ """That run ended -- successfully or not."""
148
+
149
+ def bind(self, span_id: str, thread_id) -> None:
150
+ """That run's conversation thread exists, and this is its id.
151
+
152
+ Separate from `enter` because it genuinely happens later: the
153
+ span brackets the call, and the thread is created inside it. A
154
+ sink that wants to make a row openable holds this against the
155
+ span id it was given at `enter`.
156
+
157
+ Called at most once per span, and not at all for a run that
158
+ never gets that far -- a spawn refused before it starts. A run
159
+ whose provider fails at the FIRST CALL is bound all the same:
160
+ `run_agent_conversation` binds as soon as the thread exists, before
161
+ its user message and before any model call, which is what lets a
162
+ failed child still be opened from its spawn line. (This docstring
163
+ said the opposite until batch 91.)
164
+ """
165
+
166
+ @contextmanager
167
+ def span(self, name: str, depth: int, call_id=None):
168
+ """Bracket one agent-shaped run.
169
+
170
+ A CONTEXT MANAGER RATHER THAN A PAIR OF CALLS, and that is the
171
+ whole reason this module exists as more than a dataclass. `exit`
172
+ has to run when the child RAISES -- a subagent whose provider
173
+ errors, a compactor that times out -- or its row stays on screen
174
+ for the rest of the session, describing a run that is over. A
175
+ panel that lies is worse than no panel, and the way to make the
176
+ `finally` unforgettable is to make it structural.
177
+
178
+ FAILURES IN THE SINK ARE CONTAINED, both halves. A sink is
179
+ display machinery; a raise inside one must not take down the run
180
+ it is merely describing. Logged rather than swallowed silently,
181
+ so a broken sink is findable -- the same posture
182
+ tools/registry.dispatch() takes around a tool handler.
183
+
184
+ THE ContextVar IS RESET IN THE SAME `finally` AS `exit`, and that
185
+ pairing is the point rather than a convenience. A token that
186
+ outlived its span would make the NEXT sibling a child of a run
187
+ that has finished -- lineage that is wrong rather than missing,
188
+ which is the harder kind to notice. `reset(token)` rather than
189
+ `set(parent)`, because that is what restores the exact state this
190
+ frame found, including "there was nothing".
191
+ """
192
+ parent = _CURRENT.get()
193
+ span = AgentSpan(
194
+ name, depth, call_id=call_id,
195
+ parent_id=parent.id if parent is not None else None)
196
+ token = _CURRENT.set(span)
197
+ try:
198
+ self.enter(span)
199
+ except Exception: # noqa: BLE001 -- contained
200
+ logger.exception("agent activity sink raised on enter")
201
+ try:
202
+ yield span
203
+ finally:
204
+ _CURRENT.reset(token)
205
+ try:
206
+ self.exit(span)
207
+ except Exception: # noqa: BLE001 -- contained
208
+ logger.exception("agent activity sink raised on exit")
209
+
210
+
211
+ NULL = AgentActivity()
212
+ """The no-op sink. Every non-TUI shell runs on this."""
213
+
214
+
215
+ def span(activity, name: str, depth: int, call_id=None):
216
+ """Bracket a run against an OPTIONAL sink.
217
+
218
+ `activity` is None on every path but the TUI's, and this is what
219
+ keeps the call sites unconditional: one `with` statement, no branch,
220
+ nothing to get wrong at the five places that open a span. Callers say
221
+ `with agent_activity.span(activity, name, depth):` and never have to
222
+ ask whether anyone is watching.
223
+ """
224
+ return (activity or NULL).span(name, depth, call_id)
225
+
226
+
227
+ def current() -> Optional[AgentSpan]:
228
+ """The innermost span open on this thread, or None.
229
+
230
+ Public because two things outside this module need to know which run
231
+ is speaking without being handed it: `bind()` below, and the approval
232
+ path, which names the asking agent on a modal that would otherwise
233
+ say only which TOOL was asked for.
234
+ """
235
+ return _CURRENT.get()
236
+
237
+
238
+ def bind(activity, thread_id) -> None:
239
+ """Tell the sink which thread the innermost open run is writing.
240
+
241
+ A no-op when nothing is open, which is the ordinary state of a
242
+ top-level `run_agent_conversation` -- the CLI's chat, a test calling
243
+ it directly. That is why the call site needs no branch, matching
244
+ `span()` above.
245
+
246
+ CONTAINED like the sink's other two calls, and for the identical
247
+ reason: this is display machinery. A sink that raises while learning
248
+ an id must not fail the run whose id it was learning.
249
+ """
250
+ span = _CURRENT.get()
251
+ if span is None or thread_id is None:
252
+ return
253
+ try:
254
+ (activity or NULL).bind(span.id, thread_id)
255
+ except Exception: # noqa: BLE001 -- contained
256
+ logger.exception("agent activity sink raised on bind")