@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.
- package/.env.example +19 -19
- package/CONFIG_ARCHITECTURE.md +2139 -2002
- package/LICENSE +201 -201
- package/README.md +1043 -1034
- package/agents/builtin/compactor.md +75 -75
- package/agents/builtin/explore.md +77 -77
- package/agents/builtin/pipeline-reviewer.md +100 -100
- package/agents/builtin/plan.md +106 -106
- package/agents/builtin/review.md +74 -74
- package/agents/manager.py +261 -261
- package/agents/subagent_tool.py +472 -472
- package/agents/tui_commands.py +238 -146
- package/bin/venastine.mjs +584 -528
- package/bin/venastine.py +73 -71
- package/cli_commands.py +848 -835
- package/config.yaml +64 -0
- package/config_edit.py +1301 -1301
- package/config_schema.py +987 -966
- package/config_update.py +749 -749
- package/core/agent_activity.py +256 -256
- package/core/ansi.py +452 -452
- package/core/approval.py +137 -137
- package/core/call_view.py +364 -364
- package/core/cancel.py +121 -121
- package/core/chatgpt_auth.py +747 -747
- package/core/claims_view.py +107 -107
- package/core/client.py +2756 -2715
- package/core/commands.py +464 -454
- package/core/compaction.py +1735 -1735
- package/core/config_loader.py +1982 -1982
- package/core/connect.py +686 -686
- package/core/events.py +123 -123
- package/core/file_mentions.py +280 -280
- package/core/interaction.py +411 -411
- package/core/loop.py +2566 -2566
- package/core/memory.py +482 -482
- package/core/pipeline_models.py +190 -190
- package/core/provider_errors.py +274 -234
- package/core/reasoning/authorization.py +130 -130
- package/core/reasoning/base.py +219 -219
- package/core/reasoning/confidence_scoring.py +484 -484
- package/core/reasoning/events.py +149 -149
- package/core/reasoning/orchestrator.py +1561 -1561
- package/core/reasoning/output_writer.py +345 -345
- package/core/reasoning/payload_validation.py +524 -524
- package/core/reasoning/pipeline_storage.py +427 -427
- package/core/reasoning/scholar.py +467 -458
- package/core/reasoning/source_corpus.py +433 -433
- package/core/reasoning/source_scoring.py +855 -855
- package/core/replay.py +315 -315
- package/core/shell_sessions.py +1553 -1553
- package/credentials.py +307 -307
- package/database.py +333 -333
- package/docs/PRIVACY.md +78 -78
- package/docs/SECURITY.md +114 -108
- package/docs/THIRD_PARTY_NOTICES.md +148 -148
- package/env_secrets.py +118 -118
- package/json_store.py +343 -343
- package/logging_setup.py +295 -295
- package/main.py +3433 -3433
- package/mcp_client/client.py +780 -733
- package/mcp_client/config.py +484 -484
- package/mcp_client/registration.py +343 -343
- package/memories/manager.py +147 -147
- package/memories/tui_commands.py +319 -239
- package/package.json +303 -303
- package/project_init/config_files.py +282 -282
- package/project_init/generator.py +728 -728
- package/project_init/manifest.py +418 -418
- package/project_init/tui_commands.py +147 -147
- package/prompts/critic_pass.md +24 -24
- package/prompts/revalidate.md +25 -25
- package/prompts/revise.md +17 -17
- package/prompts/source_grounding.md +66 -66
- package/prompts/system_prompts.py +316 -316
- package/providers.json.example +94 -94
- package/pyproject.toml +149 -149
- package/requirements.txt +314 -295
- package/safety/policy_enforcement.py +1082 -1082
- package/security/askpass.py +419 -419
- package/security/capability.py +207 -207
- package/security/confine.py +484 -484
- package/security/hosted.py +182 -182
- package/security/permissions.py +237 -237
- package/security/protected_paths.py +501 -501
- package/security/sandbox.py +4108 -4108
- package/skills/builtin/math/formal-specification.md +67 -67
- package/skills/builtin/math/numerical-methods.md +66 -66
- package/skills/builtin/research/experiment-design.md +62 -62
- package/skills/builtin/research/reproducibility.md +55 -55
- package/skills/builtin/research/source-evaluation.md +70 -70
- package/skills/builtin/research/statistical-inference.md +63 -63
- package/skills/builtin/research/technical-writing.md +59 -59
- package/skills/builtin/software/code-review.md +61 -61
- package/skills/builtin/software/debugging.md +61 -61
- package/skills/builtin/software/test-design.md +67 -67
- package/skills/tui_commands.py +110 -110
- package/storage.py +1338 -1338
- package/tools/base.py +465 -465
- package/tools/builtin/_math_common.py +667 -667
- package/tools/builtin/_net_common.py +1145 -267
- package/tools/builtin/_page_text.py +490 -0
- package/tools/builtin/_pdf_text.py +113 -0
- package/tools/builtin/arxiv.py +685 -681
- package/tools/builtin/fetch_url.py +639 -371
- package/tools/builtin/file_ops.py +720 -720
- package/tools/builtin/geometry.py +184 -184
- package/tools/builtin/load_skill.py +76 -76
- package/tools/builtin/pin.py +227 -227
- package/tools/builtin/probability_stats.py +224 -224
- package/tools/builtin/project_docs.py +464 -464
- package/tools/builtin/remember.py +175 -175
- package/tools/builtin/shell.py +980 -980
- package/tools/builtin/todo.py +149 -149
- package/tools/builtin/web_search.py +402 -328
- package/tools/context.py +159 -159
- package/tools/isolation.py +387 -387
- package/tools/registry.py +1252 -1242
- package/tui/app.py +8372 -8307
- package/tui/app.tcss +754 -739
- package/tui/commands.py +26 -26
- package/tui/diffs.py +286 -286
- package/tui/history.py +128 -128
- package/tui/hosted_driver.py +102 -102
- package/tui/markdown.py +1329 -1329
- package/tui/meters.py +364 -364
- package/tui/ravens.py +146 -146
- package/tui/screens.py +1255 -1197
- package/tui/themes.py +599 -599
- package/tui/widgets.py +3861 -3796
package/core/agent_activity.py
CHANGED
|
@@ -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")
|