@yahyahammad/venastine 0.2.0 → 0.3.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (152) hide show
  1. package/.env.example +9 -4
  2. package/CONFIG_ARCHITECTURE.md +2030 -0
  3. package/LICENSE +201 -201
  4. package/NOTICE +1 -1
  5. package/README.md +1034 -895
  6. package/agents/builtin/build.md +73 -0
  7. package/agents/builtin/compactor.md +75 -75
  8. package/agents/builtin/explore.md +77 -77
  9. package/agents/builtin/general.md +80 -0
  10. package/agents/builtin/pipeline-reviewer.md +100 -100
  11. package/agents/builtin/plan.md +106 -88
  12. package/agents/builtin/review.md +74 -74
  13. package/agents/builtin/test.md +65 -0
  14. package/agents/builtin/writer.md +67 -0
  15. package/agents/manager.py +68 -2
  16. package/agents/subagent_tool.py +472 -238
  17. package/agents/tui_commands.py +238 -151
  18. package/bin/venastine.mjs +150 -4
  19. package/bin/venastine.py +71 -0
  20. package/cli_commands.py +838 -0
  21. package/config.py +95 -1198
  22. package/config.yaml +1103 -0
  23. package/config_edit.py +1301 -0
  24. package/config_schema.py +971 -0
  25. package/config_update.py +749 -0
  26. package/core/agent_activity.py +256 -118
  27. package/core/ansi.py +452 -0
  28. package/core/approval.py +137 -115
  29. package/core/call_view.py +364 -0
  30. package/core/cancel.py +121 -0
  31. package/core/chatgpt_auth.py +747 -0
  32. package/core/claims_view.py +107 -0
  33. package/core/client.py +2715 -1559
  34. package/core/commands.py +460 -0
  35. package/core/compaction.py +1735 -971
  36. package/core/config_loader.py +1982 -1563
  37. package/core/connect.py +686 -0
  38. package/core/events.py +123 -61
  39. package/core/file_mentions.py +280 -0
  40. package/core/interaction.py +411 -328
  41. package/core/line_pattern.py +128 -0
  42. package/core/loop.py +2566 -1490
  43. package/core/memory.py +482 -370
  44. package/core/pipeline_models.py +190 -176
  45. package/core/provider_errors.py +234 -0
  46. package/core/reasoning/authorization.py +130 -130
  47. package/core/reasoning/base.py +219 -219
  48. package/core/reasoning/confidence_scoring.py +484 -468
  49. package/core/reasoning/events.py +149 -149
  50. package/core/reasoning/json_retry.py +19 -1
  51. package/core/reasoning/orchestrator.py +1561 -1382
  52. package/core/reasoning/output_writer.py +345 -286
  53. package/core/reasoning/payload_validation.py +524 -398
  54. package/core/reasoning/pipeline_storage.py +88 -22
  55. package/core/reasoning/review.py +659 -615
  56. package/core/reasoning/scholar.py +458 -434
  57. package/core/reasoning/source_corpus.py +433 -327
  58. package/core/reasoning/source_scoring.py +855 -855
  59. package/core/replay.py +315 -183
  60. package/core/session.py +36 -12
  61. package/core/session_view.py +259 -0
  62. package/core/session_wake.py +259 -0
  63. package/core/shell_sessions.py +1553 -0
  64. package/core/workspace_trust.py +1 -1
  65. package/credentials.py +148 -20
  66. package/database.py +333 -252
  67. package/{PRIVACY.md → docs/PRIVACY.md} +78 -66
  68. package/docs/SECURITY.md +108 -0
  69. package/docs/THIRD_PARTY_NOTICES.md +148 -0
  70. package/env_secrets.py +50 -9
  71. package/json_store.py +343 -123
  72. package/logging_setup.py +295 -185
  73. package/main.py +3433 -1961
  74. package/mcp_client/client.py +733 -499
  75. package/mcp_client/config.py +126 -21
  76. package/mcp_client/registration.py +343 -182
  77. package/memories/manager.py +147 -132
  78. package/memories/tui_commands.py +319 -244
  79. package/package.json +303 -73
  80. package/project_init/config_files.py +282 -278
  81. package/project_init/generator.py +728 -564
  82. package/project_init/manifest.py +18 -6
  83. package/project_init/tui_commands.py +147 -144
  84. package/prompts/critic_pass.md +24 -24
  85. package/prompts/revalidate.md +25 -25
  86. package/prompts/revise.md +2 -0
  87. package/prompts/source_grounding.md +66 -66
  88. package/prompts/system_prompts.py +316 -262
  89. package/providers.json.example +4 -2
  90. package/pyproject.toml +149 -100
  91. package/requirements.txt +295 -72
  92. package/safety/policy_enforcement.py +1082 -746
  93. package/security/askpass.py +419 -0
  94. package/security/capability.py +207 -177
  95. package/security/confine.py +484 -0
  96. package/security/hosted.py +182 -0
  97. package/security/permissions.py +237 -190
  98. package/security/posture.py +124 -12
  99. package/security/protected_paths.py +501 -309
  100. package/security/sandbox.py +4108 -985
  101. package/security/secrets.py +855 -0
  102. package/skills/builtin/math/formal-specification.md +67 -67
  103. package/skills/builtin/math/numerical-methods.md +66 -66
  104. package/skills/builtin/research/experiment-design.md +62 -62
  105. package/skills/builtin/research/reproducibility.md +55 -55
  106. package/skills/builtin/research/source-evaluation.md +70 -70
  107. package/skills/builtin/research/statistical-inference.md +63 -63
  108. package/skills/builtin/research/technical-writing.md +59 -59
  109. package/skills/builtin/software/code-review.md +61 -61
  110. package/skills/builtin/software/debugging.md +61 -61
  111. package/skills/builtin/software/test-design.md +67 -67
  112. package/skills/tui_commands.py +110 -111
  113. package/storage.py +1338 -1005
  114. package/tools/base.py +161 -1
  115. package/tools/builtin/_math_common.py +667 -377
  116. package/tools/builtin/_net_common.py +225 -19
  117. package/tools/builtin/arxiv.py +497 -39
  118. package/tools/builtin/ask_user.py +231 -213
  119. package/tools/builtin/discrete_math.py +35 -4
  120. package/tools/builtin/fetch_url.py +371 -153
  121. package/tools/builtin/file_ops.py +720 -412
  122. package/tools/builtin/geometry.py +48 -12
  123. package/tools/builtin/get_time.py +2 -2
  124. package/tools/builtin/linear_algebra.py +66 -23
  125. package/tools/builtin/load_skill.py +76 -66
  126. package/tools/builtin/logic.py +171 -12
  127. package/tools/builtin/pin.py +227 -193
  128. package/tools/builtin/probability_stats.py +12 -16
  129. package/tools/builtin/project_docs.py +464 -405
  130. package/tools/builtin/remember.py +175 -158
  131. package/tools/builtin/shell.py +980 -461
  132. package/tools/builtin/shell_sessions.py +613 -0
  133. package/tools/builtin/symbolic_math.py +80 -10
  134. package/tools/builtin/todo.py +149 -147
  135. package/tools/builtin/web_search.py +191 -13
  136. package/tools/context.py +159 -136
  137. package/tools/isolation.py +107 -34
  138. package/tools/registry.py +1242 -925
  139. package/tui/app.py +8318 -4100
  140. package/tui/app.tcss +747 -556
  141. package/tui/commands.py +26 -170
  142. package/tui/diffs.py +34 -13
  143. package/tui/history.py +128 -128
  144. package/tui/hosted_driver.py +102 -0
  145. package/tui/markdown.py +1329 -1279
  146. package/tui/meters.py +364 -268
  147. package/tui/ravens.py +146 -146
  148. package/tui/screens.py +1255 -943
  149. package/tui/themes.py +599 -559
  150. package/tui/widgets.py +3813 -2332
  151. package/SECURITY.md +0 -88
  152. package/THIRD_PARTY_NOTICES.md +0 -100
