@yahyahammad/venastine 0.1.0

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 (143) hide show
  1. package/.env.example +14 -0
  2. package/LICENSE +201 -0
  3. package/NOTICE +14 -0
  4. package/PRIVACY.md +66 -0
  5. package/README.md +878 -0
  6. package/SECURITY.md +88 -0
  7. package/THIRD_PARTY_NOTICES.md +100 -0
  8. package/agents/builtin/compactor.md +75 -0
  9. package/agents/builtin/explore.md +77 -0
  10. package/agents/builtin/grill-me.md +27 -0
  11. package/agents/builtin/initializer.md +94 -0
  12. package/agents/builtin/pipeline-reviewer.md +100 -0
  13. package/agents/builtin/plan.md +88 -0
  14. package/agents/builtin/review.md +74 -0
  15. package/agents/manager.py +195 -0
  16. package/agents/subagent_tool.py +215 -0
  17. package/agents/tui_commands.py +136 -0
  18. package/bin/venastine.mjs +382 -0
  19. package/config.py +1198 -0
  20. package/core/__init__.py +0 -0
  21. package/core/approval.py +115 -0
  22. package/core/client.py +1548 -0
  23. package/core/compaction.py +959 -0
  24. package/core/config_loader.py +1563 -0
  25. package/core/events.py +61 -0
  26. package/core/interaction.py +328 -0
  27. package/core/loop.py +1353 -0
  28. package/core/memory.py +370 -0
  29. package/core/model_windows.py +175 -0
  30. package/core/pipeline_models.py +176 -0
  31. package/core/reasoning/__init__.py +0 -0
  32. package/core/reasoning/authorization.py +130 -0
  33. package/core/reasoning/base.py +219 -0
  34. package/core/reasoning/confidence_scoring.py +468 -0
  35. package/core/reasoning/events.py +149 -0
  36. package/core/reasoning/json_retry.py +219 -0
  37. package/core/reasoning/orchestrator.py +1382 -0
  38. package/core/reasoning/output_writer.py +286 -0
  39. package/core/reasoning/payload_validation.py +398 -0
  40. package/core/reasoning/pipeline_storage.py +361 -0
  41. package/core/reasoning/review.py +615 -0
  42. package/core/reasoning/scholar.py +434 -0
  43. package/core/reasoning/source_corpus.py +327 -0
  44. package/core/reasoning/source_scoring.py +855 -0
  45. package/core/replay.py +167 -0
  46. package/core/session.py +153 -0
  47. package/core/workspace_trust.py +207 -0
  48. package/credentials.py +180 -0
  49. package/database.py +252 -0
  50. package/env_secrets.py +77 -0
  51. package/json_store.py +123 -0
  52. package/logging_setup.py +185 -0
  53. package/main.py +1959 -0
  54. package/mcp_client/__init__.py +15 -0
  55. package/mcp_client/client.py +499 -0
  56. package/mcp_client/config.py +379 -0
  57. package/mcp_client/registration.py +182 -0
  58. package/memories/manager.py +132 -0
  59. package/memories/tui_commands.py +232 -0
  60. package/package.json +73 -0
  61. package/project_init/config_files.py +278 -0
  62. package/project_init/doc_sets.py +330 -0
  63. package/project_init/generator.py +564 -0
  64. package/project_init/manifest.py +406 -0
  65. package/project_init/tui_commands.py +144 -0
  66. package/prompts/__init__.py +0 -0
  67. package/prompts/annotate.md +14 -0
  68. package/prompts/assumption_audit.md +27 -0
  69. package/prompts/claim_extraction.md +34 -0
  70. package/prompts/completeness.md +18 -0
  71. package/prompts/confidence_tiers.md +23 -0
  72. package/prompts/critic_pass.md +24 -0
  73. package/prompts/final_synthesis.md +13 -0
  74. package/prompts/initial_generation.md +14 -0
  75. package/prompts/preliminary_plan.md +23 -0
  76. package/prompts/revalidate.md +25 -0
  77. package/prompts/revise.md +15 -0
  78. package/prompts/source_grounding.md +66 -0
  79. package/prompts/system_prompts.py +262 -0
  80. package/prompts/universal_system_prompt +7 -0
  81. package/prompts/untrusted_content +1 -0
  82. package/providers.json.example +92 -0
  83. package/pyproject.toml +100 -0
  84. package/requirements.txt +72 -0
  85. package/safety/__init__.py +0 -0
  86. package/safety/policy_enforcement.py +682 -0
  87. package/security/__init__.py +0 -0
  88. package/security/capability.py +177 -0
  89. package/security/permissions.py +190 -0
  90. package/security/posture.py +302 -0
  91. package/security/protected_paths.py +309 -0
  92. package/security/sandbox.py +985 -0
  93. package/skills/builtin/crypto/cryptography-verification.md +66 -0
  94. package/skills/builtin/math/formal-specification.md +67 -0
  95. package/skills/builtin/math/numerical-methods.md +66 -0
  96. package/skills/builtin/math/proof-writing.md +61 -0
  97. package/skills/builtin/research/experiment-design.md +62 -0
  98. package/skills/builtin/research/literature-review.md +65 -0
  99. package/skills/builtin/research/reproducibility.md +55 -0
  100. package/skills/builtin/research/source-evaluation.md +70 -0
  101. package/skills/builtin/research/statistical-inference.md +63 -0
  102. package/skills/builtin/research/technical-writing.md +59 -0
  103. package/skills/builtin/security/cybersecurity-research.md +63 -0
  104. package/skills/builtin/software/code-review.md +61 -0
  105. package/skills/builtin/software/debugging.md +61 -0
  106. package/skills/builtin/software/test-design.md +67 -0
  107. package/skills/manager.py +138 -0
  108. package/skills/tui_commands.py +111 -0
  109. package/storage.py +1005 -0
  110. package/tools/base.py +305 -0
  111. package/tools/builtin/__init__.py +0 -0
  112. package/tools/builtin/_math_common.py +377 -0
  113. package/tools/builtin/_net_common.py +61 -0
  114. package/tools/builtin/arxiv.py +223 -0
  115. package/tools/builtin/ask_user.py +213 -0
  116. package/tools/builtin/discrete_math.py +134 -0
  117. package/tools/builtin/fetch_url.py +153 -0
  118. package/tools/builtin/file_ops.py +412 -0
  119. package/tools/builtin/geometry.py +148 -0
  120. package/tools/builtin/get_time.py +20 -0
  121. package/tools/builtin/linear_algebra.py +155 -0
  122. package/tools/builtin/load_skill.py +66 -0
  123. package/tools/builtin/logic.py +96 -0
  124. package/tools/builtin/pin.py +193 -0
  125. package/tools/builtin/probability_stats.py +228 -0
  126. package/tools/builtin/project_docs.py +405 -0
  127. package/tools/builtin/remember.py +158 -0
  128. package/tools/builtin/shell.py +461 -0
  129. package/tools/builtin/symbolic_math.py +119 -0
  130. package/tools/builtin/todo.py +147 -0
  131. package/tools/builtin/web_search.py +151 -0
  132. package/tools/context.py +136 -0
  133. package/tools/isolation.py +314 -0
  134. package/tools/registry.py +897 -0
  135. package/tui/app.py +3423 -0
  136. package/tui/app.tcss +458 -0
  137. package/tui/commands.py +61 -0
  138. package/tui/diffs.py +265 -0
  139. package/tui/preferences.py +182 -0
  140. package/tui/ravens.py +146 -0
  141. package/tui/screens.py +943 -0
  142. package/tui/themes.py +366 -0
  143. package/tui/widgets.py +1239 -0
