@yahyahammad/venastine 0.3.8 → 0.3.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (128) hide show
  1. package/.env.example +19 -19
  2. package/CONFIG_ARCHITECTURE.md +2030 -2002
  3. package/LICENSE +201 -201
  4. package/README.md +1034 -1034
  5. package/agents/builtin/compactor.md +75 -75
  6. package/agents/builtin/explore.md +77 -77
  7. package/agents/builtin/pipeline-reviewer.md +100 -100
  8. package/agents/builtin/plan.md +106 -106
  9. package/agents/builtin/review.md +74 -74
  10. package/agents/manager.py +261 -261
  11. package/agents/subagent_tool.py +472 -472
  12. package/agents/tui_commands.py +238 -146
  13. package/bin/venastine.mjs +528 -528
  14. package/bin/venastine.py +71 -71
  15. package/cli_commands.py +838 -835
  16. package/config.yaml +13 -0
  17. package/config_edit.py +1301 -1301
  18. package/config_schema.py +971 -966
  19. package/config_update.py +749 -749
  20. package/core/agent_activity.py +256 -256
  21. package/core/ansi.py +452 -452
  22. package/core/approval.py +137 -137
  23. package/core/call_view.py +364 -364
  24. package/core/cancel.py +121 -121
  25. package/core/chatgpt_auth.py +747 -747
  26. package/core/claims_view.py +107 -107
  27. package/core/client.py +2715 -2715
  28. package/core/commands.py +460 -454
  29. package/core/compaction.py +1735 -1735
  30. package/core/config_loader.py +1982 -1982
  31. package/core/connect.py +686 -686
  32. package/core/events.py +123 -123
  33. package/core/file_mentions.py +280 -280
  34. package/core/interaction.py +411 -411
  35. package/core/loop.py +2566 -2566
  36. package/core/memory.py +482 -482
  37. package/core/pipeline_models.py +190 -190
  38. package/core/provider_errors.py +234 -234
  39. package/core/reasoning/authorization.py +130 -130
  40. package/core/reasoning/base.py +219 -219
  41. package/core/reasoning/confidence_scoring.py +484 -484
  42. package/core/reasoning/events.py +149 -149
  43. package/core/reasoning/orchestrator.py +1561 -1561
  44. package/core/reasoning/output_writer.py +345 -345
  45. package/core/reasoning/payload_validation.py +524 -524
  46. package/core/reasoning/pipeline_storage.py +427 -427
  47. package/core/reasoning/scholar.py +458 -458
  48. package/core/reasoning/source_corpus.py +433 -433
  49. package/core/reasoning/source_scoring.py +855 -855
  50. package/core/replay.py +315 -315
  51. package/core/shell_sessions.py +1553 -1553
  52. package/credentials.py +307 -307
  53. package/database.py +333 -333
  54. package/docs/PRIVACY.md +78 -78
  55. package/docs/SECURITY.md +108 -108
  56. package/docs/THIRD_PARTY_NOTICES.md +148 -148
  57. package/env_secrets.py +118 -118
  58. package/json_store.py +343 -343
  59. package/logging_setup.py +295 -295
  60. package/main.py +3433 -3433
  61. package/mcp_client/client.py +733 -733
  62. package/mcp_client/config.py +484 -484
  63. package/mcp_client/registration.py +343 -343
  64. package/memories/manager.py +147 -147
  65. package/memories/tui_commands.py +319 -239
  66. package/package.json +303 -303
  67. package/project_init/config_files.py +282 -282
  68. package/project_init/generator.py +728 -728
  69. package/project_init/manifest.py +418 -418
  70. package/project_init/tui_commands.py +147 -147
  71. package/prompts/critic_pass.md +24 -24
  72. package/prompts/revalidate.md +25 -25
  73. package/prompts/revise.md +17 -17
  74. package/prompts/source_grounding.md +66 -66
  75. package/prompts/system_prompts.py +316 -316
  76. package/providers.json.example +94 -94
  77. package/pyproject.toml +149 -149
  78. package/requirements.txt +295 -295
  79. package/safety/policy_enforcement.py +1082 -1082
  80. package/security/askpass.py +419 -419
  81. package/security/capability.py +207 -207
  82. package/security/confine.py +484 -484
  83. package/security/hosted.py +182 -182
  84. package/security/permissions.py +237 -237
  85. package/security/protected_paths.py +501 -501
  86. package/security/sandbox.py +4108 -4108
  87. package/skills/builtin/math/formal-specification.md +67 -67
  88. package/skills/builtin/math/numerical-methods.md +66 -66
  89. package/skills/builtin/research/experiment-design.md +62 -62
  90. package/skills/builtin/research/reproducibility.md +55 -55
  91. package/skills/builtin/research/source-evaluation.md +70 -70
  92. package/skills/builtin/research/statistical-inference.md +63 -63
  93. package/skills/builtin/research/technical-writing.md +59 -59
  94. package/skills/builtin/software/code-review.md +61 -61
  95. package/skills/builtin/software/debugging.md +61 -61
  96. package/skills/builtin/software/test-design.md +67 -67
  97. package/skills/tui_commands.py +110 -110
  98. package/storage.py +1338 -1338
  99. package/tools/base.py +465 -465
  100. package/tools/builtin/_math_common.py +667 -667
  101. package/tools/builtin/_net_common.py +267 -267
  102. package/tools/builtin/arxiv.py +681 -681
  103. package/tools/builtin/fetch_url.py +371 -371
  104. package/tools/builtin/file_ops.py +720 -720
  105. package/tools/builtin/geometry.py +184 -184
  106. package/tools/builtin/load_skill.py +76 -76
  107. package/tools/builtin/pin.py +227 -227
  108. package/tools/builtin/probability_stats.py +224 -224
  109. package/tools/builtin/project_docs.py +464 -464
  110. package/tools/builtin/remember.py +175 -175
  111. package/tools/builtin/shell.py +980 -980
  112. package/tools/builtin/todo.py +149 -149
  113. package/tools/builtin/web_search.py +328 -328
  114. package/tools/context.py +159 -159
  115. package/tools/isolation.py +387 -387
  116. package/tools/registry.py +1242 -1242
  117. package/tui/app.py +8318 -8307
  118. package/tui/app.tcss +747 -739
  119. package/tui/commands.py +26 -26
  120. package/tui/diffs.py +286 -286
  121. package/tui/history.py +128 -128
  122. package/tui/hosted_driver.py +102 -102
  123. package/tui/markdown.py +1329 -1329
  124. package/tui/meters.py +364 -364
  125. package/tui/ravens.py +146 -146
  126. package/tui/screens.py +1255 -1197
  127. package/tui/themes.py +599 -599
  128. package/tui/widgets.py +3813 -3796
