@yahyahammad/venastine 0.3.8 → 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 (128) hide show
  1. package/.env.example +19 -19
  2. package/CONFIG_ARCHITECTURE.md +2030 -2002
  3. package/LICENSE +201 -201
  4. package/README.md +1034 -1034
  5. package/agents/builtin/compactor.md +75 -75
  6. package/agents/builtin/explore.md +77 -77
  7. package/agents/builtin/pipeline-reviewer.md +100 -100
  8. package/agents/builtin/plan.md +106 -106
  9. package/agents/builtin/review.md +74 -74
  10. package/agents/manager.py +261 -261
  11. package/agents/subagent_tool.py +472 -472
  12. package/agents/tui_commands.py +238 -146
  13. package/bin/venastine.mjs +528 -528
  14. package/bin/venastine.py +71 -71
  15. package/cli_commands.py +838 -835
  16. package/config.yaml +13 -0
  17. package/config_edit.py +1301 -1301
  18. package/config_schema.py +971 -966
  19. package/config_update.py +749 -749
  20. package/core/agent_activity.py +256 -256
  21. package/core/ansi.py +452 -452
  22. package/core/approval.py +137 -137
  23. package/core/call_view.py +364 -364
  24. package/core/cancel.py +121 -121
  25. package/core/chatgpt_auth.py +747 -747
  26. package/core/claims_view.py +107 -107
  27. package/core/client.py +2715 -2715
  28. package/core/commands.py +460 -454
  29. package/core/compaction.py +1735 -1735
  30. package/core/config_loader.py +1982 -1982
  31. package/core/connect.py +686 -686
  32. package/core/events.py +123 -123
  33. package/core/file_mentions.py +280 -280
  34. package/core/interaction.py +411 -411
  35. package/core/loop.py +2566 -2566
  36. package/core/memory.py +482 -482
  37. package/core/pipeline_models.py +190 -190
  38. package/core/provider_errors.py +234 -234
  39. package/core/reasoning/authorization.py +130 -130
  40. package/core/reasoning/base.py +219 -219
  41. package/core/reasoning/confidence_scoring.py +484 -484
  42. package/core/reasoning/events.py +149 -149
  43. package/core/reasoning/orchestrator.py +1561 -1561
  44. package/core/reasoning/output_writer.py +345 -345
  45. package/core/reasoning/payload_validation.py +524 -524
  46. package/core/reasoning/pipeline_storage.py +427 -427
  47. package/core/reasoning/scholar.py +458 -458
  48. package/core/reasoning/source_corpus.py +433 -433
  49. package/core/reasoning/source_scoring.py +855 -855
  50. package/core/replay.py +315 -315
  51. package/core/shell_sessions.py +1553 -1553
  52. package/credentials.py +307 -307
  53. package/database.py +333 -333
  54. package/docs/PRIVACY.md +78 -78
  55. package/docs/SECURITY.md +108 -108
  56. package/docs/THIRD_PARTY_NOTICES.md +148 -148
  57. package/env_secrets.py +118 -118
  58. package/json_store.py +343 -343
  59. package/logging_setup.py +295 -295
  60. package/main.py +3433 -3433
  61. package/mcp_client/client.py +733 -733
  62. package/mcp_client/config.py +484 -484
  63. package/mcp_client/registration.py +343 -343
  64. package/memories/manager.py +147 -147
  65. package/memories/tui_commands.py +319 -239
  66. package/package.json +303 -303
  67. package/project_init/config_files.py +282 -282
  68. package/project_init/generator.py +728 -728
  69. package/project_init/manifest.py +418 -418
  70. package/project_init/tui_commands.py +147 -147
  71. package/prompts/critic_pass.md +24 -24
  72. package/prompts/revalidate.md +25 -25
  73. package/prompts/revise.md +17 -17
  74. package/prompts/source_grounding.md +66 -66
  75. package/prompts/system_prompts.py +316 -316
  76. package/providers.json.example +94 -94
  77. package/pyproject.toml +149 -149
  78. package/requirements.txt +295 -295
  79. package/safety/policy_enforcement.py +1082 -1082
  80. package/security/askpass.py +419 -419
  81. package/security/capability.py +207 -207
  82. package/security/confine.py +484 -484
  83. package/security/hosted.py +182 -182
  84. package/security/permissions.py +237 -237
  85. package/security/protected_paths.py +501 -501
  86. package/security/sandbox.py +4108 -4108
  87. package/skills/builtin/math/formal-specification.md +67 -67
  88. package/skills/builtin/math/numerical-methods.md +66 -66
  89. package/skills/builtin/research/experiment-design.md +62 -62
  90. package/skills/builtin/research/reproducibility.md +55 -55
  91. package/skills/builtin/research/source-evaluation.md +70 -70
  92. package/skills/builtin/research/statistical-inference.md +63 -63
  93. package/skills/builtin/research/technical-writing.md +59 -59
  94. package/skills/builtin/software/code-review.md +61 -61
  95. package/skills/builtin/software/debugging.md +61 -61
  96. package/skills/builtin/software/test-design.md +67 -67
  97. package/skills/tui_commands.py +110 -110
  98. package/storage.py +1338 -1338
  99. package/tools/base.py +465 -465
  100. package/tools/builtin/_math_common.py +667 -667
  101. package/tools/builtin/_net_common.py +267 -267
  102. package/tools/builtin/arxiv.py +681 -681
  103. package/tools/builtin/fetch_url.py +371 -371
  104. package/tools/builtin/file_ops.py +720 -720
  105. package/tools/builtin/geometry.py +184 -184
  106. package/tools/builtin/load_skill.py +76 -76
  107. package/tools/builtin/pin.py +227 -227
  108. package/tools/builtin/probability_stats.py +224 -224
  109. package/tools/builtin/project_docs.py +464 -464
  110. package/tools/builtin/remember.py +175 -175
  111. package/tools/builtin/shell.py +980 -980
  112. package/tools/builtin/todo.py +149 -149
  113. package/tools/builtin/web_search.py +328 -328
  114. package/tools/context.py +159 -159
  115. package/tools/isolation.py +387 -387
  116. package/tools/registry.py +1242 -1242
  117. package/tui/app.py +8318 -8307
  118. package/tui/app.tcss +747 -739
  119. package/tui/commands.py +26 -26
  120. package/tui/diffs.py +286 -286
  121. package/tui/history.py +128 -128
  122. package/tui/hosted_driver.py +102 -102
  123. package/tui/markdown.py +1329 -1329
  124. package/tui/meters.py +364 -364
  125. package/tui/ravens.py +146 -146
  126. package/tui/screens.py +1255 -1197
  127. package/tui/themes.py +599 -599
  128. package/tui/widgets.py +3813 -3796
@@ -1,411 +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
- 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)
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)