package/core/events.py ADDED
@@ -0,0 +1,61 @@
1
+ """
2
+ core/events.py
3
+
4
+ LoopEvent is the single event type yielded by RunAgentLoop._run() as it
5
+ progresses through the call-dispatch-repeat cycle. Exactly one field is
6
+ meaningfully populated per event, matching what happened at that point
7
+ in the loop.
8
+
9
+ Consumers (CLI, TUI, research pipeline) iterate the generator and react
10
+ to whichever field is set. run_to_completion() in core/loop.py drains
11
+ the generator for callers that only need the final ModelResponse.
12
+
13
+ Error handling: there is deliberately no error variant. Exceptions
14
+ raised mid-loop propagate naturally out of the generator, unchanged
15
+ from the pre-streaming behavior. orchestrator.py's failure-path
16
+ persistence (except Exception: update_pipeline_run(..., status="failed");
17
+ raise) depends on a real exception propagating -- converting failures
18
+ into data-shaped events would require every consumer to know to unpack
19
+ and re-raise. Consumers that want graceful error display (the TUI) wrap
20
+ their own consumption loop in try/except.
21
+ """
22
+
23
+ from dataclasses import dataclass
24
+ from typing import Optional, Any
25
+
26
+
27
+ @dataclass
28
+ class LoopEvent:
29
+ """One event yielded by RunAgentLoop._run()."""
30
+ token_delta: Optional[str] = None
31
+ # ROADMAP_v2 §38 (O4) -- the EIGHTH field, and P1 re-made rather than
32
+ # widened by accretion. P1 rejected putting §22's and §23's kinds here
33
+ # because those describe a ten-pass RUN and live for the run; a
34
+ # thinking delta describes one model call's progress and lives for a
35
+ # turn, which is token_delta's family exactly. So this is the case P1's
36
+ # rule was never about, and the ninth field still has to argue for
37
+ # itself in tests/test_pipeline_events.py.
38
+ #
39
+ # Reasoning text, streamed as it arrives, for the shells that want to
40
+ # show it. Display-only: it is not persisted, not part of
41
+ # ModelResponse.text, and never sent back on the wire. Empty on
42
+ # providers that return no reasoning (OPENAI, GOOGLE) -- see
43
+ # StreamToken's note.
44
+ thinking_delta: Optional[str] = None
45
+ tool_call_start: Optional[dict] = None # {"id", "name", "input"}
46
+ tool_result: Optional[dict] = None # {"id", "result"}
47
+ permission_request: Optional[dict] = None # {"tool_name", "params"}
48
+ # ROADMAP_v2 §21: {"kind", "text"} -- a compaction that happened, an
49
+ # early warning that one is coming, or a compaction that could not
50
+ # help. §21's "no silent compaction, ever": both automatic and manual
51
+ # compaction show a marker inline.
52
+ #
53
+ # ALSO carried on the ModelResponse, because run_to_completion()
54
+ # discards every non-final event -- so a notice delivered only here
55
+ # would be invisible to the CLI and the pipeline, which drain the
56
+ # generator rather than watching it. That is the same defect §20 and
57
+ # §25 each hit once; the event is for live display, the response field
58
+ # is for everyone else.
59
+ notice: Optional[dict] = None
60
+ final_response: Optional[Any] = None # ModelResponse on terminal event
61
+ stop_reason: Optional[str] = None # "complete" | "max_steps_reached" | "token_budget_exceeded"
@@ -0,0 +1,328 @@
1
+ """
2
+ core/interaction.py
3
+
4
+ ROADMAP_v2 §23 (AC1): the ONE way anything in this harness asks a human a
5
+ question and blocks for the answer.
6
+
7
+ Before this there were five, and each re-derived the same four rules --
8
+ what a dismissal carries, what a timeout means, how shutdown releases a
9
+ parked worker, and how a malformed answer decodes:
10
+
11
+ * `permission_channel`, a queue.Queue of booleans (§13)
12
+ * `ApprovalProvider.ask(tool_name, params, notice) -> bool` (§25), which
13
+ exists only because run_to_completion() DISCARDS the LoopEvent carrying
14
+ the question, so the CLI and the pipeline would block on a queue with
15
+ nothing displayed
16
+ * `ReviewConsent.decide(finding, round) -> (decision, notes)` (§20)
17
+ * two more in §24's /init, added by the section immediately before this one
18
+
19
+ §23's spec put the generalisation first for a reason it has now been proved
20
+ right about twice: "doing the tools first and the generalisation afterwards
21
+ produces two bespoke channels and a third when §18 wants one."
22
+
23
+ WHAT IS ACTUALLY SHARED IS `decode`, NOT THE DATACLASS. A request/response
24
+ dataclass pair is nearly free to write badly -- five call sites can each
25
+ build one and still each invent their own failure handling. The consolidation
26
+ that pays is that every route into an answer (a queue, a callable, a timeout,
27
+ a shutdown release, a callback that raised) funnels through ONE function that
28
+ owns the safe default per kind. "The inability to ask is not permission to
29
+ proceed" (§25's V6) stops being a habit five places remember and becomes a
30
+ property of this module.
31
+
32
+ THE DEFAULT IS ALWAYS THE DECLINING ANSWER, never the permissive one. That
33
+ asymmetry is the whole design: an approval that cannot be obtained is a
34
+ denial, a sign-off nobody answered grants nothing, a review correction nobody
35
+ approved is not applied.
36
+
37
+ Deliberately a leaf module with no project imports, matching core/approval.py
38
+ -- core/loop.py, main.py, tui/app.py and core/reasoning/ all depend on it and
39
+ it depends on none of them.
40
+ """
41
+
42
+ 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)