@yahyahammad/venastine 0.2.0 → 0.3.8

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