@yahyahammad/venastine 0.2.0 → 0.3.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (152) hide show
  1. package/.env.example +9 -4
  2. package/CONFIG_ARCHITECTURE.md +2030 -0
  3. package/LICENSE +201 -201
  4. package/NOTICE +1 -1
  5. package/README.md +1034 -895
  6. package/agents/builtin/build.md +73 -0
  7. package/agents/builtin/compactor.md +75 -75
  8. package/agents/builtin/explore.md +77 -77
  9. package/agents/builtin/general.md +80 -0
  10. package/agents/builtin/pipeline-reviewer.md +100 -100
  11. package/agents/builtin/plan.md +106 -88
  12. package/agents/builtin/review.md +74 -74
  13. package/agents/builtin/test.md +65 -0
  14. package/agents/builtin/writer.md +67 -0
  15. package/agents/manager.py +68 -2
  16. package/agents/subagent_tool.py +472 -238
  17. package/agents/tui_commands.py +238 -151
  18. package/bin/venastine.mjs +150 -4
  19. package/bin/venastine.py +71 -0
  20. package/cli_commands.py +838 -0
  21. package/config.py +95 -1198
  22. package/config.yaml +1103 -0
  23. package/config_edit.py +1301 -0
  24. package/config_schema.py +971 -0
  25. package/config_update.py +749 -0
  26. package/core/agent_activity.py +256 -118
  27. package/core/ansi.py +452 -0
  28. package/core/approval.py +137 -115
  29. package/core/call_view.py +364 -0
  30. package/core/cancel.py +121 -0
  31. package/core/chatgpt_auth.py +747 -0
  32. package/core/claims_view.py +107 -0
  33. package/core/client.py +2715 -1559
  34. package/core/commands.py +460 -0
  35. package/core/compaction.py +1735 -971
  36. package/core/config_loader.py +1982 -1563
  37. package/core/connect.py +686 -0
  38. package/core/events.py +123 -61
  39. package/core/file_mentions.py +280 -0
  40. package/core/interaction.py +411 -328
  41. package/core/line_pattern.py +128 -0
  42. package/core/loop.py +2566 -1490
  43. package/core/memory.py +482 -370
  44. package/core/pipeline_models.py +190 -176
  45. package/core/provider_errors.py +234 -0
  46. package/core/reasoning/authorization.py +130 -130
  47. package/core/reasoning/base.py +219 -219
  48. package/core/reasoning/confidence_scoring.py +484 -468
  49. package/core/reasoning/events.py +149 -149
  50. package/core/reasoning/json_retry.py +19 -1
  51. package/core/reasoning/orchestrator.py +1561 -1382
  52. package/core/reasoning/output_writer.py +345 -286
  53. package/core/reasoning/payload_validation.py +524 -398
  54. package/core/reasoning/pipeline_storage.py +88 -22
  55. package/core/reasoning/review.py +659 -615
  56. package/core/reasoning/scholar.py +458 -434
  57. package/core/reasoning/source_corpus.py +433 -327
  58. package/core/reasoning/source_scoring.py +855 -855
  59. package/core/replay.py +315 -183
  60. package/core/session.py +36 -12
  61. package/core/session_view.py +259 -0
  62. package/core/session_wake.py +259 -0
  63. package/core/shell_sessions.py +1553 -0
  64. package/core/workspace_trust.py +1 -1
  65. package/credentials.py +148 -20
  66. package/database.py +333 -252
  67. package/{PRIVACY.md → docs/PRIVACY.md} +78 -66
  68. package/docs/SECURITY.md +108 -0
  69. package/docs/THIRD_PARTY_NOTICES.md +148 -0
  70. package/env_secrets.py +50 -9
  71. package/json_store.py +343 -123
  72. package/logging_setup.py +295 -185
  73. package/main.py +3433 -1961
  74. package/mcp_client/client.py +733 -499
  75. package/mcp_client/config.py +126 -21
  76. package/mcp_client/registration.py +343 -182
  77. package/memories/manager.py +147 -132
  78. package/memories/tui_commands.py +319 -244
  79. package/package.json +303 -73
  80. package/project_init/config_files.py +282 -278
  81. package/project_init/generator.py +728 -564
  82. package/project_init/manifest.py +18 -6
  83. package/project_init/tui_commands.py +147 -144
  84. package/prompts/critic_pass.md +24 -24
  85. package/prompts/revalidate.md +25 -25
  86. package/prompts/revise.md +2 -0
  87. package/prompts/source_grounding.md +66 -66
  88. package/prompts/system_prompts.py +316 -262
  89. package/providers.json.example +4 -2
  90. package/pyproject.toml +149 -100
  91. package/requirements.txt +295 -72
  92. package/safety/policy_enforcement.py +1082 -746
  93. package/security/askpass.py +419 -0
  94. package/security/capability.py +207 -177
  95. package/security/confine.py +484 -0
  96. package/security/hosted.py +182 -0
  97. package/security/permissions.py +237 -190
  98. package/security/posture.py +124 -12
  99. package/security/protected_paths.py +501 -309
  100. package/security/sandbox.py +4108 -985
  101. package/security/secrets.py +855 -0
  102. package/skills/builtin/math/formal-specification.md +67 -67
  103. package/skills/builtin/math/numerical-methods.md +66 -66
  104. package/skills/builtin/research/experiment-design.md +62 -62
  105. package/skills/builtin/research/reproducibility.md +55 -55
  106. package/skills/builtin/research/source-evaluation.md +70 -70
  107. package/skills/builtin/research/statistical-inference.md +63 -63
  108. package/skills/builtin/research/technical-writing.md +59 -59
  109. package/skills/builtin/software/code-review.md +61 -61
  110. package/skills/builtin/software/debugging.md +61 -61
  111. package/skills/builtin/software/test-design.md +67 -67
  112. package/skills/tui_commands.py +110 -111
  113. package/storage.py +1338 -1005
  114. package/tools/base.py +161 -1
  115. package/tools/builtin/_math_common.py +667 -377
  116. package/tools/builtin/_net_common.py +225 -19
  117. package/tools/builtin/arxiv.py +497 -39
  118. package/tools/builtin/ask_user.py +231 -213
  119. package/tools/builtin/discrete_math.py +35 -4
  120. package/tools/builtin/fetch_url.py +371 -153
  121. package/tools/builtin/file_ops.py +720 -412
  122. package/tools/builtin/geometry.py +48 -12
  123. package/tools/builtin/get_time.py +2 -2
  124. package/tools/builtin/linear_algebra.py +66 -23
  125. package/tools/builtin/load_skill.py +76 -66
  126. package/tools/builtin/logic.py +171 -12
  127. package/tools/builtin/pin.py +227 -193
  128. package/tools/builtin/probability_stats.py +12 -16
  129. package/tools/builtin/project_docs.py +464 -405
  130. package/tools/builtin/remember.py +175 -158
  131. package/tools/builtin/shell.py +980 -461
  132. package/tools/builtin/shell_sessions.py +613 -0
  133. package/tools/builtin/symbolic_math.py +80 -10
  134. package/tools/builtin/todo.py +149 -147
  135. package/tools/builtin/web_search.py +191 -13
  136. package/tools/context.py +159 -136
  137. package/tools/isolation.py +107 -34
  138. package/tools/registry.py +1242 -925
  139. package/tui/app.py +8318 -4100
  140. package/tui/app.tcss +747 -556
  141. package/tui/commands.py +26 -170
  142. package/tui/diffs.py +34 -13
  143. package/tui/history.py +128 -128
  144. package/tui/hosted_driver.py +102 -0
  145. package/tui/markdown.py +1329 -1279
  146. package/tui/meters.py +364 -268
  147. package/tui/ravens.py +146 -146
  148. package/tui/screens.py +1255 -943
  149. package/tui/themes.py +599 -559
  150. package/tui/widgets.py +3813 -2332
  151. package/SECURITY.md +0 -88
  152. package/THIRD_PARTY_NOTICES.md +0 -100
