@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
@@ -0,0 +1,615 @@
1
+ """
2
+ core/reasoning/review.py
3
+
4
+ ROADMAP_v2 §20 -- the post-pipeline review, and the only place in this
5
+ codebase where a model's proposal can change a finished run's output.
6
+
7
+ Three functions, in the order they run:
8
+
9
+ run_review() ask the reviewer agent what is wrong. No mutation.
10
+ walk_consent() put each finding to the human. No mutation.
11
+ apply_deferred() build the corrected claim set. No asking, no commit.
12
+
13
+ Kept separate because they fail differently and because the middle one is
14
+ the whole security argument: a reviewer that could apply its own findings
15
+ would be a model with write access to the report, and the pipeline reads
16
+ attacker-controlled web pages by design. Splitting proposal from
17
+ application means the mutation step has no model in it at all.
18
+
19
+ The third one returns a COPY rather than mutating in place, and a
20
+ direct-mutation variant is the thing not to reintroduce -- see its
21
+ docstring for the ordering bug that shape produces.
22
+
23
+ WHY THE ORCHESTRATOR CALLS THIS AND NOT THE SHELL (V3). The obvious
24
+ alternative -- a post-pipeline stage each shell invokes, mirroring
25
+ output_writer.py's "writing files is the CALLER's decision" -- is exactly
26
+ the shape that produced this project's live asymmetry: write_run_artifacts
27
+ has one production call site, so /research in the TUI wrote no output
28
+ directory at all. The consent OBJECT still comes from the shell, because
29
+ only a shell knows how to reach a human; the decision to run does not.
30
+
31
+ WHY THE REPORT IS REGENERATED RATHER THAN EDITED (V2). final_report was
32
+ synthesised FROM the claims. Correcting a claim and leaving the report
33
+ alone gives one run two artifacts that contradict each other, which is
34
+ worse than either error alone for a harness whose output is meant to be
35
+ auditable. So corrections land on claims and the report is re-synthesised
36
+ from the corrected set -- by the orchestrator, which owns pass
37
+ sequencing. The re-synthesised report is NOT re-reviewed; that regress is
38
+ cut deliberately and a later reader should not "fix" it.
39
+ """
40
+
41
+ from __future__ import annotations
42
+
43
+ import logging
44
+
45
+ import config
46
+ from core import interaction
47
+ # §23: the decision vocabulary lives in core.interaction, beside the decoder
48
+ # that validates it. Imported under the names this module and its tests
49
+ # already use -- two spellings of the same four strings is how a decoder and
50
+ # its caller come to disagree about what "refine" is.
51
+ from core.interaction import ACCEPT, REJECT, REFINE, REJECT_ALL
52
+ from core.reasoning.json_retry import parse_json_response, retry_until_json
53
+ from storage import THREAD_KIND_SUBAGENT
54
+
55
+ logger = logging.getLogger(__name__)
56
+
57
+ REVIEWER_AGENT = "pipeline-reviewer"
58
+
59
+ VALID_KINDS = {"text", "tier", "synthesis"}
60
+ VALID_TIERS = {"HIGH", "MEDIUM", "LOW", "UNVERIFIED"}
61
+
62
+
63
+ # ===========================================================================
64
+ # ---- Stage 1: ask the reviewer --------------------------------------------
65
+ # ===========================================================================
66
+
67
+ def _review_input(run) -> str:
68
+ """What the reviewer sees.
69
+
70
+ §20's one-line spec said `run.trace`. Trace alone cannot support
71
+ correction -- it is process log lines ("Pass 2: extracted 14 claim(s)")
72
+ describing what happened, not what was concluded. Reviewing CONTENT
73
+ needs the claims, their tiers and the report.
74
+
75
+ Still distilled, not raw: these are the pipeline's own outputs, the
76
+ same artifacts a human reads. No per-pass conversation thread is
77
+ shared, so the "distill, don't share raw history" principle holds.
78
+ """
79
+ import json
80
+
81
+ claims = [
82
+ {
83
+ "id": c.id,
84
+ "text": c.final_text or c.text,
85
+ "type": c.type,
86
+ "confidence_tier": c.confidence_tier,
87
+ "grounding_status": c.grounding_status,
88
+ "grounding_sources": c.grounding_sources,
89
+ "score_breakdown": c.score_breakdown,
90
+ "assumption_flags": c.assumption_flags,
91
+ }
92
+ for c in run.claims
93
+ ]
94
+ return (
95
+ f"Original query:\n{run.user_query}\n\n"
96
+ f"Final annotated claims:\n{json.dumps(claims, indent=2)}\n\n"
97
+ f"Coverage gaps:\n{json.dumps(run.coverage_gaps)}\n\n"
98
+ f"Final report:\n{run.final_report}\n\n"
99
+ f"Pipeline trace:\n" + "\n".join(f"- {line}" for line in run.trace)
100
+ )
101
+
102
+
103
+ def run_review(run, model: str, provider_name: str, authorization=None,
104
+ effort: str | None = None):
105
+ """Runs the reviewer agent over the finished run. Returns
106
+ (findings, thread_id) -- the thread_id is what a refinement re-enters.
107
+
108
+ The reviewer inherits the run's RunAuthorization unchanged (V7): the
109
+ same grants, the same provider, and the same GrantBudget INSTANCE, so
110
+ its tool calls spend from the ceiling the launcher set rather than a
111
+ fresh one. An unauthorised run gives it no tools and it reviews what
112
+ it was handed; that is a weaker review, not a broken one.
113
+
114
+ Batch 25 (#139): effort joins the inheritance -- V7's rule applied to
115
+ one more axis. The reviewer thinks at the depth the run was launched
116
+ with, not at the parameter's silent default.
117
+ """
118
+ from agents.manager import manager
119
+ from core.loop import RunAgentLoop, DEFAULT_SYSTEM_PROMPT
120
+
121
+ agent = manager.get(REVIEWER_AGENT)
122
+ if agent is None:
123
+ # Not fatal. A missing builtin means a broken install or a
124
+ # discovery failure, and losing a completed ten-pass run over the
125
+ # absence of an optional stage would be the wrong trade.
126
+ logger.warning(
127
+ "Review skipped: agent %r was not discovered.", REVIEWER_AGENT)
128
+ run.log(f"Review: skipped -- agent {REVIEWER_AGENT!r} not found.")
129
+ return [], None
130
+
131
+ context = manager.active_context(agent)
132
+ # The context suppresses both catalogs here, because this agent's
133
+ # allowed_tools excludes load_skill and spawn_subagent -- but the rule
134
+ # lives in with_catalogs, not in this call (review f19, generalised).
135
+ #
136
+ # The authorization is passed anyway (#68). It changes nothing for
137
+ # the reviewer AS SHIPPED, since the context already excludes both
138
+ # tools -- and that is exactly why it is here: the day somebody
139
+ # widens pipeline-reviewer's allowed_tools, this call should not be
140
+ # the one place that quietly goes back to advertising a headless
141
+ # run's uncallable tools.
142
+ prompt = _reviewer_prompt(authorization, agent=agent, context=context)
143
+ try:
144
+ response = RunAgentLoop.run_agent_conversation(
145
+ user_goal=_review_input(run),
146
+ model=model,
147
+ provider_name=provider_name,
148
+ max_steps=agent.max_steps or config.MAX_ITERATIONS,
149
+ context=context,
150
+ system_prompt=prompt,
151
+ authorization=authorization,
152
+ effort=effort,
153
+ # §27 AC1. The reviewer IS a subagent -- §20 calls it one and it
154
+ # runs through the same entry point -- so its thread is labelled
155
+ # like one rather than getting a fourth kind of its own.
156
+ thread_kind=THREAD_KIND_SUBAGENT,
157
+ )
158
+ _record_granted_calls(run, response, authorization)
159
+
160
+ text = retry_until_json(
161
+ response,
162
+ label="Review",
163
+ system_prompt=prompt,
164
+ model=model,
165
+ provider_name=provider_name,
166
+ trace=run.trace,
167
+ authorization=authorization,
168
+ on_response=lambda r: _record_granted_calls(run, r, authorization),
169
+ context=context,
170
+ effort=effort,
171
+ )
172
+ except Exception as e:
173
+ # A transient reviewer failure (provider error, unrecoverable
174
+ # JSON) must not cost a completed ten-pass run: the stage is
175
+ # optional, the same trade the missing-agent branch above makes.
176
+ # The run finishes with status='complete' and a traced skip.
177
+ logger.exception("Review call failed; skipping the review.")
178
+ run.log(f"Review: skipped -- reviewer call failed ({e}).")
179
+ return [], None
180
+ findings = _validated(parse_json_response(text), run)
181
+
182
+ if len(findings) > config.MAX_REVIEW_FINDINGS:
183
+ # TRACED, never silent. A truncation nobody is told about reads as
184
+ # "the reviewer found twenty-five things", which is a different
185
+ # claim from "it found sixty and you saw the worst twenty-five".
186
+ run.log(
187
+ f"Review: {len(findings)} finding(s) returned, showing the first "
188
+ f"{config.MAX_REVIEW_FINDINGS} (config.MAX_REVIEW_FINDINGS).")
189
+ findings = findings[:config.MAX_REVIEW_FINDINGS]
190
+
191
+ return findings, response.thread_id
192
+
193
+
194
+ def _record_granted_calls(run, response, authorization) -> None:
195
+ """The reviewer's granted calls join the run's audit trail.
196
+
197
+ Same list, by reference, as every pass writes to -- §25 keeps ONE
198
+ list precisely so a call cannot be authorised in one place and
199
+ recorded in another.
200
+ """
201
+ if authorization is None:
202
+ return
203
+ for call in getattr(response, "granted_calls", ()) or ():
204
+ authorization.granted_calls.append({"pass": "Review", **call})
205
+
206
+
207
+ def _validated(raw, run) -> list:
208
+ """Drops findings that could not be applied, before a human is asked
209
+ about them.
210
+
211
+ A finding naming a claim that does not exist, or a tier that is not a
212
+ tier, cannot become a correction -- so putting it to the user would
213
+ solicit consent for something that then silently does nothing. Better
214
+ to never show it. Dropping is traced for the same reason truncation
215
+ is.
216
+ """
217
+ if not isinstance(raw, list):
218
+ run.log(f"Review: expected a JSON array of findings, got "
219
+ f"{type(raw).__name__}; treating as no findings.")
220
+ return []
221
+
222
+ known = {c.id for c in run.claims}
223
+ # TWO counters, because they are two different things to know. A
224
+ # duplicate is neither malformed nor unresolvable -- it is a
225
+ # well-formed finding the reviewer raised twice -- and one number
226
+ # covering both causes tells the reader neither.
227
+ out, dropped, duplicates = [], 0, 0
228
+ seen_targets = set()
229
+ for item in raw:
230
+ if not isinstance(item, dict):
231
+ dropped += 1
232
+ continue
233
+ kind = item.get("kind")
234
+ claim_id = item.get("claim_id")
235
+ proposed = item.get("proposed")
236
+ # Type guards BEFORE the membership tests: a JSON list/dict in
237
+ # kind or claim_id is unhashable and would raise TypeError here,
238
+ # escaping into the pipeline's failure path for a shape this
239
+ # function exists to drop (review r2-2).
240
+ if not isinstance(kind, str) or kind not in VALID_KINDS:
241
+ dropped += 1
242
+ continue
243
+ if not isinstance(proposed, str) or not proposed:
244
+ dropped += 1
245
+ continue
246
+ if kind == "synthesis":
247
+ # #85: the dedupe guard used to be unreachable for synthesis
248
+ # findings -- there is no claim to overwrite, so the early
249
+ # return predates it. Being asked once per COPY is a different
250
+ # cost from being overwritten, and it is the one the human
251
+ # pays: walk_consent asks per finding, the re-synthesis prompt
252
+ # repeats each directive, and 07_review.json records each
253
+ # decision. Identical proposals are one finding raised
254
+ # several times: key on the normalised text and keep the
255
+ # first. Distinct proposals stay distinct -- two different
256
+ # report-level notes are two reviewers' worth of instruction,
257
+ # not duplicates (D1/D2).
258
+ key = (None, "synthesis", proposed.strip())
259
+ if key in seen_targets:
260
+ duplicates += 1
261
+ continue
262
+ if claim_id is not None:
263
+ # D3(b): a synthesis correction has no target claim, so a
264
+ # stray claim_id would have _describe attribute a
265
+ # report-level note to a claim in the trace and
266
+ # 07_review.json. The FINDING survives; only the lying
267
+ # key goes, and the strip is traced (#49's rule).
268
+ item = dict(item)
269
+ item.pop("claim_id", None)
270
+ run.log(f"Review: ignored claim_id {claim_id!r} on a "
271
+ f"synthesis finding -- report-level corrections "
272
+ f"have no target.")
273
+ seen_targets.add(key)
274
+ out.append(item)
275
+ continue
276
+ if not isinstance(claim_id, str) or claim_id not in known:
277
+ dropped += 1
278
+ continue
279
+ if kind == "tier" and proposed not in VALID_TIERS:
280
+ dropped += 1
281
+ continue
282
+ # Two corrections to the same claim+kind: applying both would let
283
+ # the last silently overwrite the first while the record says
284
+ # both applied. Keep the first (the reviewer orders by severity,
285
+ # most serious first) and drop the rest, traced (review r1-3).
286
+ if (claim_id, kind) in seen_targets:
287
+ duplicates += 1
288
+ continue
289
+ seen_targets.add((claim_id, kind))
290
+ out.append(item)
291
+
292
+ if duplicates:
293
+ # #85: "claim and kind" became "target" -- for a synthesis
294
+ # duplicate there is no claim, and the old sentence was false
295
+ # twice over on that branch.
296
+ run.log(f"Review: dropped {duplicates} duplicate finding(s) "
297
+ f"(same target as an earlier, higher-severity one).")
298
+ if dropped:
299
+ run.log(f"Review: dropped {dropped} malformed or unresolvable "
300
+ f"finding(s) before asking.")
301
+ return out
302
+
303
+
304
+ # ===========================================================================
305
+ # ---- Stage 2: put each finding to the human -------------------------------
306
+ # ===========================================================================
307
+
308
+ def walk_consent(findings, consent, run, *, model=None, provider_name=None,
309
+ thread_id=None, authorization=None,
310
+ effort: str | None = None) -> list:
311
+ """Returns one decision record per finding, in the order asked.
312
+
313
+ `consent` is a core.interaction.ResponseChannel (§23) -- it was a
314
+ ReviewConsent with its own `decide` callable until the two collapsed.
315
+
316
+ V6 -- consent is None means nobody can be asked, and every finding is
317
+ recorded as rejected without a prompt. This is the property that keeps
318
+ a MUTATING stage from widening the security stance: a piped CLI, a
319
+ cron job or any shell that cannot reach a human gets the findings and
320
+ an unmodified report. The inability to ask is not permission to
321
+ proceed, which is the same rule §25 applies to gated tools.
322
+ """
323
+ if consent is None:
324
+ if findings:
325
+ run.log(f"Review: {len(findings)} finding(s) recorded; nothing "
326
+ f"applied (no consent route -- V6).")
327
+ return [dict(f, decision=REJECT, reason_declined="no consent route")
328
+ for f in findings]
329
+
330
+ decisions, stopped = [], False
331
+ for finding in findings:
332
+ if stopped:
333
+ decisions.append(dict(finding, decision=REJECT,
334
+ reason_declined="declined with the rest"))
335
+ continue
336
+ decision, current = _decide_one(
337
+ finding, consent, run, model=model, provider_name=provider_name,
338
+ thread_id=thread_id, authorization=authorization, effort=effort)
339
+ if decision == REJECT_ALL:
340
+ stopped = True
341
+ decisions.append(dict(current, decision=REJECT,
342
+ reason_declined="declined with the rest"))
343
+ continue
344
+ decisions.append(dict(current, decision=decision))
345
+ return decisions
346
+
347
+
348
+ def _decide_one(finding, consent, run, *, model, provider_name, thread_id,
349
+ authorization, effort: str | None = None):
350
+ """One finding through however many refinement rounds it takes.
351
+
352
+ Returns (decision, finding) where finding is the LAST version shown --
353
+ a refined proposal is what the user accepted, so it is what must be
354
+ applied and what must be recorded.
355
+ """
356
+ current = finding
357
+ refinements = []
358
+ for round_index in range(config.MAX_REVIEW_REFINEMENTS + 1):
359
+ decision, notes = _ask(consent, current, round_index)
360
+ if decision != REFINE:
361
+ return decision, dict(current, refinements=refinements)
362
+ if round_index >= config.MAX_REVIEW_REFINEMENTS:
363
+ # The final ask may still be answered refine, but there is no
364
+ # send-back left: exactly MAX refinements for MAX+1 asks. The
365
+ # pre-fix loop spent one more model call (and possibly grant)
366
+ # on a revision no consent round ever displayed (review f2).
367
+ break
368
+ if thread_id is None or model is None:
369
+ # Nothing to re-enter. Treat as a rejection rather than
370
+ # silently applying an unrefined proposal the user asked to
371
+ # change -- "make this better" is not "apply this".
372
+ run.log("Review: refinement requested but the reviewer thread "
373
+ "is unavailable; recorded as rejected.")
374
+ return REJECT, dict(current, refinements=refinements)
375
+ refined = _refine(current, notes, run, model=model,
376
+ provider_name=provider_name, thread_id=thread_id,
377
+ authorization=authorization, effort=effort)
378
+ if refined is None:
379
+ run.log("Review: refinement produced no revised finding; "
380
+ "recorded as rejected.")
381
+ return REJECT, dict(current, refinements=refinements)
382
+ # The consent PROCESS is part of the audit record (review r4-2):
383
+ # notes and superseded proposals live only here until now.
384
+ refinements.append({"round": round_index, "note": notes,
385
+ "superseded": current})
386
+ run.log(f"Review: refinement round {round_index + 1} of "
387
+ f"{config.MAX_REVIEW_REFINEMENTS}: note={notes!r}")
388
+ current = refined
389
+ run.log(f"Review: refinement limit "
390
+ f"({config.MAX_REVIEW_REFINEMENTS}) reached; recorded as rejected.")
391
+ return REJECT, dict(current, refinements=refinements)
392
+
393
+
394
+ def _ask(consent, finding, round_index):
395
+ """Put one finding to the human and return (decision, notes).
396
+
397
+ §23: the normalising this used to do itself now lives in
398
+ core.interaction.decode, which every kind of question funnels through.
399
+ That matters here more than anywhere else -- this is the only request
400
+ whose permissive failure APPLIES an edit rather than declining one, and
401
+ it previously had a SECOND decoder in tui/app.py that disagreed with
402
+ this one about whether a bare "accept" string counted. It did here and
403
+ did not there; neither behaviour was tested, and the strict rule won.
404
+
405
+ A shell that returns None, raises, or is torn down mid-prompt still
406
+ reads as a rejection. That is now a property of the module rather than
407
+ a try/except each caller remembers.
408
+ """
409
+ return interaction.ask(consent, interaction.Request(
410
+ kind=interaction.REVIEW,
411
+ payload={"finding": finding, "round": round_index},
412
+ ))
413
+
414
+
415
+ def _refine(finding, notes, run, *, model, provider_name, thread_id,
416
+ authorization, effort: str | None = None):
417
+ """Sends one finding back into the reviewer's OWN thread (V5).
418
+
419
+ The thread continuation is the point: the reviewer sees its own
420
+ wording, the objection to it, and anything already rejected. A fresh
421
+ stateless call would lose why it proposed what it did, so a note like
422
+ "you missed that the source is dated 2019" can come back as the same
423
+ error from another angle.
424
+
425
+ Scoped to this finding. A note about #3 must not silently redraft #7 --
426
+ the user consented to reconsidering one thing.
427
+ """
428
+ import json
429
+
430
+ from agents.manager import manager
431
+ from core.loop import RunAgentLoop
432
+
433
+ agent = manager.get(REVIEWER_AGENT)
434
+ context = manager.active_context(agent) if agent is not None else None
435
+ message = (
436
+ f"The reviewer's finding below was NOT accepted. The human "
437
+ f"reviewing it said:\n\n{notes or '(no note given)'}\n\n"
438
+ f"Finding under discussion:\n{json.dumps(finding, indent=2)}\n\n"
439
+ f"Take the note as fact -- they have context you do not. Revise "
440
+ f"THIS finding only and respond with a JSON array containing just "
441
+ f"the revised finding, in the same shape. If the note convinces "
442
+ f"you the finding was wrong, respond with an empty array."
443
+ )
444
+ try:
445
+ response = RunAgentLoop.continue_conversation(
446
+ thread_id=thread_id,
447
+ message=message,
448
+ system_prompt=_reviewer_prompt(authorization),
449
+ model=model,
450
+ provider_name=provider_name,
451
+ authorization=authorization,
452
+ context=context,
453
+ effort=effort,
454
+ )
455
+ _record_granted_calls(run, response, authorization)
456
+ # Same recovery as the first reviewer call: a prose-wrapped
457
+ # revision gets the corrective follow-up instead of permanently
458
+ # rejecting the engaged finding (review f5).
459
+ text = retry_until_json(
460
+ response,
461
+ label="Review",
462
+ system_prompt=_reviewer_prompt(authorization),
463
+ model=model,
464
+ provider_name=provider_name,
465
+ trace=run.trace,
466
+ authorization=authorization,
467
+ on_response=lambda r: _record_granted_calls(run, r, authorization),
468
+ context=context,
469
+ effort=effort,
470
+ )
471
+ revised = _validated(parse_json_response(text), run)
472
+ except Exception as e:
473
+ # A refinement failing must not take down a run that has already
474
+ # produced ten passes of output.
475
+ logger.exception("Review refinement failed")
476
+ run.log(f"Review: refinement call failed ({e}).")
477
+ return None
478
+ if revised and (revised[0].get("kind") != finding.get("kind")
479
+ or revised[0].get("claim_id") != finding.get("claim_id")):
480
+ # V5 scope, kept in code: a revision that re-targets another
481
+ # claim is dropped, not carried into the next consent round.
482
+ run.log("Review: refinement re-targeted a different finding; "
483
+ "dropped.")
484
+ return None
485
+ return revised[0] if revised else None
486
+
487
+
488
+ def _reviewer_prompt(authorization=None, agent=None, context=None) -> str:
489
+ from agents.manager import manager
490
+ from core.loop import DEFAULT_SYSTEM_PROMPT, advertisement_facts
491
+
492
+ if agent is None:
493
+ agent = manager.get(REVIEWER_AGENT)
494
+ # The SAME context run_review built, so a refinement continues under
495
+ # the prompt its own first turn ran under -- and since #68 the same
496
+ # authorization too, for the same reason: a refinement that saw a
497
+ # different catalog than the finding it is revising would be
498
+ # arguing under different terms.
499
+ if context is None:
500
+ context = manager.active_context(agent)
501
+ callable_only, granted = advertisement_facts(authorization)
502
+ return manager.system_prompt_for(
503
+ agent, DEFAULT_SYSTEM_PROMPT, context=context,
504
+ callable_only=callable_only, granted=granted)
505
+
506
+
507
+ # ===========================================================================
508
+ # ---- Stage 3: apply what was accepted -------------------------------------
509
+ # ===========================================================================
510
+
511
+ def apply_deferred(run, decisions):
512
+ """Applies every accepted decision to a deep COPY of the claims.
513
+
514
+ The copy is the whole point, and a direct-mutation version of this
515
+ function is the thing not to reintroduce however much simpler it
516
+ looks. V2's contradiction lives at the ORDERING level (review f4): the
517
+ orchestrator re-synthesises from the corrected set and commits claims
518
+ + report only after the synthesis succeeds. Applying to the live run
519
+ first meant a failed re-synthesis persisted corrected claims beside
520
+ the stale report -- one run, two contradicting artifacts, durable.
521
+
522
+ Returns (changed, corrected_claims, applied_decisions). Nothing is
523
+ logged here: the "accepted and applied" lines must not precede the
524
+ commit, so the caller logs via log_outcomes() after success.
525
+ """
526
+ import copy
527
+
528
+ corrected = [copy.deepcopy(c) for c in run.claims]
529
+ by_id = {c.id: c for c in corrected}
530
+
531
+ class _View:
532
+ @staticmethod
533
+ def claim_by_id(claim_id):
534
+ return by_id.get(claim_id)
535
+
536
+ changed = False
537
+ applied = []
538
+ for decision in decisions:
539
+ if decision.get("decision") != ACCEPT:
540
+ continue
541
+ if _apply_one(_View, decision):
542
+ changed = True
543
+ applied.append(decision)
544
+ return changed, corrected, applied
545
+
546
+
547
+ def log_outcomes(run, decisions, applied, *, committed: bool) -> None:
548
+ """Trace the consent outcomes. 'accepted and applied' is only said
549
+ for decisions in `applied` when `committed` -- a re-synthesis failure
550
+ must not leave applied-lines beside unmodified claims."""
551
+ for decision in decisions:
552
+ if decision.get("decision") != ACCEPT:
553
+ run.log(f"Review: {_describe(decision)} -- declined.")
554
+ elif committed and decision in applied:
555
+ run.log(f"Review: {_describe(decision)} -- accepted and applied.")
556
+ else:
557
+ run.log(f"Review: {_describe(decision)} -- accepted but no "
558
+ f"longer applicable; skipped.")
559
+
560
+
561
+ def _apply_one(run, decision) -> bool:
562
+ kind = decision.get("kind")
563
+ if kind == "synthesis":
564
+ # Changes no claim. It becomes a directive the report is
565
+ # regenerated under, which is how a "the prose overstates this"
566
+ # finding gets fixed without letting a model rewrite the report
567
+ # directly.
568
+ return True
569
+
570
+ claim = run.claim_by_id(decision.get("claim_id"))
571
+ if claim is None:
572
+ return False
573
+
574
+ if kind == "text":
575
+ # No-op guard: an equal-value "correction" is not a change, and
576
+ # counting it as applied would spend a re-synthesis on an
577
+ # unchanged claim set and overstate the audit trail (review r4-1).
578
+ if claim.final_text == decision["proposed"]:
579
+ return False
580
+ claim.final_text = decision["proposed"]
581
+ return True
582
+
583
+ if kind == "tier":
584
+ if claim.confidence_tier == decision["proposed"]:
585
+ return False
586
+ claim.confidence_tier = decision["proposed"]
587
+ # The old tier's tag would otherwise contradict the corrected
588
+ # tier inside the re-synthesis input and in every vars(c) dump
589
+ # (02_claims.json, claims_json) -- the same stale-field class the
590
+ # review_override marker below was added for, one field over
591
+ # (review r3-1).
592
+ claim.annotation = f"[{decision['proposed']}]"
593
+ # Pass 5's breakdown was computed from grounding and critic data
594
+ # that the review did not change, so it still describes the OLD
595
+ # tier. Without this marker 05_confidence.json shows a 0.91
596
+ # raw_score beside a reviewer-downgraded LOW and reads as a bug in
597
+ # the scoring formula. score_breakdown is already a dict, so this
598
+ # adds no field to Claim and triggers no vars(c) migration (V8).
599
+ claim.score_breakdown = dict(claim.score_breakdown or {})
600
+ claim.score_breakdown["review_override"] = decision["proposed"]
601
+ return True
602
+
603
+ return False
604
+
605
+
606
+ def _describe(decision) -> str:
607
+ kind = decision.get("kind")
608
+ target = decision.get("claim_id") or "report"
609
+ return f"{kind} correction to {target}"
610
+
611
+
612
+ def synthesis_directives(decisions) -> list:
613
+ """The accepted synthesis findings, as instructions for the re-run."""
614
+ return [d["proposed"] for d in decisions
615
+ if d.get("decision") == ACCEPT and d.get("kind") == "synthesis"]