@@ -1,1382 +1,1561 @@
1
- """
2
- core/reasoning/orchestrator.py
3
-
4
- Sequences the deep-research pipeline: Pass 0 -> 1 -> 2 -> gate D0 -> (3a -> 3b
5
- for factual claims) -> 3c -> 4 (all claims) -> Pass 5 (code) -> D1 -> the
6
- 6a/6b/D2 retry loop -> 6c (template) -> merge -> final synthesis.
7
-
8
- SCOPE OF THIS VERSION: core sequential pipeline with optional ensemble
9
- mode (ROADMAP §10: N-candidate Pass 1 generation + cross-candidate
10
- consistency check feeding Pass 5's scoring). No filesystem output yet
11
- (returns a PipelineRun object; the /output/<run_id>/ file-writing system
12
- is a separate, later piece of work).
13
-
14
- ROADMAP §11 (critic-model routing): when a critic pair is configured,
15
- Pass 3a, 3b, and 6c (which re-runs 3a/3b logic) use the critic
16
- provider/model instead of the generator's. Every other pass keeps using
17
- the main provider_name/model. This prevents a model from checking its
18
- own output for errors with the same blind spots. §45 (SQ7) moved WHERE
19
- that pair comes from: core/pipeline_models.resolve("critic") owns the
20
- precedence -- a `/critic` choice in the user-tier store, else
21
- config.CRITIC_MODEL -- so the routing is reachable without editing the
22
- checkout, which for §11's whole life it was not.
23
-
24
- ROADMAP §3 (malformed-JSON recovery): JSON-emitting passes are wrapped in
25
- _run_pass_with_json_retry, which on a parse failure re-enters the SAME
26
- pass-thread via RunAgentLoop.continue_conversation() with a corrective
27
- follow-up message. The failed assistant turn is already in the thread's
28
- history (see _run()'s always-persist fix in core/loop.py), so the model
29
- sees its own prior output in context. Up to config.MAX_JSON_RETRIES
30
- corrective attempts are made; a final ValueError surfaces unrecoverable
31
- failures.
32
-
33
- ROADMAP §5 (durable pipeline persistence): each run is wrapped in a
34
- try/except that records status='failed' (with a snapshot of the partial
35
- run) before re-raising, so a mid-pipeline crash still leaves a durable
36
- record. A data-only update_pipeline_run() checkpoint fires after every
37
- run.log() trace line, so even a hard kill (KeyboardInterrupt / SystemExit,
38
- which bypass the except Exception block) leaves the record populated
39
- through the last completed pass. load_pipeline_run() in
40
- pipeline_storage.py provides the read API.
41
-
42
- ROADMAP_v2 §22 (pipeline observability): the pipeline is a GENERATOR
43
- yielding PipelineEvents (core/reasoning/events.py), so a shell can render
44
- pass boundaries, trace lines, claim tiers and retries as they happen
45
- rather than waiting for the whole run. Two names:
46
-
47
- stream_deep_research_pipeline() the generator
48
- run_pipeline_to_completion() the drainer, for a caller that wants
49
- only the finished PipelineRun
50
-
51
- DECISION P3 IS RETIRED, and it is worth saying why rather than quietly
52
- dropping a name. P3 kept a third, synchronous `run_deep_research_pipeline()`
53
- -- the drainer applied to the generator -- so that "every existing caller:
54
- main.py, tui/app.py and fifteen test sites" would go on working unchanged.
55
- Both shells then left of their own accord: `main.run_research` and
56
- `tui/app.py` iterate the generator so they can render progress, each with a
57
- comment saying it deliberately does not call the wrapper. That left a
58
- public function with no production caller and fifty call sites in tests,
59
- while this docstring went on naming it the live entry point. The
60
- convenience moved to `tests/conftest.run_pipeline`, which is what it had
61
- become; P3's argument was sound and its premise expired.
62
-
63
- Decision P2: a pass's own LoopEvents are NOT forwarded up as LoopEvents --
64
- _run_pass TRANSLATES a chosen subset into PipelineEvents (§26 amended this;
65
- §22 had kept a pass fully opaque). It iterates
66
- RunAgentLoop.stream_deep_research_mode() directly. `run_deep_research_mode`,
67
- the synchronous wrapper this line used to name, is gone for
68
- `run_deep_research_pipeline`'s reason and one layer down.
69
- """
70
-
71
- from __future__ import annotations
72
-
73
- import json
74
- import logging
75
-
76
- import config
77
- import prompts.system_prompts as system_prompts
78
- from core import pipeline_models
79
- from core.config_loader import effective_confidence, effective_source_scoring
80
- from core.loop import RunAgentLoop, advertisement_facts
81
- from core.reasoning.base import Claim, PipelineRun, resolve_by_id
82
- from core.reasoning.confidence_scoring import run_confidence_tiering
83
- from core.reasoning.events import PipelineEvent
84
- from core.reasoning.json_retry import parse_json_response as _parse_json_response
85
- from core.reasoning.json_retry import retry_until_json
86
- from core.reasoning.payload_validation import validate as _validate_payload
87
- from core.reasoning.pipeline_storage import create_pipeline_run, update_pipeline_run
88
- from core.reasoning.scholar import ScholarLookup
89
- from core.reasoning.source_corpus import SourceCorpus
90
- from core.reasoning.source_scoring import make_scorer, score_grounding_sources
91
- from safety.policy_enforcement import redact_secrets
92
- from tools.registry import registry
93
-
94
- logger = logging.getLogger(__name__)
95
-
96
- DEFAULT_PROVIDER = "ANTHROPIC"
97
- FLAGGED_TIERS = {"LOW", "UNVERIFIED"}
98
- MAX_RETRIES = config.MAX_PIPELINE_RETRIES
99
- # The JSON-retry budget lives in core/reasoning/json_retry.py since the
100
- # §20 extraction; a second constant here was a dead knob that invited
101
- # no-op patches (review §19-20 f9).
102
-
103
- _CLAIM_INPUT_FIELDS = {"id", "text", "type", "entities", "source_span", "asserted_by_candidates"}
104
-
105
-
106
- # ============================================================================
107
- # ---- Small helpers ----------------------------------------------------------
108
- # ============================================================================
109
-
110
- class _Progress:
111
- """The ONE place a trace line becomes durable and becomes an event
112
- (§22 AC3).
113
-
114
- Before §22 this file paired every `run.log(...)` with an
115
- `update_pipeline_run(...)` at twenty call sites, and `run.trace` had
116
- THREE writers: those, review.py's fifteen `run.log()` calls (which
117
- checkpointed nowhere), and json_retry.py's bare `trace.append()` per
118
- failed parse. So "§5's persistence fires on every trace line" was
119
- already untrue, and adding a per-call-site event emission would have
120
- made it two independent writers of related data -- the bug shape §22
121
- warns about by name.
122
-
123
- So both are DERIVED from `run.trace` itself. `checkpoint()` emits
124
- every line appended since it last ran and then persists. Because the
125
- watermark reads the list rather than the call site, review.py's and
126
- json_retry.py's lines are picked up too, WITHOUT either module being
127
- edited or knowing this exists.
128
-
129
- The watermark lives here rather than on PipelineRun because base.py
130
- is data only and §5 serializes that object -- a field meaningful
131
- only inside a live generator has no business in a persisted row.
132
- """
133
-
134
- def __init__(self, run: PipelineRun) -> None:
135
- self.run = run
136
- self._emitted = 0
137
-
138
- def checkpoint(self, message: str | None = None):
139
- """Log (optionally), PERSIST, then emit every un-emitted line.
140
-
141
- Persist BEFORE emitting, not after. A generator only advances
142
- while someone iterates it, so a consumer that abandons the run
143
- between the yield and the persist would take that checkpoint down
144
- with it -- §5's durability would silently start depending on a
145
- UI's willingness to keep reading. This way, a line is already in
146
- the record by the time anyone is told about it.
147
-
148
- Monotonic: `_emitted` only ever advances, so no line can be
149
- yielded twice however many times this is called.
150
- """
151
- if message is not None:
152
- self.run.log(message)
153
- update_pipeline_run(self.run.run_id, self.run)
154
- while self._emitted < len(self.run.trace):
155
- line = self.run.trace[self._emitted]
156
- self._emitted += 1
157
- yield PipelineEvent(kind="trace_line", text=line)
158
-
159
-
160
- # One pass_activity event per this many characters streamed. A per-token
161
- # event would be thousands of post_message hand-offs per pass, which is the
162
- # cost Transcript.stream_delta already exists to avoid on the chat path.
163
- _ACTIVITY_CHARS = 2000
164
-
165
- # §26's _param_digest, and its two truncation constants, MOVED to
166
- # safety/policy_enforcement.py in §27 -- beside redact_secrets, because
167
- # §27's replay renderer is its second caller and the redact-before-truncate
168
- # ordering must not exist twice. Imported under its own name rather than
169
- # aliased back to the old private one: an alias would leave two spellings
170
- # for one function, and a reader who greps the old name here should be sent
171
- # to where it now lives, not handed a local rebinding.
172
-
173
-
174
- def _translate(pass_id: str, stream, corpus=None):
175
- """Turn one pass's LoopEvents into PipelineEvents, and return the
176
- ModelResponse the pass produced (ROADMAP_v2 §26).
177
-
178
- THE one place a LoopEvent becomes a PipelineEvent. Both _run_pass and
179
- _run_pass_with_json_retry consume this rather than each iterating the
180
- stream themselves -- two emission sites for the same translation is how
181
- they drift, and this file has the twenty-checkpoint version of that
182
- mistake in its own history (see _Progress).
183
-
184
- What is translated is a SUBSET, chosen for what a person watching a
185
- ten-pass run needs:
186
-
187
- tool_call / tool_result the thing §22 P2 made invisible. A pass
188
- making fourteen fetch_url calls over
189
- several minutes looked exactly like one
190
- that had hung.
191
- pass_activity for the passes that call no tools at all.
192
- Throttled: a total, every _ACTIVITY_CHARS.
193
-
194
- What is NOT translated, and why:
195
-
196
- token_delta text seven of the ten passes emit raw JSON, so
197
- streaming pass output into a transcript
198
- buries the report under it. Only the volume
199
- escapes, never the content.
200
- thinking_delta §38 (O5). Not translated AND not counted
201
- into pass_activity's running total, so
202
- `chars` keeps meaning one thing -- output
203
- streamed so far -- rather than quietly
204
- becoming two instruments the way batch 27
205
- item 9 describes for the token figures. The
206
- cost is stated rather than hidden: a pass
207
- that thinks for minutes before writing
208
- anything shows no activity, which is the
209
- shape §26 built pass_activity to cure. Flip
210
- it here if that turns up in a real run.
211
- permission_request §25's ApprovalProvider already carries this
212
- to the shell and blocks on the answer. A
213
- second rendering of a question already on
214
- screen is not observability.
215
- notice a pass's compaction notices, forwarded as
216
- trace LINES. M6 makes these backstop-only,
217
- but "rare" is not "silent" -- §21's rule
218
- has no exception for the pipeline, and a
219
- backstop fold rewrites what the REST of
220
- the pass sees. This used to drop them with
221
- the claim that they "already reach the
222
- shell as WARNING log records", which was
223
- true of blocked and failed compactions and
224
- FALSE of successful ones (INFO only --
225
- audit #172). A trace line lands in
226
- trace.md and both shells print it.
227
-
228
- §45 (SQ2). `corpus` is a SECOND SINK for tool results, not a change to
229
- what is translated. The rule above -- a successful result body never
230
- reaches the UI -- is unchanged; this is a different consumer with a
231
- different need, and the scoring stage cannot check a quote against a
232
- page nobody kept. None, the default, collects nothing: that is every
233
- caller that predates §45 and every test double."""
234
- names: dict = {} # tool_call id -> name, since tool_result has none
235
- streamed = 0
236
- announced = 0
237
- while True:
238
- # next() rather than `for event in stream`, because a for loop
239
- # SWALLOWS the generator's return value -- and the response is
240
- # returned rather than read off the terminal event precisely
241
- # because thread_id is attached after the loop finishes. A for
242
- # loop here would hand every pass a response with no thread_id,
243
- # and the only symptom would be §3's JSON retry silently starting
244
- # a new thread instead of correcting the failed one.
245
- try:
246
- event = next(stream)
247
- except StopIteration as stop:
248
- return stop.value
249
-
250
- if event.token_delta:
251
- streamed += len(event.token_delta)
252
- if streamed - announced >= _ACTIVITY_CHARS:
253
- announced = streamed
254
- yield PipelineEvent(kind="pass_activity", pass_id=pass_id,
255
- chars=streamed)
256
- if event.notice:
257
- yield PipelineEvent(
258
- kind="trace_line",
259
- text=f"compaction during {pass_id}: {event.notice['text']}")
260
- if event.tool_call_start:
261
- name = event.tool_call_start.get("name")
262
- names[event.tool_call_start.get("id")] = name
263
- yield PipelineEvent(
264
- kind="tool_call", pass_id=pass_id, tool=name,
265
- # §42 (RA3): through the registry, so a tool's
266
- # declared rationale param is dropped here too -- a
267
- # pass row is as narrow as a transcript line.
268
- text=registry.call_digest(
269
- name, event.tool_call_start.get("input")))
270
- if event.tool_result:
271
- result = event.tool_result.get("result")
272
- failed = isinstance(result, dict) and "error" in result
273
- name = names.get(event.tool_result.get("id"))
274
- if corpus is not None and not failed:
275
- # BEFORE the yield, for #42's reason one layer up: a
276
- # generator only advances while someone iterates it, so
277
- # collecting after the yield would make the corpus depend
278
- # on a consumer continuing to read. `corpus.add` ignores
279
- # every tool it does not recognise.
280
- corpus.add(name, result)
281
- yield PipelineEvent(
282
- kind="tool_result", pass_id=pass_id,
283
- tool=name,
284
- ok=not failed,
285
- # Redacted here too, though dispatch() already ran the
286
- # result through check_output_policy. One rule owned at one
287
- # boundary -- "nothing leaves this function unredacted" --
288
- # beats depending on a guarantee made two layers away that
289
- # a later refactor could quietly drop.
290
- text=redact_secrets(str(result.get("error"))) if failed else None)
291
-
292
-
293
- def _check_not_truncated(pass_id: str, response, trace: list[str] | None):
294
- """A pass that ended on a stop condition did NOT finish; say so.
295
-
296
- `_run_pass` used to return `response.text` and discard `stop_reason`,
297
- so a pass cut off by the token budget looked exactly like one that
298
- completed -- and because a budget stop returns the last response AS
299
- IT STANDS, a pass that was mid-tool-call returned the EMPTY STRING.
300
-
301
- That is not hypothetical. A Pass 1 making 14 tool calls crossed the
302
- old 250k ceiling, returned "", and the orchestrator stored it as
303
- raw_response. Pass 2 was then handed "Response to extract claims
304
- from:\\n" and correctly answered that there was nothing to extract --
305
- in a shape that is not a claim list -- and the run finally died in
306
- Claim's constructor, three passes and one confusing TypeError away
307
- from the thing that actually went wrong.
308
-
309
- TWO outcomes, because truncation is not uniformly fatal:
310
-
311
- * truncated WITH text -- degraded but usable. The pass produced an
312
- answer and was cut off finishing it; downstream passes can work
313
- with that. Traced, so the report's own audit log says the answer
314
- was incomplete, and the run continues.
315
- * truncated with NO text -- unusable. Everything downstream is
316
- working from an empty string, and the only question is how many
317
- passes it takes to produce an incomprehensible error. Raise here,
318
- naming the pass and the stop reason.
319
- """
320
- stop = getattr(response, "stop_reason", None)
321
- if stop in (None, "complete"):
322
- return
323
- text = (getattr(response, "text", "") or "").strip()
324
- # #4: the figures turn a bare reason into a diagnosis. A user who
325
- # reads token_budget_exceeded as a context problem is repeating the
326
- # exact misreading item 9 recorded.
327
- billed = getattr(response, "turn_billed_tokens", None)
328
- figures = (f" billed {billed:,} this turn"
329
- if isinstance(billed, int) else "")
330
- if not text:
331
- raise ValueError(
332
- f"{pass_id} ended on {stop!r} with no text{figures}. A stop "
333
- f"condition returns the last response as it stands, so a pass "
334
- f"cut off mid-tool-call yields an empty string -- and every "
335
- f"later pass would be working from nothing. "
336
- f"(config.MAX_ITERATIONS and a configured settings.json "
337
- f"max_token_budget spend cap are the two ceilings that "
338
- f"produce this.)"
339
- )
340
- message = (f"{pass_id}: TRUNCATED ({stop}{figures}) -- the pass was cut "
341
- f"off but produced output; continuing with what it returned.")
342
- logger.warning("%s", message)
343
- if trace is not None:
344
- trace.append(message)
345
-
346
-
347
- def _ensemble_roster(ensemble_mode: bool) -> list[dict]:
348
- """The (provider_name, model) pairs Pass 1 runs on, or [] when ensemble
349
- mode is off. Raises ValueError on a roster that cannot produce a
350
- meaningful consistency signal (ROADMAP §10 revisit, E1/E5).
351
-
352
- A separate function so every refusal is testable without running a
353
- pipeline, and so the reasons stay together: this replaces §16's
354
- sampling-parameter guard, which refused for a mechanism that no longer
355
- exists.
356
-
357
- Validated by SHAPE only -- provider names and API keys are not checked
358
- here (E6). §16's /model warns rather than refuses on an empty API_KEY so
359
- a local OpenAI-compatible endpoint stays usable, and MCP's posture is
360
- that validation happens by connecting. A candidate whose provider is
361
- unreachable is named, traced and skipped at run time instead.
362
- """
363
- if not ensemble_mode:
364
- return []
365
-
366
- roster = config.ENSEMBLE_MODELS
367
- if not roster:
368
- raise ValueError(
369
- "Ensemble mode is on but config.ENSEMBLE_MODELS is empty. "
370
- "Diversity comes from different models now, not from a raised "
371
- "temperature (ROADMAP §10 revisit), so the roster is required. "
372
- "Set it in config.py to a list of at least two distinct "
373
- '{"provider_name": ..., "model": ...} entries, or disable '
374
- "ensemble_mode. There is deliberately no settings.json key for "
375
- "the roster -- see E2."
376
- )
377
-
378
- for entry in roster:
379
- if not isinstance(entry, dict) or not entry.get("provider_name") or not entry.get("model"):
380
- raise ValueError(
381
- f"Malformed config.ENSEMBLE_MODELS entry {entry!r}: every "
382
- f'entry needs both "provider_name" and "model".'
383
- )
384
-
385
- # DISTINCT pairs, not merely two entries. Repeating one model N times
386
- # would generate N near-identical candidates -- there is no sampling
387
- # variation left to make them differ -- and then report maximal
388
- # cross-candidate consistency for every claim, which Pass 5 reads as
389
- # confidence. That is precisely the failure §16's guard was added to
390
- # prevent, and this config is the way to recreate it.
391
- distinct = {(e["provider_name"], e["model"]) for e in roster}
392
- if len(distinct) < 2:
393
- raise ValueError(
394
- f"Ensemble mode needs at least two DISTINCT models; "
395
- f"config.ENSEMBLE_MODELS resolves to {len(distinct)} "
396
- f"({sorted(distinct)}). One model cannot disagree with itself, so "
397
- f"every claim would score maximal consistency and Pass 5 would "
398
- f"read that as confidence."
399
- )
400
- return list(roster)
401
-
402
-
403
- def _pass_failed_event(pass_id: str, exc: BaseException) -> PipelineEvent:
404
- """E14/#115. The one shape a pass failure is reported in: a
405
- pass_complete carrying ok=False, mirroring tool_result's
406
- outcome-plus-reason contract. A NEW kind was considered and rejected
407
- -- tool_result already established payload-carried outcomes in this
408
- very event set, and a second mechanism for 'ended' would make every
409
- future consumer learn which applies where. The text is TRUNCATED:
410
- the trace line (run.log at whatever site caught this) carries the
411
- full cause, and an event payload is not the place to duplicate it
412
- unboundedly."""
413
- return PipelineEvent(
414
- kind="pass_complete", pass_id=pass_id, ok=False,
415
- text=f"{type(exc).__name__}: {exc}"[:200])
416
-
417
-
418
- def _run_pass(pass_id: str, pass_input: str, model: str, provider_name: str,
419
- temperature: float | None = None, authorization=None,
420
- trace: list[str] | None = None, pass_threads: list | None = None,
421
- effort: str | None = None, corpus=None):
422
- """One LLM-backed pass. Every actual model call in this file goes
423
- through this single function.
424
-
425
- §22: a GENERATOR that yields the pass boundary and returns the
426
- response text (`text = yield from _run_pass(...)`). The pass id is
427
- named once here rather than restated beside twelve call sites.
428
-
429
- §26: the pass is now ITERATED rather than called, through _translate,
430
- so what it does between its start and its end is visible. Same shape
431
- as §22's own change to the shells -- the drainer still exists and is
432
- still what every other caller uses.
433
-
434
- Batch 25 (#139): effort reaches the passes like authorization does --
435
- threaded from the shell's setting through the pipeline, validated per
436
- RECEIVING model by effort_for() inside the loop, so an ensemble roster
437
- or critic routing needs no effort-specific handling here.
438
- """
439
- yield PipelineEvent(kind="pass_start", pass_id=pass_id)
440
- try:
441
- response = yield from _translate(pass_id, RunAgentLoop.stream_deep_research_mode(
442
- pass_input=pass_input, model=model, pass_id=pass_id, provider_name=provider_name,
443
- temperature=temperature, authorization=authorization, effort=effort,
444
- ), corpus=corpus)
445
- _record_granted_calls(pass_id, response, authorization)
446
- _record_pass_thread(pass_id, response, pass_threads)
447
- _check_not_truncated(pass_id, response, trace)
448
- except Exception as exc:
449
- # E14/#115, UNIFORM: a fatal pass reports itself before its
450
- # exception propagates, so no shell is left holding a row that
451
- # only ever says "running" -- the same property the ensemble
452
- # skip path needs, reached from the one site both share.
453
- yield _pass_failed_event(pass_id, exc)
454
- raise
455
- yield PipelineEvent(kind="pass_complete", pass_id=pass_id, ok=True)
456
- return response.text
457
-
458
-
459
- def _record_pass_thread(pass_id: str, response, pass_threads) -> None:
460
- """Note which thread this pass ran in (§27 T2 / AC6).
461
-
462
- BEFORE _check_not_truncated, which can raise: the thread of a pass that
463
- died mid-tool-call is the single most useful one to be able to open, and
464
- recording after the check would lose exactly that one.
465
-
466
- `pass_threads` IS `run.pass_threads`, shared by reference for the same
467
- reason §25's granted_calls is: one object means the record is already on
468
- the run at every §5 checkpoint and on the failure path, rather than
469
- being assembled at the end by a run that reached the end.
470
-
471
- A separate optional argument rather than a `run` parameter, because
472
- `trace` beside it is a list too and _run_pass_with_json_retry takes it
473
- positionally in twelve call sites -- swapping both for the run object is
474
- a bigger change than §27 asked for. Default None keeps every test double
475
- that calls these two functions working.
476
- """
477
- if pass_threads is None:
478
- return
479
- thread_id = getattr(response, "thread_id", None)
480
- if thread_id is None:
481
- return
482
- pass_threads.append({"pass": pass_id, "thread_id": str(thread_id)})
483
-
484
-
485
- def _record_granted_calls(pass_id: str, response, authorization) -> None:
486
- """Note calls that ran on a pre-flight grant (§25 audit trail).
487
-
488
- Authorization moved up-front, so accountability moves after: this is
489
- the record of what one launch-time yes actually authorised, for a run
490
- nobody was watching.
491
-
492
- Accumulated ON THE AUTHORIZATION BUNDLE rather than in module state or
493
- a thirteenth argument. The bundle is already shared by reference across
494
- every pass -- that is how GrantBudget counts one ceiling rather than
495
- ten -- and what the authorization was spent on is authorization state.
496
- A module global would also break the moment two pipelines ran.
497
- """
498
- if authorization is None:
499
- return
500
- for call in getattr(response, "granted_calls", ()) or ():
501
- authorization.granted_calls.append({"pass": pass_id, **call})
502
-
503
-
504
- def _run_pass_with_json_retry(
505
- pass_id: str,
506
- pass_input: str,
507
- model: str,
508
- provider_name: str,
509
- trace: list[str] | None = None,
510
- temperature: float | None = None,
511
- authorization=None,
512
- pass_threads: list | None = None,
513
- claim_ids: list | None = None,
514
- ensemble: bool = False,
515
- effort: str | None = None,
516
- corpus=None,
517
- ):
518
- """Runs one JSON-emitting pass and recovers from malformed JSON.
519
-
520
- The recovery itself lives in core/reasoning/json_retry.py, shared with
521
- §20's reviewer. All this function adds is the pass's own first attempt
522
- and the two pass-specific facts the shared loop cannot know: which
523
- system prompt to continue under, and that a retry's tool calls belong
524
- on the same §25 audit trail as the original attempt's.
525
-
526
- ROADMAP §3: attempts = max_retries + 1 (1 initial +
527
- config.MAX_JSON_RETRIES corrective, per core/reasoning/json_retry.py).
528
- Unrecoverable failure raises ValueError with the final parse error
529
- attached; the caller's try/except turns that into a durable
530
- status='failed' record.
531
-
532
- §30 (B3): the payload spec is bound HERE, from the pass id, rather
533
- than passed in by each of the eight call sites. A call site that
534
- forgot the argument would be silently unvalidated, which is the exact
535
- condition this batch exists to remove -- and payload_validation.validate
536
- raises on a pass id it has no spec for, so an eleventh JSON-emitting
537
- pass cannot arrive by omission.
538
-
539
- This function still returns TEXT, deliberately, even though it now
540
- parses the payload internally to check it. Around twenty test sites
541
- patch or drain it and assert on the returned string, and §20's
542
- reviewer shares retry_until_json's contract; re-parsing a short string
543
- is cheaper than moving twenty seams in the batch that adds the check.
544
-
545
- `claim_ids` is the set the APPLY step will resolve against -- every
546
- claim for 3a/3b/5/6c, the currently-flagged batch for 6a -- because
547
- validating against a wider set would accept an entry that then lands
548
- on nothing.
549
-
550
- §22: a generator, like _run_pass, and for the same reason. The
551
- corrective attempts inside retry_until_json need no event kind of
552
- their own -- that function already appends a trace line per failed
553
- parse, so _Progress's watermark carries them to the consumer at the
554
- next checkpoint with json_retry.py untouched. pass_complete fires
555
- after the retries resolve, so a pass is not reported finished while
556
- it is still arguing with the model about JSON.
557
-
558
- §26 limit, stated rather than fixed: the FIRST attempt is translated,
559
- the retries are not. retry_until_json reaches the model through
560
- continue_conversation(), which drains its own loop internally, so a
561
- tool call made while correcting malformed JSON produces no tool_call
562
- event. Making it visible means a streaming sibling for
563
- continue_conversation too, which is chat's entry point as well -- a
564
- larger change than the thing it would show.
565
-
566
- §45 inherits that limit rather than widening it: a page fetched during
567
- a corrective retry reaches no corpus either, so a source cited only
568
- from such a fetch scores with `similarity_method: "llm"` like any
569
- other source with no captured text. It degrades to the documented
570
- fallback instead of to a wrong number, which is why the limit is
571
- stated here and not worked around.
572
- """
573
- yield PipelineEvent(kind="pass_start", pass_id=pass_id)
574
- try:
575
- response = yield from _translate(pass_id, RunAgentLoop.stream_deep_research_mode(
576
- pass_input=pass_input, model=model, pass_id=pass_id, provider_name=provider_name,
577
- temperature=temperature, authorization=authorization, effort=effort,
578
- ), corpus=corpus)
579
- _record_granted_calls(pass_id, response, authorization)
580
- # §27: the retries re-enter THIS thread (continue_conversation), so one
581
- # entry per pass is the whole truth however many corrections it took.
582
- _record_pass_thread(pass_id, response, pass_threads)
583
- # BEFORE the retry loop. A truncated pass returned no JSON because it
584
- # was cut off, not because the model wrote malformed JSON -- sending
585
- # a "your last response did not parse" nudge into a thread that has
586
- # already exhausted its budget spends more of it to be told the same
587
- # thing, and reports a parse failure for something that never parsed
588
- # because it was never finished.
589
- _check_not_truncated(pass_id, response, trace)
590
-
591
- text = retry_until_json(
592
- response,
593
- label=pass_id,
594
- # pass_prompt(), NOT the raw pass file: BOTH the original attempt
595
- # and its retry must carry the same catalogs, or a retry silently
596
- # sees a different tool set than the attempt it is correcting.
597
- # #68 makes that literal -- the same AUTHORIZATION decides the
598
- # catalogs here as decided them for the attempt.
599
- system_prompt=system_prompts.pass_prompt(
600
- pass_id, *advertisement_facts(authorization)),
601
- model=model,
602
- provider_name=provider_name,
603
- trace=trace,
604
- temperature=temperature,
605
- authorization=authorization,
606
- effort=effort,
607
- on_response=lambda r: _record_granted_calls(pass_id, r, authorization),
608
- # The retry re-enters THIS pass's thread. No separate pass
609
- # ceiling any more (#4): omitting the kwarg lets the wrapper
610
- # resolve the configured spend cap, exactly as the pass itself
611
- # did.
612
- validate=lambda payload: _validate_payload(
613
- pass_id, payload, claim_ids=claim_ids, ensemble=ensemble),
614
- )
615
- except Exception as exc:
616
- # E14/#115: same uniform failure report as _run_pass -- a JSON
617
- # pass that exhausts its retries is a pass that ended badly,
618
- # whatever the exception class.
619
- yield _pass_failed_event(pass_id, exc)
620
- raise
621
- yield PipelineEvent(kind="pass_complete", pass_id=pass_id, ok=True)
622
- return text
623
-
624
-
625
- def _claim_from_json(raw: dict) -> Claim:
626
- """Filters to known input fields so an unexpected extra key from the
627
- model doesn't crash claim construction; required fields (id/text/type)
628
- still raise if genuinely missing."""
629
- filtered = {k: v for k, v in raw.items() if k in _CLAIM_INPUT_FIELDS}
630
- return Claim(**filtered)
631
-
632
-
633
- # ROADMAP_v2 §30 (B5). THE THREE _apply_* FUNCTIONS RETURN WHAT THEY
634
- # APPLIED, and their checkpoint lines interpolate that rather than the
635
- # count the pass was ASKED about.
636
- #
637
- # `Pass 3a: grounded {len(unique_entities)} unique entities across
638
- # {len(factual_claims)} factual claim(s).` is emitted verbatim whether
639
- # every entry landed or none did -- it is built entirely from this side of
640
- # the call. Driven with 3a/3b answering about ids Pass 2 never issued, the
641
- # run reported grounding 4 entities across 3 claims while grounding
642
- # nothing, then spent four more model calls in the 6a/6c loop and reported
643
- # that nothing could be verified. base.py:87 calls the trace "at least as
644
- # trustworthy an artifact as the final report itself"; a line derived from
645
- # its own input cannot be.
646
- #
647
- # A count of CLAIMS TOUCHED, not entries consumed: a pass that answers
648
- # twice about one claim has affected one claim, and the reader is deciding
649
- # whether the pass did its job.
650
-
651
-
652
- def _apply_grounding(claims: list[Claim], grounding_entries: list[dict]) -> int:
653
- by_id = resolve_by_id(claims)
654
- applied = set()
655
- for entry in grounding_entries:
656
- claim = by_id.get(entry.get("claim_id"))
657
- if claim:
658
- claim.grounding_sources = entry.get("sources", [])
659
- claim.grounding_status = entry.get("status")
660
- applied.add(claim.id)
661
- return len(applied)
662
-
663
-
664
- def _ground_and_score(run: PipelineRun, grounding_entries: list[dict], corpus,
665
- scorer=None, knobs=None, scholar=None) -> int:
666
- """Apply Pass 3a/6b's grounding, then everything §45 derives from it.
667
-
668
- THE ONE SEAM BOTH GROUNDING SITES GO THROUGH. There are two -- Pass 3a
669
- and Pass 6b's re-validation -- and §45 adds work that has to happen at
670
- both: a source scored only on the run's first grounding would carry a
671
- stale number after a revision changed the claim it was scored against.
672
- Deriving beside each call instead is the shape the "fix at the
673
- producer" rule exists to prevent, and a third caller could then arrive
674
- without it.
675
-
676
- Returns what `_apply_grounding` returned, so the checkpoint lines that
677
- interpolate it keep reporting what was APPLIED rather than what the
678
- pass was asked about (§30, B5).
679
-
680
- `run.source_documents` is refreshed HERE, and this is its only writer.
681
- Late enough to include everything grounding retrieved, and early
682
- enough that a run dying in a later pass still carries the evidence it
683
- had already gathered -- the failure path being where an unattended
684
- run's record matters most.
685
- """
686
- applied = _apply_grounding(run.claims, grounding_entries)
687
- if corpus is not None:
688
- run.source_documents = corpus.artifact_entries()
689
- knobs = knobs or {}
690
- score_grounding_sources(
691
- run, corpus=corpus, scorer=scorer, scholar=scholar,
692
- overrides=knobs.get("domain_overrides"),
693
- **{k: knobs[k] for k in ("window_chars", "max_windows",
694
- "claim_min_chars",
695
- "authority_adjustment_cap") if k in knobs})
696
- return applied
697
-
698
-
699
- def _sources_were_scored(run: PipelineRun) -> bool:
700
- """Whether §45's scoring stage ran for this run.
701
-
702
- Pass 5 needs this because an empty source list is AMBIGUOUS on its own
703
- -- "the model claimed grounded and cited nothing" on a scored run,
704
- "this claim was built without a scoring stage" everywhere else -- and
705
- only the first should cost a claim its grounding weight.
706
-
707
- Derived from the run rather than tracked in a flag, so it cannot go
708
- stale: the stage runs exactly when Pass 3a produced grounding, which
709
- is exactly when some factual claim carries a status.
710
- """
711
- return any(c.grounding_status is not None for c in run.claims)
712
-
713
-
714
- def _apply_critic(claims: list[Claim], critic_entries: list[dict]) -> int:
715
- by_id = resolve_by_id(claims)
716
- applied = set()
717
- for entry in critic_entries:
718
- claim = by_id.get(entry.get("claim_id"))
719
- if claim:
720
- claim.fallacies = entry.get("fallacies", [])
721
- claim.contradictions = entry.get("contradictions", [])
722
- claim.critic_severity = entry.get("severity", 0.0)
723
- applied.add(claim.id)
724
- return len(applied)
725
-
726
-
727
- def _apply_assumption_flags(claims: list[Claim], assumptions: dict) -> int:
728
- by_id = resolve_by_id(claims)
729
- applied = set()
730
- for claim_id, flags in assumptions.get("per_claim_flags", {}).items():
731
- claim = by_id.get(claim_id)
732
- if claim:
733
- claim.assumption_flags = flags
734
- applied.add(claim.id)
735
- return len(applied)
736
-
737
-
738
- def _synthesis_input(run: PipelineRun, directives: list | None = None) -> str:
739
- """What final synthesis reads.
740
-
741
- A FUNCTION, not a string built once. §20 re-runs synthesis after a
742
- correction is accepted, and reusing the string built before the review
743
- would regenerate the report from the UNCORRECTED claims -- producing a
744
- report that changed for no reason while the correction silently went
745
- nowhere.
746
- """
747
- text = (
748
- f"Original query:\n{run.user_query}\n\n"
749
- f"Final annotated claims:\n{json.dumps([vars(c) for c in run.claims])}\n\n"
750
- f"Coverage gaps:\n{json.dumps(run.coverage_gaps)}"
751
- )
752
- if directives:
753
- text += (
754
- "\n\nA reviewer raised the following about the previous draft of "
755
- "this report, and a human approved each one. Address them:\n"
756
- + "\n".join(f"- {d}" for d in directives)
757
- )
758
- return text
759
-
760
-
761
- def _review_stage(run: PipelineRun, progress: _Progress, model: str,
762
- provider_name: str, authorization, review,
763
- enabled: bool = False, effort: str | None = None):
764
- """ROADMAP_v2 §20. Opt-in review of the finished run, with every
765
- correction consented to individually.
766
-
767
- §22: a generator, because it logs, checkpoints and runs a pass. It
768
- takes the run's _Progress rather than making its own, so review.py's
769
- trace lines -- which never checkpointed at all before §22 -- land on
770
- the same watermark as everything else.
771
-
772
- Called from INSIDE the orchestrator (V3) rather than left to each
773
- shell. The obvious alternative -- a post-pipeline stage the caller
774
- invokes, mirroring write_run_artifacts -- is exactly the shape that
775
- produced this project's live asymmetry: that function has one
776
- production call site, so /research in the TUI writes no output
777
- directory at all. The consent OBJECT still comes from the shell,
778
- because only a shell knows how to reach a human.
779
-
780
- `enabled` and `review` are SEPARATE on purpose. "The user asked for a
781
- review" and "someone can be asked about its findings" are different
782
- facts, and collapsing them loses the case that matters: --review on a
783
- piped run must still produce findings and still change nothing (V6).
784
- If the consent object alone enabled the stage, that run would skip the
785
- review entirely and report nothing at all.
786
-
787
- A consent object with `enabled` false still runs it, because a caller
788
- that went to the trouble of building one wants the review.
789
-
790
- Batch 25 (#139): effort inherits into the reviewer (V7's rule applied
791
- to one more axis) and into the re-synthesis pass below.
792
- """
793
- if not enabled and review is None:
794
- return
795
-
796
- from core.reasoning import review as review_module
797
-
798
- findings, thread_id = review_module.run_review(
799
- run, model, provider_name, authorization, effort=effort)
800
- run.log(f"Review: {len(findings)} finding(s) raised.")
801
- # The findings' CONTENT is durable from this checkpoint on (review
802
- # r1-2): a kill during the consent walk used to leave only the count,
803
- # with what the reviewer found unrecoverable. Trace is serialized by
804
- # every update_pipeline_run, so this needs no new column (V8).
805
- for f in findings:
806
- target = f.get("claim_id") or "report"
807
- excerpt = str(f.get("proposed") or "")[:80]
808
- run.log(f"Review: finding -- {f.get('kind')} correction to {target}"
809
- + (f": {excerpt}" if excerpt else ""))
810
- yield from progress.checkpoint()
811
-
812
- decisions = review_module.walk_consent(
813
- findings, review, run, model=model, provider_name=provider_name,
814
- thread_id=thread_id, authorization=authorization, effort=effort)
815
- run.subagent_reviews = decisions
816
- yield from progress.checkpoint()
817
-
818
- # Deferred commit (review f4): corrections land on a copy, and the
819
- # live claims/report change only after the re-synthesis succeeds. A
820
- # failed re-synthesis therefore persists a consistent record -- the
821
- # pre-fix order stored corrected claims beside the stale report.
822
- changed, corrected, applied = review_module.apply_deferred(run, decisions)
823
- if changed:
824
- original_claims = run.claims
825
- run.claims = corrected
826
- try:
827
- run.final_report = yield from _run_pass(
828
- "Final synthesis",
829
- _synthesis_input(run, review_module.synthesis_directives(decisions)),
830
- model, provider_name, authorization=authorization,
831
- trace=run.trace,
832
- pass_threads=run.pass_threads,
833
- effort=effort,
834
- )
835
- except Exception as e:
836
- # CONTAINED, not re-raised. A provider error on this one call
837
- # is the same transient class as a reviewer call failing, and
838
- # f1 settled that an optional stage must not flip a finished
839
- # ten-pass run to status='failed'. The deferred commit already
840
- # guarantees a consistent record: the pre-review claims and the
841
- # report generated from them, which is a complete run's output
842
- # minus the corrections -- and the trace says which.
843
- #
844
- # A failure that escapes this STAGE (a bug, not a transient
845
- # provider error) still reaches the pipeline's except and
846
- # records status='failed'. That distinction is the whole
847
- # policy, and both halves are test-pinned.
848
- logger.exception("Review re-synthesis failed; corrections not applied.")
849
- run.claims = original_claims
850
- review_module.log_outcomes(run, decisions, applied, committed=False)
851
- run.log(f"Review: re-synthesis failed ({e}); accepted corrections "
852
- f"NOT applied -- claims and report left unchanged.")
853
- yield from progress.checkpoint()
854
- return
855
- review_module.log_outcomes(run, decisions, applied, committed=True)
856
- # NOT re-reviewed. The regress is cut deliberately: a review of the
857
- # re-synthesised report would need its own consent pass, and so on.
858
- run.log(f"Review: {len(applied)} correction(s) accepted; final "
859
- f"synthesis re-run. The re-synthesised report is not "
860
- f"re-reviewed.")
861
- else:
862
- review_module.log_outcomes(run, decisions, applied, committed=False)
863
- run.log("Review: no correction applied; report unchanged.")
864
- yield from progress.checkpoint()
865
-
866
-
867
- def _stage(pass_id: str):
868
- """One event for a stage that made ZERO model calls (§26).
869
-
870
- A separate kind from pass_start/pass_complete rather than a pair of
871
- those, because a code stage cannot meaningfully be "running": it
872
- completes in the time it takes to yield, and a consumer that showed it
873
- as in-progress would be showing a state that never exists. Pass 5 and
874
- Pass 6c are passes by the pipeline's numbering and stages by their
875
- cost, and this is the field that says which.
876
-
877
- Before this, every zero-LLM stage was invisible to both shells -- not
878
- by decision but because _run_pass was the only thing that emitted a
879
- boundary, and it wraps a model call. So a sidebar showed Pass 4
880
- followed by Pass 6a with the tiering that decided which claims were
881
- flagged in between, unmentioned.
882
- """
883
- yield PipelineEvent(kind="stage", pass_id=pass_id)
884
-
885
-
886
- def _tier_events(run: PipelineRun):
887
- """One claim_tiered event per claim, after a tiering pass.
888
-
889
- Called after EVERY run_confidence_tiering() -- Pass 5 and each 6b
890
- round -- so a consumer sees a claim's tier change rather than only
891
- its first value. Repeats are by design: the events are a stream of
892
- "this is the tier now", and a panel re-renders from the latest.
893
-
894
- Derived from run.claims after the fact rather than emitted inside
895
- confidence_scoring.py, which makes zero LLM calls and knows nothing
896
- about events; §22's own warning about two writers of related data
897
- applies to the tiering just as it does to the trace.
898
- """
899
- for claim in run.claims:
900
- yield PipelineEvent(kind="claim_tiered", claim_id=claim.id,
901
- tier=claim.confidence_tier)
902
-
903
-
904
- def _apply_fallback(claim: Claim) -> None:
905
- """D2 exhausted / fallback branch -- pure code, no LLM call."""
906
- claim.confidence_tier = "UNVERIFIED"
907
- claim.annotation = (
908
- f"[UNVERIFIED] Could not be adequately verified after {claim.retry_count} "
909
- f"revision attempt(s). Treat with caution."
910
- )
911
- claim.final_text = claim.revision_text or claim.text
912
-
913
-
914
- # ============================================================================
915
- # ---- The pipeline ------------------------------------------------------
916
- # ============================================================================
917
-
918
- def run_pipeline_to_completion(gen) -> PipelineRun:
919
- """Consumes a stream_deep_research_pipeline() generator fully,
920
- discarding intermediate events, and returns the finished PipelineRun.
921
-
922
- The exact counterpart of core.loop.run_to_completion(), including the
923
- RuntimeError: a generator that ends without its terminal event has a
924
- bug, and returning None instead would push the failure into whichever
925
- caller dereferences the run first.
926
- """
927
- final = None
928
- for event in gen:
929
- if event.kind == "run_complete":
930
- final = event.run
931
- if final is None:
932
- raise RuntimeError(
933
- "Pipeline generator completed without yielding a run_complete event"
934
- )
935
- return final
936
-
937
-
938
- def stream_deep_research_pipeline(
939
- user_query: str,
940
- model: str,
941
- provider_name: str = DEFAULT_PROVIDER,
942
- ensemble_mode: bool | None = None,
943
- ensemble_n: int | None = None,
944
- authorization=None,
945
- review=None,
946
- subagent_review: bool | None = None,
947
- effort: str | None = None,
948
- ):
949
- """The pipeline, as a generator of PipelineEvents (§22). The terminal
950
- `run_complete` event carries the finished PipelineRun.
951
-
952
- ABANDONMENT (§22, recorded rather than fixed). A consumer that stops
953
- iterating early -- a TUI quitting mid-run -- raises GeneratorExit
954
- inside the try below, which `except Exception` deliberately does not
955
- catch. The record therefore stays status='running', populated through
956
- the last checkpoint. That is honest: the run was abandoned, not
957
- failed, and forcing 'failed' would make an interrupted run
958
- indistinguishable from a broken one. Both shipped consumers drain
959
- fully.
960
-
961
- authorization (§25): a core.approval.RunAuthorization built by the
962
- shell that launched this run, or None for the pre-§25 behaviour (no
963
- grants, nobody to ask, every approval-gated tool hidden from every
964
- pass). Carried, not interpreted -- the decisions about WHAT may be
965
- granted live in core/reasoning/authorization.py, and the enforcement
966
- lives in core/loop.py.
967
-
968
- review (§20): a core.interaction.ResponseChannel, or None (§23 moved
969
- it there from core.approval.ReviewConsent). Carried the same
970
- way and for the same reason -- only a shell knows how to reach a
971
- human. A SECOND parameter rather than a field on the authorization
972
- bundle: that bundle answers "may this gated call proceed?" and this
973
- answers "may this edit be applied?". None means nothing is applied,
974
- even when the review itself runs (V6).
975
-
976
- subagent_review (§20/D9): whether the review stage runs at all. None
977
- falls back to config.SUBAGENT_REVIEW, matching ensemble_mode's
978
- pattern. Separate from `review` because --review on a piped run must
979
- still produce findings while applying nothing."""
980
- ensemble_mode = config.ENSEMBLE_MODE if ensemble_mode is None else ensemble_mode
981
- subagent_review = (config.SUBAGENT_REVIEW if subagent_review is None
982
- else subagent_review)
983
-
984
- # §10 revisit (E4). `ensemble_n` is vestigial: N is len(ENSEMBLE_MODELS)
985
- # now, because a separately configured count could disagree with the
986
- # roster that produced the candidates, and the denominator of a
987
- # confidence score must not be able to lie. The parameter and the
988
- # settings.json key are KEPT rather than removed -- unknown settings keys
989
- # raise, so deleting the key would make every existing settings.json that
990
- # sets it fail to load.
991
- if ensemble_n is not None:
992
- logger.warning(
993
- "Ignoring ensemble_n=%s: the number of candidates is "
994
- "len(config.ENSEMBLE_MODELS) now (ROADMAP §10 revisit, E3). "
995
- "Change the roster in config.py to change N.",
996
- ensemble_n,
997
- )
998
-
999
- roster = _ensemble_roster(ensemble_mode)
1000
-
1001
- run = PipelineRun(user_query=user_query)
1002
-
1003
- # §45 (SQ2). RUN-SCOPED, and attached to every pass rather than only to
1004
- # the two that ground. The question it answers is "what did this run
1005
- # retrieve from this URL", which is not a per-pass question: a page
1006
- # Pass 1 fetched and Pass 3a then cited without re-fetching is still
1007
- # evidence about that URL, and scoping the corpus to 3a would report
1008
- # no captured text for it and fall back to the model's own number.
1009
- corpus = SourceCorpus()
1010
-
1011
- # §45 (SQ2). Resolved ONCE, before Pass 0, so the warning about
1012
- # running without one is the first thing the trace says rather than
1013
- # something a reader meets forty lines in beside a score it already
1014
- # explains. One scorer for the whole run, because its vector cache and
1015
- # its give-up flag are both run-scoped: a claim is embedded once
1016
- # however many sources it has, and a provider that is down stays down.
1017
- scoring_knobs = effective_source_scoring(warn=True)
1018
- scorer = make_scorer(run, floor=scoring_knobs["similarity_floor"],
1019
- ceiling=scoring_knobs["similarity_ceiling"])
1020
-
1021
- # §45 (SQ9). OFF by default, so an out-of-the-box run makes no call
1022
- # the user did not ask for. One lookup object for the run, for the
1023
- # scorer's reason: its cohort cache and its give-up flag are both
1024
- # run-scoped.
1025
- scholar = ScholarLookup(knobs=scoring_knobs)
1026
-
1027
- # §45 (SQ6). Both knob sections resolved ONCE, here, with warn=True so
1028
- # a mistyped weight is said once per run rather than once per claim --
1029
- # `effective_compaction`'s gating, for its reason. score_claim stays a
1030
- # pure function of its arguments, and a run's numbers cannot change
1031
- # halfway through it.
1032
- confidence_weights = effective_confidence(warn=True)
1033
-
1034
- # §25 audit trail: ONE list, shared, not two kept in step. The run and
1035
- # the authorization bundle now refer to the same object, so a granted
1036
- # call is visible on the PipelineRun the moment it happens -- including
1037
- # at every §5 checkpoint and on the FAILURE path, which is where an
1038
- # unattended run's record matters most. Copying at the end instead
1039
- # would lose the trail on exactly the runs most worth auditing, and two
1040
- # writers of related data is the bug shape §22 warns about by name.
1041
- if authorization is not None:
1042
- run.granted_calls = authorization.granted_calls
1043
-
1044
- # ROADMAP §5 minimal core: create the durable record up front. On a
1045
- # mid-pipeline crash, the except block below flips status to 'failed'
1046
- # and persists a snapshot of the partial run before re-raising.
1047
- run.run_id = create_pipeline_run(user_query)
1048
-
1049
- # ROADMAP §11: resolve critic provider/model once. When no critic is
1050
- # configured these fall back to the main provider/model — no-op
1051
- # routing.
1052
- #
1053
- # §45 (SQ7): through pipeline_models.resolve rather than
1054
- # config.CRITIC_MODEL directly, so a `/critic` choice reaches the CLI,
1055
- # the TUI and a spawned run alike. That function owns the precedence —
1056
- # the user-tier store outranks config.py — and owning it in one place
1057
- # is the point: §11 gave this routing to config.py alone, which meant
1058
- # the methodology's own "a model must not check its own output" was
1059
- # available only to whoever could edit the checkout.
1060
- critic = pipeline_models.resolve("critic")
1061
- critic_provider = critic["provider_name"] if critic else provider_name
1062
- critic_model = critic["model"] if critic else model
1063
-
1064
- progress = _Progress(run)
1065
-
1066
- try:
1067
- # --- Pass 0: preliminary plan ---
1068
- run.plan = _parse_json_response((yield from _run_pass_with_json_retry("Pass 0", user_query, model, provider_name, run.trace, authorization=authorization, corpus=corpus, pass_threads=run.pass_threads, effort=effort)))
1069
- yield from progress.checkpoint(f"Pass 0: plan produced ({len(run.plan.get('key_entities_or_subjects', []))} key entities anticipated).")
1070
-
1071
- # --- Pass 1: initial generation (ensemble mode: N candidates) ---
1072
- pass1_input = f"Original query:\n{user_query}\n\nPreliminary plan (loose context, may deviate freely):\n{json.dumps(run.plan)}"
1073
- effective_n = 0
1074
- if roster:
1075
- # A LOOP, not a comprehension: _run_pass is a generator now
1076
- # (§22), and a comprehension would collect generator objects
1077
- # without ever running a pass.
1078
- #
1079
- # One candidate per roster entry, each on its OWN provider/model
1080
- # (E1). No new plumbing: _run() calls api_initialization() itself
1081
- # and effort_for() validates against the receiving model, so a
1082
- # heterogeneous roster is correct by construction -- the same way
1083
- # §11 already routes 3a/3b/6c to critic_provider/critic_model.
1084
- candidates = []
1085
- for entry in roster:
1086
- label = f"{entry['provider_name']}/{entry['model']}"
1087
- try:
1088
- candidates.append((yield from _run_pass(
1089
- "Pass 1", pass1_input, entry["model"], entry["provider_name"],
1090
- authorization=authorization, trace=run.trace,
1091
- pass_threads=run.pass_threads, effort=effort)))
1092
- except Exception as e:
1093
- # NAMED, TRACED, SKIPPED (E7) -- §20's containment rule.
1094
- # An optional generation strategy must not flip a
1095
- # ten-pass run to status='failed' because one provider
1096
- # was unreachable. Same posture MCP takes per server.
1097
- message = (f"Pass 1: ensemble candidate on {label} failed "
1098
- f"({type(e).__name__}: {e}) — skipped.")
1099
- logger.warning("%s", message)
1100
- run.log(message)
1101
- continue
1102
- run.log(f"Pass 1: ensemble candidate {len(candidates)} generated on {label}.")
1103
- # E13/#77: the record keeps every surviving candidate.
1104
- # The metadata half sits beside the trace's candidate-N
1105
- # lines so a stored asserted_by_candidates tag names
1106
- # models this run can still identify; the text half feeds
1107
- # the per-candidate artifacts and Pass 3b's input -- the
1108
- # two places that must be able to check a claim against
1109
- # what its number actually said. pipeline_storage strips
1110
- # `text` at serialization; see PipelineRunRecord.
1111
- run.candidates.append({
1112
- "candidate": len(candidates),
1113
- "provider_name": entry["provider_name"],
1114
- "model": entry["model"],
1115
- "chars": len(candidates[-1]),
1116
- "text": candidates[-1],
1117
- })
1118
-
1119
- # Labels come from the SURVIVORS, never from position in the
1120
- # roster (E11). Labelling by roster position leaves a gap when a
1121
- # candidate fails -- "Candidate 1, Candidate 3" -- so Pass 2
1122
- # would tag a claim both survivors asserted as [1, 3] while the
1123
- # denominator said 2, and a unanimous claim would be scored as
1124
- # dissented-against. A silently deflated confidence score is the
1125
- # exact failure class this section exists to remove.
1126
- effective_n = len(candidates)
1127
- if effective_n >= 2:
1128
- run.raw_response = candidates[0]
1129
- pass2_input = "\n\n".join(
1130
- f"Candidate {i + 1}:\n{c}" for i, c in enumerate(candidates)
1131
- )
1132
- run.log(f"Pass 1: ensemble mode — {effective_n} candidate(s) "
1133
- f"across {effective_n} model(s); consistency is measured "
1134
- f"out of {effective_n}.")
1135
- else:
1136
- # DEGRADE TO THE SINGLE-CANDIDATE PATH (E7), rather than
1137
- # scoring one candidate as an ensemble of one -- which would
1138
- # give every claim consistency 1.0 and a zero penalty while
1139
- # reporting that agreement as if it had been corroborated.
1140
- # ensemble_n=0 is not a degraded formula, it is the correct
1141
- # one when there is nothing to compare against.
1142
- effective_n = 0
1143
- if candidates:
1144
- run.raw_response = candidates[0]
1145
- pass2_input = f"Response to extract claims from:\n{run.raw_response}"
1146
- run.log("Pass 1: only one ensemble candidate survived — "
1147
- "scoring WITHOUT a disagreement penalty, since one "
1148
- "candidate cannot disagree with itself.")
1149
- else:
1150
- raise RuntimeError(
1151
- "Pass 1: every ensemble candidate failed; there is no "
1152
- "response to extract claims from. See the trace for "
1153
- "each provider's error."
1154
- )
1155
- else:
1156
- run.raw_response = yield from _run_pass("Pass 1", pass1_input, model, provider_name, authorization=authorization, corpus=corpus, trace=run.trace, pass_threads=run.pass_threads, effort=effort)
1157
- pass2_input = f"Response to extract claims from:\n{run.raw_response}"
1158
- run.log("Pass 1: initial generation complete.")
1159
- yield from progress.checkpoint()
1160
-
1161
- # --- Pass 2: claim extraction & classification ---
1162
- claims_json = _parse_json_response((yield from _run_pass_with_json_retry("Pass 2", pass2_input, model, provider_name, run.trace, authorization=authorization, corpus=corpus, pass_threads=run.pass_threads, ensemble=effective_n >= 2, effort=effort)))
1163
- run.claims = [_claim_from_json(c) for c in claims_json]
1164
- for claim in run.claims:
1165
- yield PipelineEvent(kind="claim_extracted", claim_id=claim.id,
1166
- text=claim.text)
1167
- yield from progress.checkpoint(f"Pass 2: extracted {len(run.claims)} claim(s).")
1168
-
1169
- # --- gate D0: route by claim type (pure code) ---
1170
- factual_claims = [c for c in run.claims if c.type == "factual"]
1171
- non_factual_claims = [c for c in run.claims if c.type != "factual"]
1172
- yield from _stage("D0")
1173
- yield from progress.checkpoint(
1174
- f"D0: {len(factual_claims)} factual claim(s) routed to 3a/3b, "
1175
- f"{len(non_factual_claims)} synthesis/speculative claim(s) routed directly to Pass 4."
1176
- )
1177
-
1178
- # --- Pass 3a + 3b: only for factual claims, batched by deduplicated entity ---
1179
- if factual_claims:
1180
- unique_entities = sorted({e for c in factual_claims for e in c.entities})
1181
- pass3a_input = (
1182
- f"Factual claims:\n{json.dumps([vars(c) for c in factual_claims])}\n\n"
1183
- f"Deduplicated entities to research (search each ONCE, map results back "
1184
- f"to every claim referencing it):\n{json.dumps(unique_entities)}"
1185
- )
1186
- grounding_json = _parse_json_response((yield from _run_pass_with_json_retry("Pass 3a", pass3a_input, critic_model, critic_provider, run.trace, authorization=authorization, corpus=corpus, pass_threads=run.pass_threads, claim_ids=[c.id for c in run.claims], effort=effort)))
1187
- grounded = _ground_and_score(run, grounding_json, corpus, scorer,
1188
- scoring_knobs, scholar)
1189
- yield from progress.checkpoint(f"Pass 3a: grounded {grounded} of {len(factual_claims)} factual claim(s), across {len(unique_entities)} deduplicated entities.")
1190
-
1191
- # E13/#77. Two or more survivors: the claims were extracted
1192
- # from the UNION of the candidates, so the critic sees every
1193
- # candidate under the labels Pass 2 used -- a claim only
1194
- # candidate 3 asserted is checked against text that actually
1195
- # contains it, and contradictions ACROSS candidates are
1196
- # findable. Handing it bare `raw_response` (candidate 1)
1197
- # asked an ill-posed question: find conflicts within a text
1198
- # much of your input did not come from.
1199
- if len(run.candidates) >= 2:
1200
- pass3b_input = (
1201
- "\n\n".join(
1202
- f"Candidate {entry['candidate']}:\n{entry['text']}"
1203
- for entry in run.candidates)
1204
- + f"\n\nFactual claims with grounding:\n{json.dumps([vars(c) for c in factual_claims])}"
1205
- )
1206
- else:
1207
- pass3b_input = (
1208
- f"Raw response:\n{run.raw_response}\n\n"
1209
- f"Factual claims with grounding:\n{json.dumps([vars(c) for c in factual_claims])}"
1210
- )
1211
- critic_json = _parse_json_response((yield from _run_pass_with_json_retry("Pass 3b", pass3b_input, critic_model, critic_provider, run.trace, authorization=authorization, corpus=corpus, pass_threads=run.pass_threads, claim_ids=[c.id for c in run.claims], effort=effort)))
1212
- critiqued = _apply_critic(run.claims, critic_json)
1213
- yield from progress.checkpoint(f"Pass 3b: critique applied to {critiqued} of {len(factual_claims)} factual claim(s).")
1214
- else:
1215
- # A stage, not a silence. "3a/3b did not run" is a fact about
1216
- # the run's shape -- it means nothing was factual -- and a
1217
- # panel that simply skipped from Pass 2 to Pass 3c would leave
1218
- # the reader to infer it from an absence.
1219
- yield from _stage("Pass 3a/3b")
1220
- yield from progress.checkpoint("Pass 3a/3b: skipped -- no factual claims to ground or critique.")
1221
-
1222
- # --- Pass 3c: completeness, independent of Pass 1's raw_response ---
1223
- pass3c_input = f"Original query:\n{user_query}\n\nPreliminary plan:\n{json.dumps(run.plan)}"
1224
- run.completeness = _parse_json_response((yield from _run_pass_with_json_retry("Pass 3c", pass3c_input, model, provider_name, run.trace, authorization=authorization, corpus=corpus, pass_threads=run.pass_threads, effort=effort)))
1225
- yield from progress.checkpoint(
1226
- f"Pass 3c: coverage_score={run.completeness.get('coverage_score')}, "
1227
- f"{len(run.completeness.get('gaps', []))} gap(s) identified."
1228
- )
1229
-
1230
- # --- Pass 4: assumption audit -- ALL claims, plus completeness ---
1231
- pass4_input = (
1232
- f"Original query:\n{user_query}\n\n"
1233
- f"All claims:\n{json.dumps([vars(c) for c in run.claims])}\n\n"
1234
- f"Completeness findings:\n{json.dumps(run.completeness)}"
1235
- )
1236
- run.assumptions = _parse_json_response((yield from _run_pass_with_json_retry("Pass 4", pass4_input, model, provider_name, run.trace, authorization=authorization, corpus=corpus, pass_threads=run.pass_threads, claim_ids=[c.id for c in run.claims], effort=effort)))
1237
- flagged_count = _apply_assumption_flags(run.claims, run.assumptions)
1238
- yield from progress.checkpoint(f"Pass 4: assumption audit complete, {flagged_count} of {len(run.claims)} claim(s) flagged.")
1239
-
1240
- # --- Pass 5: confidence tiering (0 LLM calls) ---
1241
- run_confidence_tiering(run, ensemble_n=effective_n,
1242
- sources_scored=_sources_were_scored(run),
1243
- weights=confidence_weights)
1244
- yield from _stage("Pass 5")
1245
- yield from _tier_events(run)
1246
- yield from progress.checkpoint("Pass 5: confidence tiers assigned (pure code, zero LLM calls).")
1247
-
1248
- # --- D1 + the 6a/6b/D2 retry loop ---
1249
- flagged = [c for c in run.claims if c.confidence_tier in FLAGGED_TIERS]
1250
- yield from _stage("D1")
1251
- yield from progress.checkpoint(f"D1: {len(flagged)} claim(s) flagged for revision, {len(run.claims) - len(flagged)} already clean.")
1252
-
1253
- while flagged:
1254
- # --- Pass 6a: ONE batched call across every currently-flagged claim ---
1255
- pass6a_input = json.dumps([
1256
- {
1257
- "claim": vars(c),
1258
- "critic_feedback": {"fallacies": c.fallacies, "contradictions": c.contradictions},
1259
- "grounding_feedback": c.grounding_sources,
1260
- "assumption_flags": c.assumption_flags,
1261
- }
1262
- for c in flagged
1263
- ])
1264
- revisions = _parse_json_response((yield from _run_pass_with_json_retry("Pass 6a", pass6a_input, model, provider_name, run.trace, authorization=authorization, corpus=corpus, pass_threads=run.pass_threads, claim_ids=[c.id for c in flagged], effort=effort)))
1265
-
1266
- # COUNT THE ROUND, NOT THE REVISION. The increment used to live
1267
- # inside the loop below, so only a claim Pass 6a NAMED counted --
1268
- # and 6a is one batched call across every flagged claim, which is
1269
- # exactly the shape a model drops an item from. A claim it omitted
1270
- # could never reach D2's cap, so `while flagged:` had no bound at
1271
- # all: two model calls per round, for ever. An omission, an empty
1272
- # list and an
1273
- # unknown id are indistinguishable here -- the lookup returns None
1274
- # and the `if claim:` skips in silence -- which is why the bound
1275
- # cannot be data the model supplies.
1276
- #
1277
- # Counting the round makes D2's cap bound the loop by
1278
- # construction, and since `flagged` only ever shrinks, every claim
1279
- # still in it exhausts on the same round.
1280
- for claim in flagged:
1281
- claim.retry_count += 1
1282
-
1283
- revised = 0
1284
- for rev in revisions:
1285
- # Resolved WITHIN the batch, first-wins like
1286
- # PipelineRun.claim_by_id: 6a was only asked about `flagged`,
1287
- # and a revision naming a claim outside it would land on one
1288
- # already finished -- while carrying a retry_count this round
1289
- # did not increment, so the event below would report a stale
1290
- # attempt number.
1291
- claim = next((c for c in flagged if c.id == rev["claim_id"]), None)
1292
- if claim:
1293
- revised += 1
1294
- claim.revision_text = rev["revised_text"]
1295
- # §22's "which claim, which attempt" -- emitted from the
1296
- # claim retry loop, which is the retry the section means.
1297
- # A JSON-parse retry is a different thing and reaches the
1298
- # consumer as a trace_line, via json_retry.py's own line.
1299
- yield PipelineEvent(kind="retry", claim_id=claim.id,
1300
- attempt=claim.retry_count)
1301
- yield from progress.checkpoint(f"Pass 6a: revised {revised} of {len(flagged)} claim(s) in this retry round.")
1302
-
1303
- # --- Pass 6b: re-validate the revised subset only (batched, reuses Pass 5's code) ---
1304
- pass6b_input = json.dumps([vars(c) for c in flagged])
1305
- revalidation = _parse_json_response((yield from _run_pass_with_json_retry("Pass 6b", pass6b_input, critic_model, critic_provider, run.trace, authorization=authorization, corpus=corpus, pass_threads=run.pass_threads, claim_ids=[c.id for c in run.claims], effort=effort)))
1306
- _ground_and_score(run, revalidation.get("grounding", []), corpus,
1307
- scorer, scoring_knobs, scholar)
1308
- _apply_critic(run.claims, revalidation.get("critic", []))
1309
- # 6b's own checkpoint below already reports an EFFECT -- how
1310
- # many claims came out clean -- rather than what it was asked
1311
- # about, so it needs no count from these two.
1312
- # Pass 5's function again -- code, not a call. Scoped to THIS
1313
- # round's batch: 6b is only asked about `flagged`, and re-tiering
1314
- # the whole run once per round recomputes claims that are already
1315
- # finished, from score data those rounds did not change.
1316
- run_confidence_tiering(run, ensemble_n=effective_n, claims=flagged,
1317
- sources_scored=_sources_were_scored(run),
1318
- weights=confidence_weights)
1319
- yield from _tier_events(run)
1320
-
1321
- still_flagged = [c for c in flagged if c.confidence_tier in FLAGGED_TIERS]
1322
- yield from progress.checkpoint(f"Pass 6b: {len(flagged) - len(still_flagged)} claim(s) now clean, {len(still_flagged)} still flagged.")
1323
-
1324
- # --- D2: retry cap check (pure code) ---
1325
- exhausted = [c for c in still_flagged if c.retry_count >= MAX_RETRIES]
1326
- if exhausted:
1327
- # ONCE per round, outside the per-claim loop. D2 is one
1328
- # decision applied to every claim that ran out of retries;
1329
- # emitting inside the loop would put a D2 row in the panel
1330
- # per claim, so a round that exhausted six claims would
1331
- # read as six separate stages.
1332
- yield from _stage("D2")
1333
- for c in exhausted:
1334
- _apply_fallback(c)
1335
- yield PipelineEvent(kind="claim_tiered", claim_id=c.id,
1336
- tier=c.confidence_tier)
1337
- yield from progress.checkpoint(f"D2: claim {c.id} exhausted retries ({c.retry_count}) -> fallback UNVERIFIED.")
1338
-
1339
- flagged = [c for c in still_flagged if c.retry_count < MAX_RETRIES]
1340
-
1341
- # --- Pass 6c: annotate (templated, 0 LLM calls) ---
1342
- for claim in run.claims:
1343
- if claim.final_text is None:
1344
- claim.final_text = claim.revision_text or claim.text
1345
- if claim.annotation is None:
1346
- claim.annotation = f"[{claim.confidence_tier}]"
1347
- yield from _stage("Pass 6c")
1348
- yield from progress.checkpoint("Pass 6c: annotation complete (templated, zero LLM calls).")
1349
-
1350
- # --- Merge (pure code) ---
1351
- yield from _stage("Merge")
1352
- yield from progress.checkpoint(f"Merge: final claim set assembled -- {len(run.claims)} claim(s), {len(run.coverage_gaps)} coverage gap(s).")
1353
-
1354
- # --- Final synthesis ---
1355
- run.final_report = yield from _run_pass("Final synthesis", _synthesis_input(run), model, provider_name, authorization=authorization, corpus=corpus, trace=run.trace, pass_threads=run.pass_threads, effort=effort)
1356
- yield from progress.checkpoint("Final synthesis complete.")
1357
-
1358
- # --- §20: review, consent, correct ---
1359
- yield from _review_stage(run, progress, model, provider_name,
1360
- authorization, review,
1361
- enabled=subagent_review, effort=effort)
1362
-
1363
- update_pipeline_run(run.run_id, run, status="complete")
1364
- yield PipelineEvent(kind="run_complete", run=run)
1365
- return
1366
- except Exception:
1367
- # Persist the partial state before the exception propagates. The
1368
- # update is best-effort: if storage itself is what failed, we must
1369
- # not mask the original error, so a second failure here is logged
1370
- # (via the real logger -- it reaches stderr through Python's
1371
- # lastResort handler even before logging_setup is wired in) and the
1372
- # original exception still re-raises. run.log() would be inert here:
1373
- # the propagated exception carries no reference back to this local
1374
- # `run`, and persistence already failed, so a trace entry would
1375
- # never reach anywhere durable.
1376
- try:
1377
- update_pipeline_run(run.run_id, run, status="failed")
1378
- except Exception as persist_error:
1379
- logger.error(
1380
- f"Failed to persist failure state for run {run.run_id}: {persist_error}"
1381
- )
1382
- raise
1
+ """
2
+ core/reasoning/orchestrator.py
3
+
4
+ Sequences the deep-research pipeline: Pass 0 -> 1 -> 2 -> gate D0 -> (3a -> 3b
5
+ for factual claims) -> 3c -> 4 (all claims) -> Pass 5 (code) -> D1 -> the
6
+ 6a/6b/D2 retry loop -> 6c (template) -> merge -> final synthesis.
7
+
8
+ SCOPE OF THIS VERSION: core sequential pipeline with optional ensemble
9
+ mode (ROADMAP §10: N-candidate Pass 1 generation + a cross-candidate
10
+ consistency check, whose contested claims D1 routes to the 6a/6b loop,
11
+ ROADMAP_v3 §90). No filesystem output yet
12
+ (returns a PipelineRun object; the /output/<run_id>/ file-writing system
13
+ is a separate, later piece of work).
14
+
15
+ ROADMAP §11 (critic-model routing): when a critic pair is configured,
16
+ Pass 3a, 3b, and 6c (which re-runs 3a/3b logic) use the critic
17
+ provider/model instead of the generator's. Every other pass keeps using
18
+ the main provider_name/model. This prevents a model from checking its
19
+ own output for errors with the same blind spots. §45 (SQ7) moved WHERE
20
+ that pair comes from: core/pipeline_models.resolve("critic") owns the
21
+ precedence -- a `/critic` choice in the user-tier store, else
22
+ config.CRITIC_MODEL -- so the routing is reachable without editing the
23
+ checkout, which for §11's whole life it was not.
24
+
25
+ ROADMAP §3 (malformed-JSON recovery): JSON-emitting passes are wrapped in
26
+ _run_pass_with_json_retry, which on a parse failure re-enters the SAME
27
+ pass-thread via RunAgentLoop.continue_conversation() with a corrective
28
+ follow-up message. The failed assistant turn is already in the thread's
29
+ history (see _run()'s always-persist fix in core/loop.py), so the model
30
+ sees its own prior output in context. Up to config.MAX_JSON_RETRIES
31
+ corrective attempts are made; a final ValueError surfaces unrecoverable
32
+ failures.
33
+
34
+ ROADMAP §5 (durable pipeline persistence): each run is wrapped in a
35
+ try/except that records status='failed' (with a snapshot of the partial
36
+ run) before re-raising, so a mid-pipeline crash still leaves a durable
37
+ record. A data-only update_pipeline_run() checkpoint fires after every
38
+ run.log() trace line, so even a hard kill (KeyboardInterrupt / SystemExit,
39
+ which bypass the except Exception block) leaves the record populated
40
+ through the last completed pass. load_pipeline_run() in
41
+ pipeline_storage.py provides the read API.
42
+
43
+ ROADMAP_v2 §22 (pipeline observability): the pipeline is a GENERATOR
44
+ yielding PipelineEvents (core/reasoning/events.py), so a shell can render
45
+ pass boundaries, trace lines, claim tiers and retries as they happen
46
+ rather than waiting for the whole run. Two names:
47
+
48
+ stream_deep_research_pipeline() the generator
49
+ run_pipeline_to_completion() the drainer, for a caller that wants
50
+ only the finished PipelineRun
51
+
52
+ DECISION P3 IS RETIRED, and it is worth saying why rather than quietly
53
+ dropping a name. P3 kept a third, synchronous `run_deep_research_pipeline()`
54
+ -- the drainer applied to the generator -- so that "every existing caller:
55
+ main.py, tui/app.py and fifteen test sites" would go on working unchanged.
56
+ Both shells then left of their own accord: `main.run_research` and
57
+ `tui/app.py` iterate the generator so they can render progress, each with a
58
+ comment saying it deliberately does not call the wrapper. That left a
59
+ public function with no production caller and fifty call sites in tests,
60
+ while this docstring went on naming it the live entry point. The
61
+ convenience moved to `tests/conftest.run_pipeline`, which is what it had
62
+ become; P3's argument was sound and its premise expired.
63
+
64
+ Decision P2: a pass's own LoopEvents are NOT forwarded up as LoopEvents --
65
+ _run_pass TRANSLATES a chosen subset into PipelineEvents (§26 amended this;
66
+ §22 had kept a pass fully opaque). It iterates
67
+ RunAgentLoop.stream_deep_research_mode() directly. `run_deep_research_mode`,
68
+ the synchronous wrapper this line used to name, is gone for
69
+ `run_deep_research_pipeline`'s reason and one layer down.
70
+ """
71
+
72
+ from __future__ import annotations
73
+
74
+ import json
75
+ import logging
76
+
77
+ import config
78
+ import prompts.system_prompts as system_prompts
79
+ from core import pipeline_models
80
+ from core.config_loader import effective_confidence, effective_source_scoring
81
+ from core.loop import RunAgentLoop, advertisement_facts
82
+ from core.reasoning.base import Claim, PipelineRun, resolve_by_id
83
+ from core.reasoning.confidence_scoring import is_contested, run_confidence_tiering
84
+ from core.reasoning.events import PipelineEvent
85
+ from core.reasoning.json_retry import parse_json_response as _parse_json_response
86
+ from core.reasoning.json_retry import retry_until_json
87
+ from core.reasoning.payload_validation import validate as _validate_payload
88
+ from core.reasoning.pipeline_storage import create_pipeline_run, update_pipeline_run
89
+ from core.reasoning.scholar import ScholarLookup
90
+ from core.reasoning.source_corpus import SourceCorpus
91
+ from core.reasoning.source_scoring import make_scorer, score_grounding_sources
92
+ from safety.policy_enforcement import redact_diagnostic_text
93
+ from tools.registry import registry
94
+
95
+ logger = logging.getLogger(__name__)
96
+
97
+ DEFAULT_PROVIDER = "ANTHROPIC"
98
+ FLAGGED_TIERS = {"LOW", "UNVERIFIED"}
99
+ MAX_RETRIES = config.MAX_PIPELINE_RETRIES
100
+ # The JSON-retry budget lives in core/reasoning/json_retry.py since the
101
+ # §20 extraction; a second constant here was a dead knob that invited
102
+ # no-op patches (review §19-20 f9).
103
+
104
+ _CLAIM_INPUT_FIELDS = {"id", "text", "type", "entities", "source_span", "asserted_by_candidates"}
105
+
106
+
107
+ # ============================================================================
108
+ # ---- Small helpers ----------------------------------------------------------
109
+ # ============================================================================
110
+
111
+ class _Progress:
112
+ """The ONE place a trace line becomes durable and becomes an event
113
+ (§22 AC3).
114
+
115
+ Before §22 this file paired every `run.log(...)` with an
116
+ `update_pipeline_run(...)` at twenty call sites, and `run.trace` had
117
+ THREE writers: those, review.py's fifteen `run.log()` calls (which
118
+ checkpointed nowhere), and json_retry.py's bare `trace.append()` per
119
+ failed parse. So "§5's persistence fires on every trace line" was
120
+ already untrue, and adding a per-call-site event emission would have
121
+ made it two independent writers of related data -- the bug shape §22
122
+ warns about by name.
123
+
124
+ So both are DERIVED from `run.trace` itself. `checkpoint()` emits
125
+ every line appended since it last ran and then persists. Because the
126
+ watermark reads the list rather than the call site, review.py's and
127
+ json_retry.py's lines are picked up too, WITHOUT either module being
128
+ edited or knowing this exists.
129
+
130
+ The watermark lives here rather than on PipelineRun because base.py
131
+ is data only and §5 serializes that object -- a field meaningful
132
+ only inside a live generator has no business in a persisted row.
133
+ """
134
+
135
+ def __init__(self, run: PipelineRun) -> None:
136
+ self.run = run
137
+ self._emitted = 0
138
+
139
+ def checkpoint(self, message: str | None = None):
140
+ """Log (optionally), PERSIST, then emit every un-emitted line.
141
+
142
+ Persist BEFORE emitting, not after. A generator only advances
143
+ while someone iterates it, so a consumer that abandons the run
144
+ between the yield and the persist would take that checkpoint down
145
+ with it -- §5's durability would silently start depending on a
146
+ UI's willingness to keep reading. This way, a line is already in
147
+ the record by the time anyone is told about it.
148
+
149
+ Monotonic: `_emitted` only ever advances, so no line can be
150
+ yielded twice however many times this is called.
151
+ """
152
+ if message is not None:
153
+ self.run.log(message)
154
+ update_pipeline_run(self.run.run_id, self.run)
155
+ while self._emitted < len(self.run.trace):
156
+ line = self.run.trace[self._emitted]
157
+ self._emitted += 1
158
+ yield PipelineEvent(kind="trace_line", text=line)
159
+
160
+
161
+ # One pass_activity event per this many characters streamed. A per-token
162
+ # event would be thousands of post_message hand-offs per pass, which is the
163
+ # cost Transcript.stream_delta already exists to avoid on the chat path.
164
+ _ACTIVITY_CHARS = 2000
165
+
166
+ # §26's _param_digest, and its two truncation constants, MOVED to
167
+ # safety/policy_enforcement.py in §27 -- beside the redactors, because
168
+ # §27's replay renderer is its second caller and the redact-before-truncate
169
+ # ordering must not exist twice. Imported under its own name rather than
170
+ # aliased back to the old private one: an alias would leave two spellings
171
+ # for one function, and a reader who greps the old name here should be sent
172
+ # to where it now lives, not handed a local rebinding.
173
+
174
+
175
+ def _translate(pass_id: str, stream, corpus=None):
176
+ """Turn one pass's LoopEvents into PipelineEvents, and return the
177
+ ModelResponse the pass produced (ROADMAP_v2 §26).
178
+
179
+ THE one place a LoopEvent becomes a PipelineEvent. Both _run_pass and
180
+ _run_pass_with_json_retry consume this rather than each iterating the
181
+ stream themselves -- two emission sites for the same translation is how
182
+ they drift, and this file has the twenty-checkpoint version of that
183
+ mistake in its own history (see _Progress).
184
+
185
+ What is translated is a SUBSET, chosen for what a person watching a
186
+ ten-pass run needs:
187
+
188
+ tool_call / tool_result the thing §22 P2 made invisible. A pass
189
+ making fourteen fetch_url calls over
190
+ several minutes looked exactly like one
191
+ that had hung.
192
+ pass_activity for the passes that call no tools at all.
193
+ Throttled: a total, every _ACTIVITY_CHARS.
194
+
195
+ What is NOT translated, and why:
196
+
197
+ token_delta text seven of the ten passes emit raw JSON, so
198
+ streaming pass output into a transcript
199
+ buries the report under it. Only the volume
200
+ escapes, never the content.
201
+ thinking_delta §38 (O5). Not translated AND not counted
202
+ into pass_activity's running total, so
203
+ `chars` keeps meaning one thing -- output
204
+ streamed so far -- rather than quietly
205
+ becoming two instruments the way batch 27
206
+ item 9 describes for the token figures. The
207
+ cost is stated rather than hidden: a pass
208
+ that thinks for minutes before writing
209
+ anything shows no activity, which is the
210
+ shape §26 built pass_activity to cure. Flip
211
+ it here if that turns up in a real run.
212
+ retract batch 113. A retraction tells a surface
213
+ that DREW model text to take it back, and
214
+ this one never drew any -- `chars` is the
215
+ only thing that escaped. Left monotonic
216
+ deliberately: the total measures what the
217
+ pass produced, it is the panel's liveness
218
+ figure rather than a bill, and a running
219
+ total that jumped backwards mid-pass
220
+ would read as the defect instead of the
221
+ honesty. The TUI's own output-char meter
222
+ is left alone for the same reason.
223
+ permission_request §25's ApprovalProvider already carries this
224
+ to the shell and blocks on the answer. A
225
+ second rendering of a question already on
226
+ screen is not observability.
227
+ notice a pass's compaction notices, forwarded as
228
+ trace LINES. M6 makes these backstop-only,
229
+ but "rare" is not "silent" -- §21's rule
230
+ has no exception for the pipeline, and a
231
+ backstop fold rewrites what the REST of
232
+ the pass sees. This used to drop them with
233
+ the claim that they "already reach the
234
+ shell as WARNING log records", which was
235
+ true of blocked and failed compactions and
236
+ FALSE of successful ones (INFO only --
237
+ audit #172). A trace line lands in
238
+ trace.md and both shells print it.
239
+
240
+ §45 (SQ2). `corpus` is a SECOND SINK for tool results, not a change to
241
+ what is translated. The rule above -- a successful result body never
242
+ reaches the UI -- is unchanged; this is a different consumer with a
243
+ different need, and the scoring stage cannot check a quote against a
244
+ page nobody kept. None, the default, collects nothing: that is every
245
+ caller that predates §45 and every test double."""
246
+ names: dict = {} # tool_call id -> name, since tool_result has none
247
+ streamed = 0
248
+ announced = 0
249
+ while True:
250
+ # next() rather than `for event in stream`, because a for loop
251
+ # SWALLOWS the generator's return value -- and the response is
252
+ # returned rather than read off the terminal event precisely
253
+ # because thread_id is attached after the loop finishes. A for
254
+ # loop here would hand every pass a response with no thread_id,
255
+ # and the only symptom would be §3's JSON retry silently starting
256
+ # a new thread instead of correcting the failed one.
257
+ try:
258
+ event = next(stream)
259
+ except StopIteration as stop:
260
+ return stop.value
261
+
262
+ if event.token_delta:
263
+ streamed += len(event.token_delta)
264
+ if streamed - announced >= _ACTIVITY_CHARS:
265
+ announced = streamed
266
+ yield PipelineEvent(kind="pass_activity", pass_id=pass_id,
267
+ chars=streamed)
268
+ if event.notice:
269
+ yield PipelineEvent(
270
+ kind="trace_line",
271
+ text=f"compaction during {pass_id}: {event.notice['text']}")
272
+ if event.tool_call_start:
273
+ name = event.tool_call_start.get("name")
274
+ names[event.tool_call_start.get("id")] = name
275
+ yield PipelineEvent(
276
+ kind="tool_call", pass_id=pass_id, tool=name,
277
+ # §42 (RA3): through the registry, so a tool's
278
+ # declared rationale param is dropped here too -- a
279
+ # pass row is as narrow as a transcript line.
280
+ text=registry.call_digest(
281
+ name, event.tool_call_start.get("input")))
282
+ if event.tool_result:
283
+ result = event.tool_result.get("result")
284
+ failed = isinstance(result, dict) and "error" in result
285
+ name = names.get(event.tool_result.get("id"))
286
+ if corpus is not None and not failed:
287
+ # BEFORE the yield, for #42's reason one layer up: a
288
+ # generator only advances while someone iterates it, so
289
+ # collecting after the yield would make the corpus depend
290
+ # on a consumer continuing to read. `corpus.add` ignores
291
+ # every tool it does not recognise.
292
+ corpus.add(name, result)
293
+ yield PipelineEvent(
294
+ kind="tool_result", pass_id=pass_id,
295
+ tool=name,
296
+ ok=not failed,
297
+ # Redacted here too, though dispatch() already ran the
298
+ # result through check_output_policy. One rule owned at one
299
+ # boundary -- "nothing leaves this function unredacted" --
300
+ # beats depending on a guarantee made two layers away that
301
+ # a later refactor could quietly drop.
302
+ text=(redact_diagnostic_text(str(result.get("error")))
303
+ if failed else None))
304
+
305
+
306
+ def _check_not_truncated(pass_id: str, response, trace: list[str] | None):
307
+ """A pass that ended on a stop condition did NOT finish; say so.
308
+
309
+ `_run_pass` used to return `response.text` and discard `stop_reason`,
310
+ so a pass cut off by the token budget looked exactly like one that
311
+ completed -- and because a budget stop returns the last response AS
312
+ IT STANDS, a pass that was mid-tool-call returned the EMPTY STRING.
313
+
314
+ That is not hypothetical. A Pass 1 making 14 tool calls crossed the
315
+ old 250k ceiling, returned "", and the orchestrator stored it as
316
+ raw_response. Pass 2 was then handed "Response to extract claims
317
+ from:\\n" and correctly answered that there was nothing to extract --
318
+ in a shape that is not a claim list -- and the run finally died in
319
+ Claim's constructor, three passes and one confusing TypeError away
320
+ from the thing that actually went wrong.
321
+
322
+ TWO outcomes, because truncation is not uniformly fatal:
323
+
324
+ * truncated WITH text -- degraded but usable. The pass produced an
325
+ answer and was cut off finishing it; downstream passes can work
326
+ with that. Traced, so the report's own audit log says the answer
327
+ was incomplete, and the run continues.
328
+ * truncated with NO text -- unusable. Everything downstream is
329
+ working from an empty string, and the only question is how many
330
+ passes it takes to produce an incomprehensible error. Raise here,
331
+ naming the pass and the stop reason.
332
+ """
333
+ stop = getattr(response, "stop_reason", None)
334
+ if stop in (None, "complete"):
335
+ return
336
+ text = (getattr(response, "text", "") or "").strip()
337
+ # #4: the figures turn a bare reason into a diagnosis. A user who
338
+ # reads token_budget_exceeded as a context problem is repeating the
339
+ # exact misreading item 9 recorded.
340
+ billed = getattr(response, "turn_billed_tokens", None)
341
+ figures = (f" billed {billed:,} this turn"
342
+ if isinstance(billed, int) else "")
343
+ if not text:
344
+ raise ValueError(
345
+ f"{pass_id} ended on {stop!r} with no text{figures}. A stop "
346
+ f"condition returns the last response as it stands, so a pass "
347
+ f"cut off mid-tool-call yields an empty string -- and every "
348
+ f"later pass would be working from nothing. "
349
+ f"(config.MAX_ITERATIONS and a configured settings.json "
350
+ f"max_token_budget spend cap are the two ceilings that "
351
+ f"produce this.)"
352
+ )
353
+ message = (f"{pass_id}: TRUNCATED ({stop}{figures}) -- the pass was cut "
354
+ f"off but produced output; continuing with what it returned.")
355
+ logger.warning("%s", message)
356
+ if trace is not None:
357
+ trace.append(message)
358
+
359
+
360
+ def _ensemble_roster(ensemble_mode: bool) -> list[dict]:
361
+ """The (provider_name, model) pairs Pass 1 runs on, or [] when ensemble
362
+ mode is off. Raises ValueError on a roster that cannot produce a
363
+ meaningful consistency signal (ROADMAP §10 revisit, E1/E5).
364
+
365
+ A separate function so every refusal is testable without running a
366
+ pipeline, and so the reasons stay together: this replaces §16's
367
+ sampling-parameter guard, which refused for a mechanism that no longer
368
+ exists.
369
+
370
+ Validated by SHAPE only -- provider names and API keys are not checked
371
+ here (E6). §16's /model warns rather than refuses on an empty API_KEY so
372
+ a local OpenAI-compatible endpoint stays usable, and MCP's posture is
373
+ that validation happens by connecting. A candidate whose provider is
374
+ unreachable is named, traced and skipped at run time instead.
375
+ """
376
+ if not ensemble_mode:
377
+ return []
378
+
379
+ roster = config.ENSEMBLE_MODELS
380
+ if not roster:
381
+ raise ValueError(
382
+ "Ensemble mode is on but ensemble_models in config.yaml is empty. "
383
+ "Diversity comes from different models now, not from a raised "
384
+ "temperature (ROADMAP §10 revisit), so the roster is required. "
385
+ "Set it in config.yaml to a list of at least two distinct "
386
+ '{"provider_name": ..., "model": ...} entries, or disable '
387
+ "ensemble_mode. There is deliberately no settings.json key for "
388
+ "the roster -- see E2."
389
+ )
390
+
391
+ for entry in roster:
392
+ if not isinstance(entry, dict) or not entry.get("provider_name") or not entry.get("model"):
393
+ raise ValueError(
394
+ f"Malformed ensemble_models entry in config.yaml {entry!r}: every "
395
+ f'entry needs both "provider_name" and "model".'
396
+ )
397
+
398
+ # DISTINCT pairs, not merely two entries. Repeating one model N times
399
+ # would generate N near-identical candidates -- there is no sampling
400
+ # variation left to make them differ -- and then report maximal
401
+ # cross-candidate consistency for every claim, which Pass 5 reads as
402
+ # confidence. That is precisely the failure §16's guard was added to
403
+ # prevent, and this config is the way to recreate it.
404
+ distinct = {(e["provider_name"], e["model"]) for e in roster}
405
+ if len(distinct) < 2:
406
+ raise ValueError(
407
+ f"Ensemble mode needs at least two DISTINCT models; "
408
+ f"ensemble_models in config.yaml resolves to {len(distinct)} "
409
+ f"({sorted(distinct)}). One model cannot disagree with itself, so "
410
+ f"every claim would score maximal consistency and Pass 5 would "
411
+ f"read that as confidence."
412
+ )
413
+ return list(roster)
414
+
415
+
416
+ def _pass_failed_event(pass_id: str, exc: BaseException) -> PipelineEvent:
417
+ """E14/#115. The one shape a pass failure is reported in: a
418
+ pass_complete carrying ok=False, mirroring tool_result's
419
+ outcome-plus-reason contract. A NEW kind was considered and rejected
420
+ -- tool_result already established payload-carried outcomes in this
421
+ very event set, and a second mechanism for 'ended' would make every
422
+ future consumer learn which applies where. The text is TRUNCATED:
423
+ the trace line (run.log at whatever site caught this) carries the
424
+ full cause, and an event payload is not the place to duplicate it
425
+ unboundedly."""
426
+ return PipelineEvent(
427
+ kind="pass_complete", pass_id=pass_id, ok=False,
428
+ text=f"{type(exc).__name__}: {exc}"[:200])
429
+
430
+
431
+ def _run_pass(pass_id: str, pass_input: str, model: str, provider_name: str,
432
+ temperature: float | None = None, authorization=None,
433
+ trace: list[str] | None = None, pass_threads: list | None = None,
434
+ effort: str | None = None, corpus=None, activity=None):
435
+ """One LLM-backed pass. Every actual model call in this file goes
436
+ through this single function.
437
+
438
+ §22: a GENERATOR that yields the pass boundary and returns the
439
+ response text (`text = yield from _run_pass(...)`). The pass id is
440
+ named once here rather than restated beside twelve call sites.
441
+
442
+ §26: the pass is now ITERATED rather than called, through _translate,
443
+ so what it does between its start and its end is visible. Same shape
444
+ as §22's own change to the shells -- the drainer still exists and is
445
+ still what every other caller uses.
446
+
447
+ Batch 25 (#139): effort reaches the passes like authorization does --
448
+ threaded from the shell's setting through the pipeline, validated per
449
+ RECEIVING model by effort_for() inside the loop, so an ensemble roster
450
+ or critic routing needs no effort-specific handling here.
451
+ """
452
+ yield PipelineEvent(kind="pass_start", pass_id=pass_id)
453
+ try:
454
+ response = yield from _translate(pass_id, RunAgentLoop.stream_deep_research_mode(
455
+ pass_input=pass_input, model=model, pass_id=pass_id, provider_name=provider_name,
456
+ temperature=temperature, authorization=authorization, effort=effort,
457
+ activity=activity,
458
+ ), corpus=corpus)
459
+ _record_granted_calls(pass_id, response, authorization)
460
+ _record_pass_thread(pass_id, response, pass_threads)
461
+ _check_not_truncated(pass_id, response, trace)
462
+ except Exception as exc:
463
+ # E14/#115, UNIFORM: a fatal pass reports itself before its
464
+ # exception propagates, so no shell is left holding a row that
465
+ # only ever says "running" -- the same property the ensemble
466
+ # skip path needs, reached from the one site both share.
467
+ yield _pass_failed_event(pass_id, exc)
468
+ raise
469
+ yield PipelineEvent(kind="pass_complete", pass_id=pass_id, ok=True)
470
+ return response.text
471
+
472
+
473
+ def _record_pass_thread(pass_id: str, response, pass_threads) -> None:
474
+ """Note which thread this pass ran in (§27 T2 / AC6).
475
+
476
+ BEFORE _check_not_truncated, which can raise: the thread of a pass that
477
+ died mid-tool-call is the single most useful one to be able to open, and
478
+ recording after the check would lose exactly that one.
479
+
480
+ `pass_threads` IS `run.pass_threads`, shared by reference for the same
481
+ reason §25's granted_calls is: one object means the record is already on
482
+ the run at every §5 checkpoint and on the failure path, rather than
483
+ being assembled at the end by a run that reached the end.
484
+
485
+ A separate optional argument rather than a `run` parameter, because
486
+ `trace` beside it is a list too and _run_pass_with_json_retry takes it
487
+ positionally in twelve call sites -- swapping both for the run object is
488
+ a bigger change than §27 asked for. Default None keeps every test double
489
+ that calls these two functions working.
490
+ """
491
+ if pass_threads is None:
492
+ return
493
+ thread_id = getattr(response, "thread_id", None)
494
+ if thread_id is None:
495
+ return
496
+ pass_threads.append({"pass": pass_id, "thread_id": str(thread_id)})
497
+
498
+
499
+ def _record_granted_calls(pass_id: str, response, authorization) -> None:
500
+ """Note calls that ran on a pre-flight grant (§25 audit trail).
501
+
502
+ Authorization moved up-front, so accountability moves after: this is
503
+ the record of what one launch-time yes actually authorised, for a run
504
+ nobody was watching.
505
+
506
+ Accumulated ON THE AUTHORIZATION BUNDLE rather than in module state or
507
+ a thirteenth argument. The bundle is already shared by reference across
508
+ every pass -- that is how GrantBudget counts one ceiling rather than
509
+ ten -- and what the authorization was spent on is authorization state.
510
+ A module global would also break the moment two pipelines ran.
511
+ """
512
+ if authorization is None:
513
+ return
514
+ for call in getattr(response, "granted_calls", ()) or ():
515
+ authorization.granted_calls.append({"pass": pass_id, **call})
516
+
517
+
518
+ def _run_pass_with_json_retry(
519
+ pass_id: str,
520
+ pass_input: str,
521
+ model: str,
522
+ provider_name: str,
523
+ trace: list[str] | None = None,
524
+ temperature: float | None = None,
525
+ authorization=None,
526
+ pass_threads: list | None = None,
527
+ claim_ids: list | None = None,
528
+ ensemble: bool = False,
529
+ effort: str | None = None,
530
+ corpus=None,
531
+ activity=None,
532
+ ):
533
+ """Runs one JSON-emitting pass and recovers from malformed JSON.
534
+
535
+ The recovery itself lives in core/reasoning/json_retry.py, shared with
536
+ §20's reviewer. All this function adds is the pass's own first attempt
537
+ and the two pass-specific facts the shared loop cannot know: which
538
+ system prompt to continue under, and that a retry's tool calls belong
539
+ on the same §25 audit trail as the original attempt's.
540
+
541
+ ROADMAP §3: attempts = max_retries + 1 (1 initial +
542
+ config.MAX_JSON_RETRIES corrective, per core/reasoning/json_retry.py).
543
+ Unrecoverable failure raises ValueError with the final parse error
544
+ attached; the caller's try/except turns that into a durable
545
+ status='failed' record.
546
+
547
+ §30 (B3): the payload spec is bound HERE, from the pass id, rather
548
+ than passed in by each of the eight call sites. A call site that
549
+ forgot the argument would be silently unvalidated, which is the exact
550
+ condition this batch exists to remove -- and payload_validation.validate
551
+ raises on a pass id it has no spec for, so an eleventh JSON-emitting
552
+ pass cannot arrive by omission.
553
+
554
+ This function still returns TEXT, deliberately, even though it now
555
+ parses the payload internally to check it. Around twenty test sites
556
+ patch or drain it and assert on the returned string, and §20's
557
+ reviewer shares retry_until_json's contract; re-parsing a short string
558
+ is cheaper than moving twenty seams in the batch that adds the check.
559
+
560
+ `claim_ids` is the set the APPLY step will resolve against -- the
561
+ factual claims for 3a/3b (batch 220), every claim for 4, the
562
+ currently-flagged batch for 6a/6b -- because
563
+ validating against a wider set would accept an entry that then lands
564
+ on nothing.
565
+
566
+ §22: a generator, like _run_pass, and for the same reason. The
567
+ corrective attempts inside retry_until_json need no event kind of
568
+ their own -- that function already appends a trace line per failed
569
+ parse, so _Progress's watermark carries them to the consumer at the
570
+ next checkpoint with json_retry.py untouched. pass_complete fires
571
+ after the retries resolve, so a pass is not reported finished while
572
+ it is still arguing with the model about JSON.
573
+
574
+ §26 limit, stated rather than fixed: the FIRST attempt is translated,
575
+ the retries are not. retry_until_json reaches the model through
576
+ continue_conversation(), which drains its own loop internally, so a
577
+ tool call made while correcting malformed JSON produces no tool_call
578
+ event. Making it visible means a streaming sibling for
579
+ continue_conversation too, which is chat's entry point as well -- a
580
+ larger change than the thing it would show.
581
+
582
+ §45 inherits that limit rather than widening it: a page fetched during
583
+ a corrective retry reaches no corpus either, so a source cited only
584
+ from such a fetch scores with `similarity_method: "llm"` like any
585
+ other source with no captured text. It degrades to the documented
586
+ fallback instead of to a wrong number, which is why the limit is
587
+ stated here and not worked around.
588
+ """
589
+ yield PipelineEvent(kind="pass_start", pass_id=pass_id)
590
+ try:
591
+ response = yield from _translate(pass_id, RunAgentLoop.stream_deep_research_mode(
592
+ pass_input=pass_input, model=model, pass_id=pass_id, provider_name=provider_name,
593
+ temperature=temperature, authorization=authorization, effort=effort,
594
+ activity=activity,
595
+ ), corpus=corpus)
596
+ _record_granted_calls(pass_id, response, authorization)
597
+ # §27: the retries re-enter THIS thread (continue_conversation), so one
598
+ # entry per pass is the whole truth however many corrections it took.
599
+ _record_pass_thread(pass_id, response, pass_threads)
600
+ # BEFORE the retry loop. A truncated pass returned no JSON because it
601
+ # was cut off, not because the model wrote malformed JSON -- sending
602
+ # a "your last response did not parse" nudge into a thread that has
603
+ # already exhausted its budget spends more of it to be told the same
604
+ # thing, and reports a parse failure for something that never parsed
605
+ # because it was never finished.
606
+ _check_not_truncated(pass_id, response, trace)
607
+
608
+ text = retry_until_json(
609
+ response,
610
+ label=pass_id,
611
+ # pass_prompt(), NOT the raw pass file: BOTH the original attempt
612
+ # and its retry must carry the same catalogs, or a retry silently
613
+ # sees a different tool set than the attempt it is correcting.
614
+ # #68 makes that literal -- the same AUTHORIZATION decides the
615
+ # catalogs here as decided them for the attempt.
616
+ system_prompt=system_prompts.pass_prompt(
617
+ pass_id, *advertisement_facts(authorization)),
618
+ model=model,
619
+ provider_name=provider_name,
620
+ trace=trace,
621
+ temperature=temperature,
622
+ authorization=authorization,
623
+ effort=effort,
624
+ on_response=lambda r: _record_granted_calls(pass_id, r, authorization),
625
+ # §47's sink, at the hop batch 73 missed (batch 75). A
626
+ # corrective attempt reaches the model through
627
+ # continue_conversation, which drains its own loop, so a
628
+ # subagent spawned while a pass is being corrected is visible
629
+ # through this channel or not at all.
630
+ activity=activity,
631
+ # The retry re-enters THIS pass's thread. No separate pass
632
+ # ceiling any more (#4): omitting the kwarg lets the wrapper
633
+ # resolve the configured spend cap, exactly as the pass itself
634
+ # did.
635
+ validate=lambda payload: _validate_payload(
636
+ pass_id, payload, claim_ids=claim_ids, ensemble=ensemble),
637
+ )
638
+ except Exception as exc:
639
+ # E14/#115: same uniform failure report as _run_pass -- a JSON
640
+ # pass that exhausts its retries is a pass that ended badly,
641
+ # whatever the exception class.
642
+ yield _pass_failed_event(pass_id, exc)
643
+ raise
644
+ yield PipelineEvent(kind="pass_complete", pass_id=pass_id, ok=True)
645
+ return text
646
+
647
+
648
+ def _claim_from_json(raw: dict) -> Claim:
649
+ """Filters to known input fields so an unexpected extra key from the
650
+ model doesn't crash claim construction; required fields (id/text/type)
651
+ still raise if genuinely missing."""
652
+ filtered = {k: v for k, v in raw.items() if k in _CLAIM_INPUT_FIELDS}
653
+ return Claim(**filtered)
654
+
655
+
656
+ # ROADMAP_v2 §30 (B5). THE THREE _apply_* FUNCTIONS RETURN WHAT THEY
657
+ # APPLIED, and their checkpoint lines interpolate that rather than the
658
+ # count the pass was ASKED about.
659
+ #
660
+ # `Pass 3a: grounded {len(unique_entities)} unique entities across
661
+ # {len(factual_claims)} factual claim(s).` is emitted verbatim whether
662
+ # every entry landed or none did -- it is built entirely from this side of
663
+ # the call. Driven with 3a/3b answering about ids Pass 2 never issued, the
664
+ # run reported grounding 4 entities across 3 claims while grounding
665
+ # nothing, then spent four more model calls in the 6a/6c loop and reported
666
+ # that nothing could be verified. base.py:87 calls the trace "at least as
667
+ # trustworthy an artifact as the final report itself"; a line derived from
668
+ # its own input cannot be.
669
+ #
670
+ # A count of CLAIMS TOUCHED, not entries consumed: a pass that answers
671
+ # twice about one claim has affected one claim, and the reader is deciding
672
+ # whether the pass did its job.
673
+
674
+
675
+ def _apply_grounding(claims: list[Claim], grounding_entries: list[dict]) -> int:
676
+ by_id = resolve_by_id(claims)
677
+ applied = set()
678
+ for entry in grounding_entries:
679
+ claim = by_id.get(entry.get("claim_id"))
680
+ if claim:
681
+ claim.grounding_sources = entry.get("sources", [])
682
+ claim.grounding_status = entry.get("status")
683
+ applied.add(claim.id)
684
+ return len(applied)
685
+
686
+
687
+ def _ground_and_score(run: PipelineRun, grounding_entries: list[dict], corpus,
688
+ scorer=None, knobs=None, scholar=None,
689
+ claims=None) -> int:
690
+ """Apply Pass 3a/6b's grounding, then everything §45 derives from it.
691
+
692
+ THE ONE SEAM BOTH GROUNDING SITES GO THROUGH. There are two -- Pass 3a
693
+ and Pass 6b's re-validation -- and §45 adds work that has to happen at
694
+ both: a source scored only on the run's first grounding would carry a
695
+ stale number after a revision changed the claim it was scored against.
696
+ Deriving beside each call instead is the shape the "fix at the
697
+ producer" rule exists to prevent, and a third caller could then arrive
698
+ without it.
699
+
700
+ Returns what `_apply_grounding` returned, so the checkpoint lines that
701
+ interpolate it keep reporting what was APPLIED rather than what the
702
+ pass was asked about (§30, B5).
703
+
704
+ `run.source_documents` is refreshed HERE, and this is its only writer.
705
+ Late enough to include everything grounding retrieved, and early
706
+ enough that a run dying in a later pass still carries the evidence it
707
+ had already gathered -- the failure path being where an unattended
708
+ run's record matters most.
709
+
710
+ `claims` NARROWS BOTH HALVES, and defaults to the whole run. Pass 3a
711
+ passes the factual claims since batch 220 (#247), the only ones it is
712
+ shown: the default let an entry naming a speculative claim mark it
713
+ grounded. §66 (A26) passes the 6a/6b loop's current batch, and it has to
714
+ reach the SCORING as well as the apply: `score_grounding_sources`
715
+ "rewrite[s] EVERY claim's grounding_sources with computed scores" by
716
+ default, so a 6b round recomputed the sources of claims D1 had already
717
+ finished with, while the re-tiering beside it was deliberately scoped
718
+ to the batch. Driven with the corpus grown by that round -- which is
719
+ what a grounding round does -- a claim the payload never named had its
720
+ `quote_verified` rewritten from None to True. That one moves no score
721
+ by design (§45 slice A), but the embedding and scholar phases run over
722
+ the same set and do move one, and the claim they would move is not
723
+ re-tiered.
724
+
725
+ A PARAMETER THAT EXISTED AND WAS NEVER PASSED. `score_grounding_sources`
726
+ has had `claims` since §45; the one production caller omitted it, so
727
+ the narrowing it was built for was available and unused.
728
+ """
729
+ targets = run.claims if claims is None else claims
730
+ applied = _apply_grounding(targets, grounding_entries)
731
+ if corpus is not None:
732
+ run.source_documents = corpus.artifact_entries()
733
+ knobs = knobs or {}
734
+ score_grounding_sources(
735
+ run, claims=claims, corpus=corpus, scorer=scorer, scholar=scholar,
736
+ overrides=knobs.get("domain_overrides"),
737
+ **{k: knobs[k] for k in ("window_chars", "max_windows",
738
+ "claim_min_chars",
739
+ "authority_adjustment_cap") if k in knobs})
740
+ return applied
741
+
742
+
743
+ def _sources_were_scored(run: PipelineRun) -> bool:
744
+ """Whether §45's scoring stage ran for this run.
745
+
746
+ Pass 5 needs this because an empty source list is AMBIGUOUS on its own
747
+ -- "the model claimed grounded and cited nothing" on a scored run,
748
+ "this claim was built without a scoring stage" everywhere else -- and
749
+ only the first should cost a claim its grounding weight.
750
+
751
+ Derived from the run rather than tracked in a flag, so it cannot go
752
+ stale: the stage runs exactly when Pass 3a produced grounding, which
753
+ is exactly when some factual claim carries a status.
754
+ """
755
+ return any(c.grounding_status is not None for c in run.claims)
756
+
757
+
758
+ def _apply_critic(claims: list[Claim], critic_entries: list[dict]) -> int:
759
+ by_id = resolve_by_id(claims)
760
+ applied = set()
761
+ for entry in critic_entries:
762
+ claim = by_id.get(entry.get("claim_id"))
763
+ if claim:
764
+ claim.fallacies = entry.get("fallacies", [])
765
+ claim.contradictions = entry.get("contradictions", [])
766
+ claim.critic_severity = entry.get("severity", 0.0)
767
+ applied.add(claim.id)
768
+ return len(applied)
769
+
770
+
771
+ def _note_entries_outside_the_batch(run: PipelineRun, batch: list[Claim],
772
+ *entry_lists, pass_id: str, scope: str,
773
+ asked: str, why: str) -> int:
774
+ """Say that a pass answered about a claim it was not asked about.
775
+
776
+ §66 (A26). The apply is scoped to the batch, so such an entry lands on
777
+ nothing -- and `review.py` settled the policy for exactly this shape:
778
+ a finding it cannot apply is DROPPED AND TRACED, because dropping in
779
+ silence is indistinguishable from applying. 6b's own checkpoint line
780
+ reports how many claims came out clean, which is an effect and
781
+ therefore cannot report this.
782
+
783
+ FOUR PASSES SINCE BATCH 220. 6a made the same
784
+ drop twenty lines above 6b and said nothing (#248), and 3a and 3b,
785
+ shown only the factual claims, applied to every claim (#247): a 3a
786
+ entry could mark a speculative claim grounded, which gate D0 says cannot
787
+ happen, and a 3b severity on one moved its tier -- measured, MEDIUM to
788
+ LOW at 0.5 and to UNVERIFIED at 0.8, which then cost it 6a/6b rounds.
789
+ Each caller says its own `scope`, what it `asked` about and `why` an
790
+ answer outside it must not land.
791
+
792
+ The id cross-check does not cover it and is not meant to: B5 makes a
793
+ TOTAL mismatch the error and a partial one deliberately not, since a
794
+ model that gets nine of ten right must not cost a run nine passes.
795
+ Measured -- a payload naming the batch PLUS one extra id passes
796
+ `claim_ids=[c.id for c in flagged]` unchanged, which is why the apply
797
+ is where this had to be fixed and the trace is what makes the drop
798
+ visible.
799
+ """
800
+ known = {c.id for c in batch}
801
+ outside = sorted({entry.get("claim_id") for entries in entry_lists
802
+ for entry in entries if isinstance(entry, dict)}
803
+ - known - {None})
804
+ if outside:
805
+ run.log(
806
+ f"{pass_id}: {len(outside)} claim id(s) in the response name a "
807
+ f"claim outside {scope} "
808
+ f"({', '.join(repr(i) for i in outside[:3])}) -- dropped. "
809
+ f"{pass_id.removeprefix('Pass ')} was asked about {len(known)} "
810
+ f"{asked}; {why}"
811
+ )
812
+ return len(outside)
813
+
814
+
815
+ def _apply_assumption_flags(claims: list[Claim], assumptions: dict) -> int:
816
+ by_id = resolve_by_id(claims)
817
+ applied = set()
818
+ for claim_id, flags in assumptions.get("per_claim_flags", {}).items():
819
+ claim = by_id.get(claim_id)
820
+ if claim:
821
+ claim.assumption_flags = flags
822
+ applied.add(claim.id)
823
+ return len(applied)
824
+
825
+
826
+ def _synthesis_input(run: PipelineRun, directives: list | None = None) -> str:
827
+ """What final synthesis reads.
828
+
829
+ A FUNCTION, not a string built once. §20 re-runs synthesis after a
830
+ correction is accepted, and reusing the string built before the review
831
+ would regenerate the report from the UNCORRECTED claims -- producing a
832
+ report that changed for no reason while the correction silently went
833
+ nowhere.
834
+ """
835
+ text = (
836
+ f"Original query:\n{run.user_query}\n\n"
837
+ f"Final annotated claims:\n{json.dumps([vars(c) for c in run.claims])}\n\n"
838
+ f"Coverage gaps:\n{json.dumps(run.coverage_gaps)}"
839
+ )
840
+ if directives:
841
+ text += (
842
+ "\n\nA reviewer raised the following about the previous draft of "
843
+ "this report, and a human approved each one. Address them:\n"
844
+ + "\n".join(f"- {d}" for d in directives)
845
+ )
846
+ return text
847
+
848
+
849
+ def _review_stage(run: PipelineRun, progress: _Progress, model: str,
850
+ provider_name: str, authorization, review,
851
+ enabled: bool = False, effort: str | None = None,
852
+ activity=None):
853
+ """ROADMAP_v2 §20. Opt-in review of the finished run, with every
854
+ correction consented to individually.
855
+
856
+ §22: a generator, because it logs, checkpoints and runs a pass. It
857
+ takes the run's _Progress rather than making its own, so review.py's
858
+ trace lines -- which never checkpointed at all before §22 -- land on
859
+ the same watermark as everything else.
860
+
861
+ Called from INSIDE the orchestrator (V3) rather than left to each
862
+ shell. The obvious alternative -- a post-pipeline stage the caller
863
+ invokes, mirroring write_run_artifacts -- is exactly the shape that
864
+ produced this project's live asymmetry: that function has one
865
+ production call site, so /research in the TUI writes no output
866
+ directory at all. The consent OBJECT still comes from the shell,
867
+ because only a shell knows how to reach a human.
868
+
869
+ `enabled` and `review` are SEPARATE on purpose. "The user asked for a
870
+ review" and "someone can be asked about its findings" are different
871
+ facts, and collapsing them loses the case that matters: --review on a
872
+ piped run must still produce findings and still change nothing (V6).
873
+ If the consent object alone enabled the stage, that run would skip the
874
+ review entirely and report nothing at all.
875
+
876
+ A consent object with `enabled` false still runs it, because a caller
877
+ that went to the trouble of building one wants the review.
878
+
879
+ Batch 25 (#139): effort inherits into the reviewer (V7's rule applied
880
+ to one more axis) and into the re-synthesis pass below.
881
+ """
882
+ if not enabled and review is None:
883
+ return
884
+
885
+ from core.reasoning import review as review_module
886
+
887
+ findings, thread_id = review_module.run_review(
888
+ run, model, provider_name, authorization, effort=effort,
889
+ activity=activity)
890
+ run.log(f"Review: {len(findings)} finding(s) raised.")
891
+ # The findings' CONTENT is durable from this checkpoint on (review
892
+ # r1-2): a kill during the consent walk used to leave only the count,
893
+ # with what the reviewer found unrecoverable. Trace is serialized by
894
+ # every update_pipeline_run, so this needs no new column (V8).
895
+ for f in findings:
896
+ target = f.get("claim_id") or "report"
897
+ excerpt = str(f.get("proposed") or "")[:80]
898
+ run.log(f"Review: finding -- {f.get('kind')} correction to {target}"
899
+ + (f": {excerpt}" if excerpt else ""))
900
+ yield from progress.checkpoint()
901
+
902
+ decisions = review_module.walk_consent(
903
+ findings, review, run, model=model, provider_name=provider_name,
904
+ thread_id=thread_id, authorization=authorization, effort=effort,
905
+ # §47's sink, for the refinement calls the walk can make. Every
906
+ # hop is a place it can be dropped, and this one was.
907
+ activity=activity)
908
+ run.subagent_reviews = decisions
909
+ yield from progress.checkpoint()
910
+
911
+ # Deferred commit (review f4): corrections land on a copy, and the
912
+ # live claims/report change only after the re-synthesis succeeds. A
913
+ # failed re-synthesis therefore persists a consistent record -- the
914
+ # pre-fix order stored corrected claims beside the stale report.
915
+ changed, corrected, applied = review_module.apply_deferred(run, decisions)
916
+ if changed:
917
+ original_claims = run.claims
918
+ run.claims = corrected
919
+ try:
920
+ run.final_report = yield from _run_pass(
921
+ "Final synthesis",
922
+ _synthesis_input(run, review_module.synthesis_directives(decisions)),
923
+ model, provider_name, authorization=authorization,
924
+ trace=run.trace,
925
+ pass_threads=run.pass_threads,
926
+ effort=effort,
927
+ activity=activity,
928
+ )
929
+ except Exception as e:
930
+ # CONTAINED, not re-raised. A provider error on this one call
931
+ # is the same transient class as a reviewer call failing, and
932
+ # f1 settled that an optional stage must not flip a finished
933
+ # ten-pass run to status='failed'. The deferred commit already
934
+ # guarantees a consistent record: the pre-review claims and the
935
+ # report generated from them, which is a complete run's output
936
+ # minus the corrections -- and the trace says which.
937
+ #
938
+ # A failure that escapes this STAGE (a bug, not a transient
939
+ # provider error) still reaches the pipeline's except and
940
+ # records status='failed'. That distinction is the whole
941
+ # policy, and both halves are test-pinned.
942
+ logger.exception("Review re-synthesis failed; corrections not applied.")
943
+ run.claims = original_claims
944
+ review_module.log_outcomes(run, decisions, applied, committed=False)
945
+ run.log(f"Review: re-synthesis failed ({e}); accepted corrections "
946
+ f"NOT applied -- claims and report left unchanged.")
947
+ yield from progress.checkpoint()
948
+ return
949
+ review_module.log_outcomes(run, decisions, applied, committed=True)
950
+ # NOT re-reviewed. The regress is cut deliberately: a review of the
951
+ # re-synthesised report would need its own consent pass, and so on.
952
+ run.log(f"Review: {len(applied)} correction(s) accepted; final "
953
+ f"synthesis re-run. The re-synthesised report is not "
954
+ f"re-reviewed.")
955
+ else:
956
+ review_module.log_outcomes(run, decisions, applied, committed=False)
957
+ run.log("Review: no correction applied; report unchanged.")
958
+ yield from progress.checkpoint()
959
+
960
+
961
+ def _stage(pass_id: str):
962
+ """One event for a stage that made ZERO model calls (§26).
963
+
964
+ A separate kind from pass_start/pass_complete rather than a pair of
965
+ those, because a code stage cannot meaningfully be "running": it
966
+ completes in the time it takes to yield, and a consumer that showed it
967
+ as in-progress would be showing a state that never exists. Pass 5 and
968
+ Pass 6c are passes by the pipeline's numbering and stages by their
969
+ cost, and this is the field that says which.
970
+
971
+ Before this, every zero-LLM stage was invisible to both shells -- not
972
+ by decision but because _run_pass was the only thing that emitted a
973
+ boundary, and it wraps a model call. So a sidebar showed Pass 4
974
+ followed by Pass 6a with the tiering that decided which claims were
975
+ flagged in between, unmentioned.
976
+ """
977
+ yield PipelineEvent(kind="stage", pass_id=pass_id)
978
+
979
+
980
+ def _tier_events(run: PipelineRun):
981
+ """One claim_tiered event per claim, after a tiering pass.
982
+
983
+ Called after EVERY run_confidence_tiering() -- Pass 5 and each 6b
984
+ round -- so a consumer sees a claim's tier change rather than only
985
+ its first value. Repeats are by design: the events are a stream of
986
+ "this is the tier now", and a panel re-renders from the latest.
987
+
988
+ Derived from run.claims after the fact rather than emitted inside
989
+ confidence_scoring.py, which makes zero LLM calls and knows nothing
990
+ about events; §22's own warning about two writers of related data
991
+ applies to the tiering just as it does to the trace.
992
+ """
993
+ for claim in run.claims:
994
+ yield PipelineEvent(kind="claim_tiered", claim_id=claim.id,
995
+ tier=claim.confidence_tier)
996
+
997
+
998
+ def _apply_fallback(claim: Claim) -> None:
999
+ """D2 exhausted / fallback branch -- pure code, no LLM call."""
1000
+ claim.confidence_tier = "UNVERIFIED"
1001
+ claim.annotation = (
1002
+ f"[UNVERIFIED] Could not be adequately verified after {claim.retry_count} "
1003
+ f"revision attempt(s). Treat with caution."
1004
+ )
1005
+ claim.final_text = claim.revision_text or claim.text
1006
+
1007
+
1008
+ def _revision_request(claim: Claim) -> dict:
1009
+ """One claim's entry in Pass 6a's batch: the claim and the feedback
1010
+ that put it there.
1011
+
1012
+ `disagreement_feedback` only on a contested claim (ROADMAP_v3 §90),
1013
+ because D1 may have flagged it for that alone, and 6a cannot address a
1014
+ reason it is not given. `revise.md` says what to do with one."""
1015
+ entry = {
1016
+ "claim": vars(claim),
1017
+ "critic_feedback": {"fallacies": claim.fallacies, "contradictions": claim.contradictions},
1018
+ "grounding_feedback": claim.grounding_sources,
1019
+ "assumption_flags": claim.assumption_flags,
1020
+ }
1021
+ if is_contested(claim):
1022
+ entry["disagreement_feedback"] = {
1023
+ # Deduplicated, as the consistency score it came from is (B8).
1024
+ "asserted_by": len(set(claim.asserted_by_candidates)),
1025
+ "of": claim.score_breakdown["consistency_denominator"],
1026
+ }
1027
+ return entry
1028
+
1029
+
1030
+ # ============================================================================
1031
+ # ---- The pipeline ------------------------------------------------------
1032
+ # ============================================================================
1033
+
1034
+ def run_pipeline_to_completion(gen) -> PipelineRun:
1035
+ """Consumes a stream_deep_research_pipeline() generator fully,
1036
+ discarding intermediate events, and returns the finished PipelineRun.
1037
+
1038
+ The exact counterpart of core.loop.run_to_completion(), including the
1039
+ RuntimeError: a generator that ends without its terminal event has a
1040
+ bug, and returning None instead would push the failure into whichever
1041
+ caller dereferences the run first.
1042
+ """
1043
+ final = None
1044
+ for event in gen:
1045
+ if event.kind == "run_complete":
1046
+ final = event.run
1047
+ if final is None:
1048
+ raise RuntimeError(
1049
+ "Pipeline generator completed without yielding a run_complete event"
1050
+ )
1051
+ return final
1052
+
1053
+
1054
+ def stream_deep_research_pipeline(
1055
+ user_query: str,
1056
+ model: str,
1057
+ provider_name: str = DEFAULT_PROVIDER,
1058
+ ensemble_mode: bool | None = None,
1059
+ ensemble_n: int | None = None,
1060
+ authorization=None,
1061
+ review=None,
1062
+ subagent_review: bool | None = None,
1063
+ effort: str | None = None,
1064
+ # §47. Threaded like `authorization` beside it, and for the same
1065
+ # reason: both are run-scoped values the layers between here and
1066
+ # the model call only forward. Batch 59 stopped at
1067
+ # stream_deep_research_mode's signature; this is the rest of it.
1068
+ activity=None,
1069
+ ):
1070
+ """The pipeline, as a generator of PipelineEvents (§22). The terminal
1071
+ `run_complete` event carries the finished PipelineRun.
1072
+
1073
+ ABANDONMENT (§22, recorded rather than fixed). A consumer that stops
1074
+ iterating early -- a TUI quitting mid-run -- raises GeneratorExit
1075
+ inside the try below, which `except Exception` deliberately does not
1076
+ catch. The record therefore stays status='running', populated through
1077
+ the last checkpoint. That is honest: the run was abandoned, not
1078
+ failed, and forcing 'failed' would make an interrupted run
1079
+ indistinguishable from a broken one. Both shipped consumers drain
1080
+ fully.
1081
+
1082
+ authorization (§25): a core.approval.RunAuthorization built by the
1083
+ shell that launched this run, or None for the pre-§25 behaviour (no
1084
+ grants, nobody to ask, every approval-gated tool hidden from every
1085
+ pass). Carried, not interpreted -- the decisions about WHAT may be
1086
+ granted live in core/reasoning/authorization.py, and the enforcement
1087
+ lives in core/loop.py.
1088
+
1089
+ review (§20): a core.interaction.ResponseChannel, or None (§23 moved
1090
+ it there from core.approval.ReviewConsent). Carried the same
1091
+ way and for the same reason -- only a shell knows how to reach a
1092
+ human. A SECOND parameter rather than a field on the authorization
1093
+ bundle: that bundle answers "may this gated call proceed?" and this
1094
+ answers "may this edit be applied?". None means nothing is applied,
1095
+ even when the review itself runs (V6).
1096
+
1097
+ subagent_review (§20/D9): whether the review stage runs at all. None
1098
+ falls back to config.SUBAGENT_REVIEW, matching ensemble_mode's
1099
+ pattern. Separate from `review` because --review on a piped run must
1100
+ still produce findings while applying nothing."""
1101
+ ensemble_mode = config.ENSEMBLE_MODE if ensemble_mode is None else ensemble_mode
1102
+ subagent_review = (config.SUBAGENT_REVIEW if subagent_review is None
1103
+ else subagent_review)
1104
+
1105
+ # §10 revisit (E4). `ensemble_n` is vestigial: N is len(ENSEMBLE_MODELS)
1106
+ # now, because a separately configured count could disagree with the
1107
+ # roster that produced the candidates, and the denominator of a
1108
+ # confidence score must not be able to lie. The parameter and the
1109
+ # settings.json key are KEPT rather than removed -- unknown settings keys
1110
+ # raise, so deleting the key would make every existing settings.json that
1111
+ # sets it fail to load.
1112
+ if ensemble_n is not None:
1113
+ logger.warning(
1114
+ "Ignoring ensemble_n=%s: the number of candidates is "
1115
+ "len(ensemble_models) now (ROADMAP §10 revisit, E3). "
1116
+ "Change the roster in config.yaml to change N.",
1117
+ ensemble_n,
1118
+ )
1119
+
1120
+ roster = _ensemble_roster(ensemble_mode)
1121
+
1122
+ run = PipelineRun(user_query=user_query)
1123
+
1124
+ # §45 (SQ2). RUN-SCOPED, and attached to every pass rather than only to
1125
+ # the two that ground. The question it answers is "what did this run
1126
+ # retrieve from this URL", which is not a per-pass question: a page
1127
+ # Pass 1 fetched and Pass 3a then cited without re-fetching is still
1128
+ # evidence about that URL, and scoping the corpus to 3a would report
1129
+ # no captured text for it and fall back to the model's own number.
1130
+ corpus = SourceCorpus()
1131
+
1132
+ # §45 (SQ2). Resolved ONCE, before Pass 0, so the warning about
1133
+ # running without one is the first thing the trace says rather than
1134
+ # something a reader meets forty lines in beside a score it already
1135
+ # explains. One scorer for the whole run, because its vector cache and
1136
+ # its give-up flag are both run-scoped: a claim is embedded once
1137
+ # however many sources it has, and a provider that is down stays down.
1138
+ scoring_knobs = effective_source_scoring(warn=True)
1139
+ scorer = make_scorer(run, floor=scoring_knobs["similarity_floor"],
1140
+ ceiling=scoring_knobs["similarity_ceiling"])
1141
+
1142
+ # §45 (SQ9). OFF by default, so an out-of-the-box run makes no call
1143
+ # the user did not ask for. One lookup object for the run, for the
1144
+ # scorer's reason: its cohort cache and its give-up flag are both
1145
+ # run-scoped.
1146
+ scholar = ScholarLookup(knobs=scoring_knobs)
1147
+
1148
+ # §45 (SQ6). Both knob sections resolved ONCE, here, with warn=True so
1149
+ # a mistyped weight is said once per run rather than once per claim --
1150
+ # `effective_compaction`'s gating, for its reason. score_claim stays a
1151
+ # pure function of its arguments, and a run's numbers cannot change
1152
+ # halfway through it.
1153
+ confidence_weights = effective_confidence(warn=True)
1154
+
1155
+ # §25 audit trail: ONE list, shared, not two kept in step. The run and
1156
+ # the authorization bundle now refer to the same object, so a granted
1157
+ # call is visible on the PipelineRun the moment it happens -- including
1158
+ # at every §5 checkpoint and on the FAILURE path, which is where an
1159
+ # unattended run's record matters most. Copying at the end instead
1160
+ # would lose the trail on exactly the runs most worth auditing, and two
1161
+ # writers of related data is the bug shape §22 warns about by name.
1162
+ if authorization is not None:
1163
+ run.granted_calls = authorization.granted_calls
1164
+
1165
+ # ROADMAP §5 minimal core: create the durable record up front. On a
1166
+ # mid-pipeline crash, the except block below flips status to 'failed'
1167
+ # and persists a snapshot of the partial run before re-raising.
1168
+ run.run_id = create_pipeline_run(user_query)
1169
+
1170
+ # ROADMAP §11: resolve critic provider/model once. When no critic is
1171
+ # configured these fall back to the main provider/model — no-op
1172
+ # routing.
1173
+ #
1174
+ # §45 (SQ7): through pipeline_models.resolve rather than
1175
+ # config.CRITIC_MODEL directly, so a `/critic` choice reaches the CLI,
1176
+ # the TUI and a spawned run alike. That function owns the precedence —
1177
+ # the user-tier store outranks config.py — and owning it in one place
1178
+ # is the point: §11 gave this routing to config.py alone, which meant
1179
+ # the methodology's own "a model must not check its own output" was
1180
+ # available only to whoever could edit the checkout.
1181
+ critic = pipeline_models.resolve("critic")
1182
+ critic_provider = critic["provider_name"] if critic else provider_name
1183
+ critic_model = critic["model"] if critic else model
1184
+
1185
+ progress = _Progress(run)
1186
+
1187
+ try:
1188
+ # --- Pass 0: preliminary plan ---
1189
+ run.plan = _parse_json_response((yield from _run_pass_with_json_retry("Pass 0", user_query, model, provider_name, run.trace, authorization=authorization, corpus=corpus, pass_threads=run.pass_threads, effort=effort, activity=activity)))
1190
+ yield from progress.checkpoint(f"Pass 0: plan produced ({len(run.plan.get('key_entities_or_subjects', []))} key entities anticipated).")
1191
+
1192
+ # --- Pass 1: initial generation (ensemble mode: N candidates) ---
1193
+ pass1_input = f"Original query:\n{user_query}\n\nPreliminary plan (loose context, may deviate freely):\n{json.dumps(run.plan)}"
1194
+ effective_n = 0
1195
+ if roster:
1196
+ # A LOOP, not a comprehension: _run_pass is a generator now
1197
+ # (§22), and a comprehension would collect generator objects
1198
+ # without ever running a pass.
1199
+ #
1200
+ # One candidate per roster entry, each on its OWN provider/model
1201
+ # (E1). No new plumbing: _run() calls api_initialization() itself
1202
+ # and effort_for() validates against the receiving model, so a
1203
+ # heterogeneous roster is correct by construction -- the same way
1204
+ # §11 already routes 3a/3b/6c to critic_provider/critic_model.
1205
+ candidates = []
1206
+ for entry in roster:
1207
+ label = f"{entry['provider_name']}/{entry['model']}"
1208
+ try:
1209
+ candidates.append((yield from _run_pass(
1210
+ "Pass 1", pass1_input, entry["model"], entry["provider_name"],
1211
+ authorization=authorization, trace=run.trace,
1212
+ pass_threads=run.pass_threads, effort=effort,
1213
+ activity=activity)))
1214
+ except Exception as e:
1215
+ # NAMED, TRACED, SKIPPED (E7) -- §20's containment rule.
1216
+ # An optional generation strategy must not flip a
1217
+ # ten-pass run to status='failed' because one provider
1218
+ # was unreachable. Same posture MCP takes per server.
1219
+ message = (f"Pass 1: ensemble candidate on {label} failed "
1220
+ f"({type(e).__name__}: {e}) — skipped.")
1221
+ logger.warning("%s", message)
1222
+ run.log(message)
1223
+ continue
1224
+ run.log(f"Pass 1: ensemble candidate {len(candidates)} generated on {label}.")
1225
+ # E13/#77: the record keeps every surviving candidate.
1226
+ # The metadata half sits beside the trace's candidate-N
1227
+ # lines so a stored asserted_by_candidates tag names
1228
+ # models this run can still identify; the text half feeds
1229
+ # the per-candidate artifacts and Pass 3b's input -- the
1230
+ # two places that must be able to check a claim against
1231
+ # what its number actually said. pipeline_storage strips
1232
+ # `text` at serialization; see PipelineRunRecord.
1233
+ run.candidates.append({
1234
+ "candidate": len(candidates),
1235
+ "provider_name": entry["provider_name"],
1236
+ "model": entry["model"],
1237
+ "chars": len(candidates[-1]),
1238
+ "text": candidates[-1],
1239
+ })
1240
+
1241
+ # Labels come from the SURVIVORS, never from position in the
1242
+ # roster (E11). Labelling by roster position leaves a gap when a
1243
+ # candidate fails -- "Candidate 1, Candidate 3" -- so Pass 2
1244
+ # would tag a claim both survivors asserted as [1, 3] while the
1245
+ # denominator said 2, and a unanimous claim would be scored as
1246
+ # dissented-against. A silently deflated confidence score is the
1247
+ # exact failure class this section exists to remove.
1248
+ effective_n = len(candidates)
1249
+ if effective_n >= 2:
1250
+ run.raw_response = candidates[0]
1251
+ pass2_input = "\n\n".join(
1252
+ f"Candidate {i + 1}:\n{c}" for i, c in enumerate(candidates)
1253
+ )
1254
+ run.log(f"Pass 1: ensemble mode — {effective_n} candidate(s) "
1255
+ f"across {effective_n} model(s); consistency is measured "
1256
+ f"out of {effective_n}.")
1257
+ else:
1258
+ # DEGRADE TO THE SINGLE-CANDIDATE PATH (E7), rather than
1259
+ # scoring one candidate as an ensemble of one -- which would
1260
+ # give every claim consistency 1.0, so none could ever be
1261
+ # contested, while reporting that agreement as if it had
1262
+ # been corroborated.
1263
+ # ensemble_n=0 is not a degraded formula, it is the correct
1264
+ # one when there is nothing to compare against.
1265
+ effective_n = 0
1266
+ if candidates:
1267
+ run.raw_response = candidates[0]
1268
+ pass2_input = f"Response to extract claims from:\n{run.raw_response}"
1269
+ run.log("Pass 1: only one ensemble candidate survived — "
1270
+ "no claim can be contested, since one candidate "
1271
+ "cannot disagree with itself.")
1272
+ else:
1273
+ raise RuntimeError(
1274
+ "Pass 1: every ensemble candidate failed; there is no "
1275
+ "response to extract claims from. See the trace for "
1276
+ "each provider's error."
1277
+ )
1278
+ else:
1279
+ run.raw_response = yield from _run_pass("Pass 1", pass1_input, model, provider_name, authorization=authorization, corpus=corpus, trace=run.trace, pass_threads=run.pass_threads, effort=effort, activity=activity)
1280
+ pass2_input = f"Response to extract claims from:\n{run.raw_response}"
1281
+ run.log("Pass 1: initial generation complete.")
1282
+ yield from progress.checkpoint()
1283
+
1284
+ # --- Pass 2: claim extraction & classification ---
1285
+ claims_json = _parse_json_response((yield from _run_pass_with_json_retry("Pass 2", pass2_input, model, provider_name, run.trace, authorization=authorization, corpus=corpus, pass_threads=run.pass_threads, ensemble=effective_n >= 2, effort=effort, activity=activity)))
1286
+ run.claims = [_claim_from_json(c) for c in claims_json]
1287
+ for claim in run.claims:
1288
+ yield PipelineEvent(kind="claim_extracted", claim_id=claim.id,
1289
+ text=claim.text)
1290
+ yield from progress.checkpoint(f"Pass 2: extracted {len(run.claims)} claim(s).")
1291
+
1292
+ # --- gate D0: route by claim type (pure code) ---
1293
+ factual_claims = [c for c in run.claims if c.type == "factual"]
1294
+ non_factual_claims = [c for c in run.claims if c.type != "factual"]
1295
+ yield from _stage("D0")
1296
+ yield from progress.checkpoint(
1297
+ f"D0: {len(factual_claims)} factual claim(s) routed to 3a/3b, "
1298
+ f"{len(non_factual_claims)} synthesis/speculative claim(s) routed directly to Pass 4."
1299
+ )
1300
+
1301
+ # --- Pass 3a + 3b: only for factual claims, batched by deduplicated entity ---
1302
+ if factual_claims:
1303
+ unique_entities = sorted({e for c in factual_claims for e in c.entities})
1304
+ pass3a_input = (
1305
+ f"Factual claims:\n{json.dumps([vars(c) for c in factual_claims])}\n\n"
1306
+ f"Deduplicated entities to research (search each ONCE, map results back "
1307
+ f"to every claim referencing it):\n{json.dumps(unique_entities)}"
1308
+ )
1309
+ # SCOPED TO `factual_claims`, like 6b to its batch (batch 220,
1310
+ # #247): 3a is shown the factual claims and nothing else, so an
1311
+ # entry naming another claim is dropped and traced rather than
1312
+ # marking a claim grounded that gate D0 routed past grounding.
1313
+ grounding_json = _parse_json_response((yield from _run_pass_with_json_retry("Pass 3a", pass3a_input, critic_model, critic_provider, run.trace, authorization=authorization, corpus=corpus, pass_threads=run.pass_threads, claim_ids=[c.id for c in factual_claims], effort=effort, activity=activity)))
1314
+ grounded = _ground_and_score(run, grounding_json, corpus, scorer,
1315
+ scoring_knobs, scholar,
1316
+ claims=factual_claims)
1317
+ yield from progress.checkpoint(f"Pass 3a: grounded {grounded} of {len(factual_claims)} factual claim(s), across {len(unique_entities)} deduplicated entities.")
1318
+ _note_entries_outside_the_batch(
1319
+ run, factual_claims, grounding_json, pass_id="Pass 3a",
1320
+ scope="the factual claims", asked="factual claim(s)",
1321
+ why="Gate D0 routes every other claim past 3a/3b, so grounding "
1322
+ "one would record a check gate D0 says never ran.")
1323
+
1324
+ # E13/#77. Two or more survivors: the claims were extracted
1325
+ # from the UNION of the candidates, so the critic sees every
1326
+ # candidate under the labels Pass 2 used -- a claim only
1327
+ # candidate 3 asserted is checked against text that actually
1328
+ # contains it, and contradictions ACROSS candidates are
1329
+ # findable. Handing it bare `raw_response` (candidate 1)
1330
+ # asked an ill-posed question: find conflicts within a text
1331
+ # much of your input did not come from.
1332
+ if len(run.candidates) >= 2:
1333
+ pass3b_input = (
1334
+ "\n\n".join(
1335
+ f"Candidate {entry['candidate']}:\n{entry['text']}"
1336
+ for entry in run.candidates)
1337
+ + f"\n\nFactual claims with grounding:\n{json.dumps([vars(c) for c in factual_claims])}"
1338
+ )
1339
+ else:
1340
+ pass3b_input = (
1341
+ f"Raw response:\n{run.raw_response}\n\n"
1342
+ f"Factual claims with grounding:\n{json.dumps([vars(c) for c in factual_claims])}"
1343
+ )
1344
+ critic_json = _parse_json_response((yield from _run_pass_with_json_retry("Pass 3b", pass3b_input, critic_model, critic_provider, run.trace, authorization=authorization, corpus=corpus, pass_threads=run.pass_threads, claim_ids=[c.id for c in factual_claims], effort=effort, activity=activity)))
1345
+ # The same scope as 3a, for a stronger reason: a non-factual
1346
+ # claim's score IS its capped critic component, so a severity
1347
+ # landing on one moved its tier (measured, batch 220).
1348
+ critiqued = _apply_critic(factual_claims, critic_json)
1349
+ yield from progress.checkpoint(f"Pass 3b: critique applied to {critiqued} of {len(factual_claims)} factual claim(s).")
1350
+ _note_entries_outside_the_batch(
1351
+ run, factual_claims, critic_json, pass_id="Pass 3b",
1352
+ scope="the factual claims", asked="factual claim(s)",
1353
+ why="Gate D0 routes every other claim past 3a/3b, and a "
1354
+ "severity on one would lower the score Pass 5 gives "
1355
+ "it.")
1356
+ else:
1357
+ # A stage, not a silence. "3a/3b did not run" is a fact about
1358
+ # the run's shape -- it means nothing was factual -- and a
1359
+ # panel that simply skipped from Pass 2 to Pass 3c would leave
1360
+ # the reader to infer it from an absence.
1361
+ yield from _stage("Pass 3a/3b")
1362
+ yield from progress.checkpoint("Pass 3a/3b: skipped -- no factual claims to ground or critique.")
1363
+
1364
+ # --- Pass 3c: completeness, independent of Pass 1's raw_response ---
1365
+ pass3c_input = f"Original query:\n{user_query}\n\nPreliminary plan:\n{json.dumps(run.plan)}"
1366
+ run.completeness = _parse_json_response((yield from _run_pass_with_json_retry("Pass 3c", pass3c_input, model, provider_name, run.trace, authorization=authorization, corpus=corpus, pass_threads=run.pass_threads, effort=effort, activity=activity)))
1367
+ yield from progress.checkpoint(
1368
+ f"Pass 3c: coverage_score={run.completeness.get('coverage_score')}, "
1369
+ f"{len(run.completeness.get('gaps', []))} gap(s) identified."
1370
+ )
1371
+
1372
+ # --- Pass 4: assumption audit -- ALL claims, plus completeness ---
1373
+ pass4_input = (
1374
+ f"Original query:\n{user_query}\n\n"
1375
+ f"All claims:\n{json.dumps([vars(c) for c in run.claims])}\n\n"
1376
+ f"Completeness findings:\n{json.dumps(run.completeness)}"
1377
+ )
1378
+ run.assumptions = _parse_json_response((yield from _run_pass_with_json_retry("Pass 4", pass4_input, model, provider_name, run.trace, authorization=authorization, corpus=corpus, pass_threads=run.pass_threads, claim_ids=[c.id for c in run.claims], effort=effort, activity=activity)))
1379
+ flagged_count = _apply_assumption_flags(run.claims, run.assumptions)
1380
+ yield from progress.checkpoint(f"Pass 4: assumption audit complete, {flagged_count} of {len(run.claims)} claim(s) flagged.")
1381
+
1382
+ # --- Pass 5: confidence tiering (0 LLM calls) ---
1383
+ run_confidence_tiering(run, ensemble_n=effective_n,
1384
+ sources_scored=_sources_were_scored(run),
1385
+ weights=confidence_weights)
1386
+ yield from _stage("Pass 5")
1387
+ yield from _tier_events(run)
1388
+ yield from progress.checkpoint("Pass 5: confidence tiers assigned (pure code, zero LLM calls).")
1389
+
1390
+ # --- D1 + the 6a/6b/D2 retry loop ---
1391
+ # ROADMAP_v3 §90 (A85). D1 also takes the claims most ensemble
1392
+ # candidates did not assert, whatever they scored: disagreement is
1393
+ # a reason to check a claim, and the loop is where claims are
1394
+ # checked. ENTRY ONLY -- `still_flagged` below reads the tier alone.
1395
+ # Who asserted a claim does not change when 6a rewrites it, so a
1396
+ # loop that kept a contested claim for being contested would hold
1397
+ # it to D2's cap and publish it UNVERIFIED, which is the defect the
1398
+ # E8 penalty had.
1399
+ flagged = [c for c in run.claims
1400
+ if c.confidence_tier in FLAGGED_TIERS or is_contested(c)]
1401
+ contested = sum(1 for c in flagged if is_contested(c))
1402
+ yield from _stage("D1")
1403
+ yield from progress.checkpoint(
1404
+ f"D1: {len(flagged)} claim(s) flagged for revision"
1405
+ + (f" ({contested} contested by the ensemble)" if contested else "")
1406
+ + f", {len(run.claims) - len(flagged)} already clean.")
1407
+
1408
+ while flagged:
1409
+ # --- Pass 6a: ONE batched call across every currently-flagged claim ---
1410
+ pass6a_input = json.dumps([_revision_request(c) for c in flagged])
1411
+ revisions = _parse_json_response((yield from _run_pass_with_json_retry("Pass 6a", pass6a_input, model, provider_name, run.trace, authorization=authorization, corpus=corpus, pass_threads=run.pass_threads, claim_ids=[c.id for c in flagged], effort=effort, activity=activity)))
1412
+
1413
+ # COUNT THE ROUND, NOT THE REVISION. The increment used to live
1414
+ # inside the loop below, so only a claim Pass 6a NAMED counted --
1415
+ # and 6a is one batched call across every flagged claim, which is
1416
+ # exactly the shape a model drops an item from. A claim it omitted
1417
+ # could never reach D2's cap, so `while flagged:` had no bound at
1418
+ # all: two model calls per round, for ever. An omission, an empty
1419
+ # list and an
1420
+ # unknown id are indistinguishable here -- the lookup returns None
1421
+ # and the `if claim:` skips in silence -- which is why the bound
1422
+ # cannot be data the model supplies.
1423
+ #
1424
+ # Counting the round makes D2's cap bound the loop by
1425
+ # construction, and since `flagged` only ever shrinks, every claim
1426
+ # still in it exhausts on the same round.
1427
+ for claim in flagged:
1428
+ claim.retry_count += 1
1429
+
1430
+ revised = 0
1431
+ for rev in revisions:
1432
+ # Resolved WITHIN the batch, first-wins like
1433
+ # PipelineRun.claim_by_id: 6a was only asked about `flagged`,
1434
+ # and a revision naming a claim outside it would land on one
1435
+ # already finished -- while carrying a retry_count this round
1436
+ # did not increment, so the event below would report a stale
1437
+ # attempt number.
1438
+ claim = next((c for c in flagged if c.id == rev["claim_id"]), None)
1439
+ if claim:
1440
+ revised += 1
1441
+ claim.revision_text = rev["revised_text"]
1442
+ # §22's "which claim, which attempt" -- emitted from the
1443
+ # claim retry loop, which is the retry the section means.
1444
+ # A JSON-parse retry is a different thing and reaches the
1445
+ # consumer as a trace_line, via json_retry.py's own line.
1446
+ yield PipelineEvent(kind="retry", claim_id=claim.id,
1447
+ attempt=claim.retry_count)
1448
+ yield from progress.checkpoint(f"Pass 6a: revised {revised} of {len(flagged)} claim(s) in this retry round.")
1449
+ # The count above shows that something was dropped, not why
1450
+ # (#248). The comment on the loop bound is about the BOUND,
1451
+ # which the round counter settled; a reader of the trace still
1452
+ # needs to tell an omission from a misdirected revision.
1453
+ _note_entries_outside_the_batch(
1454
+ run, flagged, revisions, pass_id="Pass 6a",
1455
+ scope="this round's batch", asked="flagged claim(s)",
1456
+ why="a revision to a claim D1 had already finished with "
1457
+ "would replace its text without re-validating it.")
1458
+
1459
+ # --- Pass 6b: re-validate the revised subset only (batched, reuses Pass 5's code) ---
1460
+ pass6b_input = json.dumps([vars(c) for c in flagged])
1461
+ # SCOPED TO `flagged`, ALL THREE OF THEM -- the ids validated
1462
+ # against, the claims the entries are applied to, and the
1463
+ # claims whose sources are rescored (§66 A26). 6a was already
1464
+ # resolved within the batch, with the reason written beside it
1465
+ # ("a revision naming a claim outside it would land on one
1466
+ # already finished"); 6b validated against every id in the run
1467
+ # and applied to every claim in it, while the re-tiering below
1468
+ # stayed narrow. So an entry naming a clean claim changed its
1469
+ # grounding and left its tier alone: driven, a HIGH claim
1470
+ # ended up `grounding_status='ungrounded'` with `sources=[]`
1471
+ # beside a breakdown still recording `source_count: 1` -- which
1472
+ # breaks B10's property that the breakdown alone lets a reader
1473
+ # recompute the score.
1474
+ revalidation = _parse_json_response((yield from _run_pass_with_json_retry("Pass 6b", pass6b_input, critic_model, critic_provider, run.trace, authorization=authorization, corpus=corpus, pass_threads=run.pass_threads, claim_ids=[c.id for c in flagged], effort=effort, activity=activity)))
1475
+ grounding_entries = revalidation.get("grounding", [])
1476
+ critic_entries = revalidation.get("critic", [])
1477
+ _ground_and_score(run, grounding_entries, corpus,
1478
+ scorer, scoring_knobs, scholar, claims=flagged)
1479
+ _apply_critic(flagged, critic_entries)
1480
+ _note_entries_outside_the_batch(
1481
+ run, flagged, grounding_entries, critic_entries,
1482
+ pass_id="Pass 6b", scope="this round's batch",
1483
+ asked="flagged claim(s)",
1484
+ why="applying an answer to a claim D1 had already finished "
1485
+ "with would change its grounding without recomputing "
1486
+ "its tier.")
1487
+ # 6b's own checkpoint below already reports an EFFECT -- how
1488
+ # many claims came out clean -- rather than what it was asked
1489
+ # about, so it needs no count from these two.
1490
+ # Pass 5's function again -- code, not a call. Scoped to THIS
1491
+ # round's batch: 6b is only asked about `flagged`, and re-tiering
1492
+ # the whole run once per round recomputes claims that are already
1493
+ # finished, from score data those rounds did not change.
1494
+ run_confidence_tiering(run, ensemble_n=effective_n, claims=flagged,
1495
+ sources_scored=_sources_were_scored(run),
1496
+ weights=confidence_weights)
1497
+ yield from _tier_events(run)
1498
+
1499
+ still_flagged = [c for c in flagged if c.confidence_tier in FLAGGED_TIERS]
1500
+ yield from progress.checkpoint(f"Pass 6b: {len(flagged) - len(still_flagged)} claim(s) now clean, {len(still_flagged)} still flagged.")
1501
+
1502
+ # --- D2: retry cap check (pure code) ---
1503
+ exhausted = [c for c in still_flagged if c.retry_count >= MAX_RETRIES]
1504
+ if exhausted:
1505
+ # ONCE per round, outside the per-claim loop. D2 is one
1506
+ # decision applied to every claim that ran out of retries;
1507
+ # emitting inside the loop would put a D2 row in the panel
1508
+ # per claim, so a round that exhausted six claims would
1509
+ # read as six separate stages.
1510
+ yield from _stage("D2")
1511
+ for c in exhausted:
1512
+ _apply_fallback(c)
1513
+ yield PipelineEvent(kind="claim_tiered", claim_id=c.id,
1514
+ tier=c.confidence_tier)
1515
+ yield from progress.checkpoint(f"D2: claim {c.id} exhausted retries ({c.retry_count}) -> fallback UNVERIFIED.")
1516
+
1517
+ flagged = [c for c in still_flagged if c.retry_count < MAX_RETRIES]
1518
+
1519
+ # --- Pass 6c: annotate (templated, 0 LLM calls) ---
1520
+ for claim in run.claims:
1521
+ if claim.final_text is None:
1522
+ claim.final_text = claim.revision_text or claim.text
1523
+ if claim.annotation is None:
1524
+ claim.annotation = f"[{claim.confidence_tier}]"
1525
+ yield from _stage("Pass 6c")
1526
+ yield from progress.checkpoint("Pass 6c: annotation complete (templated, zero LLM calls).")
1527
+
1528
+ # --- Merge (pure code) ---
1529
+ yield from _stage("Merge")
1530
+ yield from progress.checkpoint(f"Merge: final claim set assembled -- {len(run.claims)} claim(s), {len(run.coverage_gaps)} coverage gap(s).")
1531
+
1532
+ # --- Final synthesis ---
1533
+ run.final_report = yield from _run_pass("Final synthesis", _synthesis_input(run), model, provider_name, authorization=authorization, corpus=corpus, trace=run.trace, pass_threads=run.pass_threads, effort=effort, activity=activity)
1534
+ yield from progress.checkpoint("Final synthesis complete.")
1535
+
1536
+ # --- §20: review, consent, correct ---
1537
+ yield from _review_stage(run, progress, model, provider_name,
1538
+ authorization, review,
1539
+ enabled=subagent_review, effort=effort,
1540
+ activity=activity)
1541
+
1542
+ update_pipeline_run(run.run_id, run, status="complete")
1543
+ yield PipelineEvent(kind="run_complete", run=run)
1544
+ return
1545
+ except Exception:
1546
+ # Persist the partial state before the exception propagates. The
1547
+ # update is best-effort: if storage itself is what failed, we must
1548
+ # not mask the original error, so a second failure here is logged
1549
+ # (via the real logger -- it reaches stderr through Python's
1550
+ # lastResort handler even before logging_setup is wired in) and the
1551
+ # original exception still re-raises. run.log() would be inert here:
1552
+ # the propagated exception carries no reference back to this local
1553
+ # `run`, and persistence already failed, so a trace entry would
1554
+ # never reach anywhere durable.
1555
+ try:
1556
+ update_pipeline_run(run.run_id, run, status="failed")
1557
+ except Exception as persist_error:
1558
+ logger.error(
1559
+ f"Failed to persist failure state for run {run.run_id}: {persist_error}"
1560
+ )
1561
+ raise