@@ -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
- from dataclasses import dataclass, field
43
- from typing import Any, Callable, Optional
44
-
45
- import logging
46
-
47
- logger = logging.getLogger(__name__)
48
-
49
-
50
- # ---------------------------------------------------------------------------
51
- # ---- Kinds ----------------------------------------------------------------
52
- # ---------------------------------------------------------------------------
53
-
54
- APPROVAL = "approval"
55
- SUBAGENT_SIGNOFF = "subagent_signoff"
56
- REVIEW = "review"
57
- # §24's two, migrated in §23 slice 1. CONFIRM and APPROVAL both answer with
58
- # a bool and are still separate kinds, because the KIND is what tells a
59
- # shell how to render: APPROVAL is a gated tool call with params, CONFIRM
60
- # is a titled yes/no over a block of text the caller composed.
61
- CONFIRM = "confirm"
62
- CHOICE = "choice"
63
- # §23 slice 2. Separate from CHOICE, which answers with exactly one of the
64
- # options offered and nothing else. A QUESTION can come back as several
65
- # options, as free text, as both, or as "I would rather talk about this" --
66
- # four affordances the spec asks for by name, and a shape CHOICE's decoder
67
- # cannot express without becoming two decoders wearing one name.
68
- QUESTION = "question"
69
-
70
- # Review decisions, moved here from core/reasoning/review.py so the decoder
71
- # and the pipeline cannot disagree about what a valid answer is.
72
- ACCEPT = "accept"
73
- REJECT = "reject"
74
- REFINE = "refine"
75
- REJECT_ALL = "reject_all"
76
- REVIEW_DECISIONS = (ACCEPT, REJECT, REFINE, REJECT_ALL)
77
-
78
- # What each kind means when nobody answered, answered incoherently, or could
79
- # not be asked at all. Every entry declines.
80
- #
81
- # INVARIANT, pinned by a test: `decode(Request(kind), None) ==
82
- # SAFE_DEFAULTS[kind]` for
83
- # every kind. That is what lets `ask()` route the no-channel and the
84
- # callback-raised paths through `decode` rather than reading this table -- so
85
- # there is genuinely one function deciding what a non-answer means, and a new
86
- # kind cannot be added with a default the decoder disagrees about.
87
- SAFE_DEFAULTS = {
88
- APPROVAL: False,
89
- # None, not set(): the two are DIFFERENT answers. None denies the spawn
90
- # outright; an empty set spawns the subagent with nothing pre-granted,
91
- # which is a legitimate choice a user can make. Defaulting to set() would
92
- # turn "nobody answered" into "go ahead, just ask me later" -- and in a
93
- # headless run there is nobody to ask later either.
94
- SUBAGENT_SIGNOFF: None,
95
- REVIEW: (REJECT, ""),
96
- CONFIRM: False,
97
- # None, not the first option: "nobody answered" is not a choice, and
98
- # picking one on the user's behalf is exactly what a declining default
99
- # exists to avoid.
100
- CHOICE: None,
101
- # None, for CHOICE's reason. Note what this makes indistinguishable, on
102
- # purpose: an unanswered question and a dismissed one both arrive here,
103
- # and the TOOL turns that into an error result the model can work
104
- # around. "I would rather discuss this" is NOT this -- it is a real
105
- # answer carrying defer=True, because a user who says that has told the
106
- # model something, and a user who closed the modal has not.
107
- QUESTION: None,
108
- }
109
-
110
-
111
- @dataclass
112
- class Request:
113
- """One question, addressed to whoever can answer it.
114
-
115
- `payload` is kind-specific and is not validated here: this module owns
116
- the ANSWER contract, not the question's. A shell renders the payload it
117
- understands; an unrecognised kind is a programming error, and `decode`
118
- raises on one rather than inventing a default for a question nobody
119
- designed.
120
- """
121
-
122
- kind: str
123
- payload: dict = field(default_factory=dict)
124
- # Extra text explaining what answering actually authorises. Supplied by
125
- # ToolSpec.approval_notice for tool calls -- the tool's knowledge, not
126
- # the shell's (spawn_subagent uses it to name the tools a child could
127
- # then run unprompted).
128
- notice: Optional[str] = None
129
-
130
-
131
- @dataclass
132
- class ResponseChannel:
133
- """A caller-supplied way to put one Request to a human and block.
134
-
135
- ask(request) -> raw answer. Implementations live in the shells, because
136
- only they know how to reach the person: main.py reads stdin, tui/app.py
137
- posts to the UI thread and waits on a queue.
138
-
139
- The raw answer is never trusted. Callers go through this module's
140
- `ask()`, which decodes it and substitutes the declining default for
141
- anything unrecognised.
142
-
143
- honour_run_scope mirrors ToolSpec.grant_scope, carried over unchanged
144
- from §25's ApprovalProvider. A channel that sets it False makes every
145
- call ask, even for a tool whose approval would normally cover the rest
146
- of the run. Attended mode sets it False: a mode whose entire purpose is
147
- per-call supervision must not let one yes silently cover later calls,
148
- however sensible that shortcut is inside a chat turn.
149
- """
150
-
151
- ask: Callable[[Request], Any]
152
- honour_run_scope: bool = True
153
-
154
-
155
- # ---------------------------------------------------------------------------
156
- # ---- Decoding --------------------------------------------------------------
157
- # ---------------------------------------------------------------------------
158
-
159
- def decode(request: "Request", raw: Any) -> Any:
160
- """Normalise whatever a shell returned into this kind's answer type.
161
-
162
- Anything unrecognised becomes SAFE_DEFAULTS[kind]. That covers a
163
- dismissal carrying None, a modal torn down by shutdown (which puts a
164
- bare False), a timeout, and a shell that returned something of the
165
- wrong shape entirely.
166
-
167
- TAKES THE REQUEST, NOT JUST THE KIND, because two kinds cannot be
168
- validated without knowing what was ASKED. A choice is only valid
169
- against the options it was offered, and a sign-off subset is only
170
- valid against the candidates that were listed -- a shell returning a
171
- tool nobody offered must not thereby grant it. Passing the kind alone
172
- made those two unverifiable, which is the sort of gap that shows up
173
- later as "the answer was honoured but nothing had proposed it".
174
-
175
- Raises on an unknown KIND, deliberately, rather than returning a
176
- default. An unanswerable question is a runtime condition to fail safe
177
- on; a question nobody defined is a bug, and inventing "no" for it would
178
- hide the typo in whichever call site built the Request.
179
- """
180
- kind = request.kind
181
- if kind not in SAFE_DEFAULTS:
182
- raise ValueError(
183
- f"Unknown request kind {kind!r}; expected one of "
184
- f"{', '.join(sorted(SAFE_DEFAULTS))}.")
185
-
186
- if kind in (APPROVAL, CONFIRM):
187
- # bool(), not `is True`: a shell answering with a truthy value it
188
- # considers a yes should not be silently denied. The permissive
189
- # direction is safe here ONLY because the alternative is also a
190
- # decision the user made -- unlike the shapes below, there is no
191
- # third state to confuse it with.
192
- return bool(raw)
193
-
194
- if kind == CHOICE:
195
- # Valid ONLY against what was offered. A shell returning something
196
- # nobody proposed is answering a different question, and the
197
- # options live on the request precisely so this can be checked --
198
- # `decode(kind, raw)` could not, which is why it takes the request.
199
- options = request.payload.get("options") or ()
200
- return raw if raw in options else None
201
-
202
- if kind == SUBAGENT_SIGNOFF:
203
- # Three answers, and the middle one is the easy one to lose: None
204
- # denies the spawn, an EMPTY collection spawns with nothing
205
- # granted, a non-empty one grants those names. The emptiness test
206
- # is therefore `isinstance`, never truthiness -- `if raw:` would
207
- # fold the middle answer into the first.
208
- #
209
- # Everything else denies by falling through, booleans included: a
210
- # shell that answered this like an approval must not hand the
211
- # child its whole gated set. That needs no explicit `raw is True`
212
- # branch, since bool subclasses int rather than any collection --
213
- # one was written here and removed, because a guard that cannot
214
- # fire still reads as the thing protecting you.
215
- if not isinstance(raw, (set, frozenset, list, tuple)):
216
- return None
217
- chosen = {str(name) for name in raw}
218
- # INTERSECTED with what was offered. A shell returning a name that
219
- # was never a candidate must not grant it -- the sign-off's whole
220
- # substance is that the list shown and the list granted are the
221
- # same, which agents/manager.py's candidate_approvals() says in its
222
- # own docstring. An empty `candidates` means nothing was offered,
223
- # so nothing can be granted.
224
- offered = {str(name) for name in
225
- (request.payload.get("candidates") or ())}
226
- unoffered = chosen - offered
227
- if unoffered:
228
- logger.warning(
229
- "Sign-off answer named %s, which %s not offered; ignoring "
230
- "them.", sorted(unoffered),
231
- "was" if len(unoffered) == 1 else "were")
232
- return chosen & offered
233
-
234
- if kind == QUESTION:
235
- # A dict, or nothing. Three answers again, and again the middle one
236
- # is the one to lose:
237
- #
238
- # None nobody answered -- dismissed, timed
239
- # out, no channel, or a shape this
240
- # cannot read. The TOOL turns it into an
241
- # error result.
242
- # {..., "defer": True} "let's talk about it instead". A REAL
243
- # answer: the user engaged and declined
244
- # to pick, which is different from not
245
- # being there. This is the spec's "chat
246
- # about this" escape.
247
- # {"options": [...], ...} a choice, or free text, or both.
248
- #
249
- # Deliberately NOT truthiness on the dict: an answer of
250
- # {"options": [], "text": ""} is someone submitting a blank form,
251
- # which is still not "nobody answered", and the tool can say so.
252
- if not isinstance(raw, dict):
253
- return None
254
- if raw.get("defer"):
255
- # Nothing else is read. A deferral is not a partial answer, and
256
- # carrying half-filled options alongside it would invite a
257
- # caller to act on both.
258
- return {"options": [], "text": "", "defer": True}
259
-
260
- # INTERSECTED with what was offered, in OFFERED order -- the same
261
- # rule as SUBAGENT_SIGNOFF above, and for J3's reason: a shell
262
- # returning something nobody proposed is answering a different
263
- # question. Offered order rather than answer order so the model
264
- # reads options back in the sequence it wrote them, which is the
265
- # sequence its own prompt explained.
266
- offered = [str(o) for o in (request.payload.get("options") or ())]
267
- answered = raw.get("options")
268
- if not isinstance(answered, (set, frozenset, list, tuple)):
269
- answered = ()
270
- chosen = {str(o) for o in answered}
271
- unoffered = chosen - set(offered)
272
- if unoffered:
273
- logger.warning(
274
- "Question answer named %s, which %s not offered; ignoring "
275
- "them.", sorted(unoffered),
276
- "was" if len(unoffered) == 1 else "were")
277
-
278
- text = raw.get("text")
279
- return {
280
- "options": [o for o in offered if o in chosen],
281
- "text": str(text) if text else "",
282
- "defer": False,
283
- }
284
-
285
- # REVIEW. Strict: a well-formed (decision, notes) pair or nothing.
286
- #
287
- # The two decoders this replaces DISAGREED -- review.py's accepted a
288
- # bare "accept" string and a 1-tuple, tui/app.py's required exactly two
289
- # elements. Neither behaviour was tested, and the strict one wins
290
- # because the unsafe direction here is ACCEPTING: this is the only kind
291
- # whose permissive failure silently applies an edit to a finished
292
- # research run rather than merely declining something.
293
- if not isinstance(raw, (tuple, list)) or len(raw) != 2:
294
- return SAFE_DEFAULTS[REVIEW]
295
- decision, notes = raw
296
- if decision not in REVIEW_DECISIONS:
297
- return SAFE_DEFAULTS[REVIEW]
298
- return (decision, notes or "")
299
-
300
-
301
- def ask(channel: Optional[ResponseChannel], request: Request) -> Any:
302
- """Put `request` to `channel` and return a decoded answer.
303
-
304
- THE ONE ENTRY POINT. Callers never invoke `channel.ask` directly, so
305
- there is exactly one place that knows a missing channel declines, a
306
- raising callback declines, and a malformed answer declines.
307
-
308
- A channel of None is not an error: it is the ordinary state of every
309
- headless run, and §13 pairs it with hiding approval-gated tools rather
310
- than calling them and failing. Anything that reaches here anyway --
311
- a path-dependent approval_check that only resolved at call time -- gets
312
- the declining default.
313
- """
314
- if channel is None:
315
- return decode(request, None)
316
- try:
317
- raw = channel.ask(request)
318
- except Exception: # noqa: BLE001 -- a shell's failure is not the run's
319
- # Logged with the traceback, because a shell raising here is a real
320
- # bug worth finding, and at ERROR because the user's answer was
321
- # silently discarded. The run continues on the declining default:
322
- # a broken prompt must not take down a ten-pass pipeline, and must
323
- # not be read as a yes either.
324
- logger.exception(
325
- "Response channel raised answering a %r request; "
326
- "treating as declined.", request.kind)
327
- return decode(request, None)
328
- return decode(request, raw)
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)