@yahyahammad/venastine 0.2.0 → 0.3.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.env.example +9 -4
- package/CONFIG_ARCHITECTURE.md +2030 -0
- package/LICENSE +201 -201
- package/NOTICE +1 -1
- package/README.md +1034 -895
- package/agents/builtin/build.md +73 -0
- package/agents/builtin/compactor.md +75 -75
- package/agents/builtin/explore.md +77 -77
- package/agents/builtin/general.md +80 -0
- package/agents/builtin/pipeline-reviewer.md +100 -100
- package/agents/builtin/plan.md +106 -88
- package/agents/builtin/review.md +74 -74
- package/agents/builtin/test.md +65 -0
- package/agents/builtin/writer.md +67 -0
- package/agents/manager.py +68 -2
- package/agents/subagent_tool.py +472 -238
- package/agents/tui_commands.py +238 -151
- package/bin/venastine.mjs +150 -4
- package/bin/venastine.py +71 -0
- package/cli_commands.py +838 -0
- package/config.py +95 -1198
- package/config.yaml +1103 -0
- package/config_edit.py +1301 -0
- package/config_schema.py +971 -0
- package/config_update.py +749 -0
- package/core/agent_activity.py +256 -118
- package/core/ansi.py +452 -0
- package/core/approval.py +137 -115
- package/core/call_view.py +364 -0
- package/core/cancel.py +121 -0
- package/core/chatgpt_auth.py +747 -0
- package/core/claims_view.py +107 -0
- package/core/client.py +2715 -1559
- package/core/commands.py +460 -0
- package/core/compaction.py +1735 -971
- package/core/config_loader.py +1982 -1563
- package/core/connect.py +686 -0
- package/core/events.py +123 -61
- package/core/file_mentions.py +280 -0
- package/core/interaction.py +411 -328
- package/core/line_pattern.py +128 -0
- package/core/loop.py +2566 -1490
- package/core/memory.py +482 -370
- package/core/pipeline_models.py +190 -176
- package/core/provider_errors.py +234 -0
- package/core/reasoning/authorization.py +130 -130
- package/core/reasoning/base.py +219 -219
- package/core/reasoning/confidence_scoring.py +484 -468
- package/core/reasoning/events.py +149 -149
- package/core/reasoning/json_retry.py +19 -1
- package/core/reasoning/orchestrator.py +1561 -1382
- package/core/reasoning/output_writer.py +345 -286
- package/core/reasoning/payload_validation.py +524 -398
- package/core/reasoning/pipeline_storage.py +88 -22
- package/core/reasoning/review.py +659 -615
- package/core/reasoning/scholar.py +458 -434
- package/core/reasoning/source_corpus.py +433 -327
- package/core/reasoning/source_scoring.py +855 -855
- package/core/replay.py +315 -183
- package/core/session.py +36 -12
- package/core/session_view.py +259 -0
- package/core/session_wake.py +259 -0
- package/core/shell_sessions.py +1553 -0
- package/core/workspace_trust.py +1 -1
- package/credentials.py +148 -20
- package/database.py +333 -252
- package/{PRIVACY.md → docs/PRIVACY.md} +78 -66
- package/docs/SECURITY.md +108 -0
- package/docs/THIRD_PARTY_NOTICES.md +148 -0
- package/env_secrets.py +50 -9
- package/json_store.py +343 -123
- package/logging_setup.py +295 -185
- package/main.py +3433 -1961
- package/mcp_client/client.py +733 -499
- package/mcp_client/config.py +126 -21
- package/mcp_client/registration.py +343 -182
- package/memories/manager.py +147 -132
- package/memories/tui_commands.py +319 -244
- package/package.json +303 -73
- package/project_init/config_files.py +282 -278
- package/project_init/generator.py +728 -564
- package/project_init/manifest.py +18 -6
- package/project_init/tui_commands.py +147 -144
- package/prompts/critic_pass.md +24 -24
- package/prompts/revalidate.md +25 -25
- package/prompts/revise.md +2 -0
- package/prompts/source_grounding.md +66 -66
- package/prompts/system_prompts.py +316 -262
- package/providers.json.example +4 -2
- package/pyproject.toml +149 -100
- package/requirements.txt +295 -72
- package/safety/policy_enforcement.py +1082 -746
- package/security/askpass.py +419 -0
- package/security/capability.py +207 -177
- package/security/confine.py +484 -0
- package/security/hosted.py +182 -0
- package/security/permissions.py +237 -190
- package/security/posture.py +124 -12
- package/security/protected_paths.py +501 -309
- package/security/sandbox.py +4108 -985
- package/security/secrets.py +855 -0
- 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 -111
- package/storage.py +1338 -1005
- package/tools/base.py +161 -1
- package/tools/builtin/_math_common.py +667 -377
- package/tools/builtin/_net_common.py +225 -19
- package/tools/builtin/arxiv.py +497 -39
- package/tools/builtin/ask_user.py +231 -213
- package/tools/builtin/discrete_math.py +35 -4
- package/tools/builtin/fetch_url.py +371 -153
- package/tools/builtin/file_ops.py +720 -412
- package/tools/builtin/geometry.py +48 -12
- package/tools/builtin/get_time.py +2 -2
- package/tools/builtin/linear_algebra.py +66 -23
- package/tools/builtin/load_skill.py +76 -66
- package/tools/builtin/logic.py +171 -12
- package/tools/builtin/pin.py +227 -193
- package/tools/builtin/probability_stats.py +12 -16
- package/tools/builtin/project_docs.py +464 -405
- package/tools/builtin/remember.py +175 -158
- package/tools/builtin/shell.py +980 -461
- package/tools/builtin/shell_sessions.py +613 -0
- package/tools/builtin/symbolic_math.py +80 -10
- package/tools/builtin/todo.py +149 -147
- package/tools/builtin/web_search.py +191 -13
- package/tools/context.py +159 -136
- package/tools/isolation.py +107 -34
- package/tools/registry.py +1242 -925
- package/tui/app.py +8318 -4100
- package/tui/app.tcss +747 -556
- package/tui/commands.py +26 -170
- package/tui/diffs.py +34 -13
- package/tui/history.py +128 -128
- package/tui/hosted_driver.py +102 -0
- package/tui/markdown.py +1329 -1279
- package/tui/meters.py +364 -268
- package/tui/ravens.py +146 -146
- package/tui/screens.py +1255 -943
- package/tui/themes.py +599 -559
- package/tui/widgets.py +3813 -2332
- package/SECURITY.md +0 -88
- package/THIRD_PARTY_NOTICES.md +0 -100
package/core/interaction.py
CHANGED
|
@@ -1,328 +1,411 @@
|
|
|
1
|
-
"""
|
|
2
|
-
core/interaction.py
|
|
3
|
-
|
|
4
|
-
ROADMAP_v2 §23 (AC1): the ONE way anything in this harness asks a human a
|
|
5
|
-
question and blocks for the answer.
|
|
6
|
-
|
|
7
|
-
Before this there were five, and each re-derived the same four rules --
|
|
8
|
-
what a dismissal carries, what a timeout means, how shutdown releases a
|
|
9
|
-
parked worker, and how a malformed answer decodes:
|
|
10
|
-
|
|
11
|
-
* `permission_channel`, a queue.Queue of booleans (§13)
|
|
12
|
-
* `ApprovalProvider.ask(tool_name, params, notice) -> bool` (§25), which
|
|
13
|
-
exists only because run_to_completion() DISCARDS the LoopEvent carrying
|
|
14
|
-
the question, so the CLI and the pipeline would block on a queue with
|
|
15
|
-
nothing displayed
|
|
16
|
-
* `ReviewConsent.decide(finding, round) -> (decision, notes)` (§20)
|
|
17
|
-
* two more in §24's /init, added by the section immediately before this one
|
|
18
|
-
|
|
19
|
-
§23's spec put the generalisation first for a reason it has now been proved
|
|
20
|
-
right about twice: "doing the tools first and the generalisation afterwards
|
|
21
|
-
produces two bespoke channels and a third when §18 wants one."
|
|
22
|
-
|
|
23
|
-
WHAT IS ACTUALLY SHARED IS `decode`, NOT THE DATACLASS. A request/response
|
|
24
|
-
dataclass pair is nearly free to write badly -- five call sites can each
|
|
25
|
-
build one and still each invent their own failure handling. The consolidation
|
|
26
|
-
that pays is that every route into an answer (a queue, a callable, a timeout,
|
|
27
|
-
a shutdown release, a callback that raised) funnels through ONE function that
|
|
28
|
-
owns the safe default per kind. "The inability to ask is not permission to
|
|
29
|
-
proceed" (§25's V6) stops being a habit five places remember and becomes a
|
|
30
|
-
property of this module.
|
|
31
|
-
|
|
32
|
-
THE DEFAULT IS ALWAYS THE DECLINING ANSWER, never the permissive one. That
|
|
33
|
-
asymmetry is the whole design: an approval that cannot be obtained is a
|
|
34
|
-
denial, a sign-off nobody answered grants nothing, a review correction nobody
|
|
35
|
-
approved is not applied.
|
|
36
|
-
|
|
37
|
-
Deliberately a leaf module with no project imports, matching core/approval.py
|
|
38
|
-
-- core/loop.py, main.py, tui/app.py and core/reasoning/ all depend on it and
|
|
39
|
-
it depends on none of them.
|
|
40
|
-
"""
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
import
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
#
|
|
51
|
-
#
|
|
52
|
-
#
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
#
|
|
58
|
-
#
|
|
59
|
-
#
|
|
60
|
-
#
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
#
|
|
64
|
-
#
|
|
65
|
-
#
|
|
66
|
-
#
|
|
67
|
-
#
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
#
|
|
71
|
-
#
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
#
|
|
79
|
-
#
|
|
80
|
-
#
|
|
81
|
-
#
|
|
82
|
-
#
|
|
83
|
-
#
|
|
84
|
-
#
|
|
85
|
-
#
|
|
86
|
-
#
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
#
|
|
157
|
-
#
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
kind
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
#
|
|
251
|
-
#
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
#
|
|
261
|
-
#
|
|
262
|
-
#
|
|
263
|
-
#
|
|
264
|
-
#
|
|
265
|
-
#
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
if not isinstance(
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
#
|
|
320
|
-
#
|
|
321
|
-
#
|
|
322
|
-
#
|
|
323
|
-
#
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
1
|
+
"""
|
|
2
|
+
core/interaction.py
|
|
3
|
+
|
|
4
|
+
ROADMAP_v2 §23 (AC1): the ONE way anything in this harness asks a human a
|
|
5
|
+
question and blocks for the answer.
|
|
6
|
+
|
|
7
|
+
Before this there were five, and each re-derived the same four rules --
|
|
8
|
+
what a dismissal carries, what a timeout means, how shutdown releases a
|
|
9
|
+
parked worker, and how a malformed answer decodes:
|
|
10
|
+
|
|
11
|
+
* `permission_channel`, a queue.Queue of booleans (§13)
|
|
12
|
+
* `ApprovalProvider.ask(tool_name, params, notice) -> bool` (§25), which
|
|
13
|
+
exists only because run_to_completion() DISCARDS the LoopEvent carrying
|
|
14
|
+
the question, so the CLI and the pipeline would block on a queue with
|
|
15
|
+
nothing displayed
|
|
16
|
+
* `ReviewConsent.decide(finding, round) -> (decision, notes)` (§20)
|
|
17
|
+
* two more in §24's /init, added by the section immediately before this one
|
|
18
|
+
|
|
19
|
+
§23's spec put the generalisation first for a reason it has now been proved
|
|
20
|
+
right about twice: "doing the tools first and the generalisation afterwards
|
|
21
|
+
produces two bespoke channels and a third when §18 wants one."
|
|
22
|
+
|
|
23
|
+
WHAT IS ACTUALLY SHARED IS `decode`, NOT THE DATACLASS. A request/response
|
|
24
|
+
dataclass pair is nearly free to write badly -- five call sites can each
|
|
25
|
+
build one and still each invent their own failure handling. The consolidation
|
|
26
|
+
that pays is that every route into an answer (a queue, a callable, a timeout,
|
|
27
|
+
a shutdown release, a callback that raised) funnels through ONE function that
|
|
28
|
+
owns the safe default per kind. "The inability to ask is not permission to
|
|
29
|
+
proceed" (§25's V6) stops being a habit five places remember and becomes a
|
|
30
|
+
property of this module.
|
|
31
|
+
|
|
32
|
+
THE DEFAULT IS ALWAYS THE DECLINING ANSWER, never the permissive one. That
|
|
33
|
+
asymmetry is the whole design: an approval that cannot be obtained is a
|
|
34
|
+
denial, a sign-off nobody answered grants nothing, a review correction nobody
|
|
35
|
+
approved is not applied.
|
|
36
|
+
|
|
37
|
+
Deliberately a leaf module with no project imports, matching core/approval.py
|
|
38
|
+
-- core/loop.py, main.py, tui/app.py and core/reasoning/ all depend on it and
|
|
39
|
+
it depends on none of them.
|
|
40
|
+
"""
|
|
41
|
+
|
|
42
|
+
import logging
|
|
43
|
+
import threading
|
|
44
|
+
from collections.abc import Callable
|
|
45
|
+
from dataclasses import dataclass, field
|
|
46
|
+
from typing import Any, Optional
|
|
47
|
+
|
|
48
|
+
logger = logging.getLogger(__name__)
|
|
49
|
+
|
|
50
|
+
# ROADMAP_v2 §47 slice 8 (NA12). ONE QUESTION ON SCREEN AT A TIME, and it
|
|
51
|
+
# lives here because this module is already the one entry point every
|
|
52
|
+
# question goes through.
|
|
53
|
+
#
|
|
54
|
+
# Until slice 8 nothing could ask twice at once, so no shell needed to cope
|
|
55
|
+
# with it and none does. Both of ours break in the same way and for the
|
|
56
|
+
# same reason -- a single slot for the pending answer. `tui/app.py` keeps
|
|
57
|
+
# one `_permission_channel` so shutdown can release a parked worker: a
|
|
58
|
+
# second ask overwrites the field and orphans the first, and the first ask
|
|
59
|
+
# to FINISH nulls it in its `finally`, so a still-open question becomes
|
|
60
|
+
# unreleasable. `main.py` has one `_StdinReader`, and two readers of one
|
|
61
|
+
# stdin is the defect §29's N1 exists to prevent, arrived at from the other
|
|
62
|
+
# direction. Two consent surfaces at once is also what §42 refuses on its
|
|
63
|
+
# own terms.
|
|
64
|
+
#
|
|
65
|
+
# HERE RATHER THAN IN EACH SHELL, which is this project's canonical rule --
|
|
66
|
+
# fix at the producer. A lock around `tui/app.py`'s `_blocking_modal` would
|
|
67
|
+
# leave the CLI unprotected and would have to be written again for the
|
|
68
|
+
# third shell.
|
|
69
|
+
#
|
|
70
|
+
# NO TIMEOUT, deliberately. Every waiter is bounded by the holder's own
|
|
71
|
+
# deadline ONCE THE HOLDER IS PARKED: the TUI parks for at most
|
|
72
|
+
# ATTENDED_APPROVAL_TIMEOUT_S and a run-backed CLI prompt carries the same,
|
|
73
|
+
# so the queue drains on its own. The step before the TUI's park has no
|
|
74
|
+
# deadline of its own, and until #223 this paragraph read as if it had:
|
|
75
|
+
# `_blocking_modal` first marshals its screen onto the UI thread, which is
|
|
76
|
+
# bounded only by that thread staying responsive -- the bound every other
|
|
77
|
+
# marshal in the shell lives with. Measured under textual 8.2.8 (#220), a
|
|
78
|
+
# marshal after the app exits returns or raises at once rather than
|
|
79
|
+
# parking, so what is left unbounded is a UI thread that is alive and
|
|
80
|
+
# wedged, where nothing else in the shell answers either.
|
|
81
|
+
# A deadline here would need this leaf module to know a number that
|
|
82
|
+
# belongs to config.py, and the failure it would prevent is one no shell
|
|
83
|
+
# can currently produce. Shutdown does not wait either: the TUI's release
|
|
84
|
+
# unblocks the holder, and every queued worker then finds `_shutting_down`
|
|
85
|
+
# already true and returns its declining default without pushing a screen.
|
|
86
|
+
#
|
|
87
|
+
# NOT FIFO, and nothing here claims it is -- a Lock makes no ordering
|
|
88
|
+
# promise, so which of two simultaneous questions is put first is
|
|
89
|
+
# undefined. What IS guaranteed is that each answer reaches the asker that
|
|
90
|
+
# holds it, because the request travels with the caller and never through
|
|
91
|
+
# this module's state.
|
|
92
|
+
_ask_lock = threading.Lock()
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
# ---------------------------------------------------------------------------
|
|
96
|
+
# ---- Kinds ----------------------------------------------------------------
|
|
97
|
+
# ---------------------------------------------------------------------------
|
|
98
|
+
|
|
99
|
+
APPROVAL = "approval"
|
|
100
|
+
SUBAGENT_SIGNOFF = "subagent_signoff"
|
|
101
|
+
REVIEW = "review"
|
|
102
|
+
# §24's two, migrated in §23 slice 1. CONFIRM and APPROVAL both answer with
|
|
103
|
+
# a bool and are still separate kinds, because the KIND is what tells a
|
|
104
|
+
# shell how to render: APPROVAL is a gated tool call with params, CONFIRM
|
|
105
|
+
# is a titled yes/no over a block of text the caller composed.
|
|
106
|
+
CONFIRM = "confirm"
|
|
107
|
+
CHOICE = "choice"
|
|
108
|
+
# §23 slice 2. Separate from CHOICE, which answers with exactly one of the
|
|
109
|
+
# options offered and nothing else. A QUESTION can come back as several
|
|
110
|
+
# options, as free text, as both, or as "I would rather talk about this" --
|
|
111
|
+
# four affordances the spec asks for by name, and a shape CHOICE's decoder
|
|
112
|
+
# cannot express without becoming two decoders wearing one name.
|
|
113
|
+
QUESTION = "question"
|
|
114
|
+
# ROADMAP_v3 §49 slice 5a (SS59). One value, typed by a human, that the
|
|
115
|
+
# caller needs and this module must never see printed.
|
|
116
|
+
#
|
|
117
|
+
# Its own kind rather than a QUESTION with a flag, because the KIND is what
|
|
118
|
+
# tells a shell how to RENDER -- and the rendering is the whole point here:
|
|
119
|
+
# the field is masked, the answer is not echoed, and it does not reach the
|
|
120
|
+
# transcript, the log or the scrollback. A flag on an existing kind would
|
|
121
|
+
# make a shell that ignored the flag look wired up while showing the
|
|
122
|
+
# passphrase in clear.
|
|
123
|
+
SECRET = "secret"
|
|
124
|
+
|
|
125
|
+
# Review decisions, moved here from core/reasoning/review.py so the decoder
|
|
126
|
+
# and the pipeline cannot disagree about what a valid answer is.
|
|
127
|
+
ACCEPT = "accept"
|
|
128
|
+
REJECT = "reject"
|
|
129
|
+
REFINE = "refine"
|
|
130
|
+
REJECT_ALL = "reject_all"
|
|
131
|
+
REVIEW_DECISIONS = (ACCEPT, REJECT, REFINE, REJECT_ALL)
|
|
132
|
+
|
|
133
|
+
# What each kind means when nobody answered, answered incoherently, or could
|
|
134
|
+
# not be asked at all. Every entry declines.
|
|
135
|
+
#
|
|
136
|
+
# INVARIANT, pinned by a test: `decode(Request(kind), None) ==
|
|
137
|
+
# SAFE_DEFAULTS[kind]` for
|
|
138
|
+
# every kind. That is what lets `ask()` route the no-channel and the
|
|
139
|
+
# callback-raised paths through `decode` rather than reading this table -- so
|
|
140
|
+
# there is genuinely one function deciding what a non-answer means, and a new
|
|
141
|
+
# kind cannot be added with a default the decoder disagrees about.
|
|
142
|
+
SAFE_DEFAULTS = {
|
|
143
|
+
APPROVAL: False,
|
|
144
|
+
# None, not set(): the two are DIFFERENT answers. None denies the spawn
|
|
145
|
+
# outright; an empty set spawns the subagent with nothing pre-granted,
|
|
146
|
+
# which is a legitimate choice a user can make. Defaulting to set() would
|
|
147
|
+
# turn "nobody answered" into "go ahead, just ask me later" -- and in a
|
|
148
|
+
# headless run there is nobody to ask later either.
|
|
149
|
+
SUBAGENT_SIGNOFF: None,
|
|
150
|
+
REVIEW: (REJECT, ""),
|
|
151
|
+
CONFIRM: False,
|
|
152
|
+
# None, not the first option: "nobody answered" is not a choice, and
|
|
153
|
+
# picking one on the user's behalf is exactly what a declining default
|
|
154
|
+
# exists to avoid.
|
|
155
|
+
CHOICE: None,
|
|
156
|
+
# None, for CHOICE's reason. Note what this makes indistinguishable, on
|
|
157
|
+
# purpose: an unanswered question and a dismissed one both arrive here,
|
|
158
|
+
# and the TOOL turns that into an error result the model can work
|
|
159
|
+
# around. "I would rather discuss this" is NOT this -- it is a real
|
|
160
|
+
# answer carrying defer=True, because a user who says that has told the
|
|
161
|
+
# model something, and a user who closed the modal has not.
|
|
162
|
+
QUESTION: None,
|
|
163
|
+
# None, for CHOICE's reason and one more that is specific to this kind:
|
|
164
|
+
# the empty string is a value a user could legitimately mean to type,
|
|
165
|
+
# and it is also what a torn-down modal and a shell with no branch for
|
|
166
|
+
# SECRET both produce. Defaulting to "" would hand `sudo` an empty
|
|
167
|
+
# password -- an authentication ATTEMPT made on nobody's behalf, which
|
|
168
|
+
# on a remote account is a step towards a lockout. None is not a
|
|
169
|
+
# password, so every consumer has to notice.
|
|
170
|
+
SECRET: None,
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
|
|
174
|
+
@dataclass
|
|
175
|
+
class Request:
|
|
176
|
+
"""One question, addressed to whoever can answer it.
|
|
177
|
+
|
|
178
|
+
`payload` is kind-specific and is not validated here: this module owns
|
|
179
|
+
the ANSWER contract, not the question's. A shell renders the payload it
|
|
180
|
+
understands; an unrecognised kind is a programming error, and `decode`
|
|
181
|
+
raises on one rather than inventing a default for a question nobody
|
|
182
|
+
designed.
|
|
183
|
+
"""
|
|
184
|
+
|
|
185
|
+
kind: str
|
|
186
|
+
payload: dict = field(default_factory=dict)
|
|
187
|
+
# Extra text explaining what answering actually authorises. Supplied by
|
|
188
|
+
# ToolSpec.approval_notice for tool calls -- the tool's knowledge, not
|
|
189
|
+
# the shell's (spawn_subagent uses it to name the tools a child could
|
|
190
|
+
# then run unprompted).
|
|
191
|
+
notice: Optional[str] = None
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
@dataclass
|
|
195
|
+
class ResponseChannel:
|
|
196
|
+
"""A caller-supplied way to put one Request to a human and block.
|
|
197
|
+
|
|
198
|
+
ask(request) -> raw answer. Implementations live in the shells, because
|
|
199
|
+
only they know how to reach the person: main.py reads stdin, tui/app.py
|
|
200
|
+
posts to the UI thread and waits on a queue.
|
|
201
|
+
|
|
202
|
+
The raw answer is never trusted. Callers go through this module's
|
|
203
|
+
`ask()`, which decodes it and substitutes the declining default for
|
|
204
|
+
anything unrecognised.
|
|
205
|
+
|
|
206
|
+
honour_run_scope mirrors ToolSpec.grant_scope, carried over unchanged
|
|
207
|
+
from §25's ApprovalProvider. A channel that sets it False makes every
|
|
208
|
+
call ask, even for a tool whose approval would normally cover the rest
|
|
209
|
+
of the run. Attended mode sets it False: a mode whose entire purpose is
|
|
210
|
+
per-call supervision must not let one yes silently cover later calls,
|
|
211
|
+
however sensible that shortcut is inside a chat turn.
|
|
212
|
+
"""
|
|
213
|
+
|
|
214
|
+
ask: Callable[[Request], Any]
|
|
215
|
+
honour_run_scope: bool = True
|
|
216
|
+
|
|
217
|
+
|
|
218
|
+
# ---------------------------------------------------------------------------
|
|
219
|
+
# ---- Decoding --------------------------------------------------------------
|
|
220
|
+
# ---------------------------------------------------------------------------
|
|
221
|
+
|
|
222
|
+
def decode(request: "Request", raw: Any) -> Any:
|
|
223
|
+
"""Normalise whatever a shell returned into this kind's answer type.
|
|
224
|
+
|
|
225
|
+
Anything unrecognised becomes SAFE_DEFAULTS[kind]. That covers a
|
|
226
|
+
dismissal carrying None, a modal torn down by shutdown (which puts a
|
|
227
|
+
bare False), a timeout, and a shell that returned something of the
|
|
228
|
+
wrong shape entirely.
|
|
229
|
+
|
|
230
|
+
TAKES THE REQUEST, NOT JUST THE KIND, because two kinds cannot be
|
|
231
|
+
validated without knowing what was ASKED. A choice is only valid
|
|
232
|
+
against the options it was offered, and a sign-off subset is only
|
|
233
|
+
valid against the candidates that were listed -- a shell returning a
|
|
234
|
+
tool nobody offered must not thereby grant it. Passing the kind alone
|
|
235
|
+
made those two unverifiable, which is the sort of gap that shows up
|
|
236
|
+
later as "the answer was honoured but nothing had proposed it".
|
|
237
|
+
|
|
238
|
+
Raises on an unknown KIND, deliberately, rather than returning a
|
|
239
|
+
default. An unanswerable question is a runtime condition to fail safe
|
|
240
|
+
on; a question nobody defined is a bug, and inventing "no" for it would
|
|
241
|
+
hide the typo in whichever call site built the Request.
|
|
242
|
+
"""
|
|
243
|
+
kind = request.kind
|
|
244
|
+
if kind not in SAFE_DEFAULTS:
|
|
245
|
+
raise ValueError(
|
|
246
|
+
f"Unknown request kind {kind!r}; expected one of "
|
|
247
|
+
f"{', '.join(sorted(SAFE_DEFAULTS))}.")
|
|
248
|
+
|
|
249
|
+
if kind in (APPROVAL, CONFIRM):
|
|
250
|
+
# bool(), not `is True`: a shell answering with a truthy value it
|
|
251
|
+
# considers a yes should not be silently denied. The permissive
|
|
252
|
+
# direction is safe here ONLY because the alternative is also a
|
|
253
|
+
# decision the user made -- unlike the shapes below, there is no
|
|
254
|
+
# third state to confuse it with.
|
|
255
|
+
return bool(raw)
|
|
256
|
+
|
|
257
|
+
if kind == SECRET:
|
|
258
|
+
# A string, or nothing. NOT `str(raw)`: a shell that returned a
|
|
259
|
+
# widget, a dict or a bool would be coerced into a "password" that
|
|
260
|
+
# is really a repr, and it would then be TRIED against a real
|
|
261
|
+
# account. And not `raw or None` either -- an empty string is the
|
|
262
|
+
# shape a dismissed modal produces, and it must decode as "nobody
|
|
263
|
+
# answered" rather than as a password of length zero.
|
|
264
|
+
#
|
|
265
|
+
# The value is returned raw and is NOT logged, here or anywhere on
|
|
266
|
+
# this path. This is the one decode branch whose input must not
|
|
267
|
+
# appear in a warning about its own shape.
|
|
268
|
+
if not isinstance(raw, str) or raw == "":
|
|
269
|
+
return None
|
|
270
|
+
return raw
|
|
271
|
+
|
|
272
|
+
if kind == CHOICE:
|
|
273
|
+
# Valid ONLY against what was offered. A shell returning something
|
|
274
|
+
# nobody proposed is answering a different question, and the
|
|
275
|
+
# options live on the request precisely so this can be checked --
|
|
276
|
+
# `decode(kind, raw)` could not, which is why it takes the request.
|
|
277
|
+
options = request.payload.get("options") or ()
|
|
278
|
+
return raw if raw in options else None
|
|
279
|
+
|
|
280
|
+
if kind == SUBAGENT_SIGNOFF:
|
|
281
|
+
# Three answers, and the middle one is the easy one to lose: None
|
|
282
|
+
# denies the spawn, an EMPTY collection spawns with nothing
|
|
283
|
+
# granted, a non-empty one grants those names. The emptiness test
|
|
284
|
+
# is therefore `isinstance`, never truthiness -- `if raw:` would
|
|
285
|
+
# fold the middle answer into the first.
|
|
286
|
+
#
|
|
287
|
+
# Everything else denies by falling through, booleans included: a
|
|
288
|
+
# shell that answered this like an approval must not hand the
|
|
289
|
+
# child its whole gated set. That needs no explicit `raw is True`
|
|
290
|
+
# branch, since bool subclasses int rather than any collection --
|
|
291
|
+
# one was written here and removed, because a guard that cannot
|
|
292
|
+
# fire still reads as the thing protecting you.
|
|
293
|
+
if not isinstance(raw, (set, frozenset, list, tuple)):
|
|
294
|
+
return None
|
|
295
|
+
chosen = {str(name) for name in raw}
|
|
296
|
+
# INTERSECTED with what was offered. A shell returning a name that
|
|
297
|
+
# was never a candidate must not grant it -- the sign-off's whole
|
|
298
|
+
# substance is that the list shown and the list granted are the
|
|
299
|
+
# same, which agents/manager.py's candidate_approvals() says in its
|
|
300
|
+
# own docstring. An empty `candidates` means nothing was offered,
|
|
301
|
+
# so nothing can be granted.
|
|
302
|
+
offered = {str(name) for name in
|
|
303
|
+
(request.payload.get("candidates") or ())}
|
|
304
|
+
unoffered = chosen - offered
|
|
305
|
+
if unoffered:
|
|
306
|
+
logger.warning(
|
|
307
|
+
"Sign-off answer named %s, which %s not offered; ignoring "
|
|
308
|
+
"them.", sorted(unoffered),
|
|
309
|
+
"was" if len(unoffered) == 1 else "were")
|
|
310
|
+
return chosen & offered
|
|
311
|
+
|
|
312
|
+
if kind == QUESTION:
|
|
313
|
+
# A dict, or nothing. Three answers again, and again the middle one
|
|
314
|
+
# is the one to lose:
|
|
315
|
+
#
|
|
316
|
+
# None nobody answered -- dismissed, timed
|
|
317
|
+
# out, no channel, or a shape this
|
|
318
|
+
# cannot read. The TOOL turns it into an
|
|
319
|
+
# error result.
|
|
320
|
+
# {..., "defer": True} "let's talk about it instead". A REAL
|
|
321
|
+
# answer: the user engaged and declined
|
|
322
|
+
# to pick, which is different from not
|
|
323
|
+
# being there. This is the spec's "chat
|
|
324
|
+
# about this" escape.
|
|
325
|
+
# {"options": [...], ...} a choice, or free text, or both.
|
|
326
|
+
#
|
|
327
|
+
# Deliberately NOT truthiness on the dict: an answer of
|
|
328
|
+
# {"options": [], "text": ""} is someone submitting a blank form,
|
|
329
|
+
# which is still not "nobody answered", and the tool can say so.
|
|
330
|
+
if not isinstance(raw, dict):
|
|
331
|
+
return None
|
|
332
|
+
if raw.get("defer"):
|
|
333
|
+
# Nothing else is read. A deferral is not a partial answer, and
|
|
334
|
+
# carrying half-filled options alongside it would invite a
|
|
335
|
+
# caller to act on both.
|
|
336
|
+
return {"options": [], "text": "", "defer": True}
|
|
337
|
+
|
|
338
|
+
# INTERSECTED with what was offered, in OFFERED order -- the same
|
|
339
|
+
# rule as SUBAGENT_SIGNOFF above, and for J3's reason: a shell
|
|
340
|
+
# returning something nobody proposed is answering a different
|
|
341
|
+
# question. Offered order rather than answer order so the model
|
|
342
|
+
# reads options back in the sequence it wrote them, which is the
|
|
343
|
+
# sequence its own prompt explained.
|
|
344
|
+
offered = [str(o) for o in (request.payload.get("options") or ())]
|
|
345
|
+
answered = raw.get("options")
|
|
346
|
+
if not isinstance(answered, (set, frozenset, list, tuple)):
|
|
347
|
+
answered = ()
|
|
348
|
+
chosen = {str(o) for o in answered}
|
|
349
|
+
unoffered = chosen - set(offered)
|
|
350
|
+
if unoffered:
|
|
351
|
+
logger.warning(
|
|
352
|
+
"Question answer named %s, which %s not offered; ignoring "
|
|
353
|
+
"them.", sorted(unoffered),
|
|
354
|
+
"was" if len(unoffered) == 1 else "were")
|
|
355
|
+
|
|
356
|
+
text = raw.get("text")
|
|
357
|
+
return {
|
|
358
|
+
"options": [o for o in offered if o in chosen],
|
|
359
|
+
"text": str(text) if text else "",
|
|
360
|
+
"defer": False,
|
|
361
|
+
}
|
|
362
|
+
|
|
363
|
+
# REVIEW. Strict: a well-formed (decision, notes) pair or nothing.
|
|
364
|
+
#
|
|
365
|
+
# The two decoders this replaces DISAGREED -- review.py's accepted a
|
|
366
|
+
# bare "accept" string and a 1-tuple, tui/app.py's required exactly two
|
|
367
|
+
# elements. Neither behaviour was tested, and the strict one wins
|
|
368
|
+
# because the unsafe direction here is ACCEPTING: this is the only kind
|
|
369
|
+
# whose permissive failure silently applies an edit to a finished
|
|
370
|
+
# research run rather than merely declining something.
|
|
371
|
+
if not isinstance(raw, (tuple, list)) or len(raw) != 2:
|
|
372
|
+
return SAFE_DEFAULTS[REVIEW]
|
|
373
|
+
decision, notes = raw
|
|
374
|
+
if decision not in REVIEW_DECISIONS:
|
|
375
|
+
return SAFE_DEFAULTS[REVIEW]
|
|
376
|
+
return (decision, notes or "")
|
|
377
|
+
|
|
378
|
+
|
|
379
|
+
def ask(channel: Optional[ResponseChannel], request: Request) -> Any:
|
|
380
|
+
"""Put `request` to `channel` and return a decoded answer.
|
|
381
|
+
|
|
382
|
+
THE ONE ENTRY POINT. Callers never invoke `channel.ask` directly, so
|
|
383
|
+
there is exactly one place that knows a missing channel declines, a
|
|
384
|
+
raising callback declines, and a malformed answer declines.
|
|
385
|
+
|
|
386
|
+
A channel of None is not an error: it is the ordinary state of every
|
|
387
|
+
headless run, and §13 pairs it with hiding approval-gated tools rather
|
|
388
|
+
than calling them and failing. Anything that reaches here anyway --
|
|
389
|
+
a path-dependent approval_check that only resolved at call time -- gets
|
|
390
|
+
the declining default.
|
|
391
|
+
"""
|
|
392
|
+
if channel is None:
|
|
393
|
+
return decode(request, None)
|
|
394
|
+
try:
|
|
395
|
+
# NA12. Serialised, so a shell that can only hold one pending
|
|
396
|
+
# answer is never handed two. The lock covers the shell's call and
|
|
397
|
+
# nothing else: `decode` is pure, and holding a lock across it
|
|
398
|
+
# would make one shell's slowness another's wait for no reason.
|
|
399
|
+
with _ask_lock:
|
|
400
|
+
raw = channel.ask(request)
|
|
401
|
+
except Exception: # noqa: BLE001 -- a shell's failure is not the run's
|
|
402
|
+
# Logged with the traceback, because a shell raising here is a real
|
|
403
|
+
# bug worth finding, and at ERROR because the user's answer was
|
|
404
|
+
# silently discarded. The run continues on the declining default:
|
|
405
|
+
# a broken prompt must not take down a ten-pass pipeline, and must
|
|
406
|
+
# not be read as a yes either.
|
|
407
|
+
logger.exception(
|
|
408
|
+
"Response channel raised answering a %r request; "
|
|
409
|
+
"treating as declined.", request.kind)
|
|
410
|
+
return decode(request, None)
|
|
411
|
+
return decode(request, raw)
|