package/core/loop.py CHANGED
@@ -1,2566 +1,2566 @@
1
- """
2
- core/loop.py
3
-
4
- RunAgentLoop._run() is the shared ReAct control flow: call the model,
5
- dispatch any tool calls via the registry, feed results back, repeat until
6
- the model responds with plain text or max_steps is hit. Both public
7
- methods below configure and call this same shared method -- neither
8
- reimplements the loop, so there's exactly one place the mechanics live.
9
-
10
- §13 streaming refactor: _run() is now a generator yielding LoopEvent
11
- objects. run_to_completion() drains it for callers that only need the
12
- final ModelResponse (the three public wrappers). The generator shape
13
- lets the TUI observe token deltas, tool calls, and permission prompts
14
- in real time without callbacks.
15
-
16
- §15 permission refactor: _run()'s old `allowed_tools` list is replaced by
17
- an optional ToolContext, which carries the same restriction plus approval
18
- overrides and subagent depth. One representation, threaded to the one
19
- place that enforces it (registry -> security.permissions), instead of the
20
- loop keeping a parallel membership check of its own.
21
-
22
- D20 invariant: memory.add_assistant_message(response) executes
23
- immediately after every call_model_stream return and BEFORE any
24
- stop-condition branch. This ordering is load-bearing — persisting only
25
- on the tool-calling path silently drops plain-text final answers and
26
- budget-truncated responses.
27
- """
28
-
29
- import logging
30
- import queue
31
- import threading
32
-
33
- # §47 slice 8 (NA10). Threads rather than asyncio: `_run` is a synchronous
34
- # generator and everything under it is blocking I/O, so a bounded pool is
35
- # the change that fits what is already here. `copy_context` is what makes
36
- # a submitted call carry the parent span batch 67 put on a ContextVar.
37
- from concurrent.futures import ThreadPoolExecutor
38
- from contextlib import nullcontext
39
- from contextvars import copy_context
40
- from dataclasses import dataclass, field
41
- from datetime import UTC
42
- from typing import Optional
43
- from uuid import UUID
44
-
45
- import config
46
- import prompts.system_prompts as system_prompts
47
- from core import agent_activity, interaction, provider_errors
48
- from core.cancel import is_cancelled
49
- from core.client import (
50
- ModelResponse,
51
- accepts_images,
52
- api_initialization,
53
- call_model_stream,
54
- context_window_for,
55
- effort_for,
56
- )
57
- from core.events import LoopEvent
58
- from core.memory import ConversationMemory
59
- from safety.policy_enforcement import redact_diagnostic_text
60
-
61
- # §27 (T1). The loop is where a thread's kind is DECIDED -- it knows which
62
- # of its three entry points is running -- and storage.create_thread is
63
- # where it is stored. Nothing in between learns what a kind means.
64
- from storage import (
65
- THREAD_KIND_CHAT,
66
- THREAD_KIND_RESEARCH_PASS,
67
- THREAD_KIND_SUBAGENT,
68
- )
69
- from tools.base import GRANT_NEVER
70
- from tools.context import RunInfo, ToolContext
71
- from tools.registry import ToolCallDenied, registry
72
-
73
- logger = logging.getLogger(__name__)
74
-
75
- # §32 A8 (#72). "You are a helpful assistant." was the whole of it,
76
- # and everything else in a chat prompt is generated or thread state --
77
- # the two catalogs, with_goal, with_memories, with_refs, with_todos,
78
- # and any active skill bodies. So the one paragraph a chat turn most
79
- # needs was the one part no tier supplied.
80
- #
81
- # Shared with the ten research passes rather than copied: see
82
- # prompts/untrusted_content and system_prompts.untrusted_content_paragraph.
83
- DEFAULT_SYSTEM_PROMPT = (
84
- "You are a helpful assistant.\n\n"
85
- + system_prompts.untrusted_content_paragraph(
86
- system_prompts.CHAT_INSTRUCTION_SOURCE))
87
- DEFAULT_PROVIDER = "ANTHROPIC"
88
-
89
- # The headless callability notice (§18) names tools hidden by
90
- # schemas(callable_only=True). Deduplicated on the HIDDEN SET, not once
91
- # per process: the set is context-dependent, so a once-per-process flag
92
- # reported only the first run's and left every later one silent. A
93
- # subagent whose definition tightens approval for another tool hides a
94
- # strictly larger set, and that difference was exactly what never got
95
- # logged -- the quiet invisibility this notice exists to prevent.
96
- _headless_notices_shown: set = set()
97
-
98
- # ROADMAP_v3 §81 (IM6), on the headless notice's terms: a tool the user
99
- # enabled and this run leaves out because no image could reach the model is
100
- # named once, deduplicated on (provider, thread kind, hidden set) -- the three
101
- # things the answer depends on, so a later run that differs in any of them
102
- # still hears about its own.
103
- _image_notices_shown: set = set()
104
-
105
-
106
- def _images_deliverable(provider_name: str, memory) -> bool:
107
- """Whether an image in a tool result can reach the model in this run
108
- (IM6): the provider takes images, and the thread is not a research
109
- pass. A property of WHAT THE THREAD IS, for
110
- `_derived_compaction_mode`'s reason: a pass re-entered by a JSON retry
111
- or the reviewer is still a pass. Its sources, claims and grounding are
112
- all text, so a pass is never offered an image tool (§81 leaves the
113
- pipeline out of scope)."""
114
- kind = getattr(memory, "kind", THREAD_KIND_CHAT)
115
- return kind != THREAD_KIND_RESEARCH_PASS and accepts_images(provider_name)
116
-
117
-
118
- def with_goal(system_prompt: str, memory: ConversationMemory) -> str:
119
- """Append a thread's persistent objective (§18 goal mode) to a system
120
- prompt. Single source for the '## Persistent objective' marker so the
121
- CLI wrapper and the TUI worker cannot drift apart. No-op when the
122
- thread has no goal."""
123
- goal = memory.extra.get("goal")
124
- if not goal:
125
- return system_prompt
126
- return f"{system_prompt}\n\n## Persistent objective\n{goal}"
127
-
128
-
129
- def with_persona(system_prompt: str, model: str, provider_name: str) -> str:
130
- """Append the live chat identity (ROADMAP_v3 §58, PR1-PR4).
131
-
132
- Callers resolve agent overrides first. Kept outside with_catalogs so
133
- research passes, the compactor and the reviewer retain their own
134
- task-specific prompts.
135
- """
136
- return (
137
- f"{system_prompt}\n\nYou are running in Venastine Research Harness, "
138
- "a tool-using assistant with a separate multi-pass research mode. "
139
- f"Your current model is {model} from {provider_name}.")
140
-
141
-
142
- def with_todos(system_prompt: str, memory: ConversationMemory) -> str:
143
- """Append §23's todo list to a prompt. No-op when the thread has none.
144
-
145
- Beside with_goal and taking the same argument, for the same reason: a
146
- checklist is a property of the THREAD, not of the agent or the session.
147
- It survives a resume and applies whichever agent is active.
148
-
149
- MUST NOT move inside prompts.system_prompts.with_catalogs(). That
150
- function feeds pass_prompt(), so a checklist written in a chat session
151
- would land in all ten passes of a research run the user started
152
- separately -- §19's K6, FOURTH instance, after §21b's memories (M13) and
153
- §21c's refs (M19). Four copies of one warning made the convergence a
154
- recorded deferral (J11); since batch 227 every tier is appended by
155
- session_tiers, and SESSION_TIERS is the list the boundary test pins.
156
-
157
- THE MODEL IS TOLD IT OWNS THIS. Unlike a memory or a reference, which
158
- are context the model reads, the todo list is state the model WRITES --
159
- so the fragment has to say that the way to change it is to call the
160
- tool, or the model reports progress in prose while the panel the user is
161
- watching stays stale.
162
- """
163
- todos = memory.extra.get("todos") or []
164
- if not todos:
165
- return system_prompt
166
-
167
- lines = ["## Your checklist for this conversation",
168
- "",
169
- "You maintain this with `todo_write`, which replaces the whole "
170
- "list. Keep it current as you work -- the user can see it.",
171
- ""]
172
- for item in todos:
173
- status = item.get("status", "pending")
174
- marker = {"completed": "[x]", "in_progress": "[>]"}.get(status, "[ ]")
175
- lines.append(f"{marker} {item.get('content', '')}")
176
- return f"{system_prompt}\n\n" + "\n".join(lines)
177
-
178
-
179
- def with_memories(system_prompt: str, agent=None) -> str:
180
- """Append §21b's durable-memory tier to a prompt. No-op when this run
181
- is opted out or nothing is in scope.
182
-
183
- Beside with_goal for the same reason: a single named function is what
184
- stops the CLI and the TUI drifting apart. Both reach it through
185
- session_tiers now (batch 227), which applies it only when no agent
186
- built the prompt -- an agent's memories arrive in system_prompt_for().
187
-
188
- MUST NOT move inside prompts.system_prompts.with_catalogs() -- that
189
- feeds pass_prompt(), so memories would land in all ten research passes.
190
- §19's K6, second instance.
191
- """
192
- from memories.manager import manager as memory_manager
193
-
194
- fragment = memory_manager.prompt_fragment(agent)
195
- if not fragment:
196
- return system_prompt
197
- return f"{system_prompt}\n\n{fragment}"
198
-
199
-
200
- def with_refs(system_prompt: str, memory: ConversationMemory) -> str:
201
- """Append §21c's referenced-conversation tier to a prompt. No-op when the
202
- thread has no references attached.
203
-
204
- Beside with_goal and taking the same argument, because a reference is a
205
- property of the THREAD rather than of the agent or the session: it was
206
- attached to this conversation by a person, it persists across a resume,
207
- and it applies whichever agent happens to be active. That is also why it
208
- is not routed through agents.manager.system_prompt_for() the way §21b's
209
- memories are -- that function has no memory object, and refs are not an
210
- agent's opt-in.
211
-
212
- MUST NOT move inside prompts.system_prompts.with_catalogs(). That function
213
- feeds pass_prompt(), so a reference attached in a chat session would land
214
- in all ten passes of a research run the user started separately. §19's K6,
215
- THIRD instance -- after §21b's memories, which is recorded as M13.
216
-
217
- THE SUMMARIES ARE ANNOUNCED AS SUMMARIES OF SOMETHING ELSE. A referenced
218
- thread is not this conversation's history, and a model that cannot tell
219
- the difference will answer as though the user said things they said
220
- elsewhere. Same reason §21a's compaction summary carries SUMMARY_PREFIX.
221
- """
222
- refs = memory.extra.get("refs") or []
223
- if not refs:
224
- return system_prompt
225
-
226
- # CAPPED, AND THE CAP IS STATED IN THE TEXT (M14). The attach path already
227
- # refuses to exceed it, so this is the second line of defence rather than
228
- # the first -- but MAX_INJECTED_REFS can be lowered between sessions, and a
229
- # thread carrying four refs under a cap of three must drop one visibly
230
- # rather than silently.
231
- cap = config.MAX_INJECTED_REFS
232
- shown, total = refs[:cap], len(refs)
233
- header = ("## Referenced conversations\n\n"
234
- "Distilled summaries of OTHER conversations, attached by the "
235
- "user for context. They are NOT part of this conversation's "
236
- "history -- nothing here was said to you in this thread.")
237
- if total > cap:
238
- logger.warning(
239
- "Injecting %s of %s attached references; the rest are not in this "
240
- "prompt. Raise config.MAX_INJECTED_REFS or drop one with "
241
- "/ref --clear.", cap, total)
242
- header = (f"{header}\n\nShowing {cap} of {total} attached references. "
243
- f"The others exist and are not included here.")
244
-
245
- lines = [header]
246
- for ref in shown:
247
- label = ref.get("label") or "(no preview)"
248
- lines.append(f"\n### {label}\n(thread {ref.get('thread_id')})\n"
249
- f"{ref.get('summary', '')}")
250
- return f"{system_prompt}\n\n" + "\n".join(lines)
251
-
252
-
253
- def with_file_mentions(system_prompt: str, memory: ConversationMemory, *,
254
- text: str | None = None) -> str:
255
- """§54 AT6/AT7: names from this user turn, never file contents.
256
-
257
- Do not move into with_catalogs: research passes and internal tasks do
258
- not inherit chat mentions. Reading still goes through the normal tool
259
- permissions, including paths outside the file-tool workspace.
260
- """
261
- from core import config_loader
262
- from core.file_mentions import mentions
263
-
264
- root = config_loader.get_project_path()
265
- if not root:
266
- return system_prompt
267
- if text is None:
268
- latest = next((row for row in reversed(memory.messages)
269
- if row.get("role") == "user" and not row.get("harness")), {})
270
- text = latest.get("content", "")
271
- paths = list(dict.fromkeys(item.path for item in mentions(text)))
272
- if not paths:
273
- return system_prompt
274
- import json
275
-
276
- fragment = (
277
- "## File mentions in the current user turn\n\n"
278
- "The user named these paths relative to project root " + json.dumps(root) + ". "
279
- "Resolve them against that root when calling file tools; the tools' workspace may differ. "
280
- "Read the named files with your tools as needed for the request; their contents "
281
- "have NOT been loaded. A trailing / names a folder: inspect it as needed, "
282
- "without assuming its files were included. Paths may have been deleted; "
283
- "report a missing path rather than guessing its contents. These names grant "
284
- "no additional file access; normal tool permissions and approvals apply.\n"
285
- + "\n".join("- " + json.dumps(path, ensure_ascii=False) for path in paths))
286
- return f"{system_prompt}\n\n{fragment}"
287
-
288
-
289
- #: The tiers a conversation turn appends after its base prompt, in the
290
- #: order `session_tiers` appends them (#9, J11, A80). Each is thread or
291
- #: session state, so none may move inside
292
- #: prompts.system_prompts.with_catalogs(), which feeds pass_prompt(): §19's
293
- #: K6. The BASE is not a tier -- the persona and the catalogs, and for an
294
- #: agent its body and the project hub, which system_prompt_for() composes.
295
- #: tests/test_prompt_tier_boundary.py keeps a canary for every name here.
296
- SESSION_TIERS = ("goal", "memories", "refs", "todos", "file_mentions",
297
- "skill_bodies")
298
-
299
-
300
- def session_tiers(system_prompt: str, memory: ConversationMemory, *,
301
- agent_built: bool, mentions: bool = True,
302
- mention_text: str | None = None, active_skills=()) -> str:
303
- """Every session tier, in SESSION_TIERS' order: the ONE assembly a
304
- conversation prompt takes, in either shell (#9, J11, A80).
305
-
306
- Three call sites assembled this by hand -- a loop turn, a TUI turn and
307
- the TUI's one-shot -- in the same order, with the memories guard
308
- spelled three ways. They call this now, and the guard is one argument.
309
-
310
- `agent_built` IS THE LOAD-BEARING DIFFERENCE, and the reason this takes
311
- a flag rather than making every tier conditional alike. An agent's
312
- prompt got its memories inside system_prompt_for() (§21b, M13), so
313
- appending them here would duplicate them. Refs, the checklist and the
314
- goal are thread state, not an agent's opt-in, so an agent-built prompt
315
- needs them too, and system_prompt_for() has no memory to read them
316
- from (§21c, M19). Making them conditional "like the line above" is the
317
- edit that looks right and drops every attached reference.
318
-
319
- `mentions` is off for an internal compaction or review turn: its
320
- source material is not a person's file-mention request (§54 AT7).
321
- `mention_text` is the one-shot's message, which is not written to the
322
- thread until its worker runs.
323
-
324
- Active skill bodies go LAST on purpose (§19 K1): an activated skill is
325
- the most specific instruction the user has given, and should read as
326
- governing what precedes it. The CLI's arrive through
327
- `run_agent_conversation` and `wake_conversation` since ROADMAP_v3 §89.
328
- """
329
- from skills.manager import manager as skills
330
-
331
- prompt = with_goal(system_prompt, memory)
332
- if not agent_built:
333
- prompt = with_memories(prompt)
334
- prompt = with_refs(prompt, memory)
335
- prompt = with_todos(prompt, memory)
336
- if mentions:
337
- prompt = with_file_mentions(prompt, memory, text=mention_text)
338
- fragment = skills.prompt_fragment(list(active_skills or ()))
339
- return f"{prompt}\n\n{fragment}" if fragment else prompt
340
-
341
-
342
- @dataclass(frozen=True)
343
- class AgentTurn:
344
- """What a session's active agent makes of one conversation turn."""
345
-
346
- model: str
347
- provider_name: str
348
- context: Optional[ToolContext]
349
- # None runs the default prompt, which the loop builds itself.
350
- system_prompt: Optional[str]
351
- max_steps: int
352
-
353
-
354
- def agent_turn(agent, model: str, provider_name: str, active_skills=(), *,
355
- callable_only: bool = False, granted=None,
356
- one_shot: bool = False) -> AgentTurn:
357
- """§18's session-scoped agent, applied to one turn, for either shell.
358
-
359
- An active agent supplies the system prompt, the ToolContext, and
360
- model/provider/max_steps overrides; with none active the turn is the
361
- default harness run (base + catalogs, built by the loop). The session
362
- tiers are NOT added here -- `_conversation_prompt` adds them to
363
- whichever prompt runs, which is what keeps a wake turn's prompt the
364
- same as the turn it continues.
365
-
366
- ONE COPY (ROADMAP_v3 §89). The TUI's chat turn built this inline, and
367
- the CLI's `/agent` needs the same answer: an agent that pins a model
368
- in one shell and not the other is two agents with one name.
369
-
370
- `callable_only` / `granted` are `advertisement_facts`' (#68), so an
371
- unattended CLI turn under an agent does not advertise gated tools it
372
- cannot call -- the TUI always has a channel and passes neither.
373
-
374
- `one_shot` is §18's /grill-me: ONE turn in the session's thread under
375
- the agent's prompt, and nothing else of the agent's -- the session's
376
- model and provider, no ToolContext, the default step budget. That is
377
- the TUI's `run_one_shot` assembly, kept as it was and now shared.
378
- """
379
- if agent is None:
380
- return AgentTurn(model, provider_name, None, None,
381
- config.MAX_ITERATIONS)
382
- from agents.manager import manager
383
-
384
- if one_shot:
385
- prompt = manager.system_prompt_for(
386
- agent, with_persona(DEFAULT_SYSTEM_PROMPT, model, provider_name),
387
- list(active_skills or ()),
388
- callable_only=callable_only, granted=granted)
389
- return AgentTurn(model, provider_name, None, prompt,
390
- config.MAX_ITERATIONS)
391
- context = manager.active_context(agent)
392
- model = agent.model or model
393
- provider_name = agent.provider or provider_name
394
- prompt = manager.system_prompt_for(
395
- agent, with_persona(DEFAULT_SYSTEM_PROMPT, model, provider_name),
396
- list(active_skills or ()), context=context,
397
- callable_only=callable_only, granted=granted)
398
- return AgentTurn(model, provider_name, context, prompt,
399
- agent.max_steps or config.MAX_ITERATIONS)
400
-
401
-
402
- def attach_ref(memory: ConversationMemory, thread_id, summary: str,
403
- label: str = "") -> tuple:
404
- """Attach one thread's summary to `memory`'s thread. Returns (ok, message).
405
-
406
- ONE writer for both shells, like with_refs is one reader: the CLI's --ref
407
- and the TUI's /ref must agree about the cap, about re-attaching the same
408
- thread, and about the stored shape, or the two disagree about what a
409
- reference IS.
410
-
411
- REFUSES AT THE CAP rather than dropping the oldest. A reference is
412
- something a person chose by name; making room by discarding one silently
413
- is what §21b's "removal is by id, never by substring" rule exists to
414
- prevent. The message names the command that makes room.
415
-
416
- Re-attaching a thread already attached REPLACES its summary rather than
417
- adding a second entry -- the newer summary is strictly better information
418
- about the same source, and two entries for one thread would spend the cap
419
- on a duplicate.
420
- """
421
- from datetime import datetime
422
-
423
- refs = [dict(r) for r in (memory.extra.get("refs") or [])]
424
- key = str(thread_id)
425
- existing = next((r for r in refs if r.get("thread_id") == key), None)
426
- if existing is None and len(refs) >= config.MAX_INJECTED_REFS:
427
- return False, (
428
- f"Already referencing {len(refs)} conversations, which is the "
429
- f"limit (config.MAX_INJECTED_REFS). Drop one with /ref --clear "
430
- f"first -- none is removed automatically.")
431
-
432
- entry = {
433
- "thread_id": key,
434
- "summary": summary,
435
- "label": label,
436
- "attached_at": datetime.now(UTC).isoformat(),
437
- }
438
- if existing is not None:
439
- refs[refs.index(existing)] = entry
440
- verb = "Updated the reference to"
441
- else:
442
- refs.append(entry)
443
- verb = "Now referencing"
444
- memory.set_extra("refs", refs)
445
- return True, f"{verb} thread {key}."
446
-
447
-
448
- def clear_refs(memory: ConversationMemory) -> int:
449
- """Drop every attached reference. Returns how many were dropped.
450
-
451
- All or nothing, deliberately: a per-reference removal needs a stable way
452
- for a person to name one, and the only handle a ref has is a thread uuid
453
- the user would have to retype. `/ref --list` then `/ref` to re-attach the
454
- ones still wanted is two steps with nothing to mistype.
455
- """
456
- refs = memory.extra.get("refs") or []
457
- if refs:
458
- memory.set_extra("refs", None)
459
- return len(refs)
460
-
461
-
462
- def _authorization_kwargs(authorization) -> dict:
463
- """Unpack a RunAuthorization into _run()'s primitives.
464
-
465
- ONE unpacking point, so the pipeline entry point and its JSON-retry
466
- twin cannot disagree about what a bundle means. The retry re-enters the
467
- SAME pass thread through continue_conversation(): passing the bundle
468
- there and not here (or the reverse) would strip a pass's tools on
469
- exactly the attempt where the model is already struggling, and the only
470
- symptom would be a second malformed answer.
471
- """
472
- if authorization is None:
473
- return {}
474
- return {
475
- "granted_tools": authorization.granted_tools or None,
476
- "grant_budget": authorization.budget,
477
- "response_channel": authorization.provider,
478
- }
479
-
480
-
481
- def advertisement_facts(authorization=None, response_channel=None,
482
- granted_tools=None) -> tuple:
483
- """(callable_only, granted) for a caller BUILDING A PROMPT (#68).
484
-
485
- Sibling of _authorization_kwargs above, and there for the same
486
- reason: one unpacking point, so the places that must agree cannot
487
- disagree about what a bundle means. The difference is only WHEN --
488
- _run() computes `headless = response_channel is None` after the
489
- bundle has been unpacked into its primitives, and a system prompt
490
- is assembled before _run() is called at all.
491
-
492
- Accepts either a bundle or the loose primitives, because
493
- run_agent_conversation takes both and rejects being given both.
494
- The bundle wins when present, which is the same precedence
495
- _authorization_kwargs applies.
496
-
497
- A NULL BUNDLE MEANS HEADLESS, not "unknown": _authorization_kwargs
498
- returns {} for None, so response_channel stays None and _run reads
499
- that as headless. Answering anything else here would advertise a
500
- catalog to exactly the runs that cannot use it.
501
- """
502
- if authorization is not None:
503
- return (authorization.provider is None,
504
- set(authorization.granted_tools or ()))
505
- return (response_channel is None, set(granted_tools or ()))
506
-
507
-
508
- def _denial_reason(tool_name: str, response_channel, context) -> str:
509
- """Why a gated call was refused, in terms the model can act on (#158).
510
-
511
- The loop already learned this lesson one branch over -- see the
512
- reachability comment above the approval block: headless, "requires
513
- approval and was not given" tells the model to retry WITH approval,
514
- which is the one thing that cannot happen there. It retries, spends a
515
- step against max_steps, and gets the same sentence back. That is the
516
- fetch_url damage class, which §15\\D24 fixed for undeclared permissions
517
- and left open on this axis.
518
-
519
- THE DISTINCTION IS WHETHER THE ARGUMENTS CAUSED THE GATE, and it is
520
- asked the same way schemas(callable_only=…) asks it -- with empty
521
- params, through the one function both dispatch() and this loop already
522
- share. A tool gated by NAME is uncallable in this run however it is
523
- called, so the useful thing to say is "stop". A tool gated by THESE
524
- PARAMS survived that filter and was advertised precisely because some
525
- other call shape is callable, so the useful thing to say is "vary the
526
- arguments" -- which is exactly the case #158 measured: `write` is
527
- advertised in a headless pass and denied only for paths outside the
528
- workspace.
529
-
530
- No tool name and no notion of a path appears here. Which argument to
531
- vary is the model's problem and the tool's schema already describes it;
532
- putting "try a path inside the workspace" in this file is the thing
533
- ToolSpec.grant_scope and request_kind exist to prevent.
534
- """
535
- if response_channel is not None:
536
- # Somebody was asked and declined. Nothing to reframe -- the answer
537
- # was a decision, not an absence, and telling the model the call
538
- # was unavailable would misreport a person's "no" as a limitation.
539
- return f"{tool_name} requires approval and was not given"
540
- if registry.approval_needed(tool_name, {}, context):
541
- return (f"{tool_name} requires approval and this run has no way to "
542
- f"ask, so it is unavailable however it is called. Do not "
543
- f"retry it.")
544
- return (f"{tool_name} requires approval for these arguments and this "
545
- f"run has no way to ask. It may not need approval with "
546
- f"different arguments.")
547
-
548
-
549
- def _obtain_approval(response_channel, tool_name: str, params: dict,
550
- notice, request_payload=None, rationale=None,
551
- headline=None) -> tuple:
552
- """Ask the human about one gated call. Returns (approved, grant).
553
-
554
- ONE route since §23. There were two -- a queue.Queue the TUI's worker
555
- parked on while its UI thread rendered a modal, and an
556
- ApprovalProvider callable, which existed only because
557
- run_to_completion() DISCARDS the LoopEvent carrying the question, so
558
- the CLI and the pipeline would have blocked on a queue with nothing
559
- displayed. Both were the same exchange with different plumbing, and
560
- the shells now supply one ResponseChannel whose `ask` does whichever
561
- of those two things that shell needs.
562
-
563
- TWO RETURN VALUES, because §23 AC1b made one question's answer richer
564
- than a yes/no. A subagent sign-off answers with the SUBSET of tools
565
- the child may then use unprompted -- None to refuse the spawn, an
566
- empty set to allow it with nothing granted, a non-empty set to grant
567
- those. `grant` is None for every other kind, which carries no subset.
568
-
569
- Which kind to ask comes from the REGISTRY, not from a name test here:
570
- the loop asks what shape of question a tool needs the same way it asks
571
- whether it needs one at all. `request_payload` is passed in already
572
- computed, because the caller needs it before this point to look up the
573
- sign-off memo -- and building a subagent's candidate list twice per
574
- call would be wasteful and could disagree with itself.
575
-
576
- `rationale` is the agent's own account of why it wants this call
577
- (§42, RA5), and it is passed in already resolved for the same
578
- reason: the caller needs it for the LoopEvent too, and looking it
579
- up twice invites the two from disagreeing. DISPLAY ONLY -- it
580
- reaches the prompt and nothing that decides anything.
581
-
582
- `headline` is the SUBJECT of the question (§46, EP2) -- for `shell`
583
- the command itself -- and travels for exactly the same reasons,
584
- resolved once by the caller and display-only. It is also already
585
- inside `params`, which every prompt renders whole; what carrying it
586
- separately buys is a shell's ability to place it where it cannot
587
- scroll out of view, without learning a parameter name.
588
- """
589
- kind = registry.request_kind(tool_name)
590
- payload = {"tool_name": tool_name, "params": params,
591
- "rationale": rationale, "headline": headline}
592
- # §47. WHICH run is asking, read off the span that is open rather
593
- # than threaded through four layers -- the same ContextVar slice 1
594
- # put the parent link on, asked one question over.
595
- #
596
- # None at depth 0, and that is the right SCOPE rather than a gap:
597
- # the asking run is then the conversation on screen, which needs no
598
- # label. A nested one does, because its approvals surface on the
599
- # parent's screen and "Allow shell?" said only which tool.
600
- #
601
- # `asking_agent`, NOT `agent`: spawn_subagent's own request_payload
602
- # carries an `agent` key meaning the agent about to be SPAWNED.
603
- # Two different agents, one key, and the sign-off screen would
604
- # have named the wrong one.
605
- payload.update(request_payload or {})
606
- # AFTER the tool's own payload, deliberately, and this is the half
607
- # that took a mutation to notice. Written before it, a tool
608
- # declaring `asking_agent` in its request_payload would silently
609
- # replace this -- an agent-supplied claim overwriting a harness
610
- # fact, which is the exact inversion §42's RA6 orders the modal to
611
- # prevent. Nothing declares that key today; the point is that
612
- # nothing CAN.
613
- asking = agent_activity.current()
614
- if asking is not None:
615
- payload["asking_agent"] = asking.name
616
- payload["asking_depth"] = asking.depth
617
- answer = interaction.ask(response_channel, interaction.Request(
618
- kind=kind, payload=payload, notice=notice))
619
- if kind == interaction.SUBAGENT_SIGNOFF:
620
- # None denies the spawn; any set (including empty) allows it.
621
- return answer is not None, answer
622
- return bool(answer), None
623
-
624
-
625
- # ROADMAP_v2 §21. Notice kinds that describe a STANDING CONDITION rather
626
- # than an event: they stay true on every step until something changes, so
627
- # emitting them per step fills a transcript with the same line and trains
628
- # the reader past it -- which is exactly the reader you need when the one
629
- # that matters arrives. A compaction that actually happened is an event and
630
- # repeats legitimately, once per compaction.
631
- _ONCE_PER_RUN_NOTICES = (
632
- "compaction_warning", # still approaching the threshold
633
- "compaction_blocked", # the keep floors still protect everything
634
- "compaction_failed", # provider down, or the compactor returned
635
- # nothing usable (#136) -- and since batch 20
636
- # this kind is also the LATCH: seen once, no
637
- # further compact() calls this turn
638
- )
639
-
640
-
641
- def _derived_compaction_mode(memory) -> str:
642
- """The compaction mode for a caller that did not say (#43, batch 16).
643
-
644
- The mode is a property of WHAT THE THREAD IS, not of the call site:
645
- `research_pass` and `subagent` threads are machinery -- unattended,
646
- already returning a distillation, and (for a retry thread) holding
647
- exactly the turns §3 exists to keep in front of the model -- so M6's
648
- backstop applies WHEREVER they are re-entered. A chat thread is a
649
- conversation someone is present for; the ordinary working-set trigger
650
- is the feature working as designed there.
651
-
652
- This closes #43 by construction rather than by forwarding: json_retry
653
- and the §20 reviewer could not express a mode at all before, and a
654
- parameter they had to remember would have re-created the D24/R13
655
- failure shape -- correct today, one forgotten call site from wrong
656
- again. Unknown kinds fail toward the chat answer: routine compaction
657
- of an unforeseen thread kind is the conservative default, and a
658
- future kind states its own answer here when it arrives.
659
- """
660
- kind = getattr(memory, "kind", THREAD_KIND_CHAT)
661
- if kind in (THREAD_KIND_RESEARCH_PASS, THREAD_KIND_SUBAGENT):
662
- return "backstop"
663
- return "working_set"
664
-
665
-
666
- def _already_said(notices, kind: str) -> bool:
667
- return kind in _ONCE_PER_RUN_NOTICES and any(
668
- n["kind"] == kind for n in notices)
669
-
670
-
671
- def _compactor_depth(context) -> int:
672
- """Where a compaction started from THIS loop sits in the agent stack.
673
-
674
- One below whoever is running: a compactor spawned from a subagent at
675
- depth 1 is at 2, exactly as a subagent spawned from there would be.
676
- Derived from the ToolContext rather than passed down, because
677
- subagent_depth is already the number C3 bounds and a second count of
678
- the same thing is the shape §22 spent a section removing.
679
- """
680
- return (context.subagent_depth if context is not None else 0) + 1
681
-
682
-
683
- def _maybe_compact(memory, model, provider_name, notices, mode,
684
- activity=None, depth: int = 1):
685
- """Evaluate §21's trigger and act on it. A generator, so the caller
686
- yields from it and the notice reaches a live UI as it happens.
687
-
688
- Every notice goes BOTH ways -- appended to `notices`, which _run()
689
- attaches to the response, and yielded as a LoopEvent. The event alone
690
- would be invisible to the CLI and the pipeline, which drain the
691
- generator through run_to_completion() and discard everything that is
692
- not final. §20 and §25 each shipped that defect once.
693
-
694
- Outcome routing (batch 16, #44). compact() returns a status dict now,
695
- and this is where reportability is decided:
696
-
697
- folded notice every occurrence -- an event, and repeats
698
- legitimately, once per compaction.
699
- blocked /
700
- all-pinned /
701
- missing-agent STANDING CONDITIONS: notice AND WARNING together,
702
- ONCE PER RUN under the same dedup list. The two
703
- WARNINGs used to live inside compact() and fired on
704
- EVERY evaluation -- up to MAX_ITERATIONS + 1
705
- identical lines per turn on a thread that stays over
706
- trigger and fully floored, which is how a reader
707
- gets trained past the warnings that do not repeat.
708
- Same defect `context_limit()` had before it learned
709
- to warn once per model.
710
- no-progress /
711
- reentrant no notice at all: ordinary non-events (nothing new
712
- to fold) or already carried by _summarize's own
713
- per-call warnings.
714
-
715
- THE LATCH (#136, batch 20). compaction_failed is both a notice and a
716
- STOP for the run: once this turn has seen one -- a provider error, or
717
- an empty compactor response (compact() now reports that as
718
- status="failed" with the same kind) -- _maybe_compact returns before
719
- calling compact() again. Without the gate the dedup above only
720
- silenced the MESSAGE while every step still spent a full compactor
721
- model call on an attempt that had just failed; measured at seven
722
- calls in one six-step turn on the thread's first crossing. The latch
723
- is per-turn by construction -- `notices` dies with _run() -- so the
724
- next turn retries cleanly and a transient provider hiccup costs one
725
- wasted call, not one per step. Deliberately NOT latched: no-progress,
726
- reentrant, blocked and all-pinned exit before any model call, cost
727
- only storage reads, and are self-correcting if state shifts.
728
-
729
- Failure here is contained. Compaction is a model call, and a provider
730
- error during it must not take down a turn that was otherwise fine --
731
- the same call §20 made for its review stage. The thread simply stays
732
- uncompacted and the next call fails or succeeds on its own merits,
733
- which is strictly better than failing this one on its behalf.
734
-
735
- Takes no authorization, deliberately. The compactor declares
736
- `allowed_tools: []`, so there is nothing for a grant to apply to --
737
- a parameter here would read as security-relevant and could not be.
738
- """
739
- from core import compaction
740
-
741
- used = memory.last_input_tokens or compaction.estimated_tokens(memory.messages)
742
- action = compaction.should_compact(used, model, mode,
743
- provider_name=provider_name)
744
- if not action:
745
- return
746
- if action == "warn":
747
- if _already_said(notices, "compaction_warning"):
748
- return
749
- notice = {
750
- "kind": "compaction_warning",
751
- "text": ("Approaching the compaction threshold — older messages "
752
- "may be summarized soon."),
753
- }
754
- notices.append(notice)
755
- yield LoopEvent(notice=notice)
756
- return
757
- # THE LATCH (#136): a failed attempt already spent its model call this
758
- # turn. Everything below the warn branch re-enters compact() on every
759
- # step while the trigger stays open, so without this early return the
760
- # dedup below only hides the message and the spend repeats. See the
761
- # docstring's latch paragraph for why only compaction_failed gates.
762
- if _already_said(notices, "compaction_failed"):
763
- return
764
- try:
765
- # The current-turn floor (M5), computed HERE rather than at the
766
- # top of the turn. Archive-space makes it time-invariant within
767
- # a turn -- the archive gains assistant and tool rows as the
768
- # turn runs but no new USER row, so the answer is the same
769
- # whenever it is asked. Asking lazily keeps a storage read off
770
- # every turn that is nowhere near the threshold.
771
- outcome = compaction.compact(
772
- memory, model, provider_name,
773
- current_turn_start=memory.completed_turns(),
774
- # Batch 59. The compactor is an agent-shaped run nested inside
775
- # THIS turn, so it is drawn one level below whatever is running
776
- # -- which is the depth the caller computed from its context,
777
- # not a constant. `activity` is None everywhere but the TUI.
778
- activity=activity, depth=depth)
779
- except Exception as e: # noqa: BLE001 -- contained on purpose, see above
780
- logger.exception("Compaction failed; continuing uncompacted.")
781
- notice = {
782
- "kind": "compaction_failed",
783
- "text": f"Could not compact this conversation: {e}",
784
- }
785
- if not _already_said(notices, notice["kind"]):
786
- notices.append(notice)
787
- yield LoopEvent(notice=notice)
788
- return
789
-
790
- kind = outcome.get("kind")
791
- if kind is None:
792
- return
793
- if _already_said(notices, kind):
794
- return
795
- if kind == "compaction_blocked":
796
- # See the docstring's standing-condition row: one WARNING per run,
797
- # said in the same breath as the one notice, never per evaluation.
798
- logger.warning("Compaction cannot proceed on thread %s: %s",
799
- memory.thread_id, outcome["text"])
800
- notices.append({"kind": kind, "text": outcome["text"]})
801
- yield LoopEvent(notice=notices[-1])
802
-
803
-
804
- def run_to_completion(gen, observe=None) -> ModelResponse:
805
- """Consumes a _run() generator fully, discarding intermediate events,
806
- and returns the final ModelResponse — this is what keeps
807
- run_agent_conversation() and continue_conversation(), the two public
808
- entry points, synchronous for every caller.
809
-
810
- It reads the response off the TERMINAL EVENT, which is right for a
811
- bare _run(): that generator returns nothing. A generator that returns
812
- its own value -- stream_deep_research_mode(), whose response carries
813
- `thread_id` attached after the loop finished -- needs the other
814
- question asked, and `tests/conftest.drain` is where that lives now
815
- that the pass wrapper is gone.
816
-
817
- `observe` (ROADMAP_v3 §86, A81) is handed every event as it is drawn,
818
- the terminal one included, so a caller that wants the answer
819
- synchronously can still draw the turn while it runs. The CLI is that
820
- caller: it prints each step as it finishes, the way the replay of the
821
- thread will. Discarding stays the default, and nothing here protects
822
- the turn from the observer -- one that raises abandons the generator
823
- exactly as an exception in any consumer would, so the observer is the
824
- one that must not."""
825
- final = None
826
- for event in gen:
827
- if observe is not None:
828
- observe(event)
829
- if event.final_response is not None:
830
- final = event.final_response
831
- if final is None:
832
- raise RuntimeError(
833
- "Generator completed without yielding a final_response"
834
- )
835
- return final
836
-
837
-
838
- # #4 (batch 27). The wrappers' default for max_total_tokens: resolve the
839
- # configured spend cap (settings.json max_token_budget) at CALL time. A
840
- # sentinel rather than a plain None default because explicit-None already
841
- # MEANS something in _run()'s signature -- genuinely uncapped -- and tests
842
- # pass it deliberately. Resolution lives at the call site, not at def time,
843
- # so a settings.json written after import is still honoured.
844
- _SPEND_UNSET = object()
845
-
846
-
847
- def _resolve_spend_cap(max_total_tokens) -> Optional[int]:
848
- """_SPEND_UNSET -> the configured cap; anything else passes through."""
849
- if max_total_tokens is _SPEND_UNSET:
850
- from core.config_loader import spend_cap
851
- return spend_cap()
852
- return max_total_tokens
853
-
854
-
855
-
856
- @dataclass
857
- class _CallOutcome:
858
- """What deciding and dispatching ONE tool call produced (§47 slice 8).
859
-
860
- Returned rather than written straight into the turn's own lists,
861
- because NA11 orders a parallel batch's effects by the MODEL'S call
862
- order and a batch finishes in whatever order it finishes. So a call
863
- collects what it would have appended, and `_settle_one` appends it at
864
- the call's turn. For a lone sequential call that turn is immediately,
865
- which is what keeps the single-call path byte-identical.
866
-
867
- `result` is what the model is told. `granted` is §25's pre-authorized
868
- call record and `notices` are §23's shell-facing lines, each a list
869
- because a call contributes zero or one of the first and zero or more
870
- of the second.
871
- """
872
-
873
- result: object
874
- granted: list = field(default_factory=list)
875
- notices: list = field(default_factory=list)
876
-
877
-
878
- #: NA9's gate for a call with no siblings. A lone call cannot contend with
879
- #: anything, so it takes no lock -- which is what makes "the sequential
880
- #: path is unchanged" a structural claim rather than a measured one.
881
- _NO_GATE = nullcontext()
882
-
883
- #: NA12's second lock, and it guards a WINDOW rather than an object.
884
- #:
885
- #: §23's sign-off memo is a check-then-act: `recall_signoff` says nobody
886
- #: has answered about this subject, the human is asked, `remember_signoff`
887
- #: records the answer. Sequentially that is why three spawns of one agent
888
- #: ask ONCE. Concurrently all three recall before any remembers, and the
889
- #: user is asked three times about the same agent -- a regression in the
890
- #: number of questions, which is the thing §25 R11 and §23 J8 are both
891
- #: about.
892
- #:
893
- #: Guarding the dict instead would not close it: no single mutation is
894
- #: racy, the WINDOW between the read and the write is. Module-level rather
895
- #: than per-run, because the runs it serialises are siblings in different
896
- #: frames with no shared object between them but this one.
897
- #:
898
- #: RELEASED BEFORE dispatch, always. That is what keeps it a plain Lock: a
899
- #: child's own gate acquisitions all happen inside its dispatch, by which
900
- #: time its parent has let go, so nothing re-enters. It is also the outer
901
- #: of this project's two ask-side locks -- gate, then
902
- #: core.interaction's -- and the order is never the other way, because
903
- #: nothing holding the interaction lock reaches back into a gate.
904
- _GATE_LOCK = threading.Lock()
905
-
906
-
907
- def _parallel_groups(calls) -> list:
908
- """Partition one response's calls into consecutive runs (NA9).
909
-
910
- A group is either several calls whose ToolSpec declares `parallel`, or
911
- exactly one call of anything else. CONSECUTIVE, and that is the
912
- decision rather than an implementation detail: NA9 keeps every
913
- non-parallel call in its original position, so two spawns either side
914
- of a `shell` cannot be grouped without moving the shell relative to
915
- them.
916
-
917
- Asked of the registry, never matched by name, so this file stays free
918
- of the knowledge that spawn_subagent is the special one -- the same
919
- trade `grant_scope`, `request_kind` and `opens_thread` already make.
920
- """
921
- groups: list = []
922
- for call in calls:
923
- # `groups[-1][-1]` rather than a flag, so the question asked is
924
- # "may this join what is already open" -- and a group is never
925
- # empty, so there is no length to check.
926
- if (registry.parallel(call.name)
927
- and groups
928
- and registry.parallel(groups[-1][-1].name)):
929
- groups[-1].append(call)
930
- else:
931
- groups.append([call])
932
- return groups
933
-
934
-
935
-
936
- def _dispatch_one(call, *, context, run_info, response_channel, memory,
937
- activity, cancel=None, gate=_NO_GATE):
938
- """Decide, ask about and dispatch ONE tool call.
939
-
940
- A GENERATOR that yields the call's own narration -- the permission
941
- request and any approval notice -- and RETURNS a `_CallOutcome`. Two
942
- drivers share it and that is the point of the shape: `_run` does
943
- `yield from` for a lone call, and `_dispatch_parallel`'s worker steps
944
- it by hand and pushes each event onto a conduit. One copy of the
945
- decision, so there is still exactly one place that decides whether a
946
- call is authorized and exactly one call to `registry.dispatch`.
947
-
948
- `gate` is NA12's window lock, supplied only when this call has
949
- siblings. See `_GATE_LOCK`.
950
-
951
- THE AUTHORIZATION IS THIS FUNCTION'S LOCAL, which is strictly stronger
952
- than the loop-body local it replaces. `authorized_call` used to be
953
- correct because of WHERE it was declared -- one indent out and it
954
- covered every later call in the turn -- and the id, rather than a
955
- bool, is what made that mistake fail closed instead of open. A
956
- function whose whole scope is one call cannot express the mistake at
957
- all: there is no enclosing iteration to hoist out of. The id stays
958
- anyway, because it is also what tells `dispatch()` which call the
959
- loop answered, and because a fail-closed shape is worth keeping when
960
- it costs nothing.
961
- """
962
- granted: list = []
963
- collected: list = []
964
-
965
- # Single source of truth with dispatch(): approval_needed()
966
- # ORs the tool's own path/command-dependent approval_check
967
- # with the config/context requirement (§15). Both callers
968
- # go through it so they cannot diverge — a path-dependent
969
- # tool must yield permission_request so the TUI user can
970
- # approve, not be silently denied by one check while the
971
- # other reports no approval needed.
972
- #
973
- # There is no separate allowed_tools membership test here
974
- # any more: dispatch() calls is_tool_allowed(name, context),
975
- # which raises ToolCallDenied with a message distinguishing
976
- # a context restriction from a global policy denial.
977
- needs_approval = registry.approval_needed(
978
- call.name, call.input, context)
979
- # Reachability before approval. Asking first meant a
980
- # context-excluded tool prompted the user, who clicked
981
- # Allow, and was then denied anyway -- and headless, it
982
- # reported "requires approval and was not given", telling
983
- # the model to retry with approval when the actionable
984
- # answer is "not available in this context". dispatch()
985
- # still enforces the denial; this only stops asking a
986
- # question whose answer cannot matter.
987
- if needs_approval and not registry.is_allowed(call.name, context):
988
- needs_approval = False
989
- # §32 A7 (#70): the same rule for a refusal only the
990
- # TOOL can see. spawn_subagent's unknown-agent and
991
- # depth-limit checks lived inside run(), so both
992
- # prompted first and errored second -- and for an
993
- # unknown name the question had an empty notice and an
994
- # empty candidate list, i.e. nothing to tick. The
995
- # call is refused by dispatch with the tool's own
996
- # reason; this only stops ASKING first. It also keeps
997
- # J8's memo from being keyed on
998
- # (spawn_subagent, None) -- a subject of None is the
999
- # absence of the very thing the key exists to
1000
- # distinguish.
1001
- if needs_approval and registry.refusal_reason(
1002
- call.name, call.input, context):
1003
- needs_approval = False
1004
- # §33 W3 (#37): the same rule for a call whose arguments
1005
- # never parsed. Approving it could not make it runnable,
1006
- # so the question has no answer that changes anything --
1007
- # and headless it would report "requires approval and was
1008
- # not given", which is A7's exact wrong-cause failure.
1009
- if needs_approval and call.parse_error is not None:
1010
- needs_approval = False
1011
- # §18 sign-off (S1), narrowed by §25 (R2): a tool whose
1012
- # grant_scope is "run" is asked about once per run, not
1013
- # once per call. The loop names no tool -- it asks the
1014
- # registry, the same way it asks whether approval is
1015
- # needed at all.
1016
- #
1017
- # THREE conditions, and the last two are the §25 change:
1018
- #
1019
- # registry.grantable -- a tool deciding approval from its
1020
- # PARAMS was never consented to by name. Before this,
1021
- # a signed-off subagent could run any shell command for
1022
- # the rest of the turn on the strength of one prompt
1023
- # that said "shell". Re-checked here rather than
1024
- # trusted from the set, so a stale or hand-built grant
1025
- # cannot widen anything.
1026
- #
1027
- # grant_budget.take() -- pre-flight authorization trades
1028
- # a per-call decision for one up-front decision, and
1029
- # gives up the natural bound on how many times the
1030
- # tool runs. Exhaustion falls back to ASKING, not to
1031
- # failing: supervised runs continue, headless ones deny
1032
- # exactly as they would for any gated tool.
1033
- #
1034
- # §23 AC1b: the memo is keyed by (tool, SUBJECT), not by
1035
- # tool name alone. A subagent sign-off answers about one
1036
- # agent's candidate list, so reusing it for a different
1037
- # agent would grant a set nobody was shown -- which is
1038
- # what the name-only version did: approving a spawn of `a`
1039
- # silently covered a later spawn of `b` in the same turn.
1040
- # Tools with no subject (every other one) memo under None
1041
- # and behave exactly as before.
1042
- # Batch 60. THIS CALL'S authorization decision, and the
1043
- # error that stands in for it.
1044
- #
1045
- # THE ID, NOT A BOOLEAN, and that is the whole point of the
1046
- # shape. `authorized` began as a bool whose correctness
1047
- # rested on WHERE it was declared -- one indent level in and
1048
- # it covers one call, one level out and it covers every
1049
- # later call in the turn, which is the exact widening §25
1050
- # R11 refuses to make even for the one tool whose grant
1051
- # scope IS the run. That version was measured: hoisting it
1052
- # out of the per-call loop survived the entire suite, because
1053
- # no path currently reaches dispatch with a stale flag that
1054
- # changes anything. Correct, and undefended.
1055
- #
1056
- # §47 SLICE 8 MADE THE SCOPE STRUCTURAL. The per-call body is
1057
- # this function now, so there is no enclosing iteration left
1058
- # to hoist out of -- the widening the paragraph above defends
1059
- # against can no longer be WRITTEN here, rather than being
1060
- # merely absent. That is why the AST guard in
1061
- # tests/test_grants.py moved with the body instead of being
1062
- # deleted: what it pins is now "one call per frame, and the
1063
- # frame is what dispatch is told about".
1064
- #
1065
- # A call id cannot be hoisted into a lie, and the id stays for
1066
- # that reason plus one more: it is also how dispatch() learns
1067
- # WHICH call the loop answered. Handed a stale one, the
1068
- # comparison at the dispatch site fails and the call is DENIED
1069
- # -- the mistake fails closed instead of failing open. It rests
1070
- # on ids being distinct within a response, which is not a new
1071
- # assumption: add_tool_result pairs every tool_result to its
1072
- # tool_use by that same id (M4/D20), and a thread whose ids
1073
- # collide is already unresumable.
1074
- #
1075
- # Set in exactly two places -- the memo/grant hit below and
1076
- # the fresh approval further down -- and read in exactly
1077
- # one, the single dispatch() call at the end of this block.
1078
- authorized_call = None
1079
- denial = None
1080
- request_payload = registry.request_payload(
1081
- call.name, call.input, context)
1082
- subject = request_payload.get("subject")
1083
- # NA12's window opens HERE and closes before dispatch. Everything
1084
- # inside is the sign-off's check-then-act: what has already been
1085
- # answered about this subject, the question if nothing has, and the
1086
- # record of the answer. A sibling that arrives mid-window waits, and
1087
- # then finds the memo -- which is what keeps three spawns of one
1088
- # agent at ONE question, exactly as they were sequentially.
1089
- #
1090
- # `gate` is a no-op for a lone call, so this costs the sequential
1091
- # path nothing and cannot be held across a suspension there. On the
1092
- # parallel path the frame that yields is the DRIVER, not this
1093
- # generator: the worker steps it and pushes, so a permission request
1094
- # still reaches the transcript before the modal it announces, with
1095
- # no lock held across anybody's `yield`.
1096
- with gate:
1097
- remembered, signoff = run_info.recall_signoff(
1098
- call.name, subject)
1099
- # grant_policy on a NAME-LEVEL grant only -- R13's literal
1100
- # claim is that approving the NAME never carries the
1101
- # authority for a GRANT_NEVER tool, on either path, and
1102
- # until now no path enforced it. Batch 6 declared the
1103
- # policy and taught the two functions that decide what
1104
- # may be OFFERED to read it; this is the reader that
1105
- # decides whether a grant already in hand APPLIES.
1106
- # `spawn_subagent` was covered only because R14's
1107
- # subject condition happens to catch it; `remember`
1108
- # carries no subject, so a grant naming it dispatched a
1109
- # durable cross-session write with no prompt -- M17's
1110
- # scenario through the one door R13 left unlocked.
1111
- #
1112
- # IT MUST NOT REACH THE SIGN-OFF MEMO, and that is not a
1113
- # nicety: `spawn_subagent` is GRANT_NEVER, so testing
1114
- # the policy unconditionally here stops §23's memo
1115
- # applying and the same agent is asked about twice in
1116
- # one turn. R13 is about what approving a NAME buys; a
1117
- # memo is an answer somebody gave about this subject,
1118
- # which J8 and R14 govern instead. recall_signoff
1119
- # already separates them by what it returns -- the memo
1120
- # always carries a subset, the grant carries None.
1121
- answered_by_name = signoff is None
1122
- if (needs_approval
1123
- and remembered
1124
- and registry.grantable(call.name)
1125
- and not (answered_by_name
1126
- and registry.grant_policy(call.name)
1127
- == GRANT_NEVER)
1128
- and (run_info.grant_budget is None
1129
- or run_info.grant_budget.take())):
1130
- needs_approval = False
1131
- # Batch 60. The half that was missing: the loop
1132
- # decided this call needs no fresh answer, and until now
1133
- # it did not tell dispatch(), which re-checks approval on
1134
- # its own and denied every call this branch let through.
1135
- # A second spawn of one agent, a subagent calling a tool
1136
- # it was signed off for, and a --grant-tools name in an
1137
- # unattended run were all refused with "requires approval
1138
- # and was not given" and no prompt.
1139
- authorized_call = call.id
1140
- granted.append(
1141
- {"tool": call.name, "params": call.input})
1142
- # §21, and the reason this batch adds a notice at all:
1143
- # a gated call proceeding with NO modal is the intended
1144
- # behaviour (§25 R11 -- re-asking about the same tool
1145
- # seconds later is noise), and it is also exactly what
1146
- # the bug looked like from the outside. Silence was
1147
- # indistinguishable from the bug.
1148
- #
1149
- # DELIBERATELY NOT in _ONCE_PER_RUN_NOTICES. That list
1150
- # is for a STANDING CONDITION re-emitted on every step;
1151
- # this fires only when a call actually reuses an answer,
1152
- # which is an event -- the same reading that lets a
1153
- # compaction that HAPPENED repeat once per compaction.
1154
- # Once per run would go quiet again from the third spawn
1155
- # onward, which is the silence that started this.
1156
- #
1157
- # Two texts, discriminated by `answered_by_name`, which
1158
- # is already computed above: one sentence cannot honestly
1159
- # cover both. A memo is something the user answered
1160
- # minutes ago in this turn; a grant is something they
1161
- # decided before the run existed, possibly on a command
1162
- # line, and telling them they "answered earlier" would
1163
- # describe a moment that never happened.
1164
- collected.append({
1165
- "kind": "approval_reused",
1166
- "text": (
1167
- "%s is running on the authorization granted "
1168
- "before this run started." % call.name
1169
- if answered_by_name else
1170
- "Reusing your approval for %s, given earlier in "
1171
- "this turn." % (subject or call.name)),
1172
- })
1173
- yield LoopEvent(notice=collected[-1])
1174
- else:
1175
- # Not reused: nothing is carried into dispatch unless
1176
- # this call's own answer supplies it below.
1177
- signoff = None
1178
- if needs_approval:
1179
- notice = registry.approval_notice(
1180
- call.name, call.input, context)
1181
- # §42 (RA5). The agent's own stated reason, asked
1182
- # of the registry so the loop names no key -- the
1183
- # same way it asks what KIND of question a tool
1184
- # needs and whether it needs one at all. The VALUE
1185
- # travels rather than the key, because the two
1186
- # shells that render it are a Textual screen that
1187
- # imports nothing from this package and a `print`
1188
- # in main.py.
1189
- rationale = registry.rationale_for(
1190
- call.name, call.input)
1191
- # §46 (EP2). The SUBJECT of the question, resolved
1192
- # the same way and travelling the same route: for
1193
- # `shell` it is the command, and a shell that shows
1194
- # it must not have to know that. Every other tool
1195
- # answers None and its prompt is unchanged.
1196
- headline = registry.headline_for(
1197
- call.name, call.input)
1198
- yield LoopEvent(permission_request={
1199
- "tool_name": call.name, "params": call.input,
1200
- "notice": notice,
1201
- "rationale": rationale,
1202
- "headline": headline,
1203
- })
1204
- approved, signoff = _obtain_approval(
1205
- response_channel, call.name, call.input, notice,
1206
- request_payload, rationale=rationale,
1207
- headline=headline)
1208
- if approved:
1209
- authorized_call = call.id
1210
- # §25 R11: run-scope is a shortcut for a chat turn,
1211
- # where re-asking about the same tool seconds later
1212
- # is noise. A provider that declines it is saying
1213
- # its whole purpose is per-call supervision --
1214
- # attended mode -- and one yes must not silently
1215
- # cover later calls there.
1216
- #
1217
- # This is ALSO the only thing that carries an answer
1218
- # between calls in a turn, and it is asked of the
1219
- # registry rather than assumed: `spawn_subagent` is
1220
- # the sole tool declaring grant_scope "run", so
1221
- # `shell`, `write` and `edit` are re-asked per call
1222
- # however many times one turn calls them.
1223
- if (registry.grant_scope(call.name) == "run"
1224
- and (response_channel is None
1225
- or response_channel.honour_run_scope)):
1226
- run_info.remember_signoff(
1227
- call.name, subject, signoff)
1228
- else:
1229
- denial = _denial_reason(
1230
- call.name, response_channel, context)
1231
- elif call.parse_error is not None:
1232
- # §33 W1 (#37). The loop is the only layer that can
1233
- # see this: dispatch() takes (name, params, context)
1234
- # and the failure is a fact about the wire, not about
1235
- # the params -- {} is a perfectly good empty dict by
1236
- # the time it gets there.
1237
- #
1238
- # RETURNED as the tool's result, not raised, for
1239
- # A10's reason: the model is told its arguments did not
1240
- # arrive and can reissue the call, which is the whole
1241
- # difference between losing one step and losing a
1242
- # ten-pass run.
1243
- denial = call.parse_error
1244
-
1245
- # ONE dispatch call site (batch 60). There were two,
1246
- # identical but for the two arguments that carry
1247
- # authorization, and the one reached by an already-answered
1248
- # call was the one that omitted them -- so every call this
1249
- # loop decided was authorized got denied by dispatch's own
1250
- # re-check. Two sites that must agree is the defect; one
1251
- # site is the fix, and no future edit can teach them to
1252
- # disagree again.
1253
- #
1254
- # dispatch() STILL RE-CHECKS, and must: it is a public
1255
- # entry point and the fail-closed backstop. What changed is
1256
- # that the loop now answers it.
1257
- #
1258
- # The callback is CONDITIONAL, and the condition is an
1259
- # identity check rather than a truth test: this call, not
1260
- # some call. See the declaration above for why the id and
1261
- # not a flag.
1262
- #
1263
- # DELETING the condition -- `lambda n, p: True` outright --
1264
- # is the one mutation here that no behaviour can catch, and
1265
- # it is caught in tests/test_grants.py by reading this
1266
- # source instead. Nothing can reach this line gated and
1267
- # un-authorized today, because the three other reasons
1268
- # `needs_approval` is turned off above are each
1269
- # short-circuited INSIDE dispatch before its gate
1270
- # (is_allowed raises, refusal_check returns, and a
1271
- # parse_error never gets here at all). A fourth reason added
1272
- # later would otherwise silently become "approve
1273
- # everything", with every test still green.
1274
- #
1275
- # `signoff` needs no condition -- the memo branch above nulls
1276
- # it on every path that is not a hit, so it is already None
1277
- # everywhere it should be.
1278
- if denial is not None:
1279
- result = {"error": denial}
1280
- else:
1281
- try:
1282
- result = registry.dispatch(
1283
- call.name, call.input, context=context,
1284
- # §47. The id the parent's MessageLog row
1285
- # already stores for this call, so a child
1286
- # thread can record which LINE made it --
1287
- # one turn can spawn three, and a name is
1288
- # not enough to tell them apart.
1289
- call_id=call.id,
1290
- approval_callback=(
1291
- (lambda n, p: True)
1292
- if authorized_call == call.id else None),
1293
- parent_run=run_info,
1294
- response_channel=response_channel,
1295
- signoff=signoff,
1296
- memory=memory,
1297
- activity=activity,
1298
- # §61 CN7. A child run is this run continuing, so it is
1299
- # handed the same switch -- the argument that
1300
- # `response_channel` and `activity` beside it already
1301
- # make, for the same reason.
1302
- cancel=cancel,
1303
- )
1304
- except ToolCallDenied as e:
1305
- result = {"error": str(e)}
1306
- except ValueError:
1307
- # Batch 147. THE OTHER EXCEPTION dispatch() RAISES ON PURPOSE.
1308
- #
1309
- # Its unknown-tool guard is a ValueError and not a
1310
- # ToolCallDenied, deliberately: the two types separate "you
1311
- # misnamed it" from "policy blocks you", and that file frames
1312
- # the first as a caller bug. It is -- but the caller here is a
1313
- # language model, so the bug arrives the way a model's bugs
1314
- # arrive: a name it invented, a name whose MCP server went
1315
- # away between turns while its schemas are still in the
1316
- # model's context (registry.unregister()), or a name a prompt
1317
- # catalog advertises and nothing registered.
1318
- #
1319
- # Uncontained, that cost the whole turn AND left the thread
1320
- # unresumable: D20 has already persisted the assistant row
1321
- # carrying the `tool_use`, nothing writes a `tool_result`, and
1322
- # M4's pairing is broken with nothing in core/compaction.py or
1323
- # core/memory.py that repairs it -- `_settle_one`'s own words
1324
- # for that state are "an unresumable thread". Reported as this
1325
- # call's error instead, for the reason the parse_error branch
1326
- # above gives in full: the model is told what went wrong and
1327
- # can reissue, which is the difference between losing one step
1328
- # and losing a ten-pass run.
1329
- #
1330
- # `is_registered` RATHER THAN THE MESSAGE is what makes this
1331
- # specific. A bare `except Exception` would stop dispatch()
1332
- # being the fail-closed backstop it is documented as -- a real
1333
- # failure in the approval machinery would come back to the
1334
- # model as a tool error and vanish -- and matching on the text
1335
- # would be a parser where a token check will do (G2). The
1336
- # question is asked of the registry, which is the only thing
1337
- # that knows the answer, and a ValueError for a name that IS
1338
- # registered re-raises exactly as it did before.
1339
- #
1340
- # A re-registration between the raise and this line answers
1341
- # True and re-raises, i.e. degrades to the behaviour this
1342
- # replaces. That is the safe direction and it is why the
1343
- # check is not a cached snapshot.
1344
- if registry.is_registered(call.name):
1345
- raise
1346
- logger.warning(
1347
- "model called %r, which is not a registered tool; "
1348
- "reporting that to it as this call's error", call.name)
1349
- result = {"error": (
1350
- f"There is no tool named {call.name} in this run, so the "
1351
- f"call could not be made. Use one of the tools listed in "
1352
- f"this request.")}
1353
- # The NAME is the only thing echoed, and it is already in
1354
- # the thread: D20 persisted the model's own `tool_use` block
1355
- # before any of this. Nothing of the exception goes back,
1356
- # which matters here more than it looks: an error result the
1357
- # LOOP builds -- a denial, a parse error, this -- does not
1358
- # pass through `check_output_policy`, while every result
1359
- # dispatch() returns does, including its own error results
1360
- # (tests/test_tool_failure_containment.py pins that). So this
1361
- # is one of the few result strings in the system that no
1362
- # redactor will ever see.
1363
- return _CallOutcome(
1364
- result=result, granted=granted, notices=collected)
1365
-
1366
-
1367
- def _dispatch_parallel(calls, *, context, run_info, response_channel,
1368
- memory, activity, cancel=None):
1369
- """Run several calls of one response at once (NA9, NA10, NA15).
1370
-
1371
- A GENERATOR yielding every worker's narration as it arrives, and
1372
- RETURNING [(call, _CallOutcome)] in the model's original call order.
1373
-
1374
- THREADS, NOT ASYNCIO. `_run` is a synchronous generator and everything
1375
- under it is blocking I/O -- a provider call, a modal a human is
1376
- looking at, a SQLite write. Converting that to coroutines is a rewrite
1377
- of every layer; a bounded pool is the change that fits what is already
1378
- here.
1379
-
1380
- EVERY FUTURE CARRIES `contextvars.copy_context()`, which is what makes
1381
- the child's span see its real parent. Batch 67 chose a ContextVar for
1382
- the parent link over a parameter partly for this: a var is per-context,
1383
- so a copied context travels with the submitted call, while a plain
1384
- module global would be wrong the moment two children ran.
1385
-
1386
- THE CONDUIT IS HOW A WORKER NARRATES, and it is the fifth blocker N8
1387
- named -- "a synchronous generator with no yield point inside
1388
- dispatch()". A worker thread cannot yield out of this generator. What
1389
- it can do is put the event on a queue that THIS frame, which is still
1390
- inside `_run`'s body and can still yield, drains as the events arrive.
1391
- So narration stays live: a permission request from one child reaches
1392
- the transcript while its siblings are still running.
1393
-
1394
- Note what this does NOT do. It does not forward a CHILD'S events --
1395
- §18/D6 keeps a child's stream out of its parent, and
1396
- core/agent_activity.py exists because of it. The events on this queue
1397
- are the PARENT'S own, about its own tool calls, which it would have
1398
- yielded itself had it not handed the work to a thread.
1399
-
1400
- UNBOUNDED QUEUE, deliberately: a worker must never block on the
1401
- conduit. A bounded one would make a slow consumer able to stall a run,
1402
- which inverts who is waiting for whom. The bound that matters is on
1403
- the POOL.
1404
-
1405
- A worker signals its own end rather than being polled for it, so this
1406
- drains exactly and never sleeps. If a call hangs, this frame waits
1407
- forever -- which is what a hanging sequential tool already does, so
1408
- the shape adds no new way to wedge.
1409
- """
1410
- conduit: queue.Queue = queue.Queue()
1411
- # `[(call, outcome_or_None, exception_or_None)]`, in the order the
1412
- # futures were submitted, which is the order the MODEL asked (NA11).
1413
- #
1414
- # A LIST RATHER THAN A DICT KEYED BY `call.id`, which is what this was
1415
- # until batch 76's review round. The id is the PROVIDER'S, and
1416
- # core/client.py's v1-compatible branch defaults a tool-call fragment's
1417
- # id to "" and fills it only if a delta carries one -- the same branch
1418
- # that accumulates `function.name` across deltas because some providers
1419
- # split it, so a provider being sloppy here is the case this code is
1420
- # written for. Two spawns arriving with one id made a dict hand every
1421
- # call in the batch the last-finishing worker's outcome: the model told
1422
- # one child's answer for a different child's call, which is the exact
1423
- # thing NA11 exists to prevent. Positions cannot collide, so ordering
1424
- # is now structural rather than a lookup.
1425
- settled_calls: list = []
1426
-
1427
- def _work(call):
1428
- """Drive one call's generator, pushing what it would have yielded."""
1429
- gen = _dispatch_one(
1430
- call, context=context, run_info=run_info,
1431
- response_channel=response_channel, memory=memory,
1432
- activity=activity, cancel=cancel, gate=_GATE_LOCK)
1433
- try:
1434
- while True:
1435
- conduit.put(("event", next(gen)))
1436
- except StopIteration as stop:
1437
- return stop.value
1438
- finally:
1439
- # Runs on the return path and on the raising one, so the
1440
- # drain below always terminates. A worker that died still
1441
- # reports that it is done.
1442
- conduit.put(("done", None))
1443
-
1444
- workers = max(1, min(len(calls), config.SUBAGENT_MAX_PARALLEL))
1445
- abandoned = False
1446
- with ThreadPoolExecutor(max_workers=workers,
1447
- thread_name_prefix="venastine-call") as pool:
1448
- futures = []
1449
- for call in calls:
1450
- futures.append(
1451
- (call, pool.submit(copy_context().run, _work, call)))
1452
- outstanding = len(calls)
1453
- # ABANDONED MID-BATCH, the window #215 names (batch 221). A
1454
- # consumer that goes away at one of these yields -- the TUI closes
1455
- # its generator on shutdown -- used to take every finished call's
1456
- # outcome with it: D20 had written their `tool_use` blocks, the
1457
- # tools had run, and no row answered them. So the GeneratorExit is
1458
- # held while the workers finish, which the pool's own exit already
1459
- # waited for, and every outcome is recorded in the model's order
1460
- # below before it is raised again. NA11 is untouched: nothing is
1461
- # recorded out of order, only no longer dropped.
1462
- try:
1463
- while outstanding:
1464
- kind, payload = conduit.get()
1465
- if kind == "done":
1466
- outstanding -= 1
1467
- else:
1468
- yield payload
1469
- except GeneratorExit:
1470
- abandoned = True
1471
- for call, future in futures:
1472
- try:
1473
- settled_calls.append((call, future.result(), None))
1474
- except Exception as e: # noqa: BLE001 -- NA14, see below
1475
- settled_calls.append((call, None, e))
1476
-
1477
- # NA14. A RAISING SIBLING BECOMES ITS OWN RESULT, and this is a
1478
- # deliberate behaviour change scoped to a parallel batch.
1479
- #
1480
- # Sequentially an exception out of a tool leaves `_run` and ends the
1481
- # turn; §16 AC3 pins that this must not kill the app (`test_tui.py`),
1482
- # and a lone call keeps exactly that. In a batch it would discard the
1483
- # finished work of every sibling -- runs that cost a model call each
1484
- # and whose answers are already in hand -- so the raise is converted
1485
- # to this call's error result and the turn goes on.
1486
- #
1487
- # A BACKSTOP RATHER THAN THE USUAL PATH. `dispatch()` already turns a
1488
- # handler's exception into an error result, and BOTH exceptions it
1489
- # raises on purpose -- ToolCallDenied and the unknown-tool ValueError
1490
- # -- are caught inside `_dispatch_one`. What reaches here is a failure
1491
- # in the approval machinery itself. Logged with the traceback for
1492
- # dispatch()'s reason -- a real bug must stay findable -- and reported
1493
- # to the model in the shape it already understands.
1494
- #
1495
- # THIS COMMENT USED TO NAME THE UNKNOWN TOOL, and could not be reached
1496
- # by it (batch 147): `registry.parallel()` answers False for a name it
1497
- # does not hold, so `_parallel_groups` always put an unknown call in a
1498
- # group of ONE, and a group of one takes the sequential branch. The
1499
- # containment it described was in the wrong function for the failure
1500
- # it named -- so the failure ended the turn and this backstop never
1501
- # saw it. Both halves are fixed: `_dispatch_one` contains it for both
1502
- # drivers, and the sentence above no longer claims a case this cannot
1503
- # see.
1504
- ordered = []
1505
- for call, outcome, failure in settled_calls:
1506
- if failure is not None:
1507
- logger.exception(
1508
- "parallel tool call %s (%s) raised; reporting it as that "
1509
- "call's error and continuing with its siblings",
1510
- call.id, call.name, exc_info=failure)
1511
- ordered.append((call, _CallOutcome(
1512
- result={"error": "%s failed: %s" % (
1513
- call.name, failure)})))
1514
- else:
1515
- ordered.append((call, outcome))
1516
- if abandoned:
1517
- # Recorded, never announced: there is nobody left to announce to,
1518
- # and a generator that yields after GeneratorExit is a
1519
- # RuntimeError. A failure to record is logged rather than raised,
1520
- # so it cannot replace the close the consumer asked for.
1521
- for call, outcome in ordered:
1522
- try:
1523
- _settle_one(call, outcome, memory, [], [])
1524
- except Exception: # noqa: BLE001 -- see above
1525
- logger.exception("Could not record %s's result while the "
1526
- "batch was being closed", call.id)
1527
- raise GeneratorExit
1528
- return ordered
1529
-
1530
-
1531
- def _settle_one(call, outcome, memory, granted_calls, notices) -> list:
1532
- """Record ONE finished call, at its turn in call order, and return the
1533
- events that announce it.
1534
-
1535
- Split out of the per-call body so both drivers reach it identically,
1536
- and so everything that touches `memory` or the turn's shared lists
1537
- happens on the generator's own thread in the model's own order (NA11).
1538
- A reordered turn is a thread that will not resume: `add_tool_result`
1539
- pairs each result to its `tool_use` by id (M4/D20).
1540
-
1541
- A FUNCTION, NOT A GENERATOR, since batch 221 (#215). As a generator it
1542
- yielded between one call's row and the next one's, so a batch closed
1543
- at its first `tool_result` lost the rows of every call after it, and
1544
- `_dispatch_parallel` had nothing to record its finished calls with
1545
- once its own consumer had gone. Returning the events lets the batch
1546
- record every result before announcing any, and lets the abandoned path
1547
- record without announcing at all.
1548
- """
1549
- granted_calls.extend(outcome.granted)
1550
- notices.extend(outcome.notices)
1551
- result = outcome.result
1552
- events = []
1553
-
1554
- # §23 slice 2 (J10). A tool may attach a `notice` to its
1555
- # result for the shell to show; it is forwarded as a
1556
- # LoopEvent and REMOVED from what the model sees.
1557
- #
1558
- # Generic on purpose. The alternative was for the loop to
1559
- # notice that `todo_write` had just run, which puts a tool
1560
- # name in this file -- exactly what ToolSpec.grant_scope and
1561
- # ToolSpec.request_kind exist to avoid. Any later tool that
1562
- # wants to say something mid-turn gets this route free.
1563
- #
1564
- # POPPED, not copied: a notice is plumbing for the shell, and
1565
- # leaving it in the result would send the TUI panel's trigger
1566
- # to the model as if it were part of the tool's answer.
1567
- if isinstance(result, dict) and "notice" in result:
1568
- notice = result.pop("notice")
1569
- if isinstance(notice, dict) and notice.get("kind"):
1570
- events.append(LoopEvent(notice=notice))
1571
- else:
1572
- # A malformed notice is a bug in the tool, not a
1573
- # reason to fail the call -- the result is still
1574
- # good. Logged rather than raised, and the key is
1575
- # gone either way so it cannot reach the model.
1576
- logger.warning(
1577
- "%s returned a malformed notice; dropping it: %r",
1578
- call.name, notice)
1579
-
1580
- # Persist BEFORE emitting (#42). A generator only advances
1581
- # while someone iterates it, so emitting first made the row
1582
- # depend on a consumer continuing to read -- and an
1583
- # abandoned generator left the `tool_use` D20 already wrote
1584
- # with no matching `tool_result`, which is M4's pairing
1585
- # broken from the other side and an unresumable thread.
1586
- # Same rule §22 gives _Progress.checkpoint() for trace
1587
- # lines. The event carries nothing the persist needs, so
1588
- # the order is free.
1589
- memory.add_tool_result(call.id, result)
1590
- events.append(LoopEvent(tool_result={"id": call.id, "result": result}))
1591
- return events
1592
-
1593
-
1594
- def _finish_cancelled(memory, response, *, partial_text, unrun, reason,
1595
- granted_calls, notices, totals):
1596
- """Everything a cancelled turn leaves behind, in ONE place (§61 CN3).
1597
-
1598
- Three sites reach it -- the step boundary, a stream cut part way
1599
- through, and the gap between two tool groups -- and they differ only
1600
- in what they have in hand. Writing the terminal event at each would
1601
- be three chances to forget one of the three things below, and the
1602
- last of them is what keeps the thread resumable.
1603
-
1604
- `partial_text` is the accumulated deltas when the stream was cut, and
1605
- None otherwise. It is the only case that PERSISTS, because it is the
1606
- only one holding an assistant turn D20 has not already written. Empty
1607
- text persists nothing: a turn stopped before its first token said
1608
- nothing, and an empty assistant row is one every later request has to
1609
- carry.
1610
-
1611
- `unrun` is every tool call of this response that will not get a
1612
- result. #42 is the same lesson from the other side -- a `tool_use`
1613
- persisted with no matching `tool_result` is M4's pairing broken and
1614
- an UNRESUMABLE thread -- so a cancelled turn answers every call the
1615
- model made, including the ones it declined to run. The answer is an
1616
- `error`, which is the shape a denied call already takes.
1617
-
1618
- CN5: a SYNTHESISED response reports an EMPTY usage dict, not zeros.
1619
- The provider sends usage with its final message and a cut stream has
1620
- none, so the honest statement is "not measured" -- and the two stay
1621
- distinguishable, since `"input_tokens" in usage` is False here and
1622
- True for a step that genuinely cost nothing. A zero would be the
1623
- instrument that lies, which batches 118 and 119 each paid for once.
1624
-
1625
- CANCELLED IS NOT FAILED. Nothing here calls `mark_turn_failed`: the
1626
- frame above draws exactly that distinction for an abandoned
1627
- generator, and §60's UH6 records UHP arriving at it independently.
1628
- """
1629
- if partial_text is not None:
1630
- response = ModelResponse(text=partial_text, usage={})
1631
- if partial_text:
1632
- memory.add_assistant_message(response)
1633
- elif response is None:
1634
- response = ModelResponse(text="", usage={})
1635
- for call in unrun:
1636
- result = {"error": reason}
1637
- memory.add_tool_result(call.id, result)
1638
- yield LoopEvent(tool_result={"id": call.id, "result": result})
1639
- response.stop_reason = "cancelled"
1640
- response.granted_calls = granted_calls
1641
- response.notices = notices
1642
- (response.turn_billed_tokens, response.turn_new_tokens,
1643
- response.turn_output_tokens) = totals
1644
- yield LoopEvent(final_response=response, stop_reason="cancelled")
1645
-
1646
-
1647
- class RunAgentLoop:
1648
-
1649
- @staticmethod
1650
- def _run(memory: ConversationMemory, *args, **kwargs):
1651
- """The loop, recording on the thread why a run that raised failed.
1652
-
1653
- Batch 91. A thin frame around `_run_steps`, which IS the loop and
1654
- whose docstring documents every argument. `yield from` forwards each
1655
- event and the return value unchanged, so nothing driving `_run` can
1656
- tell the frame is there -- and nothing about the exception changes
1657
- either: core/events.py has no error variant on purpose, and it still
1658
- propagates to whoever drains this, exactly as it did.
1659
-
1660
- Without it a run that failed left nothing behind in its thread --
1661
- D20 persists an assistant turn only once a call returns -- so a
1662
- subagent whose first call failed replayed as its task and nothing
1663
- else. One frame covers every caller: a TUI turn, a CLI turn, a
1664
- spawned subagent, a one-shot, a research pass.
1665
-
1666
- `Exception`, not `BaseException`: a GeneratorExit is an ABANDONED
1667
- generator (#42, a TUI quitting mid-turn), not a failed run, and
1668
- recording it would stamp a failure on a turn nobody saw fail.
1669
- Recording must never replace the error it records, so its own
1670
- failure is warned and swallowed.
1671
- """
1672
- try:
1673
- return (yield from RunAgentLoop._run_steps(memory, *args, **kwargs))
1674
- except Exception as error:
1675
- try:
1676
- # THE DURABLE SINK, so the vocabulary matters most
1677
- # here (batch 144). `API_URL` is user-supplied
1678
- # through `save_credentials(api_url=...)`, an httpx error
1679
- # names the URL it failed on, and this row lands in
1680
- # `MessageLog.error` in app.db -- which `docs/PRIVACY.md`
1681
- # says is deleted by wiping the database, not one thread.
1682
- # `redact_secrets` alone would keep a URL's userinfo.
1683
- memory.mark_turn_failed(
1684
- redact_diagnostic_text(provider_errors.describe(error)))
1685
- except Exception: # noqa: BLE001 -- see the docstring
1686
- logger.warning(
1687
- "Could not record this run's failure on its thread.",
1688
- exc_info=True)
1689
- raise
1690
-
1691
- @staticmethod
1692
- def _run_steps(
1693
- memory: ConversationMemory,
1694
- system_prompt: str,
1695
- provider_name: str,
1696
- model: str,
1697
- context: Optional[ToolContext],
1698
- max_steps: int,
1699
- max_total_tokens: Optional[int] = None,
1700
- temperature: Optional[float] = None,
1701
- effort: Optional[str] = None,
1702
- response_channel=None,
1703
- granted_tools: Optional[set] = None,
1704
- grant_budget=None,
1705
- compaction_mode: Optional[str] = None,
1706
- activity=None,
1707
- cancel=None,
1708
- ):
1709
- """Generator yielding LoopEvent objects as the loop progresses.
1710
-
1711
- context: an optional ToolContext (§15) restricting which tools are
1712
- available and which need approval this run. None means only global
1713
- config policy applies, which is every production caller until §18
1714
- introduces agents. This replaced an `allowed_tools` list that did
1715
- the same job one layer up: the loop no longer decides tool
1716
- membership itself, it just hands the context to the registry and
1717
- lets security/permissions.py compose the layers.
1718
-
1719
- response_channel: an optional core.interaction.ResponseChannel --
1720
- the ONE way this loop asks a human anything (§23 AC1). None means
1721
- nothing can be asked, and any call that would need approval is
1722
- denied. Replaced a queue.Queue plus a separate ApprovalProvider,
1723
- which were the same exchange with two sets of plumbing; a shell
1724
- that needs the thread handoff (the TUI parks its worker while the
1725
- UI thread renders a modal) does that inside its own `ask`.
1726
-
1727
- granted_tools: names the user has ALREADY approved for this run
1728
- (§18 subagent sign-off). A spawned subagent receives the set the
1729
- user signed off when approving the spawn, so it does not re-ask
1730
- for tools already covered. A grant, not a policy relaxation: it
1731
- records an approval given early, which is why it lives on RunInfo
1732
- rather than in the ToolContext's approval_overrides (those OR, and
1733
- so can only tighten).
1734
-
1735
- grant_budget: a core.approval.GrantBudget capping how many granted
1736
- calls may skip the prompt (§25 R6), or None for no cap. Shared by
1737
- reference across every pass of a pipeline run. Exhaustion makes
1738
- the grant stop applying, so calls fall back to being asked.
1739
-
1740
- compaction_mode (§21): None -- the default since batch 16 (#43) --
1741
- means DERIVE from what the thread is: research_pass and subagent
1742
- threads get M6's backstop wherever they are re-entered, a chat
1743
- thread gets the ordinary working-set trigger. An explicit value
1744
- wins, and stream_deep_research_mode passes "backstop" explicitly
1745
- as the definition site. Before this, every continue_conversation
1746
- caller silently ran on the chat trigger: a pass's JSON retry and
1747
- the §20 reviewer evaluated a threshold their own threads were
1748
- never meant to answer to.
1749
-
1750
- cancel (§61): an optional core.cancel.CancelToken. None -- every
1751
- caller that has not opted in, which is every caller predating
1752
- §61 -- means nothing can stop this run, exactly as before. Set,
1753
- it is read at the three sites inside this function that CN2
1754
- names (the fourth is the shell's own drain), and the run then
1755
- ENDS on `stop_reason: "cancelled"` rather than raising. It must
1756
- not raise: the frame above records a failure on the thread for
1757
- any exception that is not a GeneratorExit, and a person changing
1758
- their mind is not a failed run.
1759
- """
1760
- # §29/#45 belt. `_run` is a generator, so this fires on the first
1761
- # next() -- which for every production caller is immediate, since
1762
- # all three wrappers drain eagerly. It exists because the loader
1763
- # repairs agent files (#45) while a DIRECT caller bypasses that
1764
- # repair entirely: there is no file to lose here, only a bug worth
1765
- # naming, so this raises rather than substituting. The old failure
1766
- # was an AttributeError on `response.stop_reason` after an empty
1767
- # step loop -- a traceback pointing three layers away from the bad
1768
- # value that caused it.
1769
- if isinstance(max_steps, bool) or not isinstance(max_steps, int) \
1770
- or max_steps < 1:
1771
- raise ValueError(
1772
- f"max_steps must be a positive integer, got {max_steps!r}. "
1773
- f"Agent definitions carrying an invalid max_steps are "
1774
- f"repaired by the loader to {config.MAX_ITERATIONS} "
1775
- f"(config.MAX_ITERATIONS); direct callers must pass a valid "
1776
- f"value themselves.")
1777
- client = api_initialization(provider_name)
1778
- # Validate the level against the model that will RECEIVE it, here
1779
- # rather than at each caller. Every path -- CLI chat, each research
1780
- # pass, a TUI turn, a spawned subagent -- reaches the wire through
1781
- # this function, so this is the one place that cannot be bypassed
1782
- # by a new caller forgetting to check. It also makes the agent case
1783
- # correct by construction: an agent declaring its own model is
1784
- # validated against THAT model, not the one the parent was using.
1785
- effort = effort_for(client, provider_name, model, effort)
1786
- # Prime the context-window cache on the same one-per-process
1787
- # footing, and HERE for effort_for's reason: this is the one place
1788
- # every send crosses, so a new caller cannot forget it. On
1789
- # ANTHROPIC it is a pure cache hit -- effort_for's own retrieve
1790
- # already recorded the window off the ModelInfo it fetched -- so
1791
- # the only providers this actually calls for are Google and the
1792
- # v1-compatible roster. The result is read back, without a client,
1793
- # by compaction.context_limit(); a failure here is warned and
1794
- # simply leaves the static table answering.
1795
- context_window_for(client, provider_name, model)
1796
- # §18 headless callability rule (user-widened from approval-only):
1797
- # with no way to ask, a tool that needs approval is uncallable in
1798
- # this configuration, so it is not advertised -- but named once in
1799
- # a WARNING so the hiding is never silent.
1800
- #
1801
- # §25: "no way to ask" is not "not a TUI". A research pass with a
1802
- # channel CAN ask, so hiding its gated tools would report a
1803
- # limitation the run does not have. §23 made this one condition
1804
- # again -- it was two while there were two routes.
1805
- #
1806
- # §25 R15: and "nothing can ask" is not "nothing has answered". A
1807
- # GRANT is an answer given before the call existed, so a granted
1808
- # tool is callable with no channel at all -- which is the whole
1809
- # point of `--grant-tools` on an unattended run. #156: this filter
1810
- # could not see the grant, so a grant-only run advertised exactly
1811
- # what an unflagged one did while the CLI printed that it had
1812
- # authorised something. The enforcement path below honoured the
1813
- # grant correctly; the model was simply never told the tool was
1814
- # there, so it never emitted the call.
1815
- #
1816
- # run_info IS BUILT ABOVE THIS, not below it as it was before R15.
1817
- # The schemas call now needs the grant, and the grant lives on
1818
- # run_info -- building it after would read the name before it is
1819
- # bound. Nothing else moved: it depends only on values already in
1820
- # scope here.
1821
- run_info = RunInfo(
1822
- model=model, provider_name=provider_name, effort=effort,
1823
- granted_tools=set(granted_tools or ()),
1824
- grant_budget=grant_budget,
1825
- images=_images_deliverable(provider_name, memory))
1826
- headless = response_channel is None
1827
- # The BUDGET is deliberately not consulted here. Advertisement is
1828
- # decided once per step; R6 makes exhaustion fall back to asking
1829
- # (or, headless, to denying) at CALL time, which is a per-call
1830
- # answer. Hiding a tool mid-run when the ceiling ran out would
1831
- # change what the model can see between one step and the next for
1832
- # a reason it cannot observe, and the model would read that as the
1833
- # tool having ceased to exist.
1834
- tool_schemas = registry.schemas(
1835
- context, callable_only=headless, granted=run_info.granted_tools,
1836
- images=run_info.images)
1837
- if not run_info.images:
1838
- unoffered = tuple(sorted(registry.image_hidden(
1839
- context, granted=run_info.granted_tools)))
1840
- key = (provider_name, getattr(memory, "kind", THREAD_KIND_CHAT),
1841
- unoffered)
1842
- if unoffered and key not in _image_notices_shown:
1843
- _image_notices_shown.add(key)
1844
- logger.warning(
1845
- "Not advertising %s: an image in its result could not "
1846
- "reach the model in this run (provider %s is not marked "
1847
- "`accepts_images` in providers.json, or this is a "
1848
- "research pass).",
1849
- ", ".join(unoffered), provider_name)
1850
- if headless:
1851
- hidden = tuple(sorted(registry.headless_hidden(
1852
- context, granted=run_info.granted_tools,
1853
- images=run_info.images)))
1854
- if hidden and hidden not in _headless_notices_shown:
1855
- _headless_notices_shown.add(hidden)
1856
- logger.warning(
1857
- "Headless run (no permission channel): not advertising "
1858
- "%s -- they require approval and nothing here can "
1859
- "grant it.",
1860
- ", ".join(hidden),
1861
- )
1862
- total_tokens_used = 0
1863
- # #4: the size instrument, kept strictly beside the spend meter.
1864
- # turn_baseline_input is the FIRST call's prompt -- the thread as
1865
- # this turn inherited it, which this turn did not add. Every later
1866
- # step contributes its output plus whatever NEW material entered
1867
- # the context (positive input deltas; a mid-turn compaction SHRINKS
1868
- # the prompt, and clamping at zero keeps that shrink from being
1869
- # read as negative growth). turn_billed/turn_new ride every
1870
- # response; memory.record_billed accumulates thread-since-resume.
1871
- turn_baseline_input: Optional[int] = None
1872
- turn_prev_input = 0
1873
- turn_new_tokens = 0
1874
- # Batch 61, the third instrument. Output ALONE -- see the field's
1875
- # comment on ModelResponse for why neither of the two above can
1876
- # stand in for it once a duration is divided into the result.
1877
- turn_output_tokens = 0
1878
- # §25 audit trail. Attached to the response object below rather
1879
- # than at each of the three return points, so a stop condition
1880
- # added later cannot forget to carry it -- the list is shared by
1881
- # reference and keeps filling as tools dispatch.
1882
- granted_calls: list = []
1883
- # §21, same pattern and the same reason.
1884
- notices: list = []
1885
-
1886
- # Turn boundary (M3). The primary trigger: the thread is settled,
1887
- # nothing is mid-flight, and last_input_tokens is the provider's
1888
- # own measurement of what the previous call was sent.
1889
- yield from _maybe_compact(
1890
- memory, model, provider_name, notices,
1891
- compaction_mode
1892
- if compaction_mode is not None
1893
- else _derived_compaction_mode(memory),
1894
- activity=activity, depth=_compactor_depth(context))
1895
-
1896
- response = None
1897
- for _ in range(max_steps):
1898
- # §61 CN2, the step boundary -- and ABOVE the reset below,
1899
- # which is the whole reason it sits here rather than at the
1900
- # foot of the body. The response it reads is the PREVIOUS
1901
- # step's: already counted, already persisted, and the last
1902
- # thing the model actually said. That is the shape
1903
- # "max_steps exhausted" already has at the end of this loop.
1904
- # Below the reset it would read None on every iteration and
1905
- # report an empty answer for a turn that had produced
1906
- # several.
1907
- if is_cancelled(cancel):
1908
- yield from _finish_cancelled(
1909
- memory, response, partial_text=None, unrun=(),
1910
- reason=cancel.reason, granted_calls=granted_calls,
1911
- notices=notices,
1912
- totals=(total_tokens_used, turn_new_tokens,
1913
- turn_output_tokens))
1914
- return
1915
- response = None
1916
- # Batch 91. ONE model call, attempted up to
1917
- # 1 + MODEL_CALL_MAX_RETRIES times. The SDKs retry a request that
1918
- # fails before its stream opens; an error sent INSIDE a stream
1919
- # that opened with 200 is raised straight up by both, and that is
1920
- # how OpenRouter reports an overloaded upstream. Which failures
1921
- # qualify is core/provider_errors.py's question.
1922
- #
1923
- # `shown` was the boundary until batch 113 (TECHNICAL_DEBT 25).
1924
- # It read "a RichLog row cannot be taken back", which was true
1925
- # of the transcript as it stood: a retry after a delta would
1926
- # have drawn the answer a second time under the half already on
1927
- # screen, so a DRAWN run was refused the retry a reader most
1928
- # wanted. Batch 112 made a row retractable -- `_replay()` draws
1929
- # the transcript from `_entries` -- so the loop now says what
1930
- # happened and the drawing surface takes its own rows back.
1931
- #
1932
- # `shown` survives with a different job: it is no longer "may we
1933
- # retry" but "is there anything to retract", which is the only
1934
- # question left for it to answer.
1935
- #
1936
- # Below the wrappers that write the user message, so a retry
1937
- # never writes it twice; and before the accounting, so only the
1938
- # attempt that succeeded is counted or persisted (D20). A failed
1939
- # stream reports no usage to count in any case.
1940
- retry = 0
1941
- # §61 CN4. The deltas are accumulated HERE because no
1942
- # provider branch can supply them after a cut: the Anthropic
1943
- # one builds its text from `stream.get_final_message()`,
1944
- # which a stream broken off part way never produces. Reset
1945
- # per ATTEMPT, beside `shown`, so a retry that retracts what
1946
- # was drawn does not also keep it.
1947
- cut_short = False
1948
- while True:
1949
- shown = False
1950
- partial = []
1951
- try:
1952
- for token in call_model_stream(
1953
- client, provider_name, model, memory.messages,
1954
- system_prompt, tool_schemas, temperature, effort,
1955
- ):
1956
- if token.final_response is not None:
1957
- response = token.final_response
1958
- # §61 CN2, and guarded on `response is None`
1959
- # rather than placed by line order, because
1960
- # placement alone was not enough: a cancel
1961
- # arriving in the gap before the final-response
1962
- # token still cut a call that had already been
1963
- # made and paid for, and its usage went with it.
1964
- # A step holding a complete response is
1965
- # FINISHED -- it is accounted and persisted
1966
- # exactly as always, and the stop lands at the
1967
- # next site instead.
1968
- if response is None and is_cancelled(cancel):
1969
- cut_short = True
1970
- break
1971
- if token.text_delta:
1972
- shown = True
1973
- partial.append(token.text_delta)
1974
- yield LoopEvent(token_delta=token.text_delta)
1975
- if token.thinking_delta:
1976
- shown = True
1977
- yield LoopEvent(thinking_delta=token.thinking_delta)
1978
- break
1979
- except Exception as e: # noqa: BLE001 -- re-raised unless it qualifies
1980
- retry += 1
1981
- if (retry > config.MODEL_CALL_MAX_RETRIES
1982
- or not provider_errors.is_transient(e)):
1983
- raise
1984
- response = None
1985
- delay = provider_errors.backoff_delay(
1986
- retry, config.MODEL_CALL_RETRY_BASE_DELAY_S,
1987
- provider_errors.retry_after_s(e))
1988
- attempts = config.MODEL_CALL_MAX_RETRIES + 1
1989
- logger.warning(
1990
- "Model call to %s/%s failed (%s); retrying in %.0fs, "
1991
- "attempt %d of %d.",
1992
- provider_name, model, provider_errors.describe(e),
1993
- delay, retry + 1, attempts)
1994
- if shown:
1995
- # Batch 113. BEFORE the wait, not after it: the
1996
- # reader is about to watch a part-written answer
1997
- # disappear and then several seconds of nothing,
1998
- # and the sentence explaining that is worth more
1999
- # while it is happening than once it is over.
2000
- #
2001
- # Only when something was drawn. An attempt that
2002
- # streamed nothing has nothing to take back, and
2003
- # the warning above is already the record of it.
2004
- yield LoopEvent(retract={
2005
- "text": "the answer was interrupted (%s); "
2006
- "retrying, attempt %d of %d"
2007
- % (provider_errors.describe(e),
2008
- retry + 1, attempts),
2009
- "attempt": retry + 1,
2010
- "attempts": attempts,
2011
- })
2012
- provider_errors.wait(delay)
2013
-
2014
- # §61 CN2/CN4. Leaving the `for` above closed the
2015
- # provider stream: every branch yields from inside its own
2016
- # context manager, so the connection is already released by
2017
- # the time this runs. What is left to decide is the
2018
- # half-answer, and CN4 keeps it.
2019
- if cut_short:
2020
- yield from _finish_cancelled(
2021
- memory, None, partial_text="".join(partial), unrun=(),
2022
- reason=cancel.reason, granted_calls=granted_calls,
2023
- notices=notices,
2024
- totals=(total_tokens_used, turn_new_tokens,
2025
- turn_output_tokens))
2026
- return
2027
-
2028
- if response is None:
2029
- raise RuntimeError(
2030
- "call_model_stream completed without yielding a final response"
2031
- )
2032
-
2033
- usage_in = response.usage.get("input_tokens", 0)
2034
- usage_out = response.usage.get("output_tokens", 0)
2035
- total_tokens_used += usage_in + usage_out
2036
- if turn_baseline_input is None:
2037
- # First call of the turn: its prompt IS the inherited
2038
- # thread, so only this step's OUTPUT counts as new.
2039
- turn_baseline_input = usage_in
2040
- else:
2041
- turn_new_tokens += max(0, usage_in - turn_prev_input)
2042
- turn_new_tokens += usage_out
2043
- turn_output_tokens += usage_out
2044
- turn_prev_input = usage_in
2045
- memory.record_billed(usage_in + usage_out)
2046
- response.turn_billed_tokens = total_tokens_used
2047
- response.turn_new_tokens = turn_new_tokens
2048
- response.turn_output_tokens = turn_output_tokens
2049
-
2050
- # D20: persist EVERY assistant turn BEFORE any branching.
2051
- memory.add_assistant_message(response)
2052
- response.granted_calls = granted_calls
2053
- response.notices = notices
2054
- # §21: the provider's own count of everything it was just
2055
- # sent. Recorded here rather than at the trigger so a thread
2056
- # resumed in a later process starts from a real measurement
2057
- # instead of a character estimate.
2058
- memory.record_input_tokens(response.usage.get("input_tokens", 0))
2059
-
2060
- if max_total_tokens is not None and total_tokens_used >= max_total_tokens:
2061
- response.stop_reason = "token_budget_exceeded"
2062
- yield LoopEvent(
2063
- final_response=response, stop_reason=response.stop_reason,
2064
- )
2065
- return
2066
-
2067
- if not response.tool_calls:
2068
- response.stop_reason = "complete"
2069
- yield LoopEvent(
2070
- final_response=response, stop_reason=response.stop_reason,
2071
- )
2072
- return
2073
-
2074
- # NA9. The response is partitioned before anything runs: a run of
2075
- # calls whose ToolSpec declares `parallel` goes together, and every
2076
- # other call is a group of one in its original position. A response
2077
- # with nothing parallel in it therefore takes the same path it
2078
- # always did, one group of one at a time.
2079
- groups = _parallel_groups(response.tool_calls)
2080
- for index, group in enumerate(groups):
2081
- # §61 CN2/CN6. BETWEEN groups, never inside one. A call
2082
- # already running finishes and settles: nothing here has
2083
- # the power to kill a tool, and a cancel that threw away
2084
- # a completed call's result would discard work already
2085
- # done. Every group NOT reached still needs its rows --
2086
- # #42's lesson from the other side -- which is what
2087
- # `unrun` carries.
2088
- if is_cancelled(cancel):
2089
- yield from _finish_cancelled(
2090
- memory, response, partial_text=None,
2091
- unrun=[c for rest in groups[index:] for c in rest],
2092
- reason=cancel.reason, granted_calls=granted_calls,
2093
- notices=notices,
2094
- totals=(total_tokens_used, turn_new_tokens,
2095
- turn_output_tokens))
2096
- return
2097
- # In call order, and BEFORE anything is submitted, so a batch
2098
- # announces its whole membership at once rather than in
2099
- # whatever order three threads happen to reach their first
2100
- # line. Hoisted out of `_dispatch_one` for exactly that: the
2101
- # start of a call is a fact the frame that ordered it knows.
2102
- for call in group:
2103
- yield LoopEvent(tool_call_start={
2104
- "id": call.id, "name": call.name, "input": call.input,
2105
- })
2106
-
2107
- if len(group) == 1:
2108
- # No siblings, no gate, no thread. Byte-identical to the
2109
- # pre-slice-8 path, which is what makes every existing
2110
- # test of this loop a test of the sequential branch.
2111
- settled = [(group[0], (yield from _dispatch_one(
2112
- group[0], context=context, run_info=run_info,
2113
- response_channel=response_channel, memory=memory,
2114
- activity=activity, cancel=cancel)))]
2115
- else:
2116
- settled = yield from _dispatch_parallel(
2117
- group, context=context, run_info=run_info,
2118
- response_channel=response_channel, memory=memory,
2119
- activity=activity, cancel=cancel)
2120
-
2121
- # NA11. In the MODEL'S order, whatever order they finished in
2122
- # -- and EVERY row of the group recorded before ANY event is
2123
- # announced (#215, batch 221). #42's persist-before-emit
2124
- # held per call and not per group: a consumer gone at the
2125
- # first call's `tool_result` left the later calls' tools run
2126
- # and their rows never written.
2127
- announced = [event for call, outcome in settled
2128
- for event in _settle_one(call, outcome, memory,
2129
- granted_calls, notices)]
2130
- yield from announced
2131
-
2132
- # The mid-turn valve (M3). A single turn can add far more than
2133
- # any buffer covers -- MAX_READ_CHARS alone is ~12.5k tokens
2134
- # per read call, with up to max_steps of them -- so waiting for
2135
- # the next turn boundary would let a tool-heavy turn run the
2136
- # thread into the provider's hard limit.
2137
- #
2138
- # Safe by construction rather than by timing: the current-turn
2139
- # floor makes the current turn unfoldable, so this can only ever
2140
- # summarize exchanges that were already complete when the turn
2141
- # began. That is what made a mid-turn trigger acceptable at
2142
- # all.
2143
- #
2144
- # The floor is `memory.completed_turns()`, asked inside
2145
- # _maybe_compact. This comment used to name a `turn_start`
2146
- # variable recorded at the top of the turn (audit #91); it moved
2147
- # because archive-space turn counting is time-invariant WITHIN a
2148
- # turn -- a completed turn cannot become incomplete -- so asking
2149
- # lazily gives the same answer and keeps a storage read off every
2150
- # turn nowhere near the threshold. See core/compaction.py's note
2151
- # on why it is computed there rather than passed down.
2152
- yield from _maybe_compact(
2153
- memory, model, provider_name, notices,
2154
- compaction_mode
2155
- if compaction_mode is not None
2156
- else _derived_compaction_mode(memory),
2157
- activity=activity, depth=_compactor_depth(context))
2158
-
2159
- # max_steps exhausted without an earlier return
2160
- response.stop_reason = "max_steps_reached"
2161
- yield LoopEvent(
2162
- final_response=response, stop_reason=response.stop_reason,
2163
- )
2164
-
2165
- @staticmethod
2166
- def run_agent_conversation(
2167
- user_goal: str,
2168
- model: str,
2169
- provider_name: str = DEFAULT_PROVIDER,
2170
- max_steps: int = config.MAX_ITERATIONS,
2171
- max_total_tokens: Optional[int] = _SPEND_UNSET,
2172
- thread_id: Optional[UUID] = None,
2173
- temperature: Optional[float] = None,
2174
- effort: Optional[str] = None,
2175
- context: Optional[ToolContext] = None,
2176
- system_prompt: Optional[str] = None,
2177
- response_channel=None,
2178
- granted_tools: Optional[set] = None,
2179
- authorization=None,
2180
- thread_kind: str = THREAD_KIND_CHAT,
2181
- activity=None,
2182
- thread_parent: Optional[UUID] = None,
2183
- thread_parent_call: Optional[str] = None,
2184
- thread_agent: Optional[str] = None,
2185
- cancel=None,
2186
- observe=None,
2187
- active_skills=(),
2188
- ) -> ModelResponse:
2189
- """Regular conversation — full tool set, default system prompt,
2190
- one continuous thread. Pass thread_id to resume an existing
2191
- thread; omit (or None) to start a fresh one. Pass context (§15) to
2192
- run under an agent's tool restrictions; None means global policy
2193
- only. Pass system_prompt (§18) when running AS an agent -- the
2194
- TUI worker and spawn_subagent both build it via
2195
- agents.manager.AgentManager.system_prompt_for();
2196
- None keeps the default base + skill/agent catalogs.
2197
-
2198
- A thread's persistent goal (§18 goal mode) is appended to WHICHEVER
2199
- prompt is used, so it applies in every shell without the callers
2200
- knowing about it.
2201
-
2202
- response_channel / granted_tools exist for spawn_subagent (§18
2203
- S1). Without the channel a spawned subagent ran HEADLESS while its
2204
- parent could prompt, so it silently lost every approval-gated tool
2205
- -- including all MCP tools -- and the same agent behaved
2206
- differently depending on whether it was activated with /agent or
2207
- spawned.
2208
-
2209
- authorization (§20): a RunAuthorization, for an agent-shaped run
2210
- that is part of a research run -- §20's reviewer is the first.
2211
- §25 added the bundle to the pass entry point and
2212
- continue_conversation and stopped here, because nothing
2213
- agent-shaped needed it yet; a reviewer inheriting its run's grants
2214
- and BUDGET does.
2215
-
2216
- Mutually exclusive with granted_tools, and checked rather than
2217
- silently resolved. The two spell the same underlying argument, so
2218
- one would quietly win -- and if the bundle lost, a reviewer would
2219
- run with no budget and no provider while looking authorised.
2220
-
2221
- thread_kind (§27 T1) is what this entry point creates when it
2222
- creates a thread. It defaults to "chat" because this is ALSO the
2223
- plain-conversation entry point for both shells; the three callers
2224
- that are not a human conversation -- spawn_subagent, §20's reviewer
2225
- and §21a's compactor -- pass THREAD_KIND_SUBAGENT, which is what
2226
- keeps their threads out of the picker. Ignored when thread_id is
2227
- given: resuming does not reclassify.
2228
-
2229
- thread_parent / thread_parent_call / thread_agent (§47) record
2230
- WHO created this thread, on the same terms: forwarded to the new
2231
- thread, ignored on a resume. They are what makes a spawned run
2232
- reachable afterwards -- without them a `▸ spawn_subagent` line
2233
- describes a conversation nothing can find. Only the callers that
2234
- know they are creating a child pass them.
2235
-
2236
- observe (ROADMAP_v3 §86) is `run_to_completion`'s: handed every
2237
- event as the turn runs. The CLI passes one to print the turn live.
2238
-
2239
- active_skills (§89) are the session's `/skill` activations: marked
2240
- in the default prompt's catalog and their bodies pinned last by
2241
- session_tiers (§19 K1). The TUI builds its own prompt and passes
2242
- none here; the CLI passes its session's."""
2243
- if authorization is not None and granted_tools is not None:
2244
- raise ValueError(
2245
- "run_agent_conversation: pass authorization= or "
2246
- "granted_tools=, not both -- they set the same underlying "
2247
- "argument, so one would silently win."
2248
- )
2249
- memory = ConversationMemory(
2250
- thread_id=thread_id, kind=thread_kind,
2251
- parent_thread_id=thread_parent,
2252
- parent_call_id=thread_parent_call, agent_name=thread_agent)
2253
- # §47. THE EARLIEST MOMENT THE ID EXISTS, which is what makes a
2254
- # RUNNING child openable rather than only a finished one. The
2255
- # span was opened by the caller before this function was called
2256
- # -- the handler brackets the call, the thread is created inside
2257
- # it -- so the sink learned a name and a depth and had no address
2258
- # for them. A no-op when no span is open, which is every
2259
- # top-level conversation, so this needs no branch.
2260
- agent_activity.bind(activity, memory.thread_id)
2261
- memory.add_user_message(user_goal)
2262
- # ROADMAP_v3 §49: shared with wake_conversation, so a turn a
2263
- # background session starts runs under the same prompt tiers.
2264
- prompt = RunAgentLoop._conversation_prompt(
2265
- memory, system_prompt, model=model, provider_name=provider_name,
2266
- authorization=authorization,
2267
- response_channel=response_channel, granted_tools=granted_tools,
2268
- active_skills=active_skills)
2269
- auth_kwargs = (
2270
- _authorization_kwargs(authorization) if authorization is not None
2271
- else {"granted_tools": granted_tools}
2272
- )
2273
- # §23: the bundle's channel and the explicit parameter are now the
2274
- # SAME kind of thing, so they can collide -- they could not before,
2275
- # when one was a queue named permission_channel and the other an
2276
- # ApprovalProvider named approval_provider, and both were passed.
2277
- #
2278
- # The explicit argument wins, preserving _obtain_approval's old
2279
- # precedence ("the channel wins when both are present"). A caller
2280
- # that passes one is describing THIS run; the bundle may have been
2281
- # assembled for a pipeline several layers up.
2282
- # Popped UNCONDITIONALLY, then merged. `a or kwargs.pop(...)`
2283
- # short-circuits, so the key would survive in auth_kwargs on
2284
- # exactly the path where an explicit channel was passed -- and
2285
- # collide with it at the call below.
2286
- bundled_channel = auth_kwargs.pop("response_channel", None)
2287
- response_channel = response_channel or bundled_channel
2288
- response = run_to_completion(RunAgentLoop._run(
2289
- memory, prompt,
2290
- provider_name, model, context,
2291
- max_steps, _resolve_spend_cap(max_total_tokens),
2292
- temperature=temperature, effort=effort,
2293
- response_channel=response_channel, activity=activity,
2294
- cancel=cancel,
2295
- **auth_kwargs,
2296
- ), observe)
2297
- response.thread_id = memory.thread_id
2298
- return response
2299
-
2300
- @staticmethod
2301
- def stream_deep_research_mode(
2302
- pass_input: str,
2303
- model: str,
2304
- pass_id: str,
2305
- provider_name: str = DEFAULT_PROVIDER,
2306
- max_steps: int = config.MAX_ITERATIONS,
2307
- max_total_tokens: Optional[int] = _SPEND_UNSET,
2308
- temperature: Optional[float] = None,
2309
- effort: Optional[str] = None,
2310
- context: Optional[ToolContext] = None,
2311
- authorization=None,
2312
- activity=None,
2313
- ):
2314
- """One research pass, as a generator of LoopEvents, RETURNING the
2315
- ModelResponse (ROADMAP_v2 §26).
2316
-
2317
- Exists because §22's P2 -- "a pass's LoopEvents do not propagate
2318
- up" -- made a pass opaque while it ran. The pipeline could say
2319
- which pass had started and nothing about what it was doing, so a
2320
- pass making fourteen tool calls over several minutes looked
2321
- identical to one that had hung.
2322
-
2323
- P2 is AMENDED here, not repealed. What escapes this generator is
2324
- still consumed inside core/reasoning/orchestrator.py, which
2325
- translates a chosen subset into PipelineEvents at the pass
2326
- boundary -- so a pipeline consumer still only ever sees one event
2327
- type, which is what P1 and P2 were jointly protecting. What
2328
- changed is the premise that a pass's internals are not worth
2329
- seeing.
2330
-
2331
- A GENERATOR SIBLING, not an observer callback on the existing
2332
- function. That shape is the project's own, used three times
2333
- already, and §23 AC1 exists specifically to stop a third bespoke
2334
- request/response channel appearing beside the ones that already
2335
- existed -- which §23 has now merged into core.interaction.
2336
-
2337
- The response is RETURNED rather than read off the terminal event
2338
- because `thread_id` is attached after the loop finishes. A caller
2339
- must therefore drain this with something that keeps a generator's
2340
- return value: `yield from` (what _run_pass does) or
2341
- `tests/conftest.drain`, never run_to_completion().
2342
-
2343
- §27: the fresh thread per pass is a LOCKED INVARIANT, not the
2344
- defect §27's second bug looked like -- passes share distilled JSON
2345
- and never raw history, which is what stops a later pass reading how
2346
- an earlier one argued. What was missing is the thread saying so, so
2347
- that ~15 threads per run stop being offered as conversations.
2348
-
2349
- §47: the span brackets the WHOLE generator, which is why it is the
2350
- outermost thing in the body. A pass is a run in its own right and
2351
- takes minutes; a row that appeared only at the end would describe
2352
- something already over. It closes on GeneratorExit too, which is
2353
- the abandonment case §22 records above -- a TUI quitting mid-run
2354
- must not leave the pass on screen.
2355
- """
2356
- # Depth derived from the context the pass starts at rather than
2357
- # written as a 1: `_compactor_depth`'s rule, one entry point over.
2358
- depth = (context.subagent_depth if context is not None else 0) + 1
2359
- with agent_activity.span(activity, pass_id, depth):
2360
- memory = ConversationMemory(
2361
- kind=THREAD_KIND_RESEARCH_PASS,
2362
- # §47. No parent THREAD: a pass is a child of the RUN, and
2363
- # a run is not a conversation. §27's T2 already indexes
2364
- # them on `PipelineRun.pass_threads`, the run's own
2365
- # object, so a second index here would be two records of
2366
- # one edge -- the producer/consumer shape this project
2367
- # keeps finding.
2368
- agent_name=pass_id)
2369
- # The address, at the earliest moment it exists, so a pass is
2370
- # openable WHILE it runs rather than once the report lands.
2371
- agent_activity.bind(activity, memory.thread_id)
2372
- memory.add_user_message(pass_input)
2373
- # #68. The catalogs are decided from the SAME bundle the tool
2374
- # schemas are decided from a few frames down, so a pass cannot
2375
- # be told to spawn a subagent it will not be given.
2376
- _callable_only, _granted = advertisement_facts(authorization)
2377
- system_prompt = system_prompts.pass_prompt(
2378
- pass_id, callable_only=_callable_only, granted=_granted)
2379
- response = None
2380
- for event in RunAgentLoop._run(
2381
- memory, system_prompt, provider_name, model, context,
2382
- max_steps, _resolve_spend_cap(max_total_tokens),
2383
- temperature=temperature, effort=effort,
2384
- # §21 M6. A pass is headless and unattended and already
2385
- # returns a distillation, so routine compaction here would
2386
- # spend on a judgment call nobody is watching. The
2387
- # backstop still fires near the model's real context
2388
- # window, because the alternative there is a hard provider
2389
- # error mid-pipeline.
2390
- compaction_mode="backstop",
2391
- activity=activity,
2392
- **_authorization_kwargs(authorization),
2393
- ):
2394
- if event.final_response is not None:
2395
- response = event.final_response
2396
- yield event
2397
- if response is None:
2398
- # Same contract as run_to_completion's RuntimeError, and
2399
- # for the same reason: a loop that ended without a final
2400
- # response has a bug, and returning None would push the
2401
- # failure into whichever pass dereferences .text first.
2402
- raise RuntimeError(
2403
- "Generator completed without yielding a final_response"
2404
- )
2405
- response.thread_id = memory.thread_id
2406
- return response
2407
-
2408
- @staticmethod
2409
- def continue_conversation(
2410
- thread_id: UUID,
2411
- message: str,
2412
- system_prompt: str,
2413
- model: str,
2414
- provider_name: str = DEFAULT_PROVIDER,
2415
- max_steps: int = config.MAX_ITERATIONS,
2416
- max_total_tokens: Optional[int] = _SPEND_UNSET,
2417
- temperature: Optional[float] = None,
2418
- effort: Optional[str] = None,
2419
- context: Optional[ToolContext] = None,
2420
- authorization=None,
2421
- activity=None,
2422
- ) -> ModelResponse:
2423
- """
2424
- Sends a follow-up message into an EXISTING conversation thread and
2425
- runs the loop to completion on it. The resumed thread's full history
2426
- (every prior user/assistant/tool turn, persisted by _run()'s
2427
- always-persist behavior) is loaded by ConversationMemory and
2428
- visible to the next call_model invocation.
2429
-
2430
- ROADMAP §3's JSON-retry path uses this to retry a pass that
2431
- returned malformed JSON: the corrective follow-up is sent into
2432
- the same thread the failed pass used, so the model sees its own
2433
- prior output in context and can correct it.
2434
-
2435
- authorization (§25) is NOT optional in practice for that path. A
2436
- retry is the same pass continuing, so it must run with the same
2437
- authorization; omitting it would silently strip the pass's gated
2438
- tools on precisely the attempt where the model is already
2439
- struggling, and the only symptom would be a second malformed
2440
- answer. The budget carries across, so retries spend from the same
2441
- ceiling rather than resetting it.
2442
- """
2443
- memory = ConversationMemory(thread_id=thread_id)
2444
- memory.add_user_message(message)
2445
- response = run_to_completion(RunAgentLoop._run(
2446
- memory, system_prompt, provider_name, model, context,
2447
- max_steps, _resolve_spend_cap(max_total_tokens),
2448
- temperature=temperature, effort=effort, activity=activity,
2449
- **_authorization_kwargs(authorization),
2450
- ))
2451
- response.thread_id = thread_id
2452
- return response
2453
-
2454
- @staticmethod
2455
- def _conversation_prompt(memory, system_prompt, *, model, provider_name,
2456
- authorization=None,
2457
- response_channel=None, granted_tools=None,
2458
- active_skills=()) -> str:
2459
- """The system prompt a conversation turn runs under -- ONE copy, for a
2460
- turn the user started and a turn a background session's result
2461
- started (ROADMAP_v3 §49), so a wake turn cannot run under a prompt
2462
- missing the goal, the references or the checklist a user's turn has.
2463
-
2464
- Moved out of run_agent_conversation unchanged; its comments there
2465
- record why each tier is conditional or not.
2466
- """
2467
- # #68, and this branch is the one an unattended CLI run takes.
2468
- _callable_only, _granted = advertisement_facts(
2469
- authorization, response_channel, granted_tools)
2470
- base = (system_prompt if system_prompt is not None
2471
- else system_prompts.with_catalogs(
2472
- with_persona(DEFAULT_SYSTEM_PROMPT, model, provider_name),
2473
- list(active_skills or ()) or None,
2474
- callable_only=_callable_only,
2475
- granted=_granted))
2476
- # A system_prompt handed in is an agent's, built by
2477
- # system_prompt_for(); see session_tiers for why that decides the
2478
- # memories. §54 AT7: internal compaction and review also use this
2479
- # wrapper, and their source is not a person's file mention.
2480
- return session_tiers(base, memory,
2481
- agent_built=system_prompt is not None,
2482
- mentions=memory.kind == THREAD_KIND_CHAT,
2483
- active_skills=active_skills)
2484
-
2485
- @staticmethod
2486
- def wake_conversation(
2487
- thread_id: UUID,
2488
- text: str,
2489
- harness: dict,
2490
- model: str,
2491
- provider_name: str = DEFAULT_PROVIDER,
2492
- max_steps: int = config.MAX_ITERATIONS,
2493
- max_total_tokens: Optional[int] = _SPEND_UNSET,
2494
- temperature: Optional[float] = None,
2495
- effort: Optional[str] = None,
2496
- context: Optional[ToolContext] = None,
2497
- system_prompt: Optional[str] = None,
2498
- response_channel=None,
2499
- granted_tools: Optional[set] = None,
2500
- authorization=None,
2501
- activity=None,
2502
- cancel=None,
2503
- observe=None,
2504
- active_skills=(),
2505
- ) -> ModelResponse:
2506
- """A turn started by the HARNESS in an existing thread: a background
2507
- session's result, delivered as a harness-written user row
2508
- (ROADMAP_v3 §49, SS5). Drained, like the two wrappers above -- the
2509
- subagent asleep in its spawn and the CLI's wait loop call it; the
2510
- TUI builds its own generator, as it does for a user's turn.
2511
-
2512
- `run_agent_conversation`'s arguments, less what only a NEW thread
2513
- needs (kind, lineage) and plus the row: a wake runs with the same
2514
- channel, grant, authorization, activity and CANCEL as the run whose
2515
- session it reports, because it IS that run continuing. `cancel` was
2516
- the one member of that list the signature omitted, and because
2517
- `agents/subagent_tool.py` builds ONE `common` dict for the child's
2518
- first turn and every wake after it -- deliberately, so the two
2519
- cannot drift -- §61's CN7 adding `cancel` to that dict meant every
2520
- subagent wake turn raised `TypeError` before anything else
2521
- happened, 100% of the time, discarding a full agent run that had
2522
- already been paid for in model calls (batch 133). `authorization` is
2523
- what the CLI's chat loop carries -- without it a wake turn would
2524
- run with no way to ask a human, so every gated call in it would be
2525
- denied for a reason that is about the harness rather than the
2526
- request, which is the silent-stripping failure §25 records.
2527
-
2528
- `observe` is `run_agent_conversation`'s (§86): the CLI's wait loop
2529
- prints a wake turn live exactly as it prints the user's own.
2530
-
2531
- NOT a second `_run`. tests/test_grants.py walks this module for
2532
- exactly one function by that name, and this is a wrapper over it.
2533
- """
2534
- if authorization is not None and granted_tools is not None:
2535
- raise ValueError(
2536
- "wake_conversation: pass authorization= or granted_tools=, "
2537
- "not both -- they set the same underlying argument, so one "
2538
- "would silently win."
2539
- )
2540
- memory = ConversationMemory(thread_id=thread_id)
2541
- agent_activity.bind(activity, memory.thread_id)
2542
- memory.add_harness_message(text, harness)
2543
- prompt = RunAgentLoop._conversation_prompt(
2544
- memory, system_prompt, model=model, provider_name=provider_name,
2545
- authorization=authorization,
2546
- response_channel=response_channel, granted_tools=granted_tools,
2547
- active_skills=active_skills)
2548
- auth_kwargs = (
2549
- _authorization_kwargs(authorization) if authorization is not None
2550
- else {"granted_tools": granted_tools}
2551
- )
2552
- # The explicit argument wins, and the key is popped unconditionally
2553
- # -- run_agent_conversation's reasoning, unchanged.
2554
- bundled_channel = auth_kwargs.pop("response_channel", None)
2555
- response_channel = response_channel or bundled_channel
2556
- response = run_to_completion(RunAgentLoop._run(
2557
- memory, prompt,
2558
- provider_name, model, context,
2559
- max_steps, _resolve_spend_cap(max_total_tokens),
2560
- temperature=temperature, effort=effort,
2561
- response_channel=response_channel, activity=activity,
2562
- cancel=cancel,
2563
- **auth_kwargs,
2564
- ), observe)
2565
- response.thread_id = memory.thread_id
2566
- return response
1
+ """
2
+ core/loop.py
3
+
4
+ RunAgentLoop._run() is the shared ReAct control flow: call the model,
5
+ dispatch any tool calls via the registry, feed results back, repeat until
6
+ the model responds with plain text or max_steps is hit. Both public
7
+ methods below configure and call this same shared method -- neither
8
+ reimplements the loop, so there's exactly one place the mechanics live.
9
+
10
+ §13 streaming refactor: _run() is now a generator yielding LoopEvent
11
+ objects. run_to_completion() drains it for callers that only need the
12
+ final ModelResponse (the three public wrappers). The generator shape
13
+ lets the TUI observe token deltas, tool calls, and permission prompts
14
+ in real time without callbacks.
15
+
16
+ §15 permission refactor: _run()'s old `allowed_tools` list is replaced by
17
+ an optional ToolContext, which carries the same restriction plus approval
18
+ overrides and subagent depth. One representation, threaded to the one
19
+ place that enforces it (registry -> security.permissions), instead of the
20
+ loop keeping a parallel membership check of its own.
21
+
22
+ D20 invariant: memory.add_assistant_message(response) executes
23
+ immediately after every call_model_stream return and BEFORE any
24
+ stop-condition branch. This ordering is load-bearing — persisting only
25
+ on the tool-calling path silently drops plain-text final answers and
26
+ budget-truncated responses.
27
+ """
28
+
29
+ import logging
30
+ import queue
31
+ import threading
32
+
33
+ # §47 slice 8 (NA10). Threads rather than asyncio: `_run` is a synchronous
34
+ # generator and everything under it is blocking I/O, so a bounded pool is
35
+ # the change that fits what is already here. `copy_context` is what makes
36
+ # a submitted call carry the parent span batch 67 put on a ContextVar.
37
+ from concurrent.futures import ThreadPoolExecutor
38
+ from contextlib import nullcontext
39
+ from contextvars import copy_context
40
+ from dataclasses import dataclass, field
41
+ from datetime import UTC
42
+ from typing import Optional
43
+ from uuid import UUID
44
+
45
+ import config
46
+ import prompts.system_prompts as system_prompts
47
+ from core import agent_activity, interaction, provider_errors
48
+ from core.cancel import is_cancelled
49
+ from core.client import (
50
+ ModelResponse,
51
+ accepts_images,
52
+ api_initialization,
53
+ call_model_stream,
54
+ context_window_for,
55
+ effort_for,
56
+ )
57
+ from core.events import LoopEvent
58
+ from core.memory import ConversationMemory
59
+ from safety.policy_enforcement import redact_diagnostic_text
60
+
61
+ # §27 (T1). The loop is where a thread's kind is DECIDED -- it knows which
62
+ # of its three entry points is running -- and storage.create_thread is
63
+ # where it is stored. Nothing in between learns what a kind means.
64
+ from storage import (
65
+ THREAD_KIND_CHAT,
66
+ THREAD_KIND_RESEARCH_PASS,
67
+ THREAD_KIND_SUBAGENT,
68
+ )
69
+ from tools.base import GRANT_NEVER
70
+ from tools.context import RunInfo, ToolContext
71
+ from tools.registry import ToolCallDenied, registry
72
+
73
+ logger = logging.getLogger(__name__)
74
+
75
+ # §32 A8 (#72). "You are a helpful assistant." was the whole of it,
76
+ # and everything else in a chat prompt is generated or thread state --
77
+ # the two catalogs, with_goal, with_memories, with_refs, with_todos,
78
+ # and any active skill bodies. So the one paragraph a chat turn most
79
+ # needs was the one part no tier supplied.
80
+ #
81
+ # Shared with the ten research passes rather than copied: see
82
+ # prompts/untrusted_content and system_prompts.untrusted_content_paragraph.
83
+ DEFAULT_SYSTEM_PROMPT = (
84
+ "You are a helpful assistant.\n\n"
85
+ + system_prompts.untrusted_content_paragraph(
86
+ system_prompts.CHAT_INSTRUCTION_SOURCE))
87
+ DEFAULT_PROVIDER = "ANTHROPIC"
88
+
89
+ # The headless callability notice (§18) names tools hidden by
90
+ # schemas(callable_only=True). Deduplicated on the HIDDEN SET, not once
91
+ # per process: the set is context-dependent, so a once-per-process flag
92
+ # reported only the first run's and left every later one silent. A
93
+ # subagent whose definition tightens approval for another tool hides a
94
+ # strictly larger set, and that difference was exactly what never got
95
+ # logged -- the quiet invisibility this notice exists to prevent.
96
+ _headless_notices_shown: set = set()
97
+
98
+ # ROADMAP_v3 §81 (IM6), on the headless notice's terms: a tool the user
99
+ # enabled and this run leaves out because no image could reach the model is
100
+ # named once, deduplicated on (provider, thread kind, hidden set) -- the three
101
+ # things the answer depends on, so a later run that differs in any of them
102
+ # still hears about its own.
103
+ _image_notices_shown: set = set()
104
+
105
+
106
+ def _images_deliverable(provider_name: str, memory) -> bool:
107
+ """Whether an image in a tool result can reach the model in this run
108
+ (IM6): the provider takes images, and the thread is not a research
109
+ pass. A property of WHAT THE THREAD IS, for
110
+ `_derived_compaction_mode`'s reason: a pass re-entered by a JSON retry
111
+ or the reviewer is still a pass. Its sources, claims and grounding are
112
+ all text, so a pass is never offered an image tool (§81 leaves the
113
+ pipeline out of scope)."""
114
+ kind = getattr(memory, "kind", THREAD_KIND_CHAT)
115
+ return kind != THREAD_KIND_RESEARCH_PASS and accepts_images(provider_name)
116
+
117
+
118
+ def with_goal(system_prompt: str, memory: ConversationMemory) -> str:
119
+ """Append a thread's persistent objective (§18 goal mode) to a system
120
+ prompt. Single source for the '## Persistent objective' marker so the
121
+ CLI wrapper and the TUI worker cannot drift apart. No-op when the
122
+ thread has no goal."""
123
+ goal = memory.extra.get("goal")
124
+ if not goal:
125
+ return system_prompt
126
+ return f"{system_prompt}\n\n## Persistent objective\n{goal}"
127
+
128
+
129
+ def with_persona(system_prompt: str, model: str, provider_name: str) -> str:
130
+ """Append the live chat identity (ROADMAP_v3 §58, PR1-PR4).
131
+
132
+ Callers resolve agent overrides first. Kept outside with_catalogs so
133
+ research passes, the compactor and the reviewer retain their own
134
+ task-specific prompts.
135
+ """
136
+ return (
137
+ f"{system_prompt}\n\nYou are running in Venastine Research Harness, "
138
+ "a tool-using assistant with a separate multi-pass research mode. "
139
+ f"Your current model is {model} from {provider_name}.")
140
+
141
+
142
+ def with_todos(system_prompt: str, memory: ConversationMemory) -> str:
143
+ """Append §23's todo list to a prompt. No-op when the thread has none.
144
+
145
+ Beside with_goal and taking the same argument, for the same reason: a
146
+ checklist is a property of the THREAD, not of the agent or the session.
147
+ It survives a resume and applies whichever agent is active.
148
+
149
+ MUST NOT move inside prompts.system_prompts.with_catalogs(). That
150
+ function feeds pass_prompt(), so a checklist written in a chat session
151
+ would land in all ten passes of a research run the user started
152
+ separately -- §19's K6, FOURTH instance, after §21b's memories (M13) and
153
+ §21c's refs (M19). Four copies of one warning made the convergence a
154
+ recorded deferral (J11); since batch 227 every tier is appended by
155
+ session_tiers, and SESSION_TIERS is the list the boundary test pins.
156
+
157
+ THE MODEL IS TOLD IT OWNS THIS. Unlike a memory or a reference, which
158
+ are context the model reads, the todo list is state the model WRITES --
159
+ so the fragment has to say that the way to change it is to call the
160
+ tool, or the model reports progress in prose while the panel the user is
161
+ watching stays stale.
162
+ """
163
+ todos = memory.extra.get("todos") or []
164
+ if not todos:
165
+ return system_prompt
166
+
167
+ lines = ["## Your checklist for this conversation",
168
+ "",
169
+ "You maintain this with `todo_write`, which replaces the whole "
170
+ "list. Keep it current as you work -- the user can see it.",
171
+ ""]
172
+ for item in todos:
173
+ status = item.get("status", "pending")
174
+ marker = {"completed": "[x]", "in_progress": "[>]"}.get(status, "[ ]")
175
+ lines.append(f"{marker} {item.get('content', '')}")
176
+ return f"{system_prompt}\n\n" + "\n".join(lines)
177
+
178
+
179
+ def with_memories(system_prompt: str, agent=None) -> str:
180
+ """Append §21b's durable-memory tier to a prompt. No-op when this run
181
+ is opted out or nothing is in scope.
182
+
183
+ Beside with_goal for the same reason: a single named function is what
184
+ stops the CLI and the TUI drifting apart. Both reach it through
185
+ session_tiers now (batch 227), which applies it only when no agent
186
+ built the prompt -- an agent's memories arrive in system_prompt_for().
187
+
188
+ MUST NOT move inside prompts.system_prompts.with_catalogs() -- that
189
+ feeds pass_prompt(), so memories would land in all ten research passes.
190
+ §19's K6, second instance.
191
+ """
192
+ from memories.manager import manager as memory_manager
193
+
194
+ fragment = memory_manager.prompt_fragment(agent)
195
+ if not fragment:
196
+ return system_prompt
197
+ return f"{system_prompt}\n\n{fragment}"
198
+
199
+
200
+ def with_refs(system_prompt: str, memory: ConversationMemory) -> str:
201
+ """Append §21c's referenced-conversation tier to a prompt. No-op when the
202
+ thread has no references attached.
203
+
204
+ Beside with_goal and taking the same argument, because a reference is a
205
+ property of the THREAD rather than of the agent or the session: it was
206
+ attached to this conversation by a person, it persists across a resume,
207
+ and it applies whichever agent happens to be active. That is also why it
208
+ is not routed through agents.manager.system_prompt_for() the way §21b's
209
+ memories are -- that function has no memory object, and refs are not an
210
+ agent's opt-in.
211
+
212
+ MUST NOT move inside prompts.system_prompts.with_catalogs(). That function
213
+ feeds pass_prompt(), so a reference attached in a chat session would land
214
+ in all ten passes of a research run the user started separately. §19's K6,
215
+ THIRD instance -- after §21b's memories, which is recorded as M13.
216
+
217
+ THE SUMMARIES ARE ANNOUNCED AS SUMMARIES OF SOMETHING ELSE. A referenced
218
+ thread is not this conversation's history, and a model that cannot tell
219
+ the difference will answer as though the user said things they said
220
+ elsewhere. Same reason §21a's compaction summary carries SUMMARY_PREFIX.
221
+ """
222
+ refs = memory.extra.get("refs") or []
223
+ if not refs:
224
+ return system_prompt
225
+
226
+ # CAPPED, AND THE CAP IS STATED IN THE TEXT (M14). The attach path already
227
+ # refuses to exceed it, so this is the second line of defence rather than
228
+ # the first -- but MAX_INJECTED_REFS can be lowered between sessions, and a
229
+ # thread carrying four refs under a cap of three must drop one visibly
230
+ # rather than silently.
231
+ cap = config.MAX_INJECTED_REFS
232
+ shown, total = refs[:cap], len(refs)
233
+ header = ("## Referenced conversations\n\n"
234
+ "Distilled summaries of OTHER conversations, attached by the "
235
+ "user for context. They are NOT part of this conversation's "
236
+ "history -- nothing here was said to you in this thread.")
237
+ if total > cap:
238
+ logger.warning(
239
+ "Injecting %s of %s attached references; the rest are not in this "
240
+ "prompt. Raise config.MAX_INJECTED_REFS or drop one with "
241
+ "/ref --clear.", cap, total)
242
+ header = (f"{header}\n\nShowing {cap} of {total} attached references. "
243
+ f"The others exist and are not included here.")
244
+
245
+ lines = [header]
246
+ for ref in shown:
247
+ label = ref.get("label") or "(no preview)"
248
+ lines.append(f"\n### {label}\n(thread {ref.get('thread_id')})\n"
249
+ f"{ref.get('summary', '')}")
250
+ return f"{system_prompt}\n\n" + "\n".join(lines)
251
+
252
+
253
+ def with_file_mentions(system_prompt: str, memory: ConversationMemory, *,
254
+ text: str | None = None) -> str:
255
+ """§54 AT6/AT7: names from this user turn, never file contents.
256
+
257
+ Do not move into with_catalogs: research passes and internal tasks do
258
+ not inherit chat mentions. Reading still goes through the normal tool
259
+ permissions, including paths outside the file-tool workspace.
260
+ """
261
+ from core import config_loader
262
+ from core.file_mentions import mentions
263
+
264
+ root = config_loader.get_project_path()
265
+ if not root:
266
+ return system_prompt
267
+ if text is None:
268
+ latest = next((row for row in reversed(memory.messages)
269
+ if row.get("role") == "user" and not row.get("harness")), {})
270
+ text = latest.get("content", "")
271
+ paths = list(dict.fromkeys(item.path for item in mentions(text)))
272
+ if not paths:
273
+ return system_prompt
274
+ import json
275
+
276
+ fragment = (
277
+ "## File mentions in the current user turn\n\n"
278
+ "The user named these paths relative to project root " + json.dumps(root) + ". "
279
+ "Resolve them against that root when calling file tools; the tools' workspace may differ. "
280
+ "Read the named files with your tools as needed for the request; their contents "
281
+ "have NOT been loaded. A trailing / names a folder: inspect it as needed, "
282
+ "without assuming its files were included. Paths may have been deleted; "
283
+ "report a missing path rather than guessing its contents. These names grant "
284
+ "no additional file access; normal tool permissions and approvals apply.\n"
285
+ + "\n".join("- " + json.dumps(path, ensure_ascii=False) for path in paths))
286
+ return f"{system_prompt}\n\n{fragment}"
287
+
288
+
289
+ #: The tiers a conversation turn appends after its base prompt, in the
290
+ #: order `session_tiers` appends them (#9, J11, A80). Each is thread or
291
+ #: session state, so none may move inside
292
+ #: prompts.system_prompts.with_catalogs(), which feeds pass_prompt(): §19's
293
+ #: K6. The BASE is not a tier -- the persona and the catalogs, and for an
294
+ #: agent its body and the project hub, which system_prompt_for() composes.
295
+ #: tests/test_prompt_tier_boundary.py keeps a canary for every name here.
296
+ SESSION_TIERS = ("goal", "memories", "refs", "todos", "file_mentions",
297
+ "skill_bodies")
298
+
299
+
300
+ def session_tiers(system_prompt: str, memory: ConversationMemory, *,
301
+ agent_built: bool, mentions: bool = True,
302
+ mention_text: str | None = None, active_skills=()) -> str:
303
+ """Every session tier, in SESSION_TIERS' order: the ONE assembly a
304
+ conversation prompt takes, in either shell (#9, J11, A80).
305
+
306
+ Three call sites assembled this by hand -- a loop turn, a TUI turn and
307
+ the TUI's one-shot -- in the same order, with the memories guard
308
+ spelled three ways. They call this now, and the guard is one argument.
309
+
310
+ `agent_built` IS THE LOAD-BEARING DIFFERENCE, and the reason this takes
311
+ a flag rather than making every tier conditional alike. An agent's
312
+ prompt got its memories inside system_prompt_for() (§21b, M13), so
313
+ appending them here would duplicate them. Refs, the checklist and the
314
+ goal are thread state, not an agent's opt-in, so an agent-built prompt
315
+ needs them too, and system_prompt_for() has no memory to read them
316
+ from (§21c, M19). Making them conditional "like the line above" is the
317
+ edit that looks right and drops every attached reference.
318
+
319
+ `mentions` is off for an internal compaction or review turn: its
320
+ source material is not a person's file-mention request (§54 AT7).
321
+ `mention_text` is the one-shot's message, which is not written to the
322
+ thread until its worker runs.
323
+
324
+ Active skill bodies go LAST on purpose (§19 K1): an activated skill is
325
+ the most specific instruction the user has given, and should read as
326
+ governing what precedes it. The CLI's arrive through
327
+ `run_agent_conversation` and `wake_conversation` since ROADMAP_v3 §89.
328
+ """
329
+ from skills.manager import manager as skills
330
+
331
+ prompt = with_goal(system_prompt, memory)
332
+ if not agent_built:
333
+ prompt = with_memories(prompt)
334
+ prompt = with_refs(prompt, memory)
335
+ prompt = with_todos(prompt, memory)
336
+ if mentions:
337
+ prompt = with_file_mentions(prompt, memory, text=mention_text)
338
+ fragment = skills.prompt_fragment(list(active_skills or ()))
339
+ return f"{prompt}\n\n{fragment}" if fragment else prompt
340
+
341
+
342
+ @dataclass(frozen=True)
343
+ class AgentTurn:
344
+ """What a session's active agent makes of one conversation turn."""
345
+
346
+ model: str
347
+ provider_name: str
348
+ context: Optional[ToolContext]
349
+ # None runs the default prompt, which the loop builds itself.
350
+ system_prompt: Optional[str]
351
+ max_steps: int
352
+
353
+
354
+ def agent_turn(agent, model: str, provider_name: str, active_skills=(), *,
355
+ callable_only: bool = False, granted=None,
356
+ one_shot: bool = False) -> AgentTurn:
357
+ """§18's session-scoped agent, applied to one turn, for either shell.
358
+
359
+ An active agent supplies the system prompt, the ToolContext, and
360
+ model/provider/max_steps overrides; with none active the turn is the
361
+ default harness run (base + catalogs, built by the loop). The session
362
+ tiers are NOT added here -- `_conversation_prompt` adds them to
363
+ whichever prompt runs, which is what keeps a wake turn's prompt the
364
+ same as the turn it continues.
365
+
366
+ ONE COPY (ROADMAP_v3 §89). The TUI's chat turn built this inline, and
367
+ the CLI's `/agent` needs the same answer: an agent that pins a model
368
+ in one shell and not the other is two agents with one name.
369
+
370
+ `callable_only` / `granted` are `advertisement_facts`' (#68), so an
371
+ unattended CLI turn under an agent does not advertise gated tools it
372
+ cannot call -- the TUI always has a channel and passes neither.
373
+
374
+ `one_shot` is §18's /grill-me: ONE turn in the session's thread under
375
+ the agent's prompt, and nothing else of the agent's -- the session's
376
+ model and provider, no ToolContext, the default step budget. That is
377
+ the TUI's `run_one_shot` assembly, kept as it was and now shared.
378
+ """
379
+ if agent is None:
380
+ return AgentTurn(model, provider_name, None, None,
381
+ config.MAX_ITERATIONS)
382
+ from agents.manager import manager
383
+
384
+ if one_shot:
385
+ prompt = manager.system_prompt_for(
386
+ agent, with_persona(DEFAULT_SYSTEM_PROMPT, model, provider_name),
387
+ list(active_skills or ()),
388
+ callable_only=callable_only, granted=granted)
389
+ return AgentTurn(model, provider_name, None, prompt,
390
+ config.MAX_ITERATIONS)
391
+ context = manager.active_context(agent)
392
+ model = agent.model or model
393
+ provider_name = agent.provider or provider_name
394
+ prompt = manager.system_prompt_for(
395
+ agent, with_persona(DEFAULT_SYSTEM_PROMPT, model, provider_name),
396
+ list(active_skills or ()), context=context,
397
+ callable_only=callable_only, granted=granted)
398
+ return AgentTurn(model, provider_name, context, prompt,
399
+ agent.max_steps or config.MAX_ITERATIONS)
400
+
401
+
402
+ def attach_ref(memory: ConversationMemory, thread_id, summary: str,
403
+ label: str = "") -> tuple:
404
+ """Attach one thread's summary to `memory`'s thread. Returns (ok, message).
405
+
406
+ ONE writer for both shells, like with_refs is one reader: the CLI's --ref
407
+ and the TUI's /ref must agree about the cap, about re-attaching the same
408
+ thread, and about the stored shape, or the two disagree about what a
409
+ reference IS.
410
+
411
+ REFUSES AT THE CAP rather than dropping the oldest. A reference is
412
+ something a person chose by name; making room by discarding one silently
413
+ is what §21b's "removal is by id, never by substring" rule exists to
414
+ prevent. The message names the command that makes room.
415
+
416
+ Re-attaching a thread already attached REPLACES its summary rather than
417
+ adding a second entry -- the newer summary is strictly better information
418
+ about the same source, and two entries for one thread would spend the cap
419
+ on a duplicate.
420
+ """
421
+ from datetime import datetime
422
+
423
+ refs = [dict(r) for r in (memory.extra.get("refs") or [])]
424
+ key = str(thread_id)
425
+ existing = next((r for r in refs if r.get("thread_id") == key), None)
426
+ if existing is None and len(refs) >= config.MAX_INJECTED_REFS:
427
+ return False, (
428
+ f"Already referencing {len(refs)} conversations, which is the "
429
+ f"limit (config.MAX_INJECTED_REFS). Drop one with /ref --clear "
430
+ f"first -- none is removed automatically.")
431
+
432
+ entry = {
433
+ "thread_id": key,
434
+ "summary": summary,
435
+ "label": label,
436
+ "attached_at": datetime.now(UTC).isoformat(),
437
+ }
438
+ if existing is not None:
439
+ refs[refs.index(existing)] = entry
440
+ verb = "Updated the reference to"
441
+ else:
442
+ refs.append(entry)
443
+ verb = "Now referencing"
444
+ memory.set_extra("refs", refs)
445
+ return True, f"{verb} thread {key}."
446
+
447
+
448
+ def clear_refs(memory: ConversationMemory) -> int:
449
+ """Drop every attached reference. Returns how many were dropped.
450
+
451
+ All or nothing, deliberately: a per-reference removal needs a stable way
452
+ for a person to name one, and the only handle a ref has is a thread uuid
453
+ the user would have to retype. `/ref --list` then `/ref` to re-attach the
454
+ ones still wanted is two steps with nothing to mistype.
455
+ """
456
+ refs = memory.extra.get("refs") or []
457
+ if refs:
458
+ memory.set_extra("refs", None)
459
+ return len(refs)
460
+
461
+
462
+ def _authorization_kwargs(authorization) -> dict:
463
+ """Unpack a RunAuthorization into _run()'s primitives.
464
+
465
+ ONE unpacking point, so the pipeline entry point and its JSON-retry
466
+ twin cannot disagree about what a bundle means. The retry re-enters the
467
+ SAME pass thread through continue_conversation(): passing the bundle
468
+ there and not here (or the reverse) would strip a pass's tools on
469
+ exactly the attempt where the model is already struggling, and the only
470
+ symptom would be a second malformed answer.
471
+ """
472
+ if authorization is None:
473
+ return {}
474
+ return {
475
+ "granted_tools": authorization.granted_tools or None,
476
+ "grant_budget": authorization.budget,
477
+ "response_channel": authorization.provider,
478
+ }
479
+
480
+
481
+ def advertisement_facts(authorization=None, response_channel=None,
482
+ granted_tools=None) -> tuple:
483
+ """(callable_only, granted) for a caller BUILDING A PROMPT (#68).
484
+
485
+ Sibling of _authorization_kwargs above, and there for the same
486
+ reason: one unpacking point, so the places that must agree cannot
487
+ disagree about what a bundle means. The difference is only WHEN --
488
+ _run() computes `headless = response_channel is None` after the
489
+ bundle has been unpacked into its primitives, and a system prompt
490
+ is assembled before _run() is called at all.
491
+
492
+ Accepts either a bundle or the loose primitives, because
493
+ run_agent_conversation takes both and rejects being given both.
494
+ The bundle wins when present, which is the same precedence
495
+ _authorization_kwargs applies.
496
+
497
+ A NULL BUNDLE MEANS HEADLESS, not "unknown": _authorization_kwargs
498
+ returns {} for None, so response_channel stays None and _run reads
499
+ that as headless. Answering anything else here would advertise a
500
+ catalog to exactly the runs that cannot use it.
501
+ """
502
+ if authorization is not None:
503
+ return (authorization.provider is None,
504
+ set(authorization.granted_tools or ()))
505
+ return (response_channel is None, set(granted_tools or ()))
506
+
507
+
508
+ def _denial_reason(tool_name: str, response_channel, context) -> str:
509
+ """Why a gated call was refused, in terms the model can act on (#158).
510
+
511
+ The loop already learned this lesson one branch over -- see the
512
+ reachability comment above the approval block: headless, "requires
513
+ approval and was not given" tells the model to retry WITH approval,
514
+ which is the one thing that cannot happen there. It retries, spends a
515
+ step against max_steps, and gets the same sentence back. That is the
516
+ fetch_url damage class, which §15\\D24 fixed for undeclared permissions
517
+ and left open on this axis.
518
+
519
+ THE DISTINCTION IS WHETHER THE ARGUMENTS CAUSED THE GATE, and it is
520
+ asked the same way schemas(callable_only=…) asks it -- with empty
521
+ params, through the one function both dispatch() and this loop already
522
+ share. A tool gated by NAME is uncallable in this run however it is
523
+ called, so the useful thing to say is "stop". A tool gated by THESE
524
+ PARAMS survived that filter and was advertised precisely because some
525
+ other call shape is callable, so the useful thing to say is "vary the
526
+ arguments" -- which is exactly the case #158 measured: `write` is
527
+ advertised in a headless pass and denied only for paths outside the
528
+ workspace.
529
+
530
+ No tool name and no notion of a path appears here. Which argument to
531
+ vary is the model's problem and the tool's schema already describes it;
532
+ putting "try a path inside the workspace" in this file is the thing
533
+ ToolSpec.grant_scope and request_kind exist to prevent.
534
+ """
535
+ if response_channel is not None:
536
+ # Somebody was asked and declined. Nothing to reframe -- the answer
537
+ # was a decision, not an absence, and telling the model the call
538
+ # was unavailable would misreport a person's "no" as a limitation.
539
+ return f"{tool_name} requires approval and was not given"
540
+ if registry.approval_needed(tool_name, {}, context):
541
+ return (f"{tool_name} requires approval and this run has no way to "
542
+ f"ask, so it is unavailable however it is called. Do not "
543
+ f"retry it.")
544
+ return (f"{tool_name} requires approval for these arguments and this "
545
+ f"run has no way to ask. It may not need approval with "
546
+ f"different arguments.")
547
+
548
+
549
+ def _obtain_approval(response_channel, tool_name: str, params: dict,
550
+ notice, request_payload=None, rationale=None,
551
+ headline=None) -> tuple:
552
+ """Ask the human about one gated call. Returns (approved, grant).
553
+
554
+ ONE route since §23. There were two -- a queue.Queue the TUI's worker
555
+ parked on while its UI thread rendered a modal, and an
556
+ ApprovalProvider callable, which existed only because
557
+ run_to_completion() DISCARDS the LoopEvent carrying the question, so
558
+ the CLI and the pipeline would have blocked on a queue with nothing
559
+ displayed. Both were the same exchange with different plumbing, and
560
+ the shells now supply one ResponseChannel whose `ask` does whichever
561
+ of those two things that shell needs.
562
+
563
+ TWO RETURN VALUES, because §23 AC1b made one question's answer richer
564
+ than a yes/no. A subagent sign-off answers with the SUBSET of tools
565
+ the child may then use unprompted -- None to refuse the spawn, an
566
+ empty set to allow it with nothing granted, a non-empty set to grant
567
+ those. `grant` is None for every other kind, which carries no subset.
568
+
569
+ Which kind to ask comes from the REGISTRY, not from a name test here:
570
+ the loop asks what shape of question a tool needs the same way it asks
571
+ whether it needs one at all. `request_payload` is passed in already
572
+ computed, because the caller needs it before this point to look up the
573
+ sign-off memo -- and building a subagent's candidate list twice per
574
+ call would be wasteful and could disagree with itself.
575
+
576
+ `rationale` is the agent's own account of why it wants this call
577
+ (§42, RA5), and it is passed in already resolved for the same
578
+ reason: the caller needs it for the LoopEvent too, and looking it
579
+ up twice invites the two from disagreeing. DISPLAY ONLY -- it
580
+ reaches the prompt and nothing that decides anything.
581
+
582
+ `headline` is the SUBJECT of the question (§46, EP2) -- for `shell`
583
+ the command itself -- and travels for exactly the same reasons,
584
+ resolved once by the caller and display-only. It is also already
585
+ inside `params`, which every prompt renders whole; what carrying it
586
+ separately buys is a shell's ability to place it where it cannot
587
+ scroll out of view, without learning a parameter name.
588
+ """
589
+ kind = registry.request_kind(tool_name)
590
+ payload = {"tool_name": tool_name, "params": params,
591
+ "rationale": rationale, "headline": headline}
592
+ # §47. WHICH run is asking, read off the span that is open rather
593
+ # than threaded through four layers -- the same ContextVar slice 1
594
+ # put the parent link on, asked one question over.
595
+ #
596
+ # None at depth 0, and that is the right SCOPE rather than a gap:
597
+ # the asking run is then the conversation on screen, which needs no
598
+ # label. A nested one does, because its approvals surface on the
599
+ # parent's screen and "Allow shell?" said only which tool.
600
+ #
601
+ # `asking_agent`, NOT `agent`: spawn_subagent's own request_payload
602
+ # carries an `agent` key meaning the agent about to be SPAWNED.
603
+ # Two different agents, one key, and the sign-off screen would
604
+ # have named the wrong one.
605
+ payload.update(request_payload or {})
606
+ # AFTER the tool's own payload, deliberately, and this is the half
607
+ # that took a mutation to notice. Written before it, a tool
608
+ # declaring `asking_agent` in its request_payload would silently
609
+ # replace this -- an agent-supplied claim overwriting a harness
610
+ # fact, which is the exact inversion §42's RA6 orders the modal to
611
+ # prevent. Nothing declares that key today; the point is that
612
+ # nothing CAN.
613
+ asking = agent_activity.current()
614
+ if asking is not None:
615
+ payload["asking_agent"] = asking.name
616
+ payload["asking_depth"] = asking.depth
617
+ answer = interaction.ask(response_channel, interaction.Request(
618
+ kind=kind, payload=payload, notice=notice))
619
+ if kind == interaction.SUBAGENT_SIGNOFF:
620
+ # None denies the spawn; any set (including empty) allows it.
621
+ return answer is not None, answer
622
+ return bool(answer), None
623
+
624
+
625
+ # ROADMAP_v2 §21. Notice kinds that describe a STANDING CONDITION rather
626
+ # than an event: they stay true on every step until something changes, so
627
+ # emitting them per step fills a transcript with the same line and trains
628
+ # the reader past it -- which is exactly the reader you need when the one
629
+ # that matters arrives. A compaction that actually happened is an event and
630
+ # repeats legitimately, once per compaction.
631
+ _ONCE_PER_RUN_NOTICES = (
632
+ "compaction_warning", # still approaching the threshold
633
+ "compaction_blocked", # the keep floors still protect everything
634
+ "compaction_failed", # provider down, or the compactor returned
635
+ # nothing usable (#136) -- and since batch 20
636
+ # this kind is also the LATCH: seen once, no
637
+ # further compact() calls this turn
638
+ )
639
+
640
+
641
+ def _derived_compaction_mode(memory) -> str:
642
+ """The compaction mode for a caller that did not say (#43, batch 16).
643
+
644
+ The mode is a property of WHAT THE THREAD IS, not of the call site:
645
+ `research_pass` and `subagent` threads are machinery -- unattended,
646
+ already returning a distillation, and (for a retry thread) holding
647
+ exactly the turns §3 exists to keep in front of the model -- so M6's
648
+ backstop applies WHEREVER they are re-entered. A chat thread is a
649
+ conversation someone is present for; the ordinary working-set trigger
650
+ is the feature working as designed there.
651
+
652
+ This closes #43 by construction rather than by forwarding: json_retry
653
+ and the §20 reviewer could not express a mode at all before, and a
654
+ parameter they had to remember would have re-created the D24/R13
655
+ failure shape -- correct today, one forgotten call site from wrong
656
+ again. Unknown kinds fail toward the chat answer: routine compaction
657
+ of an unforeseen thread kind is the conservative default, and a
658
+ future kind states its own answer here when it arrives.
659
+ """
660
+ kind = getattr(memory, "kind", THREAD_KIND_CHAT)
661
+ if kind in (THREAD_KIND_RESEARCH_PASS, THREAD_KIND_SUBAGENT):
662
+ return "backstop"
663
+ return "working_set"
664
+
665
+
666
+ def _already_said(notices, kind: str) -> bool:
667
+ return kind in _ONCE_PER_RUN_NOTICES and any(
668
+ n["kind"] == kind for n in notices)
669
+
670
+
671
+ def _compactor_depth(context) -> int:
672
+ """Where a compaction started from THIS loop sits in the agent stack.
673
+
674
+ One below whoever is running: a compactor spawned from a subagent at
675
+ depth 1 is at 2, exactly as a subagent spawned from there would be.
676
+ Derived from the ToolContext rather than passed down, because
677
+ subagent_depth is already the number C3 bounds and a second count of
678
+ the same thing is the shape §22 spent a section removing.
679
+ """
680
+ return (context.subagent_depth if context is not None else 0) + 1
681
+
682
+
683
+ def _maybe_compact(memory, model, provider_name, notices, mode,
684
+ activity=None, depth: int = 1):
685
+ """Evaluate §21's trigger and act on it. A generator, so the caller
686
+ yields from it and the notice reaches a live UI as it happens.
687
+
688
+ Every notice goes BOTH ways -- appended to `notices`, which _run()
689
+ attaches to the response, and yielded as a LoopEvent. The event alone
690
+ would be invisible to the CLI and the pipeline, which drain the
691
+ generator through run_to_completion() and discard everything that is
692
+ not final. §20 and §25 each shipped that defect once.
693
+
694
+ Outcome routing (batch 16, #44). compact() returns a status dict now,
695
+ and this is where reportability is decided:
696
+
697
+ folded notice every occurrence -- an event, and repeats
698
+ legitimately, once per compaction.
699
+ blocked /
700
+ all-pinned /
701
+ missing-agent STANDING CONDITIONS: notice AND WARNING together,
702
+ ONCE PER RUN under the same dedup list. The two
703
+ WARNINGs used to live inside compact() and fired on
704
+ EVERY evaluation -- up to MAX_ITERATIONS + 1
705
+ identical lines per turn on a thread that stays over
706
+ trigger and fully floored, which is how a reader
707
+ gets trained past the warnings that do not repeat.
708
+ Same defect `context_limit()` had before it learned
709
+ to warn once per model.
710
+ no-progress /
711
+ reentrant no notice at all: ordinary non-events (nothing new
712
+ to fold) or already carried by _summarize's own
713
+ per-call warnings.
714
+
715
+ THE LATCH (#136, batch 20). compaction_failed is both a notice and a
716
+ STOP for the run: once this turn has seen one -- a provider error, or
717
+ an empty compactor response (compact() now reports that as
718
+ status="failed" with the same kind) -- _maybe_compact returns before
719
+ calling compact() again. Without the gate the dedup above only
720
+ silenced the MESSAGE while every step still spent a full compactor
721
+ model call on an attempt that had just failed; measured at seven
722
+ calls in one six-step turn on the thread's first crossing. The latch
723
+ is per-turn by construction -- `notices` dies with _run() -- so the
724
+ next turn retries cleanly and a transient provider hiccup costs one
725
+ wasted call, not one per step. Deliberately NOT latched: no-progress,
726
+ reentrant, blocked and all-pinned exit before any model call, cost
727
+ only storage reads, and are self-correcting if state shifts.
728
+
729
+ Failure here is contained. Compaction is a model call, and a provider
730
+ error during it must not take down a turn that was otherwise fine --
731
+ the same call §20 made for its review stage. The thread simply stays
732
+ uncompacted and the next call fails or succeeds on its own merits,
733
+ which is strictly better than failing this one on its behalf.
734
+
735
+ Takes no authorization, deliberately. The compactor declares
736
+ `allowed_tools: []`, so there is nothing for a grant to apply to --
737
+ a parameter here would read as security-relevant and could not be.
738
+ """
739
+ from core import compaction
740
+
741
+ used = memory.last_input_tokens or compaction.estimated_tokens(memory.messages)
742
+ action = compaction.should_compact(used, model, mode,
743
+ provider_name=provider_name)
744
+ if not action:
745
+ return
746
+ if action == "warn":
747
+ if _already_said(notices, "compaction_warning"):
748
+ return
749
+ notice = {
750
+ "kind": "compaction_warning",
751
+ "text": ("Approaching the compaction threshold — older messages "
752
+ "may be summarized soon."),
753
+ }
754
+ notices.append(notice)
755
+ yield LoopEvent(notice=notice)
756
+ return
757
+ # THE LATCH (#136): a failed attempt already spent its model call this
758
+ # turn. Everything below the warn branch re-enters compact() on every
759
+ # step while the trigger stays open, so without this early return the
760
+ # dedup below only hides the message and the spend repeats. See the
761
+ # docstring's latch paragraph for why only compaction_failed gates.
762
+ if _already_said(notices, "compaction_failed"):
763
+ return
764
+ try:
765
+ # The current-turn floor (M5), computed HERE rather than at the
766
+ # top of the turn. Archive-space makes it time-invariant within
767
+ # a turn -- the archive gains assistant and tool rows as the
768
+ # turn runs but no new USER row, so the answer is the same
769
+ # whenever it is asked. Asking lazily keeps a storage read off
770
+ # every turn that is nowhere near the threshold.
771
+ outcome = compaction.compact(
772
+ memory, model, provider_name,
773
+ current_turn_start=memory.completed_turns(),
774
+ # Batch 59. The compactor is an agent-shaped run nested inside
775
+ # THIS turn, so it is drawn one level below whatever is running
776
+ # -- which is the depth the caller computed from its context,
777
+ # not a constant. `activity` is None everywhere but the TUI.
778
+ activity=activity, depth=depth)
779
+ except Exception as e: # noqa: BLE001 -- contained on purpose, see above
780
+ logger.exception("Compaction failed; continuing uncompacted.")
781
+ notice = {
782
+ "kind": "compaction_failed",
783
+ "text": f"Could not compact this conversation: {e}",
784
+ }
785
+ if not _already_said(notices, notice["kind"]):
786
+ notices.append(notice)
787
+ yield LoopEvent(notice=notice)
788
+ return
789
+
790
+ kind = outcome.get("kind")
791
+ if kind is None:
792
+ return
793
+ if _already_said(notices, kind):
794
+ return
795
+ if kind == "compaction_blocked":
796
+ # See the docstring's standing-condition row: one WARNING per run,
797
+ # said in the same breath as the one notice, never per evaluation.
798
+ logger.warning("Compaction cannot proceed on thread %s: %s",
799
+ memory.thread_id, outcome["text"])
800
+ notices.append({"kind": kind, "text": outcome["text"]})
801
+ yield LoopEvent(notice=notices[-1])
802
+
803
+
804
+ def run_to_completion(gen, observe=None) -> ModelResponse:
805
+ """Consumes a _run() generator fully, discarding intermediate events,
806
+ and returns the final ModelResponse — this is what keeps
807
+ run_agent_conversation() and continue_conversation(), the two public
808
+ entry points, synchronous for every caller.
809
+
810
+ It reads the response off the TERMINAL EVENT, which is right for a
811
+ bare _run(): that generator returns nothing. A generator that returns
812
+ its own value -- stream_deep_research_mode(), whose response carries
813
+ `thread_id` attached after the loop finished -- needs the other
814
+ question asked, and `tests/conftest.drain` is where that lives now
815
+ that the pass wrapper is gone.
816
+
817
+ `observe` (ROADMAP_v3 §86, A81) is handed every event as it is drawn,
818
+ the terminal one included, so a caller that wants the answer
819
+ synchronously can still draw the turn while it runs. The CLI is that
820
+ caller: it prints each step as it finishes, the way the replay of the
821
+ thread will. Discarding stays the default, and nothing here protects
822
+ the turn from the observer -- one that raises abandons the generator
823
+ exactly as an exception in any consumer would, so the observer is the
824
+ one that must not."""
825
+ final = None
826
+ for event in gen:
827
+ if observe is not None:
828
+ observe(event)
829
+ if event.final_response is not None:
830
+ final = event.final_response
831
+ if final is None:
832
+ raise RuntimeError(
833
+ "Generator completed without yielding a final_response"
834
+ )
835
+ return final
836
+
837
+
838
+ # #4 (batch 27). The wrappers' default for max_total_tokens: resolve the
839
+ # configured spend cap (settings.json max_token_budget) at CALL time. A
840
+ # sentinel rather than a plain None default because explicit-None already
841
+ # MEANS something in _run()'s signature -- genuinely uncapped -- and tests
842
+ # pass it deliberately. Resolution lives at the call site, not at def time,
843
+ # so a settings.json written after import is still honoured.
844
+ _SPEND_UNSET = object()
845
+
846
+
847
+ def _resolve_spend_cap(max_total_tokens) -> Optional[int]:
848
+ """_SPEND_UNSET -> the configured cap; anything else passes through."""
849
+ if max_total_tokens is _SPEND_UNSET:
850
+ from core.config_loader import spend_cap
851
+ return spend_cap()
852
+ return max_total_tokens
853
+
854
+
855
+
856
+ @dataclass
857
+ class _CallOutcome:
858
+ """What deciding and dispatching ONE tool call produced (§47 slice 8).
859
+
860
+ Returned rather than written straight into the turn's own lists,
861
+ because NA11 orders a parallel batch's effects by the MODEL'S call
862
+ order and a batch finishes in whatever order it finishes. So a call
863
+ collects what it would have appended, and `_settle_one` appends it at
864
+ the call's turn. For a lone sequential call that turn is immediately,
865
+ which is what keeps the single-call path byte-identical.
866
+
867
+ `result` is what the model is told. `granted` is §25's pre-authorized
868
+ call record and `notices` are §23's shell-facing lines, each a list
869
+ because a call contributes zero or one of the first and zero or more
870
+ of the second.
871
+ """
872
+
873
+ result: object
874
+ granted: list = field(default_factory=list)
875
+ notices: list = field(default_factory=list)
876
+
877
+
878
+ #: NA9's gate for a call with no siblings. A lone call cannot contend with
879
+ #: anything, so it takes no lock -- which is what makes "the sequential
880
+ #: path is unchanged" a structural claim rather than a measured one.
881
+ _NO_GATE = nullcontext()
882
+
883
+ #: NA12's second lock, and it guards a WINDOW rather than an object.
884
+ #:
885
+ #: §23's sign-off memo is a check-then-act: `recall_signoff` says nobody
886
+ #: has answered about this subject, the human is asked, `remember_signoff`
887
+ #: records the answer. Sequentially that is why three spawns of one agent
888
+ #: ask ONCE. Concurrently all three recall before any remembers, and the
889
+ #: user is asked three times about the same agent -- a regression in the
890
+ #: number of questions, which is the thing §25 R11 and §23 J8 are both
891
+ #: about.
892
+ #:
893
+ #: Guarding the dict instead would not close it: no single mutation is
894
+ #: racy, the WINDOW between the read and the write is. Module-level rather
895
+ #: than per-run, because the runs it serialises are siblings in different
896
+ #: frames with no shared object between them but this one.
897
+ #:
898
+ #: RELEASED BEFORE dispatch, always. That is what keeps it a plain Lock: a
899
+ #: child's own gate acquisitions all happen inside its dispatch, by which
900
+ #: time its parent has let go, so nothing re-enters. It is also the outer
901
+ #: of this project's two ask-side locks -- gate, then
902
+ #: core.interaction's -- and the order is never the other way, because
903
+ #: nothing holding the interaction lock reaches back into a gate.
904
+ _GATE_LOCK = threading.Lock()
905
+
906
+
907
+ def _parallel_groups(calls) -> list:
908
+ """Partition one response's calls into consecutive runs (NA9).
909
+
910
+ A group is either several calls whose ToolSpec declares `parallel`, or
911
+ exactly one call of anything else. CONSECUTIVE, and that is the
912
+ decision rather than an implementation detail: NA9 keeps every
913
+ non-parallel call in its original position, so two spawns either side
914
+ of a `shell` cannot be grouped without moving the shell relative to
915
+ them.
916
+
917
+ Asked of the registry, never matched by name, so this file stays free
918
+ of the knowledge that spawn_subagent is the special one -- the same
919
+ trade `grant_scope`, `request_kind` and `opens_thread` already make.
920
+ """
921
+ groups: list = []
922
+ for call in calls:
923
+ # `groups[-1][-1]` rather than a flag, so the question asked is
924
+ # "may this join what is already open" -- and a group is never
925
+ # empty, so there is no length to check.
926
+ if (registry.parallel(call.name)
927
+ and groups
928
+ and registry.parallel(groups[-1][-1].name)):
929
+ groups[-1].append(call)
930
+ else:
931
+ groups.append([call])
932
+ return groups
933
+
934
+
935
+
936
+ def _dispatch_one(call, *, context, run_info, response_channel, memory,
937
+ activity, cancel=None, gate=_NO_GATE):
938
+ """Decide, ask about and dispatch ONE tool call.
939
+
940
+ A GENERATOR that yields the call's own narration -- the permission
941
+ request and any approval notice -- and RETURNS a `_CallOutcome`. Two
942
+ drivers share it and that is the point of the shape: `_run` does
943
+ `yield from` for a lone call, and `_dispatch_parallel`'s worker steps
944
+ it by hand and pushes each event onto a conduit. One copy of the
945
+ decision, so there is still exactly one place that decides whether a
946
+ call is authorized and exactly one call to `registry.dispatch`.
947
+
948
+ `gate` is NA12's window lock, supplied only when this call has
949
+ siblings. See `_GATE_LOCK`.
950
+
951
+ THE AUTHORIZATION IS THIS FUNCTION'S LOCAL, which is strictly stronger
952
+ than the loop-body local it replaces. `authorized_call` used to be
953
+ correct because of WHERE it was declared -- one indent out and it
954
+ covered every later call in the turn -- and the id, rather than a
955
+ bool, is what made that mistake fail closed instead of open. A
956
+ function whose whole scope is one call cannot express the mistake at
957
+ all: there is no enclosing iteration to hoist out of. The id stays
958
+ anyway, because it is also what tells `dispatch()` which call the
959
+ loop answered, and because a fail-closed shape is worth keeping when
960
+ it costs nothing.
961
+ """
962
+ granted: list = []
963
+ collected: list = []
964
+
965
+ # Single source of truth with dispatch(): approval_needed()
966
+ # ORs the tool's own path/command-dependent approval_check
967
+ # with the config/context requirement (§15). Both callers
968
+ # go through it so they cannot diverge — a path-dependent
969
+ # tool must yield permission_request so the TUI user can
970
+ # approve, not be silently denied by one check while the
971
+ # other reports no approval needed.
972
+ #
973
+ # There is no separate allowed_tools membership test here
974
+ # any more: dispatch() calls is_tool_allowed(name, context),
975
+ # which raises ToolCallDenied with a message distinguishing
976
+ # a context restriction from a global policy denial.
977
+ needs_approval = registry.approval_needed(
978
+ call.name, call.input, context)
979
+ # Reachability before approval. Asking first meant a
980
+ # context-excluded tool prompted the user, who clicked
981
+ # Allow, and was then denied anyway -- and headless, it
982
+ # reported "requires approval and was not given", telling
983
+ # the model to retry with approval when the actionable
984
+ # answer is "not available in this context". dispatch()
985
+ # still enforces the denial; this only stops asking a
986
+ # question whose answer cannot matter.
987
+ if needs_approval and not registry.is_allowed(call.name, context):
988
+ needs_approval = False
989
+ # §32 A7 (#70): the same rule for a refusal only the
990
+ # TOOL can see. spawn_subagent's unknown-agent and
991
+ # depth-limit checks lived inside run(), so both
992
+ # prompted first and errored second -- and for an
993
+ # unknown name the question had an empty notice and an
994
+ # empty candidate list, i.e. nothing to tick. The
995
+ # call is refused by dispatch with the tool's own
996
+ # reason; this only stops ASKING first. It also keeps
997
+ # J8's memo from being keyed on
998
+ # (spawn_subagent, None) -- a subject of None is the
999
+ # absence of the very thing the key exists to
1000
+ # distinguish.
1001
+ if needs_approval and registry.refusal_reason(
1002
+ call.name, call.input, context):
1003
+ needs_approval = False
1004
+ # §33 W3 (#37): the same rule for a call whose arguments
1005
+ # never parsed. Approving it could not make it runnable,
1006
+ # so the question has no answer that changes anything --
1007
+ # and headless it would report "requires approval and was
1008
+ # not given", which is A7's exact wrong-cause failure.
1009
+ if needs_approval and call.parse_error is not None:
1010
+ needs_approval = False
1011
+ # §18 sign-off (S1), narrowed by §25 (R2): a tool whose
1012
+ # grant_scope is "run" is asked about once per run, not
1013
+ # once per call. The loop names no tool -- it asks the
1014
+ # registry, the same way it asks whether approval is
1015
+ # needed at all.
1016
+ #
1017
+ # THREE conditions, and the last two are the §25 change:
1018
+ #
1019
+ # registry.grantable -- a tool deciding approval from its
1020
+ # PARAMS was never consented to by name. Before this,
1021
+ # a signed-off subagent could run any shell command for
1022
+ # the rest of the turn on the strength of one prompt
1023
+ # that said "shell". Re-checked here rather than
1024
+ # trusted from the set, so a stale or hand-built grant
1025
+ # cannot widen anything.
1026
+ #
1027
+ # grant_budget.take() -- pre-flight authorization trades
1028
+ # a per-call decision for one up-front decision, and
1029
+ # gives up the natural bound on how many times the
1030
+ # tool runs. Exhaustion falls back to ASKING, not to
1031
+ # failing: supervised runs continue, headless ones deny
1032
+ # exactly as they would for any gated tool.
1033
+ #
1034
+ # §23 AC1b: the memo is keyed by (tool, SUBJECT), not by
1035
+ # tool name alone. A subagent sign-off answers about one
1036
+ # agent's candidate list, so reusing it for a different
1037
+ # agent would grant a set nobody was shown -- which is
1038
+ # what the name-only version did: approving a spawn of `a`
1039
+ # silently covered a later spawn of `b` in the same turn.
1040
+ # Tools with no subject (every other one) memo under None
1041
+ # and behave exactly as before.
1042
+ # Batch 60. THIS CALL'S authorization decision, and the
1043
+ # error that stands in for it.
1044
+ #
1045
+ # THE ID, NOT A BOOLEAN, and that is the whole point of the
1046
+ # shape. `authorized` began as a bool whose correctness
1047
+ # rested on WHERE it was declared -- one indent level in and
1048
+ # it covers one call, one level out and it covers every
1049
+ # later call in the turn, which is the exact widening §25
1050
+ # R11 refuses to make even for the one tool whose grant
1051
+ # scope IS the run. That version was measured: hoisting it
1052
+ # out of the per-call loop survived the entire suite, because
1053
+ # no path currently reaches dispatch with a stale flag that
1054
+ # changes anything. Correct, and undefended.
1055
+ #
1056
+ # §47 SLICE 8 MADE THE SCOPE STRUCTURAL. The per-call body is
1057
+ # this function now, so there is no enclosing iteration left
1058
+ # to hoist out of -- the widening the paragraph above defends
1059
+ # against can no longer be WRITTEN here, rather than being
1060
+ # merely absent. That is why the AST guard in
1061
+ # tests/test_grants.py moved with the body instead of being
1062
+ # deleted: what it pins is now "one call per frame, and the
1063
+ # frame is what dispatch is told about".
1064
+ #
1065
+ # A call id cannot be hoisted into a lie, and the id stays for
1066
+ # that reason plus one more: it is also how dispatch() learns
1067
+ # WHICH call the loop answered. Handed a stale one, the
1068
+ # comparison at the dispatch site fails and the call is DENIED
1069
+ # -- the mistake fails closed instead of failing open. It rests
1070
+ # on ids being distinct within a response, which is not a new
1071
+ # assumption: add_tool_result pairs every tool_result to its
1072
+ # tool_use by that same id (M4/D20), and a thread whose ids
1073
+ # collide is already unresumable.
1074
+ #
1075
+ # Set in exactly two places -- the memo/grant hit below and
1076
+ # the fresh approval further down -- and read in exactly
1077
+ # one, the single dispatch() call at the end of this block.
1078
+ authorized_call = None
1079
+ denial = None
1080
+ request_payload = registry.request_payload(
1081
+ call.name, call.input, context)
1082
+ subject = request_payload.get("subject")
1083
+ # NA12's window opens HERE and closes before dispatch. Everything
1084
+ # inside is the sign-off's check-then-act: what has already been
1085
+ # answered about this subject, the question if nothing has, and the
1086
+ # record of the answer. A sibling that arrives mid-window waits, and
1087
+ # then finds the memo -- which is what keeps three spawns of one
1088
+ # agent at ONE question, exactly as they were sequentially.
1089
+ #
1090
+ # `gate` is a no-op for a lone call, so this costs the sequential
1091
+ # path nothing and cannot be held across a suspension there. On the
1092
+ # parallel path the frame that yields is the DRIVER, not this
1093
+ # generator: the worker steps it and pushes, so a permission request
1094
+ # still reaches the transcript before the modal it announces, with
1095
+ # no lock held across anybody's `yield`.
1096
+ with gate:
1097
+ remembered, signoff = run_info.recall_signoff(
1098
+ call.name, subject)
1099
+ # grant_policy on a NAME-LEVEL grant only -- R13's literal
1100
+ # claim is that approving the NAME never carries the
1101
+ # authority for a GRANT_NEVER tool, on either path, and
1102
+ # until now no path enforced it. Batch 6 declared the
1103
+ # policy and taught the two functions that decide what
1104
+ # may be OFFERED to read it; this is the reader that
1105
+ # decides whether a grant already in hand APPLIES.
1106
+ # `spawn_subagent` was covered only because R14's
1107
+ # subject condition happens to catch it; `remember`
1108
+ # carries no subject, so a grant naming it dispatched a
1109
+ # durable cross-session write with no prompt -- M17's
1110
+ # scenario through the one door R13 left unlocked.
1111
+ #
1112
+ # IT MUST NOT REACH THE SIGN-OFF MEMO, and that is not a
1113
+ # nicety: `spawn_subagent` is GRANT_NEVER, so testing
1114
+ # the policy unconditionally here stops §23's memo
1115
+ # applying and the same agent is asked about twice in
1116
+ # one turn. R13 is about what approving a NAME buys; a
1117
+ # memo is an answer somebody gave about this subject,
1118
+ # which J8 and R14 govern instead. recall_signoff
1119
+ # already separates them by what it returns -- the memo
1120
+ # always carries a subset, the grant carries None.
1121
+ answered_by_name = signoff is None
1122
+ if (needs_approval
1123
+ and remembered
1124
+ and registry.grantable(call.name)
1125
+ and not (answered_by_name
1126
+ and registry.grant_policy(call.name)
1127
+ == GRANT_NEVER)
1128
+ and (run_info.grant_budget is None
1129
+ or run_info.grant_budget.take())):
1130
+ needs_approval = False
1131
+ # Batch 60. The half that was missing: the loop
1132
+ # decided this call needs no fresh answer, and until now
1133
+ # it did not tell dispatch(), which re-checks approval on
1134
+ # its own and denied every call this branch let through.
1135
+ # A second spawn of one agent, a subagent calling a tool
1136
+ # it was signed off for, and a --grant-tools name in an
1137
+ # unattended run were all refused with "requires approval
1138
+ # and was not given" and no prompt.
1139
+ authorized_call = call.id
1140
+ granted.append(
1141
+ {"tool": call.name, "params": call.input})
1142
+ # §21, and the reason this batch adds a notice at all:
1143
+ # a gated call proceeding with NO modal is the intended
1144
+ # behaviour (§25 R11 -- re-asking about the same tool
1145
+ # seconds later is noise), and it is also exactly what
1146
+ # the bug looked like from the outside. Silence was
1147
+ # indistinguishable from the bug.
1148
+ #
1149
+ # DELIBERATELY NOT in _ONCE_PER_RUN_NOTICES. That list
1150
+ # is for a STANDING CONDITION re-emitted on every step;
1151
+ # this fires only when a call actually reuses an answer,
1152
+ # which is an event -- the same reading that lets a
1153
+ # compaction that HAPPENED repeat once per compaction.
1154
+ # Once per run would go quiet again from the third spawn
1155
+ # onward, which is the silence that started this.
1156
+ #
1157
+ # Two texts, discriminated by `answered_by_name`, which
1158
+ # is already computed above: one sentence cannot honestly
1159
+ # cover both. A memo is something the user answered
1160
+ # minutes ago in this turn; a grant is something they
1161
+ # decided before the run existed, possibly on a command
1162
+ # line, and telling them they "answered earlier" would
1163
+ # describe a moment that never happened.
1164
+ collected.append({
1165
+ "kind": "approval_reused",
1166
+ "text": (
1167
+ "%s is running on the authorization granted "
1168
+ "before this run started." % call.name
1169
+ if answered_by_name else
1170
+ "Reusing your approval for %s, given earlier in "
1171
+ "this turn." % (subject or call.name)),
1172
+ })
1173
+ yield LoopEvent(notice=collected[-1])
1174
+ else:
1175
+ # Not reused: nothing is carried into dispatch unless
1176
+ # this call's own answer supplies it below.
1177
+ signoff = None
1178
+ if needs_approval:
1179
+ notice = registry.approval_notice(
1180
+ call.name, call.input, context)
1181
+ # §42 (RA5). The agent's own stated reason, asked
1182
+ # of the registry so the loop names no key -- the
1183
+ # same way it asks what KIND of question a tool
1184
+ # needs and whether it needs one at all. The VALUE
1185
+ # travels rather than the key, because the two
1186
+ # shells that render it are a Textual screen that
1187
+ # imports nothing from this package and a `print`
1188
+ # in main.py.
1189
+ rationale = registry.rationale_for(
1190
+ call.name, call.input)
1191
+ # §46 (EP2). The SUBJECT of the question, resolved
1192
+ # the same way and travelling the same route: for
1193
+ # `shell` it is the command, and a shell that shows
1194
+ # it must not have to know that. Every other tool
1195
+ # answers None and its prompt is unchanged.
1196
+ headline = registry.headline_for(
1197
+ call.name, call.input)
1198
+ yield LoopEvent(permission_request={
1199
+ "tool_name": call.name, "params": call.input,
1200
+ "notice": notice,
1201
+ "rationale": rationale,
1202
+ "headline": headline,
1203
+ })
1204
+ approved, signoff = _obtain_approval(
1205
+ response_channel, call.name, call.input, notice,
1206
+ request_payload, rationale=rationale,
1207
+ headline=headline)
1208
+ if approved:
1209
+ authorized_call = call.id
1210
+ # §25 R11: run-scope is a shortcut for a chat turn,
1211
+ # where re-asking about the same tool seconds later
1212
+ # is noise. A provider that declines it is saying
1213
+ # its whole purpose is per-call supervision --
1214
+ # attended mode -- and one yes must not silently
1215
+ # cover later calls there.
1216
+ #
1217
+ # This is ALSO the only thing that carries an answer
1218
+ # between calls in a turn, and it is asked of the
1219
+ # registry rather than assumed: `spawn_subagent` is
1220
+ # the sole tool declaring grant_scope "run", so
1221
+ # `shell`, `write` and `edit` are re-asked per call
1222
+ # however many times one turn calls them.
1223
+ if (registry.grant_scope(call.name) == "run"
1224
+ and (response_channel is None
1225
+ or response_channel.honour_run_scope)):
1226
+ run_info.remember_signoff(
1227
+ call.name, subject, signoff)
1228
+ else:
1229
+ denial = _denial_reason(
1230
+ call.name, response_channel, context)
1231
+ elif call.parse_error is not None:
1232
+ # §33 W1 (#37). The loop is the only layer that can
1233
+ # see this: dispatch() takes (name, params, context)
1234
+ # and the failure is a fact about the wire, not about
1235
+ # the params -- {} is a perfectly good empty dict by
1236
+ # the time it gets there.
1237
+ #
1238
+ # RETURNED as the tool's result, not raised, for
1239
+ # A10's reason: the model is told its arguments did not
1240
+ # arrive and can reissue the call, which is the whole
1241
+ # difference between losing one step and losing a
1242
+ # ten-pass run.
1243
+ denial = call.parse_error
1244
+
1245
+ # ONE dispatch call site (batch 60). There were two,
1246
+ # identical but for the two arguments that carry
1247
+ # authorization, and the one reached by an already-answered
1248
+ # call was the one that omitted them -- so every call this
1249
+ # loop decided was authorized got denied by dispatch's own
1250
+ # re-check. Two sites that must agree is the defect; one
1251
+ # site is the fix, and no future edit can teach them to
1252
+ # disagree again.
1253
+ #
1254
+ # dispatch() STILL RE-CHECKS, and must: it is a public
1255
+ # entry point and the fail-closed backstop. What changed is
1256
+ # that the loop now answers it.
1257
+ #
1258
+ # The callback is CONDITIONAL, and the condition is an
1259
+ # identity check rather than a truth test: this call, not
1260
+ # some call. See the declaration above for why the id and
1261
+ # not a flag.
1262
+ #
1263
+ # DELETING the condition -- `lambda n, p: True` outright --
1264
+ # is the one mutation here that no behaviour can catch, and
1265
+ # it is caught in tests/test_grants.py by reading this
1266
+ # source instead. Nothing can reach this line gated and
1267
+ # un-authorized today, because the three other reasons
1268
+ # `needs_approval` is turned off above are each
1269
+ # short-circuited INSIDE dispatch before its gate
1270
+ # (is_allowed raises, refusal_check returns, and a
1271
+ # parse_error never gets here at all). A fourth reason added
1272
+ # later would otherwise silently become "approve
1273
+ # everything", with every test still green.
1274
+ #
1275
+ # `signoff` needs no condition -- the memo branch above nulls
1276
+ # it on every path that is not a hit, so it is already None
1277
+ # everywhere it should be.
1278
+ if denial is not None:
1279
+ result = {"error": denial}
1280
+ else:
1281
+ try:
1282
+ result = registry.dispatch(
1283
+ call.name, call.input, context=context,
1284
+ # §47. The id the parent's MessageLog row
1285
+ # already stores for this call, so a child
1286
+ # thread can record which LINE made it --
1287
+ # one turn can spawn three, and a name is
1288
+ # not enough to tell them apart.
1289
+ call_id=call.id,
1290
+ approval_callback=(
1291
+ (lambda n, p: True)
1292
+ if authorized_call == call.id else None),
1293
+ parent_run=run_info,
1294
+ response_channel=response_channel,
1295
+ signoff=signoff,
1296
+ memory=memory,
1297
+ activity=activity,
1298
+ # §61 CN7. A child run is this run continuing, so it is
1299
+ # handed the same switch -- the argument that
1300
+ # `response_channel` and `activity` beside it already
1301
+ # make, for the same reason.
1302
+ cancel=cancel,
1303
+ )
1304
+ except ToolCallDenied as e:
1305
+ result = {"error": str(e)}
1306
+ except ValueError:
1307
+ # Batch 147. THE OTHER EXCEPTION dispatch() RAISES ON PURPOSE.
1308
+ #
1309
+ # Its unknown-tool guard is a ValueError and not a
1310
+ # ToolCallDenied, deliberately: the two types separate "you
1311
+ # misnamed it" from "policy blocks you", and that file frames
1312
+ # the first as a caller bug. It is -- but the caller here is a
1313
+ # language model, so the bug arrives the way a model's bugs
1314
+ # arrive: a name it invented, a name whose MCP server went
1315
+ # away between turns while its schemas are still in the
1316
+ # model's context (registry.unregister()), or a name a prompt
1317
+ # catalog advertises and nothing registered.
1318
+ #
1319
+ # Uncontained, that cost the whole turn AND left the thread
1320
+ # unresumable: D20 has already persisted the assistant row
1321
+ # carrying the `tool_use`, nothing writes a `tool_result`, and
1322
+ # M4's pairing is broken with nothing in core/compaction.py or
1323
+ # core/memory.py that repairs it -- `_settle_one`'s own words
1324
+ # for that state are "an unresumable thread". Reported as this
1325
+ # call's error instead, for the reason the parse_error branch
1326
+ # above gives in full: the model is told what went wrong and
1327
+ # can reissue, which is the difference between losing one step
1328
+ # and losing a ten-pass run.
1329
+ #
1330
+ # `is_registered` RATHER THAN THE MESSAGE is what makes this
1331
+ # specific. A bare `except Exception` would stop dispatch()
1332
+ # being the fail-closed backstop it is documented as -- a real
1333
+ # failure in the approval machinery would come back to the
1334
+ # model as a tool error and vanish -- and matching on the text
1335
+ # would be a parser where a token check will do (G2). The
1336
+ # question is asked of the registry, which is the only thing
1337
+ # that knows the answer, and a ValueError for a name that IS
1338
+ # registered re-raises exactly as it did before.
1339
+ #
1340
+ # A re-registration between the raise and this line answers
1341
+ # True and re-raises, i.e. degrades to the behaviour this
1342
+ # replaces. That is the safe direction and it is why the
1343
+ # check is not a cached snapshot.
1344
+ if registry.is_registered(call.name):
1345
+ raise
1346
+ logger.warning(
1347
+ "model called %r, which is not a registered tool; "
1348
+ "reporting that to it as this call's error", call.name)
1349
+ result = {"error": (
1350
+ f"There is no tool named {call.name} in this run, so the "
1351
+ f"call could not be made. Use one of the tools listed in "
1352
+ f"this request.")}
1353
+ # The NAME is the only thing echoed, and it is already in
1354
+ # the thread: D20 persisted the model's own `tool_use` block
1355
+ # before any of this. Nothing of the exception goes back,
1356
+ # which matters here more than it looks: an error result the
1357
+ # LOOP builds -- a denial, a parse error, this -- does not
1358
+ # pass through `check_output_policy`, while every result
1359
+ # dispatch() returns does, including its own error results
1360
+ # (tests/test_tool_failure_containment.py pins that). So this
1361
+ # is one of the few result strings in the system that no
1362
+ # redactor will ever see.
1363
+ return _CallOutcome(
1364
+ result=result, granted=granted, notices=collected)
1365
+
1366
+
1367
+ def _dispatch_parallel(calls, *, context, run_info, response_channel,
1368
+ memory, activity, cancel=None):
1369
+ """Run several calls of one response at once (NA9, NA10, NA15).
1370
+
1371
+ A GENERATOR yielding every worker's narration as it arrives, and
1372
+ RETURNING [(call, _CallOutcome)] in the model's original call order.
1373
+
1374
+ THREADS, NOT ASYNCIO. `_run` is a synchronous generator and everything
1375
+ under it is blocking I/O -- a provider call, a modal a human is
1376
+ looking at, a SQLite write. Converting that to coroutines is a rewrite
1377
+ of every layer; a bounded pool is the change that fits what is already
1378
+ here.
1379
+
1380
+ EVERY FUTURE CARRIES `contextvars.copy_context()`, which is what makes
1381
+ the child's span see its real parent. Batch 67 chose a ContextVar for
1382
+ the parent link over a parameter partly for this: a var is per-context,
1383
+ so a copied context travels with the submitted call, while a plain
1384
+ module global would be wrong the moment two children ran.
1385
+
1386
+ THE CONDUIT IS HOW A WORKER NARRATES, and it is the fifth blocker N8
1387
+ named -- "a synchronous generator with no yield point inside
1388
+ dispatch()". A worker thread cannot yield out of this generator. What
1389
+ it can do is put the event on a queue that THIS frame, which is still
1390
+ inside `_run`'s body and can still yield, drains as the events arrive.
1391
+ So narration stays live: a permission request from one child reaches
1392
+ the transcript while its siblings are still running.
1393
+
1394
+ Note what this does NOT do. It does not forward a CHILD'S events --
1395
+ §18/D6 keeps a child's stream out of its parent, and
1396
+ core/agent_activity.py exists because of it. The events on this queue
1397
+ are the PARENT'S own, about its own tool calls, which it would have
1398
+ yielded itself had it not handed the work to a thread.
1399
+
1400
+ UNBOUNDED QUEUE, deliberately: a worker must never block on the
1401
+ conduit. A bounded one would make a slow consumer able to stall a run,
1402
+ which inverts who is waiting for whom. The bound that matters is on
1403
+ the POOL.
1404
+
1405
+ A worker signals its own end rather than being polled for it, so this
1406
+ drains exactly and never sleeps. If a call hangs, this frame waits
1407
+ forever -- which is what a hanging sequential tool already does, so
1408
+ the shape adds no new way to wedge.
1409
+ """
1410
+ conduit: queue.Queue = queue.Queue()
1411
+ # `[(call, outcome_or_None, exception_or_None)]`, in the order the
1412
+ # futures were submitted, which is the order the MODEL asked (NA11).
1413
+ #
1414
+ # A LIST RATHER THAN A DICT KEYED BY `call.id`, which is what this was
1415
+ # until batch 76's review round. The id is the PROVIDER'S, and
1416
+ # core/client.py's v1-compatible branch defaults a tool-call fragment's
1417
+ # id to "" and fills it only if a delta carries one -- the same branch
1418
+ # that accumulates `function.name` across deltas because some providers
1419
+ # split it, so a provider being sloppy here is the case this code is
1420
+ # written for. Two spawns arriving with one id made a dict hand every
1421
+ # call in the batch the last-finishing worker's outcome: the model told
1422
+ # one child's answer for a different child's call, which is the exact
1423
+ # thing NA11 exists to prevent. Positions cannot collide, so ordering
1424
+ # is now structural rather than a lookup.
1425
+ settled_calls: list = []
1426
+
1427
+ def _work(call):
1428
+ """Drive one call's generator, pushing what it would have yielded."""
1429
+ gen = _dispatch_one(
1430
+ call, context=context, run_info=run_info,
1431
+ response_channel=response_channel, memory=memory,
1432
+ activity=activity, cancel=cancel, gate=_GATE_LOCK)
1433
+ try:
1434
+ while True:
1435
+ conduit.put(("event", next(gen)))
1436
+ except StopIteration as stop:
1437
+ return stop.value
1438
+ finally:
1439
+ # Runs on the return path and on the raising one, so the
1440
+ # drain below always terminates. A worker that died still
1441
+ # reports that it is done.
1442
+ conduit.put(("done", None))
1443
+
1444
+ workers = max(1, min(len(calls), config.SUBAGENT_MAX_PARALLEL))
1445
+ abandoned = False
1446
+ with ThreadPoolExecutor(max_workers=workers,
1447
+ thread_name_prefix="venastine-call") as pool:
1448
+ futures = []
1449
+ for call in calls:
1450
+ futures.append(
1451
+ (call, pool.submit(copy_context().run, _work, call)))
1452
+ outstanding = len(calls)
1453
+ # ABANDONED MID-BATCH, the window #215 names (batch 221). A
1454
+ # consumer that goes away at one of these yields -- the TUI closes
1455
+ # its generator on shutdown -- used to take every finished call's
1456
+ # outcome with it: D20 had written their `tool_use` blocks, the
1457
+ # tools had run, and no row answered them. So the GeneratorExit is
1458
+ # held while the workers finish, which the pool's own exit already
1459
+ # waited for, and every outcome is recorded in the model's order
1460
+ # below before it is raised again. NA11 is untouched: nothing is
1461
+ # recorded out of order, only no longer dropped.
1462
+ try:
1463
+ while outstanding:
1464
+ kind, payload = conduit.get()
1465
+ if kind == "done":
1466
+ outstanding -= 1
1467
+ else:
1468
+ yield payload
1469
+ except GeneratorExit:
1470
+ abandoned = True
1471
+ for call, future in futures:
1472
+ try:
1473
+ settled_calls.append((call, future.result(), None))
1474
+ except Exception as e: # noqa: BLE001 -- NA14, see below
1475
+ settled_calls.append((call, None, e))
1476
+
1477
+ # NA14. A RAISING SIBLING BECOMES ITS OWN RESULT, and this is a
1478
+ # deliberate behaviour change scoped to a parallel batch.
1479
+ #
1480
+ # Sequentially an exception out of a tool leaves `_run` and ends the
1481
+ # turn; §16 AC3 pins that this must not kill the app (`test_tui.py`),
1482
+ # and a lone call keeps exactly that. In a batch it would discard the
1483
+ # finished work of every sibling -- runs that cost a model call each
1484
+ # and whose answers are already in hand -- so the raise is converted
1485
+ # to this call's error result and the turn goes on.
1486
+ #
1487
+ # A BACKSTOP RATHER THAN THE USUAL PATH. `dispatch()` already turns a
1488
+ # handler's exception into an error result, and BOTH exceptions it
1489
+ # raises on purpose -- ToolCallDenied and the unknown-tool ValueError
1490
+ # -- are caught inside `_dispatch_one`. What reaches here is a failure
1491
+ # in the approval machinery itself. Logged with the traceback for
1492
+ # dispatch()'s reason -- a real bug must stay findable -- and reported
1493
+ # to the model in the shape it already understands.
1494
+ #
1495
+ # THIS COMMENT USED TO NAME THE UNKNOWN TOOL, and could not be reached
1496
+ # by it (batch 147): `registry.parallel()` answers False for a name it
1497
+ # does not hold, so `_parallel_groups` always put an unknown call in a
1498
+ # group of ONE, and a group of one takes the sequential branch. The
1499
+ # containment it described was in the wrong function for the failure
1500
+ # it named -- so the failure ended the turn and this backstop never
1501
+ # saw it. Both halves are fixed: `_dispatch_one` contains it for both
1502
+ # drivers, and the sentence above no longer claims a case this cannot
1503
+ # see.
1504
+ ordered = []
1505
+ for call, outcome, failure in settled_calls:
1506
+ if failure is not None:
1507
+ logger.exception(
1508
+ "parallel tool call %s (%s) raised; reporting it as that "
1509
+ "call's error and continuing with its siblings",
1510
+ call.id, call.name, exc_info=failure)
1511
+ ordered.append((call, _CallOutcome(
1512
+ result={"error": "%s failed: %s" % (
1513
+ call.name, failure)})))
1514
+ else:
1515
+ ordered.append((call, outcome))
1516
+ if abandoned:
1517
+ # Recorded, never announced: there is nobody left to announce to,
1518
+ # and a generator that yields after GeneratorExit is a
1519
+ # RuntimeError. A failure to record is logged rather than raised,
1520
+ # so it cannot replace the close the consumer asked for.
1521
+ for call, outcome in ordered:
1522
+ try:
1523
+ _settle_one(call, outcome, memory, [], [])
1524
+ except Exception: # noqa: BLE001 -- see above
1525
+ logger.exception("Could not record %s's result while the "
1526
+ "batch was being closed", call.id)
1527
+ raise GeneratorExit
1528
+ return ordered
1529
+
1530
+
1531
+ def _settle_one(call, outcome, memory, granted_calls, notices) -> list:
1532
+ """Record ONE finished call, at its turn in call order, and return the
1533
+ events that announce it.
1534
+
1535
+ Split out of the per-call body so both drivers reach it identically,
1536
+ and so everything that touches `memory` or the turn's shared lists
1537
+ happens on the generator's own thread in the model's own order (NA11).
1538
+ A reordered turn is a thread that will not resume: `add_tool_result`
1539
+ pairs each result to its `tool_use` by id (M4/D20).
1540
+
1541
+ A FUNCTION, NOT A GENERATOR, since batch 221 (#215). As a generator it
1542
+ yielded between one call's row and the next one's, so a batch closed
1543
+ at its first `tool_result` lost the rows of every call after it, and
1544
+ `_dispatch_parallel` had nothing to record its finished calls with
1545
+ once its own consumer had gone. Returning the events lets the batch
1546
+ record every result before announcing any, and lets the abandoned path
1547
+ record without announcing at all.
1548
+ """
1549
+ granted_calls.extend(outcome.granted)
1550
+ notices.extend(outcome.notices)
1551
+ result = outcome.result
1552
+ events = []
1553
+
1554
+ # §23 slice 2 (J10). A tool may attach a `notice` to its
1555
+ # result for the shell to show; it is forwarded as a
1556
+ # LoopEvent and REMOVED from what the model sees.
1557
+ #
1558
+ # Generic on purpose. The alternative was for the loop to
1559
+ # notice that `todo_write` had just run, which puts a tool
1560
+ # name in this file -- exactly what ToolSpec.grant_scope and
1561
+ # ToolSpec.request_kind exist to avoid. Any later tool that
1562
+ # wants to say something mid-turn gets this route free.
1563
+ #
1564
+ # POPPED, not copied: a notice is plumbing for the shell, and
1565
+ # leaving it in the result would send the TUI panel's trigger
1566
+ # to the model as if it were part of the tool's answer.
1567
+ if isinstance(result, dict) and "notice" in result:
1568
+ notice = result.pop("notice")
1569
+ if isinstance(notice, dict) and notice.get("kind"):
1570
+ events.append(LoopEvent(notice=notice))
1571
+ else:
1572
+ # A malformed notice is a bug in the tool, not a
1573
+ # reason to fail the call -- the result is still
1574
+ # good. Logged rather than raised, and the key is
1575
+ # gone either way so it cannot reach the model.
1576
+ logger.warning(
1577
+ "%s returned a malformed notice; dropping it: %r",
1578
+ call.name, notice)
1579
+
1580
+ # Persist BEFORE emitting (#42). A generator only advances
1581
+ # while someone iterates it, so emitting first made the row
1582
+ # depend on a consumer continuing to read -- and an
1583
+ # abandoned generator left the `tool_use` D20 already wrote
1584
+ # with no matching `tool_result`, which is M4's pairing
1585
+ # broken from the other side and an unresumable thread.
1586
+ # Same rule §22 gives _Progress.checkpoint() for trace
1587
+ # lines. The event carries nothing the persist needs, so
1588
+ # the order is free.
1589
+ memory.add_tool_result(call.id, result)
1590
+ events.append(LoopEvent(tool_result={"id": call.id, "result": result}))
1591
+ return events
1592
+
1593
+
1594
+ def _finish_cancelled(memory, response, *, partial_text, unrun, reason,
1595
+ granted_calls, notices, totals):
1596
+ """Everything a cancelled turn leaves behind, in ONE place (§61 CN3).
1597
+
1598
+ Three sites reach it -- the step boundary, a stream cut part way
1599
+ through, and the gap between two tool groups -- and they differ only
1600
+ in what they have in hand. Writing the terminal event at each would
1601
+ be three chances to forget one of the three things below, and the
1602
+ last of them is what keeps the thread resumable.
1603
+
1604
+ `partial_text` is the accumulated deltas when the stream was cut, and
1605
+ None otherwise. It is the only case that PERSISTS, because it is the
1606
+ only one holding an assistant turn D20 has not already written. Empty
1607
+ text persists nothing: a turn stopped before its first token said
1608
+ nothing, and an empty assistant row is one every later request has to
1609
+ carry.
1610
+
1611
+ `unrun` is every tool call of this response that will not get a
1612
+ result. #42 is the same lesson from the other side -- a `tool_use`
1613
+ persisted with no matching `tool_result` is M4's pairing broken and
1614
+ an UNRESUMABLE thread -- so a cancelled turn answers every call the
1615
+ model made, including the ones it declined to run. The answer is an
1616
+ `error`, which is the shape a denied call already takes.
1617
+
1618
+ CN5: a SYNTHESISED response reports an EMPTY usage dict, not zeros.
1619
+ The provider sends usage with its final message and a cut stream has
1620
+ none, so the honest statement is "not measured" -- and the two stay
1621
+ distinguishable, since `"input_tokens" in usage` is False here and
1622
+ True for a step that genuinely cost nothing. A zero would be the
1623
+ instrument that lies, which batches 118 and 119 each paid for once.
1624
+
1625
+ CANCELLED IS NOT FAILED. Nothing here calls `mark_turn_failed`: the
1626
+ frame above draws exactly that distinction for an abandoned
1627
+ generator, and §60's UH6 records UHP arriving at it independently.
1628
+ """
1629
+ if partial_text is not None:
1630
+ response = ModelResponse(text=partial_text, usage={})
1631
+ if partial_text:
1632
+ memory.add_assistant_message(response)
1633
+ elif response is None:
1634
+ response = ModelResponse(text="", usage={})
1635
+ for call in unrun:
1636
+ result = {"error": reason}
1637
+ memory.add_tool_result(call.id, result)
1638
+ yield LoopEvent(tool_result={"id": call.id, "result": result})
1639
+ response.stop_reason = "cancelled"
1640
+ response.granted_calls = granted_calls
1641
+ response.notices = notices
1642
+ (response.turn_billed_tokens, response.turn_new_tokens,
1643
+ response.turn_output_tokens) = totals
1644
+ yield LoopEvent(final_response=response, stop_reason="cancelled")
1645
+
1646
+
1647
+ class RunAgentLoop:
1648
+
1649
+ @staticmethod
1650
+ def _run(memory: ConversationMemory, *args, **kwargs):
1651
+ """The loop, recording on the thread why a run that raised failed.
1652
+
1653
+ Batch 91. A thin frame around `_run_steps`, which IS the loop and
1654
+ whose docstring documents every argument. `yield from` forwards each
1655
+ event and the return value unchanged, so nothing driving `_run` can
1656
+ tell the frame is there -- and nothing about the exception changes
1657
+ either: core/events.py has no error variant on purpose, and it still
1658
+ propagates to whoever drains this, exactly as it did.
1659
+
1660
+ Without it a run that failed left nothing behind in its thread --
1661
+ D20 persists an assistant turn only once a call returns -- so a
1662
+ subagent whose first call failed replayed as its task and nothing
1663
+ else. One frame covers every caller: a TUI turn, a CLI turn, a
1664
+ spawned subagent, a one-shot, a research pass.
1665
+
1666
+ `Exception`, not `BaseException`: a GeneratorExit is an ABANDONED
1667
+ generator (#42, a TUI quitting mid-turn), not a failed run, and
1668
+ recording it would stamp a failure on a turn nobody saw fail.
1669
+ Recording must never replace the error it records, so its own
1670
+ failure is warned and swallowed.
1671
+ """
1672
+ try:
1673
+ return (yield from RunAgentLoop._run_steps(memory, *args, **kwargs))
1674
+ except Exception as error:
1675
+ try:
1676
+ # THE DURABLE SINK, so the vocabulary matters most
1677
+ # here (batch 144). `API_URL` is user-supplied
1678
+ # through `save_credentials(api_url=...)`, an httpx error
1679
+ # names the URL it failed on, and this row lands in
1680
+ # `MessageLog.error` in app.db -- which `docs/PRIVACY.md`
1681
+ # says is deleted by wiping the database, not one thread.
1682
+ # `redact_secrets` alone would keep a URL's userinfo.
1683
+ memory.mark_turn_failed(
1684
+ redact_diagnostic_text(provider_errors.describe(error)))
1685
+ except Exception: # noqa: BLE001 -- see the docstring
1686
+ logger.warning(
1687
+ "Could not record this run's failure on its thread.",
1688
+ exc_info=True)
1689
+ raise
1690
+
1691
+ @staticmethod
1692
+ def _run_steps(
1693
+ memory: ConversationMemory,
1694
+ system_prompt: str,
1695
+ provider_name: str,
1696
+ model: str,
1697
+ context: Optional[ToolContext],
1698
+ max_steps: int,
1699
+ max_total_tokens: Optional[int] = None,
1700
+ temperature: Optional[float] = None,
1701
+ effort: Optional[str] = None,
1702
+ response_channel=None,
1703
+ granted_tools: Optional[set] = None,
1704
+ grant_budget=None,
1705
+ compaction_mode: Optional[str] = None,
1706
+ activity=None,
1707
+ cancel=None,
1708
+ ):
1709
+ """Generator yielding LoopEvent objects as the loop progresses.
1710
+
1711
+ context: an optional ToolContext (§15) restricting which tools are
1712
+ available and which need approval this run. None means only global
1713
+ config policy applies, which is every production caller until §18
1714
+ introduces agents. This replaced an `allowed_tools` list that did
1715
+ the same job one layer up: the loop no longer decides tool
1716
+ membership itself, it just hands the context to the registry and
1717
+ lets security/permissions.py compose the layers.
1718
+
1719
+ response_channel: an optional core.interaction.ResponseChannel --
1720
+ the ONE way this loop asks a human anything (§23 AC1). None means
1721
+ nothing can be asked, and any call that would need approval is
1722
+ denied. Replaced a queue.Queue plus a separate ApprovalProvider,
1723
+ which were the same exchange with two sets of plumbing; a shell
1724
+ that needs the thread handoff (the TUI parks its worker while the
1725
+ UI thread renders a modal) does that inside its own `ask`.
1726
+
1727
+ granted_tools: names the user has ALREADY approved for this run
1728
+ (§18 subagent sign-off). A spawned subagent receives the set the
1729
+ user signed off when approving the spawn, so it does not re-ask
1730
+ for tools already covered. A grant, not a policy relaxation: it
1731
+ records an approval given early, which is why it lives on RunInfo
1732
+ rather than in the ToolContext's approval_overrides (those OR, and
1733
+ so can only tighten).
1734
+
1735
+ grant_budget: a core.approval.GrantBudget capping how many granted
1736
+ calls may skip the prompt (§25 R6), or None for no cap. Shared by
1737
+ reference across every pass of a pipeline run. Exhaustion makes
1738
+ the grant stop applying, so calls fall back to being asked.
1739
+
1740
+ compaction_mode (§21): None -- the default since batch 16 (#43) --
1741
+ means DERIVE from what the thread is: research_pass and subagent
1742
+ threads get M6's backstop wherever they are re-entered, a chat
1743
+ thread gets the ordinary working-set trigger. An explicit value
1744
+ wins, and stream_deep_research_mode passes "backstop" explicitly
1745
+ as the definition site. Before this, every continue_conversation
1746
+ caller silently ran on the chat trigger: a pass's JSON retry and
1747
+ the §20 reviewer evaluated a threshold their own threads were
1748
+ never meant to answer to.
1749
+
1750
+ cancel (§61): an optional core.cancel.CancelToken. None -- every
1751
+ caller that has not opted in, which is every caller predating
1752
+ §61 -- means nothing can stop this run, exactly as before. Set,
1753
+ it is read at the three sites inside this function that CN2
1754
+ names (the fourth is the shell's own drain), and the run then
1755
+ ENDS on `stop_reason: "cancelled"` rather than raising. It must
1756
+ not raise: the frame above records a failure on the thread for
1757
+ any exception that is not a GeneratorExit, and a person changing
1758
+ their mind is not a failed run.
1759
+ """
1760
+ # §29/#45 belt. `_run` is a generator, so this fires on the first
1761
+ # next() -- which for every production caller is immediate, since
1762
+ # all three wrappers drain eagerly. It exists because the loader
1763
+ # repairs agent files (#45) while a DIRECT caller bypasses that
1764
+ # repair entirely: there is no file to lose here, only a bug worth
1765
+ # naming, so this raises rather than substituting. The old failure
1766
+ # was an AttributeError on `response.stop_reason` after an empty
1767
+ # step loop -- a traceback pointing three layers away from the bad
1768
+ # value that caused it.
1769
+ if isinstance(max_steps, bool) or not isinstance(max_steps, int) \
1770
+ or max_steps < 1:
1771
+ raise ValueError(
1772
+ f"max_steps must be a positive integer, got {max_steps!r}. "
1773
+ f"Agent definitions carrying an invalid max_steps are "
1774
+ f"repaired by the loader to {config.MAX_ITERATIONS} "
1775
+ f"(config.MAX_ITERATIONS); direct callers must pass a valid "
1776
+ f"value themselves.")
1777
+ client = api_initialization(provider_name)
1778
+ # Validate the level against the model that will RECEIVE it, here
1779
+ # rather than at each caller. Every path -- CLI chat, each research
1780
+ # pass, a TUI turn, a spawned subagent -- reaches the wire through
1781
+ # this function, so this is the one place that cannot be bypassed
1782
+ # by a new caller forgetting to check. It also makes the agent case
1783
+ # correct by construction: an agent declaring its own model is
1784
+ # validated against THAT model, not the one the parent was using.
1785
+ effort = effort_for(client, provider_name, model, effort)
1786
+ # Prime the context-window cache on the same one-per-process
1787
+ # footing, and HERE for effort_for's reason: this is the one place
1788
+ # every send crosses, so a new caller cannot forget it. On
1789
+ # ANTHROPIC it is a pure cache hit -- effort_for's own retrieve
1790
+ # already recorded the window off the ModelInfo it fetched -- so
1791
+ # the only providers this actually calls for are Google and the
1792
+ # v1-compatible roster. The result is read back, without a client,
1793
+ # by compaction.context_limit(); a failure here is warned and
1794
+ # simply leaves the static table answering.
1795
+ context_window_for(client, provider_name, model)
1796
+ # §18 headless callability rule (user-widened from approval-only):
1797
+ # with no way to ask, a tool that needs approval is uncallable in
1798
+ # this configuration, so it is not advertised -- but named once in
1799
+ # a WARNING so the hiding is never silent.
1800
+ #
1801
+ # §25: "no way to ask" is not "not a TUI". A research pass with a
1802
+ # channel CAN ask, so hiding its gated tools would report a
1803
+ # limitation the run does not have. §23 made this one condition
1804
+ # again -- it was two while there were two routes.
1805
+ #
1806
+ # §25 R15: and "nothing can ask" is not "nothing has answered". A
1807
+ # GRANT is an answer given before the call existed, so a granted
1808
+ # tool is callable with no channel at all -- which is the whole
1809
+ # point of `--grant-tools` on an unattended run. #156: this filter
1810
+ # could not see the grant, so a grant-only run advertised exactly
1811
+ # what an unflagged one did while the CLI printed that it had
1812
+ # authorised something. The enforcement path below honoured the
1813
+ # grant correctly; the model was simply never told the tool was
1814
+ # there, so it never emitted the call.
1815
+ #
1816
+ # run_info IS BUILT ABOVE THIS, not below it as it was before R15.
1817
+ # The schemas call now needs the grant, and the grant lives on
1818
+ # run_info -- building it after would read the name before it is
1819
+ # bound. Nothing else moved: it depends only on values already in
1820
+ # scope here.
1821
+ run_info = RunInfo(
1822
+ model=model, provider_name=provider_name, effort=effort,
1823
+ granted_tools=set(granted_tools or ()),
1824
+ grant_budget=grant_budget,
1825
+ images=_images_deliverable(provider_name, memory))
1826
+ headless = response_channel is None
1827
+ # The BUDGET is deliberately not consulted here. Advertisement is
1828
+ # decided once per step; R6 makes exhaustion fall back to asking
1829
+ # (or, headless, to denying) at CALL time, which is a per-call
1830
+ # answer. Hiding a tool mid-run when the ceiling ran out would
1831
+ # change what the model can see between one step and the next for
1832
+ # a reason it cannot observe, and the model would read that as the
1833
+ # tool having ceased to exist.
1834
+ tool_schemas = registry.schemas(
1835
+ context, callable_only=headless, granted=run_info.granted_tools,
1836
+ images=run_info.images)
1837
+ if not run_info.images:
1838
+ unoffered = tuple(sorted(registry.image_hidden(
1839
+ context, granted=run_info.granted_tools)))
1840
+ key = (provider_name, getattr(memory, "kind", THREAD_KIND_CHAT),
1841
+ unoffered)
1842
+ if unoffered and key not in _image_notices_shown:
1843
+ _image_notices_shown.add(key)
1844
+ logger.warning(
1845
+ "Not advertising %s: an image in its result could not "
1846
+ "reach the model in this run (provider %s is not marked "
1847
+ "`accepts_images` in providers.json, or this is a "
1848
+ "research pass).",
1849
+ ", ".join(unoffered), provider_name)
1850
+ if headless:
1851
+ hidden = tuple(sorted(registry.headless_hidden(
1852
+ context, granted=run_info.granted_tools,
1853
+ images=run_info.images)))
1854
+ if hidden and hidden not in _headless_notices_shown:
1855
+ _headless_notices_shown.add(hidden)
1856
+ logger.warning(
1857
+ "Headless run (no permission channel): not advertising "
1858
+ "%s -- they require approval and nothing here can "
1859
+ "grant it.",
1860
+ ", ".join(hidden),
1861
+ )
1862
+ total_tokens_used = 0
1863
+ # #4: the size instrument, kept strictly beside the spend meter.
1864
+ # turn_baseline_input is the FIRST call's prompt -- the thread as
1865
+ # this turn inherited it, which this turn did not add. Every later
1866
+ # step contributes its output plus whatever NEW material entered
1867
+ # the context (positive input deltas; a mid-turn compaction SHRINKS
1868
+ # the prompt, and clamping at zero keeps that shrink from being
1869
+ # read as negative growth). turn_billed/turn_new ride every
1870
+ # response; memory.record_billed accumulates thread-since-resume.
1871
+ turn_baseline_input: Optional[int] = None
1872
+ turn_prev_input = 0
1873
+ turn_new_tokens = 0
1874
+ # Batch 61, the third instrument. Output ALONE -- see the field's
1875
+ # comment on ModelResponse for why neither of the two above can
1876
+ # stand in for it once a duration is divided into the result.
1877
+ turn_output_tokens = 0
1878
+ # §25 audit trail. Attached to the response object below rather
1879
+ # than at each of the three return points, so a stop condition
1880
+ # added later cannot forget to carry it -- the list is shared by
1881
+ # reference and keeps filling as tools dispatch.
1882
+ granted_calls: list = []
1883
+ # §21, same pattern and the same reason.
1884
+ notices: list = []
1885
+
1886
+ # Turn boundary (M3). The primary trigger: the thread is settled,
1887
+ # nothing is mid-flight, and last_input_tokens is the provider's
1888
+ # own measurement of what the previous call was sent.
1889
+ yield from _maybe_compact(
1890
+ memory, model, provider_name, notices,
1891
+ compaction_mode
1892
+ if compaction_mode is not None
1893
+ else _derived_compaction_mode(memory),
1894
+ activity=activity, depth=_compactor_depth(context))
1895
+
1896
+ response = None
1897
+ for _ in range(max_steps):
1898
+ # §61 CN2, the step boundary -- and ABOVE the reset below,
1899
+ # which is the whole reason it sits here rather than at the
1900
+ # foot of the body. The response it reads is the PREVIOUS
1901
+ # step's: already counted, already persisted, and the last
1902
+ # thing the model actually said. That is the shape
1903
+ # "max_steps exhausted" already has at the end of this loop.
1904
+ # Below the reset it would read None on every iteration and
1905
+ # report an empty answer for a turn that had produced
1906
+ # several.
1907
+ if is_cancelled(cancel):
1908
+ yield from _finish_cancelled(
1909
+ memory, response, partial_text=None, unrun=(),
1910
+ reason=cancel.reason, granted_calls=granted_calls,
1911
+ notices=notices,
1912
+ totals=(total_tokens_used, turn_new_tokens,
1913
+ turn_output_tokens))
1914
+ return
1915
+ response = None
1916
+ # Batch 91. ONE model call, attempted up to
1917
+ # 1 + MODEL_CALL_MAX_RETRIES times. The SDKs retry a request that
1918
+ # fails before its stream opens; an error sent INSIDE a stream
1919
+ # that opened with 200 is raised straight up by both, and that is
1920
+ # how OpenRouter reports an overloaded upstream. Which failures
1921
+ # qualify is core/provider_errors.py's question.
1922
+ #
1923
+ # `shown` was the boundary until batch 113 (TECHNICAL_DEBT 25).
1924
+ # It read "a RichLog row cannot be taken back", which was true
1925
+ # of the transcript as it stood: a retry after a delta would
1926
+ # have drawn the answer a second time under the half already on
1927
+ # screen, so a DRAWN run was refused the retry a reader most
1928
+ # wanted. Batch 112 made a row retractable -- `_replay()` draws
1929
+ # the transcript from `_entries` -- so the loop now says what
1930
+ # happened and the drawing surface takes its own rows back.
1931
+ #
1932
+ # `shown` survives with a different job: it is no longer "may we
1933
+ # retry" but "is there anything to retract", which is the only
1934
+ # question left for it to answer.
1935
+ #
1936
+ # Below the wrappers that write the user message, so a retry
1937
+ # never writes it twice; and before the accounting, so only the
1938
+ # attempt that succeeded is counted or persisted (D20). A failed
1939
+ # stream reports no usage to count in any case.
1940
+ retry = 0
1941
+ # §61 CN4. The deltas are accumulated HERE because no
1942
+ # provider branch can supply them after a cut: the Anthropic
1943
+ # one builds its text from `stream.get_final_message()`,
1944
+ # which a stream broken off part way never produces. Reset
1945
+ # per ATTEMPT, beside `shown`, so a retry that retracts what
1946
+ # was drawn does not also keep it.
1947
+ cut_short = False
1948
+ while True:
1949
+ shown = False
1950
+ partial = []
1951
+ try:
1952
+ for token in call_model_stream(
1953
+ client, provider_name, model, memory.messages,
1954
+ system_prompt, tool_schemas, temperature, effort,
1955
+ ):
1956
+ if token.final_response is not None:
1957
+ response = token.final_response
1958
+ # §61 CN2, and guarded on `response is None`
1959
+ # rather than placed by line order, because
1960
+ # placement alone was not enough: a cancel
1961
+ # arriving in the gap before the final-response
1962
+ # token still cut a call that had already been
1963
+ # made and paid for, and its usage went with it.
1964
+ # A step holding a complete response is
1965
+ # FINISHED -- it is accounted and persisted
1966
+ # exactly as always, and the stop lands at the
1967
+ # next site instead.
1968
+ if response is None and is_cancelled(cancel):
1969
+ cut_short = True
1970
+ break
1971
+ if token.text_delta:
1972
+ shown = True
1973
+ partial.append(token.text_delta)
1974
+ yield LoopEvent(token_delta=token.text_delta)
1975
+ if token.thinking_delta:
1976
+ shown = True
1977
+ yield LoopEvent(thinking_delta=token.thinking_delta)
1978
+ break
1979
+ except Exception as e: # noqa: BLE001 -- re-raised unless it qualifies
1980
+ retry += 1
1981
+ if (retry > config.MODEL_CALL_MAX_RETRIES
1982
+ or not provider_errors.is_transient(e)):
1983
+ raise
1984
+ response = None
1985
+ delay = provider_errors.backoff_delay(
1986
+ retry, config.MODEL_CALL_RETRY_BASE_DELAY_S,
1987
+ provider_errors.retry_after_s(e))
1988
+ attempts = config.MODEL_CALL_MAX_RETRIES + 1
1989
+ logger.warning(
1990
+ "Model call to %s/%s failed (%s); retrying in %.0fs, "
1991
+ "attempt %d of %d.",
1992
+ provider_name, model, provider_errors.describe(e),
1993
+ delay, retry + 1, attempts)
1994
+ if shown:
1995
+ # Batch 113. BEFORE the wait, not after it: the
1996
+ # reader is about to watch a part-written answer
1997
+ # disappear and then several seconds of nothing,
1998
+ # and the sentence explaining that is worth more
1999
+ # while it is happening than once it is over.
2000
+ #
2001
+ # Only when something was drawn. An attempt that
2002
+ # streamed nothing has nothing to take back, and
2003
+ # the warning above is already the record of it.
2004
+ yield LoopEvent(retract={
2005
+ "text": "the answer was interrupted (%s); "
2006
+ "retrying, attempt %d of %d"
2007
+ % (provider_errors.describe(e),
2008
+ retry + 1, attempts),
2009
+ "attempt": retry + 1,
2010
+ "attempts": attempts,
2011
+ })
2012
+ provider_errors.wait(delay)
2013
+
2014
+ # §61 CN2/CN4. Leaving the `for` above closed the
2015
+ # provider stream: every branch yields from inside its own
2016
+ # context manager, so the connection is already released by
2017
+ # the time this runs. What is left to decide is the
2018
+ # half-answer, and CN4 keeps it.
2019
+ if cut_short:
2020
+ yield from _finish_cancelled(
2021
+ memory, None, partial_text="".join(partial), unrun=(),
2022
+ reason=cancel.reason, granted_calls=granted_calls,
2023
+ notices=notices,
2024
+ totals=(total_tokens_used, turn_new_tokens,
2025
+ turn_output_tokens))
2026
+ return
2027
+
2028
+ if response is None:
2029
+ raise RuntimeError(
2030
+ "call_model_stream completed without yielding a final response"
2031
+ )
2032
+
2033
+ usage_in = response.usage.get("input_tokens", 0)
2034
+ usage_out = response.usage.get("output_tokens", 0)
2035
+ total_tokens_used += usage_in + usage_out
2036
+ if turn_baseline_input is None:
2037
+ # First call of the turn: its prompt IS the inherited
2038
+ # thread, so only this step's OUTPUT counts as new.
2039
+ turn_baseline_input = usage_in
2040
+ else:
2041
+ turn_new_tokens += max(0, usage_in - turn_prev_input)
2042
+ turn_new_tokens += usage_out
2043
+ turn_output_tokens += usage_out
2044
+ turn_prev_input = usage_in
2045
+ memory.record_billed(usage_in + usage_out)
2046
+ response.turn_billed_tokens = total_tokens_used
2047
+ response.turn_new_tokens = turn_new_tokens
2048
+ response.turn_output_tokens = turn_output_tokens
2049
+
2050
+ # D20: persist EVERY assistant turn BEFORE any branching.
2051
+ memory.add_assistant_message(response)
2052
+ response.granted_calls = granted_calls
2053
+ response.notices = notices
2054
+ # §21: the provider's own count of everything it was just
2055
+ # sent. Recorded here rather than at the trigger so a thread
2056
+ # resumed in a later process starts from a real measurement
2057
+ # instead of a character estimate.
2058
+ memory.record_input_tokens(response.usage.get("input_tokens", 0))
2059
+
2060
+ if max_total_tokens is not None and total_tokens_used >= max_total_tokens:
2061
+ response.stop_reason = "token_budget_exceeded"
2062
+ yield LoopEvent(
2063
+ final_response=response, stop_reason=response.stop_reason,
2064
+ )
2065
+ return
2066
+
2067
+ if not response.tool_calls:
2068
+ response.stop_reason = "complete"
2069
+ yield LoopEvent(
2070
+ final_response=response, stop_reason=response.stop_reason,
2071
+ )
2072
+ return
2073
+
2074
+ # NA9. The response is partitioned before anything runs: a run of
2075
+ # calls whose ToolSpec declares `parallel` goes together, and every
2076
+ # other call is a group of one in its original position. A response
2077
+ # with nothing parallel in it therefore takes the same path it
2078
+ # always did, one group of one at a time.
2079
+ groups = _parallel_groups(response.tool_calls)
2080
+ for index, group in enumerate(groups):
2081
+ # §61 CN2/CN6. BETWEEN groups, never inside one. A call
2082
+ # already running finishes and settles: nothing here has
2083
+ # the power to kill a tool, and a cancel that threw away
2084
+ # a completed call's result would discard work already
2085
+ # done. Every group NOT reached still needs its rows --
2086
+ # #42's lesson from the other side -- which is what
2087
+ # `unrun` carries.
2088
+ if is_cancelled(cancel):
2089
+ yield from _finish_cancelled(
2090
+ memory, response, partial_text=None,
2091
+ unrun=[c for rest in groups[index:] for c in rest],
2092
+ reason=cancel.reason, granted_calls=granted_calls,
2093
+ notices=notices,
2094
+ totals=(total_tokens_used, turn_new_tokens,
2095
+ turn_output_tokens))
2096
+ return
2097
+ # In call order, and BEFORE anything is submitted, so a batch
2098
+ # announces its whole membership at once rather than in
2099
+ # whatever order three threads happen to reach their first
2100
+ # line. Hoisted out of `_dispatch_one` for exactly that: the
2101
+ # start of a call is a fact the frame that ordered it knows.
2102
+ for call in group:
2103
+ yield LoopEvent(tool_call_start={
2104
+ "id": call.id, "name": call.name, "input": call.input,
2105
+ })
2106
+
2107
+ if len(group) == 1:
2108
+ # No siblings, no gate, no thread. Byte-identical to the
2109
+ # pre-slice-8 path, which is what makes every existing
2110
+ # test of this loop a test of the sequential branch.
2111
+ settled = [(group[0], (yield from _dispatch_one(
2112
+ group[0], context=context, run_info=run_info,
2113
+ response_channel=response_channel, memory=memory,
2114
+ activity=activity, cancel=cancel)))]
2115
+ else:
2116
+ settled = yield from _dispatch_parallel(
2117
+ group, context=context, run_info=run_info,
2118
+ response_channel=response_channel, memory=memory,
2119
+ activity=activity, cancel=cancel)
2120
+
2121
+ # NA11. In the MODEL'S order, whatever order they finished in
2122
+ # -- and EVERY row of the group recorded before ANY event is
2123
+ # announced (#215, batch 221). #42's persist-before-emit
2124
+ # held per call and not per group: a consumer gone at the
2125
+ # first call's `tool_result` left the later calls' tools run
2126
+ # and their rows never written.
2127
+ announced = [event for call, outcome in settled
2128
+ for event in _settle_one(call, outcome, memory,
2129
+ granted_calls, notices)]
2130
+ yield from announced
2131
+
2132
+ # The mid-turn valve (M3). A single turn can add far more than
2133
+ # any buffer covers -- MAX_READ_CHARS alone is ~12.5k tokens
2134
+ # per read call, with up to max_steps of them -- so waiting for
2135
+ # the next turn boundary would let a tool-heavy turn run the
2136
+ # thread into the provider's hard limit.
2137
+ #
2138
+ # Safe by construction rather than by timing: the current-turn
2139
+ # floor makes the current turn unfoldable, so this can only ever
2140
+ # summarize exchanges that were already complete when the turn
2141
+ # began. That is what made a mid-turn trigger acceptable at
2142
+ # all.
2143
+ #
2144
+ # The floor is `memory.completed_turns()`, asked inside
2145
+ # _maybe_compact. This comment used to name a `turn_start`
2146
+ # variable recorded at the top of the turn (audit #91); it moved
2147
+ # because archive-space turn counting is time-invariant WITHIN a
2148
+ # turn -- a completed turn cannot become incomplete -- so asking
2149
+ # lazily gives the same answer and keeps a storage read off every
2150
+ # turn nowhere near the threshold. See core/compaction.py's note
2151
+ # on why it is computed there rather than passed down.
2152
+ yield from _maybe_compact(
2153
+ memory, model, provider_name, notices,
2154
+ compaction_mode
2155
+ if compaction_mode is not None
2156
+ else _derived_compaction_mode(memory),
2157
+ activity=activity, depth=_compactor_depth(context))
2158
+
2159
+ # max_steps exhausted without an earlier return
2160
+ response.stop_reason = "max_steps_reached"
2161
+ yield LoopEvent(
2162
+ final_response=response, stop_reason=response.stop_reason,
2163
+ )
2164
+
2165
+ @staticmethod
2166
+ def run_agent_conversation(
2167
+ user_goal: str,
2168
+ model: str,
2169
+ provider_name: str = DEFAULT_PROVIDER,
2170
+ max_steps: int = config.MAX_ITERATIONS,
2171
+ max_total_tokens: Optional[int] = _SPEND_UNSET,
2172
+ thread_id: Optional[UUID] = None,
2173
+ temperature: Optional[float] = None,
2174
+ effort: Optional[str] = None,
2175
+ context: Optional[ToolContext] = None,
2176
+ system_prompt: Optional[str] = None,
2177
+ response_channel=None,
2178
+ granted_tools: Optional[set] = None,
2179
+ authorization=None,
2180
+ thread_kind: str = THREAD_KIND_CHAT,
2181
+ activity=None,
2182
+ thread_parent: Optional[UUID] = None,
2183
+ thread_parent_call: Optional[str] = None,
2184
+ thread_agent: Optional[str] = None,
2185
+ cancel=None,
2186
+ observe=None,
2187
+ active_skills=(),
2188
+ ) -> ModelResponse:
2189
+ """Regular conversation — full tool set, default system prompt,
2190
+ one continuous thread. Pass thread_id to resume an existing
2191
+ thread; omit (or None) to start a fresh one. Pass context (§15) to
2192
+ run under an agent's tool restrictions; None means global policy
2193
+ only. Pass system_prompt (§18) when running AS an agent -- the
2194
+ TUI worker and spawn_subagent both build it via
2195
+ agents.manager.AgentManager.system_prompt_for();
2196
+ None keeps the default base + skill/agent catalogs.
2197
+
2198
+ A thread's persistent goal (§18 goal mode) is appended to WHICHEVER
2199
+ prompt is used, so it applies in every shell without the callers
2200
+ knowing about it.
2201
+
2202
+ response_channel / granted_tools exist for spawn_subagent (§18
2203
+ S1). Without the channel a spawned subagent ran HEADLESS while its
2204
+ parent could prompt, so it silently lost every approval-gated tool
2205
+ -- including all MCP tools -- and the same agent behaved
2206
+ differently depending on whether it was activated with /agent or
2207
+ spawned.
2208
+
2209
+ authorization (§20): a RunAuthorization, for an agent-shaped run
2210
+ that is part of a research run -- §20's reviewer is the first.
2211
+ §25 added the bundle to the pass entry point and
2212
+ continue_conversation and stopped here, because nothing
2213
+ agent-shaped needed it yet; a reviewer inheriting its run's grants
2214
+ and BUDGET does.
2215
+
2216
+ Mutually exclusive with granted_tools, and checked rather than
2217
+ silently resolved. The two spell the same underlying argument, so
2218
+ one would quietly win -- and if the bundle lost, a reviewer would
2219
+ run with no budget and no provider while looking authorised.
2220
+
2221
+ thread_kind (§27 T1) is what this entry point creates when it
2222
+ creates a thread. It defaults to "chat" because this is ALSO the
2223
+ plain-conversation entry point for both shells; the three callers
2224
+ that are not a human conversation -- spawn_subagent, §20's reviewer
2225
+ and §21a's compactor -- pass THREAD_KIND_SUBAGENT, which is what
2226
+ keeps their threads out of the picker. Ignored when thread_id is
2227
+ given: resuming does not reclassify.
2228
+
2229
+ thread_parent / thread_parent_call / thread_agent (§47) record
2230
+ WHO created this thread, on the same terms: forwarded to the new
2231
+ thread, ignored on a resume. They are what makes a spawned run
2232
+ reachable afterwards -- without them a `▸ spawn_subagent` line
2233
+ describes a conversation nothing can find. Only the callers that
2234
+ know they are creating a child pass them.
2235
+
2236
+ observe (ROADMAP_v3 §86) is `run_to_completion`'s: handed every
2237
+ event as the turn runs. The CLI passes one to print the turn live.
2238
+
2239
+ active_skills (§89) are the session's `/skill` activations: marked
2240
+ in the default prompt's catalog and their bodies pinned last by
2241
+ session_tiers (§19 K1). The TUI builds its own prompt and passes
2242
+ none here; the CLI passes its session's."""
2243
+ if authorization is not None and granted_tools is not None:
2244
+ raise ValueError(
2245
+ "run_agent_conversation: pass authorization= or "
2246
+ "granted_tools=, not both -- they set the same underlying "
2247
+ "argument, so one would silently win."
2248
+ )
2249
+ memory = ConversationMemory(
2250
+ thread_id=thread_id, kind=thread_kind,
2251
+ parent_thread_id=thread_parent,
2252
+ parent_call_id=thread_parent_call, agent_name=thread_agent)
2253
+ # §47. THE EARLIEST MOMENT THE ID EXISTS, which is what makes a
2254
+ # RUNNING child openable rather than only a finished one. The
2255
+ # span was opened by the caller before this function was called
2256
+ # -- the handler brackets the call, the thread is created inside
2257
+ # it -- so the sink learned a name and a depth and had no address
2258
+ # for them. A no-op when no span is open, which is every
2259
+ # top-level conversation, so this needs no branch.
2260
+ agent_activity.bind(activity, memory.thread_id)
2261
+ memory.add_user_message(user_goal)
2262
+ # ROADMAP_v3 §49: shared with wake_conversation, so a turn a
2263
+ # background session starts runs under the same prompt tiers.
2264
+ prompt = RunAgentLoop._conversation_prompt(
2265
+ memory, system_prompt, model=model, provider_name=provider_name,
2266
+ authorization=authorization,
2267
+ response_channel=response_channel, granted_tools=granted_tools,
2268
+ active_skills=active_skills)
2269
+ auth_kwargs = (
2270
+ _authorization_kwargs(authorization) if authorization is not None
2271
+ else {"granted_tools": granted_tools}
2272
+ )
2273
+ # §23: the bundle's channel and the explicit parameter are now the
2274
+ # SAME kind of thing, so they can collide -- they could not before,
2275
+ # when one was a queue named permission_channel and the other an
2276
+ # ApprovalProvider named approval_provider, and both were passed.
2277
+ #
2278
+ # The explicit argument wins, preserving _obtain_approval's old
2279
+ # precedence ("the channel wins when both are present"). A caller
2280
+ # that passes one is describing THIS run; the bundle may have been
2281
+ # assembled for a pipeline several layers up.
2282
+ # Popped UNCONDITIONALLY, then merged. `a or kwargs.pop(...)`
2283
+ # short-circuits, so the key would survive in auth_kwargs on
2284
+ # exactly the path where an explicit channel was passed -- and
2285
+ # collide with it at the call below.
2286
+ bundled_channel = auth_kwargs.pop("response_channel", None)
2287
+ response_channel = response_channel or bundled_channel
2288
+ response = run_to_completion(RunAgentLoop._run(
2289
+ memory, prompt,
2290
+ provider_name, model, context,
2291
+ max_steps, _resolve_spend_cap(max_total_tokens),
2292
+ temperature=temperature, effort=effort,
2293
+ response_channel=response_channel, activity=activity,
2294
+ cancel=cancel,
2295
+ **auth_kwargs,
2296
+ ), observe)
2297
+ response.thread_id = memory.thread_id
2298
+ return response
2299
+
2300
+ @staticmethod
2301
+ def stream_deep_research_mode(
2302
+ pass_input: str,
2303
+ model: str,
2304
+ pass_id: str,
2305
+ provider_name: str = DEFAULT_PROVIDER,
2306
+ max_steps: int = config.MAX_ITERATIONS,
2307
+ max_total_tokens: Optional[int] = _SPEND_UNSET,
2308
+ temperature: Optional[float] = None,
2309
+ effort: Optional[str] = None,
2310
+ context: Optional[ToolContext] = None,
2311
+ authorization=None,
2312
+ activity=None,
2313
+ ):
2314
+ """One research pass, as a generator of LoopEvents, RETURNING the
2315
+ ModelResponse (ROADMAP_v2 §26).
2316
+
2317
+ Exists because §22's P2 -- "a pass's LoopEvents do not propagate
2318
+ up" -- made a pass opaque while it ran. The pipeline could say
2319
+ which pass had started and nothing about what it was doing, so a
2320
+ pass making fourteen tool calls over several minutes looked
2321
+ identical to one that had hung.
2322
+
2323
+ P2 is AMENDED here, not repealed. What escapes this generator is
2324
+ still consumed inside core/reasoning/orchestrator.py, which
2325
+ translates a chosen subset into PipelineEvents at the pass
2326
+ boundary -- so a pipeline consumer still only ever sees one event
2327
+ type, which is what P1 and P2 were jointly protecting. What
2328
+ changed is the premise that a pass's internals are not worth
2329
+ seeing.
2330
+
2331
+ A GENERATOR SIBLING, not an observer callback on the existing
2332
+ function. That shape is the project's own, used three times
2333
+ already, and §23 AC1 exists specifically to stop a third bespoke
2334
+ request/response channel appearing beside the ones that already
2335
+ existed -- which §23 has now merged into core.interaction.
2336
+
2337
+ The response is RETURNED rather than read off the terminal event
2338
+ because `thread_id` is attached after the loop finishes. A caller
2339
+ must therefore drain this with something that keeps a generator's
2340
+ return value: `yield from` (what _run_pass does) or
2341
+ `tests/conftest.drain`, never run_to_completion().
2342
+
2343
+ §27: the fresh thread per pass is a LOCKED INVARIANT, not the
2344
+ defect §27's second bug looked like -- passes share distilled JSON
2345
+ and never raw history, which is what stops a later pass reading how
2346
+ an earlier one argued. What was missing is the thread saying so, so
2347
+ that ~15 threads per run stop being offered as conversations.
2348
+
2349
+ §47: the span brackets the WHOLE generator, which is why it is the
2350
+ outermost thing in the body. A pass is a run in its own right and
2351
+ takes minutes; a row that appeared only at the end would describe
2352
+ something already over. It closes on GeneratorExit too, which is
2353
+ the abandonment case §22 records above -- a TUI quitting mid-run
2354
+ must not leave the pass on screen.
2355
+ """
2356
+ # Depth derived from the context the pass starts at rather than
2357
+ # written as a 1: `_compactor_depth`'s rule, one entry point over.
2358
+ depth = (context.subagent_depth if context is not None else 0) + 1
2359
+ with agent_activity.span(activity, pass_id, depth):
2360
+ memory = ConversationMemory(
2361
+ kind=THREAD_KIND_RESEARCH_PASS,
2362
+ # §47. No parent THREAD: a pass is a child of the RUN, and
2363
+ # a run is not a conversation. §27's T2 already indexes
2364
+ # them on `PipelineRun.pass_threads`, the run's own
2365
+ # object, so a second index here would be two records of
2366
+ # one edge -- the producer/consumer shape this project
2367
+ # keeps finding.
2368
+ agent_name=pass_id)
2369
+ # The address, at the earliest moment it exists, so a pass is
2370
+ # openable WHILE it runs rather than once the report lands.
2371
+ agent_activity.bind(activity, memory.thread_id)
2372
+ memory.add_user_message(pass_input)
2373
+ # #68. The catalogs are decided from the SAME bundle the tool
2374
+ # schemas are decided from a few frames down, so a pass cannot
2375
+ # be told to spawn a subagent it will not be given.
2376
+ _callable_only, _granted = advertisement_facts(authorization)
2377
+ system_prompt = system_prompts.pass_prompt(
2378
+ pass_id, callable_only=_callable_only, granted=_granted)
2379
+ response = None
2380
+ for event in RunAgentLoop._run(
2381
+ memory, system_prompt, provider_name, model, context,
2382
+ max_steps, _resolve_spend_cap(max_total_tokens),
2383
+ temperature=temperature, effort=effort,
2384
+ # §21 M6. A pass is headless and unattended and already
2385
+ # returns a distillation, so routine compaction here would
2386
+ # spend on a judgment call nobody is watching. The
2387
+ # backstop still fires near the model's real context
2388
+ # window, because the alternative there is a hard provider
2389
+ # error mid-pipeline.
2390
+ compaction_mode="backstop",
2391
+ activity=activity,
2392
+ **_authorization_kwargs(authorization),
2393
+ ):
2394
+ if event.final_response is not None:
2395
+ response = event.final_response
2396
+ yield event
2397
+ if response is None:
2398
+ # Same contract as run_to_completion's RuntimeError, and
2399
+ # for the same reason: a loop that ended without a final
2400
+ # response has a bug, and returning None would push the
2401
+ # failure into whichever pass dereferences .text first.
2402
+ raise RuntimeError(
2403
+ "Generator completed without yielding a final_response"
2404
+ )
2405
+ response.thread_id = memory.thread_id
2406
+ return response
2407
+
2408
+ @staticmethod
2409
+ def continue_conversation(
2410
+ thread_id: UUID,
2411
+ message: str,
2412
+ system_prompt: str,
2413
+ model: str,
2414
+ provider_name: str = DEFAULT_PROVIDER,
2415
+ max_steps: int = config.MAX_ITERATIONS,
2416
+ max_total_tokens: Optional[int] = _SPEND_UNSET,
2417
+ temperature: Optional[float] = None,
2418
+ effort: Optional[str] = None,
2419
+ context: Optional[ToolContext] = None,
2420
+ authorization=None,
2421
+ activity=None,
2422
+ ) -> ModelResponse:
2423
+ """
2424
+ Sends a follow-up message into an EXISTING conversation thread and
2425
+ runs the loop to completion on it. The resumed thread's full history
2426
+ (every prior user/assistant/tool turn, persisted by _run()'s
2427
+ always-persist behavior) is loaded by ConversationMemory and
2428
+ visible to the next call_model invocation.
2429
+
2430
+ ROADMAP §3's JSON-retry path uses this to retry a pass that
2431
+ returned malformed JSON: the corrective follow-up is sent into
2432
+ the same thread the failed pass used, so the model sees its own
2433
+ prior output in context and can correct it.
2434
+
2435
+ authorization (§25) is NOT optional in practice for that path. A
2436
+ retry is the same pass continuing, so it must run with the same
2437
+ authorization; omitting it would silently strip the pass's gated
2438
+ tools on precisely the attempt where the model is already
2439
+ struggling, and the only symptom would be a second malformed
2440
+ answer. The budget carries across, so retries spend from the same
2441
+ ceiling rather than resetting it.
2442
+ """
2443
+ memory = ConversationMemory(thread_id=thread_id)
2444
+ memory.add_user_message(message)
2445
+ response = run_to_completion(RunAgentLoop._run(
2446
+ memory, system_prompt, provider_name, model, context,
2447
+ max_steps, _resolve_spend_cap(max_total_tokens),
2448
+ temperature=temperature, effort=effort, activity=activity,
2449
+ **_authorization_kwargs(authorization),
2450
+ ))
2451
+ response.thread_id = thread_id
2452
+ return response
2453
+
2454
+ @staticmethod
2455
+ def _conversation_prompt(memory, system_prompt, *, model, provider_name,
2456
+ authorization=None,
2457
+ response_channel=None, granted_tools=None,
2458
+ active_skills=()) -> str:
2459
+ """The system prompt a conversation turn runs under -- ONE copy, for a
2460
+ turn the user started and a turn a background session's result
2461
+ started (ROADMAP_v3 §49), so a wake turn cannot run under a prompt
2462
+ missing the goal, the references or the checklist a user's turn has.
2463
+
2464
+ Moved out of run_agent_conversation unchanged; its comments there
2465
+ record why each tier is conditional or not.
2466
+ """
2467
+ # #68, and this branch is the one an unattended CLI run takes.
2468
+ _callable_only, _granted = advertisement_facts(
2469
+ authorization, response_channel, granted_tools)
2470
+ base = (system_prompt if system_prompt is not None
2471
+ else system_prompts.with_catalogs(
2472
+ with_persona(DEFAULT_SYSTEM_PROMPT, model, provider_name),
2473
+ list(active_skills or ()) or None,
2474
+ callable_only=_callable_only,
2475
+ granted=_granted))
2476
+ # A system_prompt handed in is an agent's, built by
2477
+ # system_prompt_for(); see session_tiers for why that decides the
2478
+ # memories. §54 AT7: internal compaction and review also use this
2479
+ # wrapper, and their source is not a person's file mention.
2480
+ return session_tiers(base, memory,
2481
+ agent_built=system_prompt is not None,
2482
+ mentions=memory.kind == THREAD_KIND_CHAT,
2483
+ active_skills=active_skills)
2484
+
2485
+ @staticmethod
2486
+ def wake_conversation(
2487
+ thread_id: UUID,
2488
+ text: str,
2489
+ harness: dict,
2490
+ model: str,
2491
+ provider_name: str = DEFAULT_PROVIDER,
2492
+ max_steps: int = config.MAX_ITERATIONS,
2493
+ max_total_tokens: Optional[int] = _SPEND_UNSET,
2494
+ temperature: Optional[float] = None,
2495
+ effort: Optional[str] = None,
2496
+ context: Optional[ToolContext] = None,
2497
+ system_prompt: Optional[str] = None,
2498
+ response_channel=None,
2499
+ granted_tools: Optional[set] = None,
2500
+ authorization=None,
2501
+ activity=None,
2502
+ cancel=None,
2503
+ observe=None,
2504
+ active_skills=(),
2505
+ ) -> ModelResponse:
2506
+ """A turn started by the HARNESS in an existing thread: a background
2507
+ session's result, delivered as a harness-written user row
2508
+ (ROADMAP_v3 §49, SS5). Drained, like the two wrappers above -- the
2509
+ subagent asleep in its spawn and the CLI's wait loop call it; the
2510
+ TUI builds its own generator, as it does for a user's turn.
2511
+
2512
+ `run_agent_conversation`'s arguments, less what only a NEW thread
2513
+ needs (kind, lineage) and plus the row: a wake runs with the same
2514
+ channel, grant, authorization, activity and CANCEL as the run whose
2515
+ session it reports, because it IS that run continuing. `cancel` was
2516
+ the one member of that list the signature omitted, and because
2517
+ `agents/subagent_tool.py` builds ONE `common` dict for the child's
2518
+ first turn and every wake after it -- deliberately, so the two
2519
+ cannot drift -- §61's CN7 adding `cancel` to that dict meant every
2520
+ subagent wake turn raised `TypeError` before anything else
2521
+ happened, 100% of the time, discarding a full agent run that had
2522
+ already been paid for in model calls (batch 133). `authorization` is
2523
+ what the CLI's chat loop carries -- without it a wake turn would
2524
+ run with no way to ask a human, so every gated call in it would be
2525
+ denied for a reason that is about the harness rather than the
2526
+ request, which is the silent-stripping failure §25 records.
2527
+
2528
+ `observe` is `run_agent_conversation`'s (§86): the CLI's wait loop
2529
+ prints a wake turn live exactly as it prints the user's own.
2530
+
2531
+ NOT a second `_run`. tests/test_grants.py walks this module for
2532
+ exactly one function by that name, and this is a wrapper over it.
2533
+ """
2534
+ if authorization is not None and granted_tools is not None:
2535
+ raise ValueError(
2536
+ "wake_conversation: pass authorization= or granted_tools=, "
2537
+ "not both -- they set the same underlying argument, so one "
2538
+ "would silently win."
2539
+ )
2540
+ memory = ConversationMemory(thread_id=thread_id)
2541
+ agent_activity.bind(activity, memory.thread_id)
2542
+ memory.add_harness_message(text, harness)
2543
+ prompt = RunAgentLoop._conversation_prompt(
2544
+ memory, system_prompt, model=model, provider_name=provider_name,
2545
+ authorization=authorization,
2546
+ response_channel=response_channel, granted_tools=granted_tools,
2547
+ active_skills=active_skills)
2548
+ auth_kwargs = (
2549
+ _authorization_kwargs(authorization) if authorization is not None
2550
+ else {"granted_tools": granted_tools}
2551
+ )
2552
+ # The explicit argument wins, and the key is popped unconditionally
2553
+ # -- run_agent_conversation's reasoning, unchanged.
2554
+ bundled_channel = auth_kwargs.pop("response_channel", None)
2555
+ response_channel = response_channel or bundled_channel
2556
+ response = run_to_completion(RunAgentLoop._run(
2557
+ memory, prompt,
2558
+ provider_name, model, context,
2559
+ max_steps, _resolve_spend_cap(max_total_tokens),
2560
+ temperature=temperature, effort=effort,
2561
+ response_channel=response_channel, activity=activity,
2562
+ cancel=cancel,
2563
+ **auth_kwargs,
2564
+ ), observe)
2565
+ response.thread_id = memory.thread_id
2566
+ return response