@yahyahammad/venastine 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (143) hide show
  1. package/.env.example +14 -0
  2. package/LICENSE +201 -0
  3. package/NOTICE +14 -0
  4. package/PRIVACY.md +66 -0
  5. package/README.md +878 -0
  6. package/SECURITY.md +88 -0
  7. package/THIRD_PARTY_NOTICES.md +100 -0
  8. package/agents/builtin/compactor.md +75 -0
  9. package/agents/builtin/explore.md +77 -0
  10. package/agents/builtin/grill-me.md +27 -0
  11. package/agents/builtin/initializer.md +94 -0
  12. package/agents/builtin/pipeline-reviewer.md +100 -0
  13. package/agents/builtin/plan.md +88 -0
  14. package/agents/builtin/review.md +74 -0
  15. package/agents/manager.py +195 -0
  16. package/agents/subagent_tool.py +215 -0
  17. package/agents/tui_commands.py +136 -0
  18. package/bin/venastine.mjs +382 -0
  19. package/config.py +1198 -0
  20. package/core/__init__.py +0 -0
  21. package/core/approval.py +115 -0
  22. package/core/client.py +1548 -0
  23. package/core/compaction.py +959 -0
  24. package/core/config_loader.py +1563 -0
  25. package/core/events.py +61 -0
  26. package/core/interaction.py +328 -0
  27. package/core/loop.py +1353 -0
  28. package/core/memory.py +370 -0
  29. package/core/model_windows.py +175 -0
  30. package/core/pipeline_models.py +176 -0
  31. package/core/reasoning/__init__.py +0 -0
  32. package/core/reasoning/authorization.py +130 -0
  33. package/core/reasoning/base.py +219 -0
  34. package/core/reasoning/confidence_scoring.py +468 -0
  35. package/core/reasoning/events.py +149 -0
  36. package/core/reasoning/json_retry.py +219 -0
  37. package/core/reasoning/orchestrator.py +1382 -0
  38. package/core/reasoning/output_writer.py +286 -0
  39. package/core/reasoning/payload_validation.py +398 -0
  40. package/core/reasoning/pipeline_storage.py +361 -0
  41. package/core/reasoning/review.py +615 -0
  42. package/core/reasoning/scholar.py +434 -0
  43. package/core/reasoning/source_corpus.py +327 -0
  44. package/core/reasoning/source_scoring.py +855 -0
  45. package/core/replay.py +167 -0
  46. package/core/session.py +153 -0
  47. package/core/workspace_trust.py +207 -0
  48. package/credentials.py +180 -0
  49. package/database.py +252 -0
  50. package/env_secrets.py +77 -0
  51. package/json_store.py +123 -0
  52. package/logging_setup.py +185 -0
  53. package/main.py +1959 -0
  54. package/mcp_client/__init__.py +15 -0
  55. package/mcp_client/client.py +499 -0
  56. package/mcp_client/config.py +379 -0
  57. package/mcp_client/registration.py +182 -0
  58. package/memories/manager.py +132 -0
  59. package/memories/tui_commands.py +232 -0
  60. package/package.json +73 -0
  61. package/project_init/config_files.py +278 -0
  62. package/project_init/doc_sets.py +330 -0
  63. package/project_init/generator.py +564 -0
  64. package/project_init/manifest.py +406 -0
  65. package/project_init/tui_commands.py +144 -0
  66. package/prompts/__init__.py +0 -0
  67. package/prompts/annotate.md +14 -0
  68. package/prompts/assumption_audit.md +27 -0
  69. package/prompts/claim_extraction.md +34 -0
  70. package/prompts/completeness.md +18 -0
  71. package/prompts/confidence_tiers.md +23 -0
  72. package/prompts/critic_pass.md +24 -0
  73. package/prompts/final_synthesis.md +13 -0
  74. package/prompts/initial_generation.md +14 -0
  75. package/prompts/preliminary_plan.md +23 -0
  76. package/prompts/revalidate.md +25 -0
  77. package/prompts/revise.md +15 -0
  78. package/prompts/source_grounding.md +66 -0
  79. package/prompts/system_prompts.py +262 -0
  80. package/prompts/universal_system_prompt +7 -0
  81. package/prompts/untrusted_content +1 -0
  82. package/providers.json.example +92 -0
  83. package/pyproject.toml +100 -0
  84. package/requirements.txt +72 -0
  85. package/safety/__init__.py +0 -0
  86. package/safety/policy_enforcement.py +682 -0
  87. package/security/__init__.py +0 -0
  88. package/security/capability.py +177 -0
  89. package/security/permissions.py +190 -0
  90. package/security/posture.py +302 -0
  91. package/security/protected_paths.py +309 -0
  92. package/security/sandbox.py +985 -0
  93. package/skills/builtin/crypto/cryptography-verification.md +66 -0
  94. package/skills/builtin/math/formal-specification.md +67 -0
  95. package/skills/builtin/math/numerical-methods.md +66 -0
  96. package/skills/builtin/math/proof-writing.md +61 -0
  97. package/skills/builtin/research/experiment-design.md +62 -0
  98. package/skills/builtin/research/literature-review.md +65 -0
  99. package/skills/builtin/research/reproducibility.md +55 -0
  100. package/skills/builtin/research/source-evaluation.md +70 -0
  101. package/skills/builtin/research/statistical-inference.md +63 -0
  102. package/skills/builtin/research/technical-writing.md +59 -0
  103. package/skills/builtin/security/cybersecurity-research.md +63 -0
  104. package/skills/builtin/software/code-review.md +61 -0
  105. package/skills/builtin/software/debugging.md +61 -0
  106. package/skills/builtin/software/test-design.md +67 -0
  107. package/skills/manager.py +138 -0
  108. package/skills/tui_commands.py +111 -0
  109. package/storage.py +1005 -0
  110. package/tools/base.py +305 -0
  111. package/tools/builtin/__init__.py +0 -0
  112. package/tools/builtin/_math_common.py +377 -0
  113. package/tools/builtin/_net_common.py +61 -0
  114. package/tools/builtin/arxiv.py +223 -0
  115. package/tools/builtin/ask_user.py +213 -0
  116. package/tools/builtin/discrete_math.py +134 -0
  117. package/tools/builtin/fetch_url.py +153 -0
  118. package/tools/builtin/file_ops.py +412 -0
  119. package/tools/builtin/geometry.py +148 -0
  120. package/tools/builtin/get_time.py +20 -0
  121. package/tools/builtin/linear_algebra.py +155 -0
  122. package/tools/builtin/load_skill.py +66 -0
  123. package/tools/builtin/logic.py +96 -0
  124. package/tools/builtin/pin.py +193 -0
  125. package/tools/builtin/probability_stats.py +228 -0
  126. package/tools/builtin/project_docs.py +405 -0
  127. package/tools/builtin/remember.py +158 -0
  128. package/tools/builtin/shell.py +461 -0
  129. package/tools/builtin/symbolic_math.py +119 -0
  130. package/tools/builtin/todo.py +147 -0
  131. package/tools/builtin/web_search.py +151 -0
  132. package/tools/context.py +136 -0
  133. package/tools/isolation.py +314 -0
  134. package/tools/registry.py +897 -0
  135. package/tui/app.py +3423 -0
  136. package/tui/app.tcss +458 -0
  137. package/tui/commands.py +61 -0
  138. package/tui/diffs.py +265 -0
  139. package/tui/preferences.py +182 -0
  140. package/tui/ravens.py +146 -0
  141. package/tui/screens.py +943 -0
  142. package/tui/themes.py +366 -0
  143. package/tui/widgets.py +1239 -0
package/tui/app.py ADDED
@@ -0,0 +1,3423 @@
1
+ """
2
+ tui/app.py
3
+
4
+ ROADMAP_v2 §16. The Textual app: streaming render, permission round-trip,
5
+ thread switching, slash commands, and the two ravens.
6
+
7
+ The shell hosts capabilities; it does not own them. D12 makes the CLI a
8
+ permanent fallback, so anything implemented here would be invisible to both
9
+ the CLI and the research pipeline -- which is why the question tool, todo
10
+ list, goal mode, and the rest land in their own sections (§18/§21/§22/§23)
11
+ and register into this shell rather than being written into it.
12
+
13
+ Two hard acceptance criteria live in this file:
14
+
15
+ §16 AC2 a permission prompt shown mid-loop resumes the SAME generator with
16
+ the user's answer. The worker thread blocks inside _run(), in this
17
+ app's `ask` on the response channel (§23); the UI thread shows the
18
+ modal and puts the decision on a queue that `ask` is waiting on.
19
+ Nothing re-enters or restarts the generator. Before §23 the chat
20
+ path did this differently from the research path -- the modal was
21
+ pushed from on_loop_event and the loop itself held the queue --
22
+ which was two mechanisms for one exchange.
23
+
24
+ §16 AC3 a tool call that raises must not kill the app. Textual's run_worker
25
+ defaults to exit_on_error=True, which would tear the whole TUI down
26
+ on a transient network error, so exit_on_error=False plus an
27
+ on_worker_state_changed handler are both required -- verified
28
+ against textual 1.0.0's actual signature, not assumed.
29
+ """
30
+
31
+ import json
32
+ import logging
33
+ import os
34
+ import queue
35
+ from pathlib import Path
36
+ from uuid import UUID
37
+
38
+ from textual.app import App, ComposeResult
39
+ from textual.containers import Horizontal, Vertical
40
+ from textual.css.query import NoMatches
41
+ from textual.message import Message
42
+ from textual.widgets import Footer, Header, Input
43
+ from textual.worker import Worker, WorkerState
44
+
45
+ import config
46
+ import storage
47
+ from agents.manager import manager
48
+ from agents.tui_commands import register_agent_commands
49
+ from skills.manager import manager as skills
50
+ from memories.tui_commands import register_memory_commands
51
+ from project_init.tui_commands import register_init_commands
52
+ from skills.tui_commands import register_skill_commands
53
+ from core import config_loader
54
+ from core.approval import RunAuthorization
55
+ from core.client import api_initialization, effort_levels_for_model
56
+ from core.loop import (
57
+ DEFAULT_PROVIDER, DEFAULT_SYSTEM_PROMPT, RunAgentLoop, advertisement_facts,
58
+ with_goal, with_refs, with_memories, with_todos,
59
+ )
60
+ from core.memory import ConversationMemory
61
+ from core.replay import replay_entries
62
+ # Module scope, not inside _cmd_research: _split_research_flags needs the
63
+ # sentinel too, and two shells comparing against two different object()
64
+ # instances would look identical and behave differently.
65
+ from core.reasoning.authorization import GRANT_PICKER, NOTHING_TO_GRANT
66
+ from prompts import system_prompts
67
+ from safety.policy_enforcement import (
68
+ redact_output_text, redact_secrets)
69
+
70
+ from tools.builtin import file_ops
71
+ from tools.registry import registry as tool_registry
72
+ from tui import diffs, preferences, ravens, themes
73
+ from tui.commands import SlashCommand, registry as commands
74
+ from tui.screens import (
75
+ ClaimsScreen, ConfirmScreen, GrantPickerScreen, PermissionScreen,
76
+ ProjectKindScreen, QuestionScreen, ReviewScreen, SubagentSignoffScreen,
77
+ ThreadPickerScreen,
78
+ )
79
+ from security import posture
80
+ from tui.widgets import (
81
+ CONVERSATION_ROLES, EffortRaven, GoalBanner, PostureBadge, RavenPanel,
82
+ ResearchProgress, ThinkingIndicator, TodoPanel, Transcript, UsageLine,
83
+ )
84
+
85
+ logger = logging.getLogger(__name__)
86
+
87
+
88
+ #: The two tools whose call the transcript shows as a diff (§41, X4).
89
+ #: `read` is deliberately absent: it changes nothing, so there is no diff
90
+ #: to draw, and its one-line `▸ read path` already says what happened.
91
+ DIFFED_TOOLS = ("write", "edit")
92
+
93
+ #: How much of a file the TUI will hold in order to diff it. NOT
94
+ #: `config.MAX_FILE_SIZE_BYTES`, which is 25 MB -- that is the bound on
95
+ #: what a tool may operate on, and this is the bound on what a transcript
96
+ #: block is worth. Past it the diff degrades rather than disappearing:
97
+ #: `write` renders as an all-new block, `edit` as its own old/new text
98
+ #: without line numbers.
99
+ DIFF_SNAPSHOT_MAX_BYTES = 512_000
100
+
101
+
102
+ class LoopEventMessage(Message):
103
+ """One LoopEvent, forwarded from the worker thread to the UI thread.
104
+
105
+ post_message is Textual's thread-safe hand-off; the worker never touches
106
+ a widget directly.
107
+ """
108
+
109
+ def __init__(self, event) -> None:
110
+ self.event = event
111
+ super().__init__()
112
+
113
+
114
+ class LogRecordMessage(Message):
115
+ """One WARNING+ log record, on its way to the transcript.
116
+
117
+ A Message rather than a direct widget write because emit() is called
118
+ from wherever the logging happened -- a research worker thread, the
119
+ MCP bridge thread -- and post_message is the thread-safe hand-off,
120
+ the same rule LoopEventMessage follows.
121
+ """
122
+
123
+ def __init__(self, text: str, role: str) -> None:
124
+ self.text = text
125
+ # A PALETTE ROLE, not a severity bool (batch 41, X2). It used to
126
+ # be `is_error`, and the receiving branch chose between
127
+ # write_error and write_system -- so every WARNING, the whole
128
+ # reason this handler exists, rendered as `system`: dim italic,
129
+ # indistinguishable from the harness announcing its own model
130
+ # name. `themes.role_styles` has carried a `warning` style since
131
+ # §26 and no transcript line had ever used it.
132
+ self.role = role
133
+ super().__init__()
134
+
135
+
136
+ class TranscriptLogHandler(logging.Handler):
137
+ """Routes WARNING+ into the transcript.
138
+
139
+ Exists because the TUI detaches the stderr handler (main.py): Textual
140
+ owns the terminal, so a log line written there lands on top of the
141
+ rendered screen, over the input bar and behind the panels, and
142
+ vanishes at the next repaint. Dropping stderr fixes the corruption
143
+ but would make every warning invisible until someone reads
144
+ logs/app.log -- which is nobody, mid-run. This is the other half.
145
+
146
+ WARNING and above only. INFO in a chat transcript is noise, and the
147
+ rotating file already has it at full detail with timestamps.
148
+
149
+ emit() must never raise: a logging handler that throws inside a
150
+ Textual message pump takes the app down over a diagnostic.
151
+ """
152
+
153
+ def __init__(self, app: "VenastineApp") -> None:
154
+ super().__init__(level=logging.WARNING)
155
+ self._app = app
156
+
157
+ def emit(self, record: logging.LogRecord) -> None:
158
+ try:
159
+ # getMessage(), not self.format(): the file handler owns
160
+ # timestamps and logger names, and repeating them eats a
161
+ # narrow transcript for no gain.
162
+ self._app.post_message(LogRecordMessage(
163
+ f"[{record.levelname.lower()}] {record.getMessage()}",
164
+ "error" if record.levelno >= logging.ERROR else "warning",
165
+ ))
166
+ except Exception: # noqa: BLE001 -- see the docstring
167
+ pass
168
+
169
+
170
+ class PipelineEventMessage(Message):
171
+ """One PipelineEvent, forwarded from the research worker to the UI
172
+ thread (ROADMAP_v2 §22).
173
+
174
+ A separate message from LoopEventMessage because they carry separate
175
+ types (§22 P1) and arrive from separate workers. Same post_message
176
+ hand-off: the worker never touches a widget directly.
177
+ """
178
+
179
+ def __init__(self, event) -> None:
180
+ self.event = event
181
+ super().__init__()
182
+
183
+
184
+ class ResearchFinished(Message):
185
+ """A /research run ended. Carries the PipelineRun, or the exception.
186
+
187
+ artifacts_ok (review §19-20 r4-3): the worker swallows artifact-write
188
+ failures so a disk error cannot discard a completed run -- but the
189
+ summary line must not then point the user at a 07_review.json that
190
+ was never written.
191
+
192
+ abandoned (#105): the user quit while the run was going. The worker
193
+ stopped forwarding at its next event and closed the generator, which
194
+ is §22's abandoned-generator path -- the record stays status='running'
195
+ with every checkpoint it took, honestly neither complete nor failed.
196
+ That is a third outcome, distinct from both: reporting it through the
197
+ error branch would call the user's own quit a pipeline failure."""
198
+
199
+ def __init__(self, run, error: BaseException | None,
200
+ artifacts_ok: bool = True, abandoned: bool = False) -> None:
201
+ self.run = run
202
+ self.error = error
203
+ self.artifacts_ok = artifacts_ok
204
+ self.abandoned = abandoned
205
+ super().__init__()
206
+
207
+
208
+ class TurnFinished(Message):
209
+ """The generator drained. Carries the exception if it raised, so the
210
+ UI thread can report it -- see the note in _consume about why this is
211
+ not left to Textual's worker-error path alone."""
212
+
213
+ def __init__(self, error: BaseException | None = None) -> None:
214
+ self.error = error
215
+ super().__init__()
216
+
217
+
218
+ class EmbedderProbeReady(Message):
219
+ """The `/embedder` validation probe finished, off the UI thread.
220
+
221
+ EffortLevelsReady's reason exactly: this is an HTTP call carrying the
222
+ SDK's default timeout, and running it inline freezes the app until it
223
+ returns. It carries the pair it was asked about rather than reading
224
+ the app's state on arrival, because the user may have typed another
225
+ command in the meantime and a probe must not report on a model nobody
226
+ asked for.
227
+ """
228
+
229
+ def __init__(self, provider_name, model, dimension, error):
230
+ super().__init__()
231
+ self.provider_name = provider_name
232
+ self.model = model
233
+ self.dimension = dimension
234
+ self.error = error
235
+
236
+
237
+ class EffortLevelsReady(Message):
238
+ """The effort-level lookup finished, off the UI thread.
239
+
240
+ For ANTHROPIC this is an HTTP call to the Models API carrying the
241
+ SDK's default 600s timeout. Running it inline froze the entire TUI --
242
+ no redraw, no input handling -- until it returned, and behind a
243
+ black-holing proxy for the full timeout: exactly the unresponsiveness
244
+ _cmd_research goes to worker lengths to avoid.
245
+
246
+ `validate_only` distinguishes the startup check (is the level we
247
+ restored from settings.json actually accepted?) from a user-issued
248
+ /effort, because the two report differently.
249
+ """
250
+
251
+ def __init__(self, levels, error, requested, validate_only=False):
252
+ self.levels = levels
253
+ self.error = error
254
+ self.requested = requested
255
+ self.validate_only = validate_only
256
+ super().__init__()
257
+
258
+
259
+ class OneShotFinished(Message):
260
+ """A one-shot turn (/grill-me) ran to completion in the CURRENT
261
+ thread via continue_conversation. Carries the final text, the
262
+ exception if it raised, and every notice the turn raised.
263
+
264
+ The notices are batch 16's #172 fix. continue_conversation drains
265
+ _run() through run_to_completion(), which discards every non-final
266
+ event -- so a compaction firing at this turn's boundary reached
267
+ NEITHER route: no event, and a response field nothing read. §21's
268
+ "no silent compaction, ever" failed on exactly one path, the one
269
+ command whose subject is the state of the thread. Carried here so
270
+ on_one_shot_finished can render them through the SAME branch the
271
+ streaming path uses."""
272
+
273
+ def __init__(self, text: str | None, error: BaseException | None = None,
274
+ notices=None):
275
+ self.text = text
276
+ self.error = error
277
+ self.notices = list(notices or [])
278
+ super().__init__()
279
+
280
+
281
+ class VenastineApp(App):
282
+ """Chat + research shell."""
283
+
284
+ CSS_PATH = "app.tcss"
285
+ TITLE = "Venastine Research Harness"
286
+
287
+ BINDINGS = [
288
+ ("ctrl+c", "quit", "Quit"),
289
+ ("ctrl+t", "pick_thread", "Threads"),
290
+ # §26. ctrl+l, NOT ctrl+k: Textual's Input binds ctrl+k to
291
+ # delete_right_all and the input holds focus almost always, so a
292
+ # ctrl+k binding here would be shadowed -- pressing it would
293
+ # silently delete the rest of the typed line instead. ctrl+l is
294
+ # bound by neither Input, App nor Footer on the pinned textual
295
+ # (D22: verified against the installed version, not assumed).
296
+ ("ctrl+l", "show_claims", "Claims"),
297
+ ]
298
+
299
+ # Set by exit(); consulted by the blocking ask paths (review §19-20
300
+ # r1-1: a walk that re-arms AFTER the one-shot channel release must
301
+ # not park a non-daemon worker on a queue nobody will ever answer),
302
+ # by _forwarding (#105), and by the timeout narration. A CLASS
303
+ # attribute so a bare-instance seam built with __new__ -- which three
304
+ # test files use for exactly this callback logic -- reads False
305
+ # instead of raising.
306
+ _shutting_down = False
307
+
308
+ def __init__(self, provider_name: str = DEFAULT_PROVIDER,
309
+ model: str = None, settings: dict | None = None,
310
+ cli_pinned: bool = False):
311
+ super().__init__()
312
+ self.provider_name = provider_name
313
+ self.model = model or config.MODEL_NAME
314
+ self._settings = settings or {}
315
+ # §43 (RM3). Whether --provider/--model named this launch's pair.
316
+ # main.resolve_runtime_defaults has already collapsed the flags
317
+ # into the resolved values above, so the app cannot tell by
318
+ # looking; a flag is an instruction for THIS launch and outranks
319
+ # anything remembered.
320
+ self._cli_pinned = cli_pinned
321
+ # Resolved here rather than in on_mount, unlike the theme: this
322
+ # one depends on nothing the mount does, and doing it now means
323
+ # the banner, refresh_status and the first turn cannot disagree
324
+ # about which pair the session is on. Sets _model_restored, which
325
+ # the banner reads so a restored pair is stated rather than
326
+ # guessed at (#138's rule).
327
+ self._model_restored = False
328
+ self.provider_name, self.model = self._startup_model()
329
+ # #138, corrected in batch 44. Launch-time provider findings for
330
+ # the pair this session will ACTUALLY use.
331
+ #
332
+ # COMPUTED HERE, AFTER _startup_model(), and not handed down from
333
+ # main(). main() resolves its pair before the app exists and froze
334
+ # the list at that moment, so a session that restored a remembered
335
+ # /model pair (§43, RM3) reported the CONFIG provider's missing key
336
+ # directly under a banner naming the restored one -- and with only
337
+ # the restored provider in providers.json it announced "Unknown
338
+ # provider: ANTHROPIC" and then ran perfectly well on OpenRouter.
339
+ # The order is what makes this the only correct site: the restore
340
+ # is early enough to fix the banner and far too late to fix a list
341
+ # main() has already built.
342
+ #
343
+ # A pre-mount print would vanish under Textual's screen and
344
+ # TranscriptLogHandler attaches only at mount, so on_mount is still
345
+ # the one route that reaches a user. Empty list is the healthy case
346
+ # and stays silent.
347
+ from credentials import provider_startup_issues
348
+
349
+ self._startup_warnings = provider_startup_issues(self.provider_name)
350
+ tui_settings = self._settings.get("tui", {})
351
+ # RAW, not themes.resolve()'d, because this is half the staleness
352
+ # key the remembered theme is recorded against (see
353
+ # _startup_theme). None -- "settings.json names no theme" -- has
354
+ # to stay distinguishable from an explicit "dark-plain", or
355
+ # ADDING tui.theme to a settings file would fail to re-assert
356
+ # itself against an older /theme.
357
+ self._settings_theme = tui_settings.get("theme")
358
+ self._theme_name = themes.resolve(self._settings_theme)
359
+ # Armed at the END of on_mount. App.theme is a Reactive with init
360
+ # on, so its watcher fires during mount as well as on a user's
361
+ # choice, and an unarmed flag is what keeps a launch that
362
+ # selected nothing from writing a store entry.
363
+ self._theme_persisting = False
364
+ # Whether the last remembered theme reached disk. Read by /theme
365
+ # so its confirmation cannot claim a save that failed.
366
+ self._theme_remembered = False
367
+ self._animations = tui_settings.get("animations", True)
368
+ # §38 (O6). Render a turn's reasoning inline, or collapse it to the
369
+ # animated one-line indicator. Defaulted HERE rather than in
370
+ # config.py, following `animations` immediately above: config.py
371
+ # holds no TUI values and is plain-values-only. /thinking flips it
372
+ # for the session and persists nothing, matching /effort.
373
+ self._show_thinking = tui_settings.get("show_thinking", True)
374
+ # Batch 25 (#139): tui.effort still wins INSIDE the TUI -- it
375
+ # predates the top-level key and changing its meaning would
376
+ # surprise existing configs -- then the universal key, then the
377
+ # config floor (now "high").
378
+ self.effort = (tui_settings.get("effort")
379
+ or self._settings.get("effort")
380
+ or config.DEFAULT_EFFORT)
381
+ # Whether a HUMAN named this level. The mount-time validation
382
+ # below exists as early feedback for a deliberate persisted
383
+ # choice (§16: tui.effort used to be trusted as-is and 400 every
384
+ # turn); a default-derived level is not that -- it validates at
385
+ # call time like every non-TUI caller, where effort_for drops an
386
+ # unsupported one with a naming warning. Probing a default here
387
+ # instead would fire the fallback WARNING on every launch for
388
+ # models without a known table, breaking #138's healthy-mount
389
+ # silence for users who never asked about effort at all.
390
+ self._effort_named = bool(tui_settings.get("effort")
391
+ or self._settings.get("effort"))
392
+ # §23 slice 2. Validated at load by config_loader against
393
+ # TODO_POSITIONS, so an unknown value never reaches here.
394
+ self._todo_position = tui_settings.get("todo_position", "side")
395
+
396
+ self._memory: ConversationMemory | None = None
397
+ self._permission_channel: queue.Queue | None = None
398
+ self._busy = False
399
+ # §18 session-scoped active agent (/agent switch). None = default
400
+ # harness. Applies to subsequent turns until switched or cleared.
401
+ self.active_agent = None
402
+ # §19 K5: active skills, session-scoped and unpersisted, matching
403
+ # /agent rather than /goal. A skill is a working-mode choice, not
404
+ # a property of the thread -- switching threads keeps them, and a
405
+ # new session starts clean. A LIST, not a set: activation order is
406
+ # the order the bodies are pinned in.
407
+ self.active_skills: list = []
408
+ # §26. What /claims reads. `_last_run` is the finished
409
+ # PipelineRun, which carries the claims with their full metadata;
410
+ # `_live_claims` is the partial picture assembled from events
411
+ # while a run is still going, so /claims answers during a run
412
+ # rather than only after. The last ANSWER is deliberately not
413
+ # here: /copy last reads Transcript.last_answer(), because a
414
+ # field beside the entry log is a second writer that has to be
415
+ # kept in step and was not.
416
+ self._last_run = None
417
+ self._live_claims: dict = {}
418
+ # Chat-mode tool_call id -> name, so a failed tool_result can be
419
+ # rendered as `✗ {tool} {error}` like research does (orchestrator
420
+ # keeps an identical map per pass). Cleared per turn in
421
+ # on_turn_finished; unbounded growth here would be a leak on a
422
+ # long-lived app.
423
+ self._tool_names: dict = {}
424
+ # §41 (X4). call id -> (name, params, pre-image) for a `write`
425
+ # or an `edit`, captured at tool_call_start because that is the
426
+ # last moment the file still holds what the call is about to
427
+ # replace. Cleared alongside _tool_names in both the places
428
+ # that clear it; a per-turn map that outlives its turn is a
429
+ # leak on an app that stays open for hours.
430
+ self._file_calls: dict = {}
431
+
432
+ # -- layout --------------------------------------------------------------
433
+
434
+ def compose(self) -> ComposeResult:
435
+ yield Header()
436
+ with Horizontal():
437
+ with Vertical(id="main"):
438
+ yield GoalBanner(id="goal-banner")
439
+ # §23 slice 2. Composed into one of three slots per
440
+ # `tui.todo_position`. The widget hides itself when the list
441
+ # is empty, so an unused slot costs nothing -- but the SLOT
442
+ # is chosen once at mount, because moving a mounted widget
443
+ # between containers to follow a setting nobody changed
444
+ # mid-session is machinery with no user.
445
+ if self._todo_position == "top":
446
+ yield TodoPanel(id="todo-panel")
447
+ yield Transcript(id="transcript")
448
+ # §38. Between the transcript and the prompt, so the
449
+ # collapsed thinking line reads as the bottom of the
450
+ # conversation. Hidden until a span starts, TodoPanel-style,
451
+ # so it costs no rows when show_thinking is on.
452
+ yield ThinkingIndicator(animations=self._animations,
453
+ id="thinking-indicator")
454
+ if self._todo_position == "bottom":
455
+ yield TodoPanel(id="todo-panel")
456
+ yield Input(placeholder="Message, or /help", id="prompt")
457
+ with Vertical(id="sidebar"):
458
+ yield RavenPanel(animations=self._animations, id="raven")
459
+ yield EffortRaven(id="effort-raven")
460
+ # §40. Above the ravens' siblings and always in view: a
461
+ # posture is not a transient, so it does not belong in the
462
+ # transcript where it would scroll away.
463
+ yield PostureBadge(posture.current().unsafe_reasons(),
464
+ id="posture-badge")
465
+ # #4: billed-since-resume and current context size, one
466
+ # line. Hidden until a turn produces figures.
467
+ yield UsageLine(id="usage-line")
468
+ if self._todo_position not in ("top", "bottom"):
469
+ yield TodoPanel(id="todo-panel")
470
+ yield ResearchProgress(id="research-progress")
471
+ yield Footer()
472
+
473
+ def on_mount(self) -> None:
474
+ # Attached before anything else can log. Removed in on_unmount --
475
+ # the handler holds a reference to this app, so leaving it on the
476
+ # root logger would keep a dead app alive and, in the test suite,
477
+ # stack one handler per App instance.
478
+ self._log_handler = TranscriptLogHandler(self)
479
+ logging.getLogger().addHandler(self._log_handler)
480
+
481
+ themes.register_all(self)
482
+ # AFTER register_all: _startup_theme consults available_themes,
483
+ # which is empty of this project's fourteen until they are
484
+ # registered. The flag arms AFTER the assignment, so mounting is
485
+ # not itself a selection.
486
+ self._theme_name = self._startup_theme()
487
+ self.theme = self._theme_name
488
+ self._theme_persisting = True
489
+ self.query_one("#effort-raven", EffortRaven).effort = self.effort
490
+ self.refresh_goal_banner()
491
+ self.refresh_todo_panel()
492
+ self.refresh_status()
493
+ self._write_session_banner()
494
+ # #138. Beside the status line it qualifies, before anything the
495
+ # user might type. write_error, matching /model: an unknown
496
+ # provider or a missing key is the same fact at both moments.
497
+ for warning in self._startup_warnings:
498
+ self._transcript.write_error(warning)
499
+ self._transcript.write_system("Type /help for commands.")
500
+ self.query_one("#prompt", Input).focus()
501
+ if self.effort and self._effort_named:
502
+ # A persisted effort level was trusted as-is and sent on every
503
+ # turn, unlike the sibling tui.theme three lines up which gets
504
+ # themes.resolve()'s fallback. A stale or mistyped level meant
505
+ # every turn failed with a provider 400 until the user
506
+ # happened to run /effort auto. Verified off the UI thread,
507
+ # so a slow or unreachable Models API delays the check, not
508
+ # the app. Gated on _effort_named: see its comment in
509
+ # __init__ for why a default-derived level does not probe.
510
+ self.start_effort_lookup(None, validate_only=True)
511
+
512
+ def _startup_theme(self) -> str:
513
+ """The theme to mount on: the last one selected, unless
514
+ settings.json has changed its mind since.
515
+
516
+ Three fallbacks to the configured theme, and the third is the one
517
+ that is easy to miss. App.theme VALIDATES against
518
+ available_themes and raises InvalidThemeError on a name it does
519
+ not know (verified against the pinned textual 1.0.0, per D22), so
520
+ a store written by a build with a theme this one has retired --
521
+ or by a future build with more of them -- would be a crash at
522
+ mount rather than a preference nobody could honour. themes.resolve
523
+ cannot cover it: its whitelist is this project's fourteen, and a
524
+ theme picked from ctrl+p's palette is one of Textual's own.
525
+
526
+ The staleness rule is the second branch. A remembered choice
527
+ outranks settings.json only while tui.theme still says what it
528
+ said when the choice was made; edit it (or add it, or remove it)
529
+ and the file re-asserts itself. Same shape as workspace_trust's
530
+ content hash and the MCP store's entry digest -- an edited config
531
+ is re-read rather than silently outranked forever, which is the
532
+ alternative that would make editing tui.theme a silent no-op.
533
+ """
534
+ remembered = preferences.load_theme()
535
+ if remembered is None:
536
+ return themes.resolve(self._settings_theme)
537
+ if remembered["settings_theme"] != self._settings_theme:
538
+ return themes.resolve(self._settings_theme)
539
+ if remembered["theme"] not in self.available_themes:
540
+ return themes.resolve(self._settings_theme)
541
+ return remembered["theme"]
542
+
543
+ def _startup_model(self) -> tuple[str, str]:
544
+ """The pair to mount on: the last one chosen with /model, unless
545
+ something better-informed has spoken since (§43, RM3).
546
+
547
+ _startup_theme's shape, one preference along, and for the same
548
+ reason batch 36 gave: the rule that nothing writes to
549
+ settings.json is about that FILE -- a project's copy beats the
550
+ user's (D29) and it is hand-authored -- not about whether a
551
+ choice may be remembered. Writing default_model into it would be
552
+ worse than merely rude here: the project copy lives inside D17's
553
+ trust content hash, so a session rewriting it would re-trigger
554
+ the trust prompt at the next launch.
555
+
556
+ Four fallbacks to the resolved pair, and the first is this
557
+ preference's own:
558
+
559
+ - a --provider/--model flag named the pair for this launch. It
560
+ is an instruction about now, and it outranks a memory of
561
+ then;
562
+ - nothing is remembered;
563
+ - the staleness key differs, i.e. default_provider or
564
+ default_model in settings.json no longer says what it said
565
+ when the choice was made. Edit either, add either, or remove
566
+ either and the file re-asserts itself -- which is why the
567
+ recorded values are the RAW ones and None stays
568
+ distinguishable from a string;
569
+ - the remembered provider is no longer configured. That is
570
+ /model's own unknown-provider refusal applied at mount:
571
+ api_initialization would raise on the first turn instead, a
572
+ long way from the providers.json edit that caused it.
573
+ load_provider_data() returns {} for a missing file, so a
574
+ fresh clone takes this branch rather than failing.
575
+
576
+ The pair is restored WHOLE or not at all. A model name is
577
+ meaningless against the wrong provider, so mixing a remembered
578
+ model with a configured provider would be a configuration nobody
579
+ chose.
580
+ """
581
+ if self._cli_pinned:
582
+ return self.provider_name, self.model
583
+ remembered = preferences.load_model()
584
+ if remembered is None:
585
+ return self.provider_name, self.model
586
+ if (remembered["settings_provider"] != self._settings.get("default_provider")
587
+ or remembered["settings_model"] != self._settings.get("default_model")):
588
+ return self.provider_name, self.model
589
+ from credentials import load_provider_data
590
+
591
+ if remembered["provider"] not in load_provider_data():
592
+ logger.warning(
593
+ "Remembered provider %r is not in providers.json; starting on "
594
+ "%s | %s instead.", remembered["provider"],
595
+ self.provider_name, self.model)
596
+ return self.provider_name, self.model
597
+ self._model_restored = True
598
+ return remembered["provider"], remembered["model"]
599
+
600
+ def watch_theme(self, theme: str) -> None:
601
+ """Remember every theme change, whatever route made it.
602
+
603
+ Textual's reactive machinery calls _watch_theme (its own restyle)
604
+ and THEN a subclass's watch_theme, so this covers /theme and
605
+ ctrl+p's command palette alike -- the palette is enabled here and
606
+ offers Textual's built-ins beside this project's fourteen, and a
607
+ selection it made that vanished at the next launch would be
608
+ exactly the silent no-op this feature exists to remove. Hooking
609
+ _cmd_theme instead would have missed it.
610
+
611
+ One parameter, so Textual passes the NEW value (invoke_watcher
612
+ dispatches on parameter count). Nothing is written before
613
+ on_mount arms the flag: App.theme is a Reactive with init on, so
614
+ without that guard every launch would record the theme it merely
615
+ restored, and a default would become indistinguishable from a
616
+ choice.
617
+ """
618
+ if not self._theme_persisting:
619
+ return
620
+ self._theme_remembered = preferences.remember_theme(
621
+ theme, self._settings_theme)
622
+
623
+ def on_unmount(self) -> None:
624
+ handler = getattr(self, "_log_handler", None)
625
+ if handler is not None:
626
+ logging.getLogger().removeHandler(handler)
627
+ self._log_handler = None
628
+
629
+ def on_log_record_message(self, message: LogRecordMessage) -> None:
630
+ """Render a routed log record in the role the handler chose.
631
+
632
+ Never re-enters the logger: Transcript.write* does no logging, so
633
+ a handler feeding a widget that logs cannot loop here.
634
+
635
+ `write_role("error", ...)` is byte-identical to `write_error()` --
636
+ both flush the stream and fall to _render_entry's else branch --
637
+ so routing both levels through one call costs the error path
638
+ nothing and gives the warning path the style it never had.
639
+ """
640
+ self._transcript.write_role(message.role, message.text)
641
+
642
+ def _write_session_banner(self) -> None:
643
+ """What this session is configured as, as one line (§43, RM2).
644
+
645
+ Written at mount and again by /new, which redraws the window --
646
+ so a thread started after a /model switch says which pair it is
647
+ actually on rather than the one the app launched with. One
648
+ helper because two copies of a status line are two copies that
649
+ can disagree, which is the shape §26 spent a decision removing
650
+ from the trace.
651
+
652
+ "(remembered)" marks a pair restored from the preference store
653
+ rather than resolved from settings.json or config.py (§43, RM3).
654
+ #138's rule: a launch should not have to be guessed at, and a
655
+ session silently coming up on a model no config file names is
656
+ exactly the confusion this feature would otherwise trade for the
657
+ one it fixes. It is the counterpart of /theme's "Remembered for
658
+ the next launch."
659
+ """
660
+ remembered = " (remembered)" if self._model_restored else ""
661
+ self._transcript.write_system(
662
+ f"{self.provider_name} | {self.model}{remembered} "
663
+ f"| theme {self._theme_name}"
664
+ )
665
+
666
+ def refresh_status(self) -> None:
667
+ """Keep the header showing which provider/model turns will use.
668
+
669
+ The mount banner scrolls away, so after a /model switch there was
670
+ nothing on screen saying what the next turn would actually call --
671
+ and getting that wrong is the difference between a working turn
672
+ and an auth error.
673
+ """
674
+ self.sub_title = f"{self.provider_name} | {self.model}"
675
+
676
+ def start_effort_lookup(self, requested, validate_only=False) -> None:
677
+ """Fetch this model's accepted effort levels in a worker."""
678
+ def work() -> None:
679
+ try:
680
+ client = api_initialization(self.provider_name)
681
+ levels = effort_levels_for_model(
682
+ client, self.provider_name, self.model)
683
+ self.post_message(
684
+ EffortLevelsReady(levels, None, requested, validate_only))
685
+ except Exception as e: # noqa: BLE001 - reported to the user
686
+ self.post_message(
687
+ EffortLevelsReady(None, e, requested, validate_only))
688
+
689
+ self.run_worker(work, thread=True, exit_on_error=False,
690
+ name="effort-levels")
691
+
692
+ def start_embedder_probe(self, provider_name: str, model: str) -> None:
693
+ """Embed one short string, to find out whether this pair works.
694
+
695
+ A MEASUREMENT RATHER THAN A TABLE (§45, SQ7). Whether a provider
696
+ has an embeddings endpoint, whether this slug is an embedding
697
+ model rather than a chat one, and whether the key is accepted are
698
+ three questions one call answers -- and the alternative is a
699
+ static capability list that goes stale as providers ship
700
+ endpoints, whose wrong answers surface three passes into a
701
+ research run.
702
+ """
703
+ def work() -> None:
704
+ try:
705
+ from core.client import embed_texts
706
+
707
+ result = embed_texts(provider_name, model, ["probe"])
708
+ self.post_message(EmbedderProbeReady(
709
+ provider_name, model, result.dimension, None))
710
+ except Exception as e: # noqa: BLE001 - reported to the user
711
+ self.post_message(
712
+ EmbedderProbeReady(provider_name, model, None, e))
713
+
714
+ self.run_worker(work, thread=True, exit_on_error=False,
715
+ name="embedder-probe")
716
+
717
+ def on_embedder_probe_ready(self, message: EmbedderProbeReady) -> None:
718
+ """REMEMBER ONLY WHAT WORKED. A pair stored before the probe
719
+ answers would survive a restart as a setting that fails on every
720
+ research run, which is the shape /model's unknown-provider refusal
721
+ already exists to prevent one door along."""
722
+ from core import pipeline_models
723
+
724
+ if message.error is not None:
725
+ self._transcript.write_error(
726
+ f"{message.provider_name} | {message.model} cannot be used "
727
+ f"as an embedder: {message.error}")
728
+ return
729
+
730
+ self._transcript.write_system(
731
+ f"Embedder set to {message.provider_name} | {message.model} "
732
+ f"({message.dimension}-dimensional). Source similarity becomes "
733
+ f"a cosine from the next research run.")
734
+ if pipeline_models.remember(
735
+ "embedder", message.provider_name, message.model):
736
+ self._transcript.write_system("Remembered for the next launch.")
737
+
738
+ def on_effort_levels_ready(self, message: EffortLevelsReady) -> None:
739
+ if message.validate_only:
740
+ self._apply_effort_validation(message)
741
+ return
742
+ self._apply_effort_command(message)
743
+
744
+ def _apply_effort_validation(self, message: EffortLevelsReady) -> None:
745
+ if message.error is not None:
746
+ # Keep the level rather than silently downgrading a deliberate
747
+ # choice on a transient failure; a genuinely wrong one still
748
+ # fails at the provider, which is the honest outcome.
749
+ self._transcript.write_system(
750
+ f"Could not verify effort {self.effort!r} ({message.error}); "
751
+ "keeping it.")
752
+ return
753
+ if self.effort in message.levels:
754
+ return
755
+ if message.levels:
756
+ detail = f"{self.model} accepts {', '.join(message.levels)}"
757
+ else:
758
+ detail = f"{self.model} exposes no reasoning-effort control"
759
+ self._transcript.write_error(
760
+ f"Persisted effort {self.effort!r} is not usable: {detail}. "
761
+ "Falling back to auto.")
762
+ self.effort = None
763
+ self.query_one("#effort-raven", EffortRaven).effort = None
764
+
765
+ def _apply_effort_command(self, message: EffortLevelsReady) -> None:
766
+ if message.error is not None:
767
+ self._transcript.write_error(
768
+ f"Could not read effort levels: {message.error}")
769
+ return
770
+ levels, args = message.levels, message.requested
771
+ if not levels:
772
+ self._transcript.write_system(
773
+ f"{self.model} exposes no reasoning-effort control.")
774
+ return
775
+ if not args:
776
+ self._transcript.write_system(
777
+ f"Effort: {self.effort or 'auto'}. "
778
+ f"Available: {', '.join(levels)} (or 'auto').")
779
+ return
780
+ if args == "auto":
781
+ self.effort = None
782
+ elif args in levels:
783
+ self.effort = args
784
+ else:
785
+ self._transcript.write_error(
786
+ f"{self.model} does not support effort {args!r}. "
787
+ f"Available: {', '.join(levels)}.")
788
+ return
789
+ self.query_one("#effort-raven", EffortRaven).effort = self.effort
790
+ self._transcript.write_system(f"Effort set to {self.effort or 'auto'}.")
791
+
792
+ @property
793
+ def memory(self) -> ConversationMemory:
794
+ """The active thread, created on first USE rather than at mount.
795
+
796
+ on_mount used to build one immediately, and constructing a
797
+ ConversationMemory persists a ConversationThread row -- so
798
+ launching the TUI, reading /help and quitting left a phantom
799
+ empty thread behind, and the Ctrl+T picker filled with rows
800
+ carrying nothing but an id and a timestamp, indistinguishable
801
+ from real ones. The CLI has always created memory only when a
802
+ turn actually happens.
803
+ """
804
+ if self._memory is None:
805
+ self._memory = ConversationMemory()
806
+ return self._memory
807
+
808
+ @memory.setter
809
+ def memory(self, value) -> None:
810
+ self._memory = value
811
+ # #4: per-thread state follows the thread (§27's lesson). A new or
812
+ # resumed thread starts session billing at zero; the line hides
813
+ # until that thread's first turn rather than keeping the previous
814
+ # thread's totals. Pre-mount setter calls have no widget yet.
815
+ try:
816
+ self.query_one("#usage-line", UsageLine)._reset()
817
+ except Exception: # noqa: BLE001 -- not mounted; nothing to reset
818
+ pass
819
+
820
+ def refresh_goal_banner(self) -> None:
821
+ # self._memory, NOT self.memory: reading the banner must not be
822
+ # what creates the thread this property exists to defer.
823
+ goal = self._memory.extra.get("goal") if self._memory else None
824
+ self.query_one("#goal-banner", GoalBanner).goal = goal
825
+
826
+ def refresh_todo_panel(self) -> None:
827
+ """Re-read the checklist from thread state and repaint.
828
+
829
+ Called from the `todo_changed` notice (§23 AC4: from an event, never
830
+ polled), and on mount/resume so a resumed thread shows the list it
831
+ already had -- §27's lesson that per-thread state must follow the
832
+ thread, or the panel keeps showing the previous one's.
833
+
834
+ self._memory, not self.memory, for refresh_goal_banner's reason:
835
+ painting a panel must not be what creates a thread.
836
+ """
837
+ todos = self._memory.extra.get("todos") if self._memory else None
838
+ self.query_one("#todo-panel", TodoPanel).todos = todos
839
+
840
+ @property
841
+ def _transcript(self) -> Transcript:
842
+ return self.query_one("#transcript", Transcript)
843
+
844
+ @property
845
+ def _raven(self) -> RavenPanel:
846
+ return self.query_one("#raven", RavenPanel)
847
+
848
+ @property
849
+ def _research_progress(self) -> ResearchProgress:
850
+ return self.query_one("#research-progress", ResearchProgress)
851
+
852
+ @property
853
+ def _thinking_indicator(self) -> ThinkingIndicator:
854
+ return self.query_one("#thinking-indicator", ThinkingIndicator)
855
+
856
+ def _end_thinking(self) -> None:
857
+ """Close a thinking span, whichever form it is being shown in
858
+ (§38). Called by every non-thinking event, so both forms end at
859
+ the same moment and a flipped tui.show_thinking cannot leave one
860
+ of them running.
861
+
862
+ Best-effort, #104's rule: a modal on top means query_one searches
863
+ the ACTIVE screen and finds neither widget (§27), and an
864
+ undrawable indicator must not be the reason an event handler
865
+ dies mid-turn.
866
+ """
867
+ try:
868
+ self._transcript.end_thinking()
869
+ self._thinking_indicator.stop()
870
+ except NoMatches:
871
+ pass
872
+
873
+ # -- input ---------------------------------------------------------------
874
+
875
+ def on_input_submitted(self, event: Input.Submitted) -> None:
876
+ text = event.value.strip()
877
+ if not text:
878
+ event.input.value = ""
879
+ return
880
+ # Clear AFTER the busy check, not before. /research holds _busy
881
+ # for a whole ten-pass pipeline, so a follow-up typed during one
882
+ # was wiped and had to be retyped from memory.
883
+ if not text.startswith("/") and self._busy:
884
+ self._transcript.write_error("Still working — wait for this turn to finish.")
885
+ return
886
+ event.input.value = ""
887
+ if text.startswith("/"):
888
+ if not commands.dispatch(self, text):
889
+ name = text[1:].split(" ")[0]
890
+ self._transcript.write_error(
891
+ f"Unknown command /{name}. Try /help."
892
+ )
893
+ return
894
+ self.run_agent_turn(text)
895
+
896
+ # -- the turn ------------------------------------------------------------
897
+
898
+ def run_agent_turn(self, user_input: str) -> None:
899
+ self._busy = True
900
+ self._transcript.write_user(user_input)
901
+ # #104. FIRST touch of `self.memory` on the UI thread, so it is
902
+ # also where the lazy ConversationMemory() gets constructed and
903
+ # its ConversationThread row written. Both the construction and
904
+ # the append are storage, and an uncaught failure here reaches the
905
+ # message pump rather than failing the turn.
906
+ #
907
+ # `_busy` is reset on the way out: it was set two lines up, and
908
+ # leaving it True on a failure wedges the shell into refusing
909
+ # every later turn with "Still working" for a turn that never
910
+ # started.
911
+ try:
912
+ self.memory.add_user_message(user_input)
913
+ except Exception as e: # noqa: BLE001
914
+ self._busy = False
915
+ self._transcript.write_error(
916
+ f"Could not start the turn: {e}")
917
+ return
918
+
919
+ # §18: a session-scoped active agent supplies the system prompt,
920
+ # the ToolContext, and model/provider/max_steps overrides. With
921
+ # none active this is the default harness run (base + catalogs).
922
+ if self.active_agent is not None:
923
+ agent = self.active_agent
924
+ context = manager.active_context(agent)
925
+ base_prompt = manager.system_prompt_for(
926
+ agent, DEFAULT_SYSTEM_PROMPT, self.active_skills,
927
+ context=context)
928
+ model = agent.model or self.model
929
+ provider = agent.provider or self.provider_name
930
+ max_steps = agent.max_steps or config.MAX_ITERATIONS
931
+ else:
932
+ context = None
933
+ base_prompt = system_prompts.with_catalogs(
934
+ DEFAULT_SYSTEM_PROMPT, self.active_skills)
935
+ model = self.model
936
+ provider = self.provider_name
937
+ max_steps = config.MAX_ITERATIONS
938
+ prompt = with_goal(base_prompt, self.memory)
939
+ # §21b (M13). Only for a plain turn -- an active agent already got
940
+ # its memories inside system_prompt_for(), and appending here too
941
+ # would duplicate them.
942
+ if self.active_agent is None:
943
+ prompt = with_memories(prompt)
944
+ # §21c. Unconditional, for the reason the loop's copy of this line
945
+ # gives: a reference is thread state, not an agent's opt-in.
946
+ prompt = with_refs(prompt, self.memory)
947
+ # §23 slice 2. Unconditional too: a checklist is thread state.
948
+ prompt = with_todos(prompt, self.memory)
949
+ # §19 K1/K6: active skill bodies are pinned HERE, beside with_goal,
950
+ # and deliberately NOT inside with_catalogs -- that function feeds
951
+ # pass_prompt(), so pinning there would inject a skill activated in
952
+ # this chat session into all ten passes of a research run.
953
+ #
954
+ # Last in the prompt on purpose: an activated skill is the most
955
+ # specific instruction the user has given, and should read as
956
+ # governing what precedes it.
957
+ fragment = skills.prompt_fragment(self.active_skills)
958
+ if fragment:
959
+ prompt = f"{prompt}\n\n{fragment}"
960
+
961
+ # §23: the SAME channel the research path uses. The chat turn used
962
+ # to hand the loop a bare queue and push its modal from
963
+ # on_loop_event, which meant two code paths for one exchange -- and
964
+ # the event-driven one could not carry a question with more than
965
+ # two answers. The worker now blocks inside the channel's `ask`,
966
+ # exactly as an attended research pass already did.
967
+ generator = RunAgentLoop._run(
968
+ self.memory,
969
+ prompt,
970
+ provider,
971
+ model,
972
+ context,
973
+ max_steps,
974
+ # #4: the TUI turn runs on the configured spend cap, same as
975
+ # every other path. _SPEND_UNSET would resolve it too; passing
976
+ # the resolved value explicitly keeps this direct-_run call
977
+ # honest about what it is doing.
978
+ config_loader.spend_cap(),
979
+ effort=self.effort,
980
+ response_channel=self.response_channel(),
981
+ )
982
+ self.run_worker(
983
+ lambda: self._consume(generator),
984
+ thread=True,
985
+ exit_on_error=False, # §16 AC3 — see the module docstring
986
+ name="agent-turn",
987
+ )
988
+
989
+ def _consume(self, generator) -> None:
990
+ """Drain the generator on the worker thread, forwarding every event.
991
+
992
+ The try/except is not redundant with on_worker_state_changed: an
993
+ exception here leaves the UI mid-turn (busy flag set, raven stuck on
994
+ whatever it was doing), and only this frame knows the turn is over.
995
+ The handler below still fires and is what surfaces the message.
996
+ """
997
+ error = None
998
+ try:
999
+ for event in generator:
1000
+ self.post_message(LoopEventMessage(event))
1001
+ except BaseException as e: # noqa: BLE001 — re-raised below
1002
+ error = e
1003
+ finally:
1004
+ self.post_message(TurnFinished(error))
1005
+ if error is not None:
1006
+ raise error
1007
+
1008
+ def run_one_shot(self, agent, message: str) -> None:
1009
+ """Run ONE turn in the CURRENT thread under a different agent's
1010
+ system prompt (§18 /grill-me: the agent sees the live history
1011
+ directly, no digest loss). Uses continue_conversation so the
1012
+ exchange persists into the thread; the live memory is reloaded
1013
+ when the result lands so the next streaming turn sees it too.
1014
+
1015
+ This method owns the WHOLE assembly (#109/#170), because prompt
1016
+ facts and run facts must come from one answer: a system_prompt
1017
+ built by the caller would have to guess whether the turn can
1018
+ ask, and #170 is exactly what that guessing produced — a prompt
1019
+ advertising tools a headless run could not call, beside a schema
1020
+ list that knew better. The channel exists before any of the
1021
+ prompt is built, and every layer after reads it.
1022
+ """
1023
+ self._busy = True
1024
+ self._raven.state = ravens.THINKING
1025
+ # #104, same shape as run_agent_turn: this can be the first touch
1026
+ # of `self.memory`, and it runs on the UI thread.
1027
+ try:
1028
+ thread_id = self.memory.thread_id
1029
+ except Exception as e: # noqa: BLE001
1030
+ self._busy = False
1031
+ self._raven.state = ravens.IDLE
1032
+ self._transcript.write_error(f"Could not open the thread: {e}")
1033
+ return
1034
+ model, provider = self.model, self.provider_name
1035
+ # §23/§25. Attended, like every other TUI turn (#170 D1): the
1036
+ # human is at the keyboard, so gated tools stay advertised AND
1037
+ # promptable instead of silently vanishing for this one command.
1038
+ channel = self.response_channel()
1039
+ authorization = RunAuthorization(provider=channel)
1040
+ callable_only, granted = advertisement_facts(
1041
+ response_channel=channel)
1042
+ base_prompt = manager.system_prompt_for(
1043
+ agent, DEFAULT_SYSTEM_PROMPT, self.active_skills,
1044
+ callable_only=callable_only, granted=granted)
1045
+ # §18/§21c/§23. Unconditional, for with_refs' documented reason:
1046
+ # goal, references and checklist are thread state, not an agent's
1047
+ # opt-in. Deliberately NO with_memories — system_prompt_for has
1048
+ # already appended this agent's memories (M13), and a second call
1049
+ # would duplicate them.
1050
+ prompt = with_goal(base_prompt, self.memory)
1051
+ prompt = with_refs(prompt, self.memory)
1052
+ prompt = with_todos(prompt, self.memory)
1053
+ # K1 holds for one-shot turns too (review §19-20 f22 decision):
1054
+ # an activated skill governs the /grill-me turn in the same
1055
+ # thread, mirroring run_agent_turn's pinning.
1056
+ fragment = skills.prompt_fragment(self.active_skills)
1057
+ if fragment:
1058
+ prompt = f"{prompt}\n\n{fragment}"
1059
+
1060
+ def work() -> None:
1061
+ error = None
1062
+ text = None
1063
+ notices = []
1064
+ try:
1065
+ response = RunAgentLoop.continue_conversation(
1066
+ thread_id=thread_id,
1067
+ message=message,
1068
+ system_prompt=prompt,
1069
+ model=model,
1070
+ provider_name=provider,
1071
+ effort=self.effort,
1072
+ authorization=authorization,
1073
+ )
1074
+ text = response.text
1075
+ notices = list(getattr(response, "notices", ()) or ())
1076
+ except BaseException as e: # noqa: BLE001 — reported, re-raised
1077
+ error = e
1078
+ self.post_message(OneShotFinished(text, error, notices))
1079
+ if error is not None:
1080
+ raise error
1081
+
1082
+ self.run_worker(
1083
+ work, thread=True, exit_on_error=False, name="one-shot",
1084
+ )
1085
+
1086
+ def _render_notice(self, notice: dict) -> None:
1087
+ """ONE renderer for a notice dict, on every route that has one.
1088
+
1089
+ Extracted from on_loop_event_message so the one-shot path (#172)
1090
+ drives the same branch instead of growing a second opinion about
1091
+ what a compaction_blocked looks like. The todo panel re-reads
1092
+ thread state here -- the event says when, the thread says what --
1093
+ which is also why callers must have reloaded the memory BEFORE
1094
+ rendering."""
1095
+ transcript = self._transcript
1096
+ if notice["kind"] == "todo_changed":
1097
+ # §23 slice 2 (AC4). PANEL ONLY, no transcript line: the
1098
+ # list changes several times in a turn, and in an
1099
+ # append-only transcript that is a column of near-identical
1100
+ # lines -- §26 made the same call for `pass_activity`.
1101
+ self.refresh_todo_panel()
1102
+ elif notice["kind"] in ("compaction_failed",
1103
+ "compaction_blocked"):
1104
+ transcript.write_error(f"— {notice['text']} —")
1105
+ else:
1106
+ transcript.write_system(f"— {notice['text']} —")
1107
+
1108
+ def on_one_shot_finished(self, message: OneShotFinished) -> None:
1109
+ self._busy = False
1110
+ self._raven.resume_animation()
1111
+ self._raven.state = ravens.IDLE
1112
+ if message.error is not None:
1113
+ self._transcript.write_error(f"[error: {message.error}]")
1114
+ return
1115
+ # Reload so the grill exchange is in the live history for the
1116
+ # next streaming turn.
1117
+ #
1118
+ # #104. A message handler, so it runs on the UI thread. The
1119
+ # failure this contains is not fatal to the session in any sense:
1120
+ # the exchange is already PERSISTED (continue_conversation wrote
1121
+ # it), so all a failed reload costs is that the next streaming
1122
+ # turn will not see it in live history. Reported, not raised.
1123
+ try:
1124
+ self.memory = ConversationMemory(thread_id=self.memory.thread_id)
1125
+ except Exception as e: # noqa: BLE001
1126
+ self._transcript.write_error(
1127
+ f"Could not reload the thread after the one-shot: {e}. The "
1128
+ f"exchange is saved; this session's next turn may not see "
1129
+ f"it in context.")
1130
+ # BEFORE the answer, because that is when they happened -- and
1131
+ # after the reload above, so refresh_todo_panel reads the state
1132
+ # the turn actually left behind (#172).
1133
+ for notice in message.notices:
1134
+ self._render_notice(notice)
1135
+ # write_answer, not write(): a one-shot answer is a model answer,
1136
+ # and rendering it as a bare row left it unlabelled, uncoloured,
1137
+ # outside the entry log and therefore invisible to /copy. That is
1138
+ # also all this path has to do for /copy last now -- the entry IS
1139
+ # the record.
1140
+ self._transcript.write_answer(message.text or "")
1141
+
1142
+ def refresh_usage_line(self) -> None:
1143
+ """#4: repaint the sidebar usage line from thread state.
1144
+
1145
+ The same split as refresh_todo_panel -- the event says when, the
1146
+ memory says what. on_loop_event_message calls this per event;
1147
+ update_usage's change-guard makes per-token-delta calls nearly
1148
+ free, since both figures only move at step boundaries.
1149
+ """
1150
+ if self._memory is None:
1151
+ return
1152
+ # The threshold this thread is actually measured against, resolved
1153
+ # through the same function _maybe_compact uses so the denominator
1154
+ # can never disagree with the number that fires. working_set by
1155
+ # construction: this line renders the CHAT thread the user is
1156
+ # looking at, and a chat thread is never in backstop mode.
1157
+ # Contained -- a usage line must not be the reason a turn dies.
1158
+ from core import compaction, session
1159
+
1160
+ try:
1161
+ _, ceiling = compaction.thresholds(
1162
+ self.model, provider_name=self.provider_name)
1163
+ except Exception: # noqa: BLE001 -- see above
1164
+ ceiling = 0
1165
+ overridden = session.trigger_for(self.provider_name, self.model) is not None
1166
+ self.query_one("#usage-line", UsageLine).update_usage(
1167
+ self._memory.billed_tokens, self._memory.last_input_tokens,
1168
+ ceiling, overridden)
1169
+
1170
+ def restyle_sidebar(self) -> None:
1171
+ """Re-render the Rich-styled sidebar widgets after a /theme
1172
+ (#183).
1173
+
1174
+ tcss-styled surfaces (the ravens, borders, the prompt) restyle
1175
+ the moment app.theme changes; the Rich-rendering ones do not --
1176
+ Transcript has rerender() for the same reason, and these are the
1177
+ sidebar's equivalent. UsageLine is deliberately absent: its only
1178
+ role is `system` -- dim italic, colourless -- so there is nothing
1179
+ to restyle, and a guard-skipped update would be machinery
1180
+ pretending to work.
1181
+ """
1182
+ self.refresh_goal_banner()
1183
+ self.refresh_todo_panel()
1184
+ self.query_one("#research-progress", ResearchProgress).restyle()
1185
+
1186
+ def on_loop_event_message(self, message: LoopEventMessage) -> None:
1187
+ event = message.event
1188
+ transcript = self._transcript
1189
+
1190
+ self.refresh_usage_line()
1191
+
1192
+ if event.thinking_delta:
1193
+ # §38. Same mascot handling as a token delta -- reasoning is
1194
+ # streaming output too, and the redraw loop costs the same.
1195
+ self._raven.pause_animation()
1196
+ self._raven.state = ravens.THINKING
1197
+ if self._show_thinking:
1198
+ transcript.thinking_delta(event.thinking_delta)
1199
+ else:
1200
+ self._thinking_indicator.start()
1201
+
1202
+ if event.token_delta:
1203
+ # Pause the mascot while tokens stream: a redraw loop competing
1204
+ # with deltas is the one place animation costs responsiveness.
1205
+ self._end_thinking()
1206
+ self._raven.pause_animation()
1207
+ self._raven.state = ravens.THINKING
1208
+ transcript.stream_delta(event.token_delta)
1209
+
1210
+ if event.tool_call_start:
1211
+ self._end_thinking()
1212
+ transcript.flush_stream()
1213
+ self._raven.resume_animation()
1214
+ name = event.tool_call_start["name"]
1215
+ self._raven.state = ravens.state_for_tool(name)
1216
+ call_id = event.tool_call_start.get("id")
1217
+ if call_id:
1218
+ self._tool_names[call_id] = name
1219
+ params = event.tool_call_start.get("input")
1220
+ if name in DIFFED_TOOLS and call_id:
1221
+ # No digest on these two (§41, X4). It showed the first
1222
+ # 60 characters of `content`, or of `old_text` and
1223
+ # `new_text` -- which is the thing the diff replaces,
1224
+ # and printing both would be the truncated payload back
1225
+ # again, above a block that says it properly.
1226
+ self._file_calls[call_id] = (
1227
+ name, params or {}, self._snapshot(params))
1228
+ transcript.write_role("tool", f"▸ {name}")
1229
+ else:
1230
+ # §42 (RA3): the registry's digest, not param_digest
1231
+ # direct -- a tool's declared rationale is prose for
1232
+ # the approval prompt and would take sixty of this
1233
+ # line's hundred and forty characters, leading it
1234
+ # whenever the model emits that key first.
1235
+ digest = tool_registry.call_digest(name, params)
1236
+ detail = f" {digest}" if digest else ""
1237
+ transcript.write_role("tool", f"▸ {name}{detail}")
1238
+
1239
+ if event.tool_result:
1240
+ result = event.tool_result["result"]
1241
+ call_id = event.tool_result.get("id")
1242
+ failed = isinstance(result, dict) and "error" in result
1243
+ if failed:
1244
+ tool_name = self._tool_names.get(call_id) if call_id else None
1245
+ error_text = redact_secrets(str(result["error"]))
1246
+ if tool_name:
1247
+ transcript.write_role("tool_error", f" ✗ {tool_name} {error_text}")
1248
+ else:
1249
+ # `tool_error`, not `error` (batch 48). A failed tool
1250
+ # whose call id went missing is still a failed tool,
1251
+ # and `error` is the harness's own voice -- one role
1252
+ # meaning two things is what stops /copy telling the
1253
+ # exchange apart from the narration. §41 X2's weight
1254
+ # rule agrees: plain, not bold.
1255
+ transcript.write_role(
1256
+ "tool_error", f" ✗ {error_text}")
1257
+ # §41 (X4). AT THE RESULT, and only a successful one. A
1258
+ # call can still be denied at the permission gate or
1259
+ # refused by the tool (old_text not unique, path
1260
+ # unwritable), and a diff drawn at tool_call_start would
1261
+ # have shown a change that never happened.
1262
+ stashed = self._file_calls.pop(call_id, None) if call_id else None
1263
+ if stashed and not failed:
1264
+ self._write_file_diff(transcript, *stashed)
1265
+
1266
+ if event.notice:
1267
+ # ROADMAP_v2 §21's "no silent compaction, ever". Flushed first
1268
+ # so the marker lands between messages rather than inside a
1269
+ # half-streamed reply. Rendering lives in _render_notice, the
1270
+ # one branch the one-shot path (#172) drives too.
1271
+ self._end_thinking()
1272
+ transcript.flush_stream()
1273
+ self._render_notice(event.notice)
1274
+
1275
+ if event.permission_request:
1276
+ self._end_thinking()
1277
+ # §23: informational only. The modal is opened by the response
1278
+ # channel from the worker thread, so this no longer pushes one
1279
+ # -- doing both would stack two modals for one question.
1280
+ self._raven.resume_animation()
1281
+ self._raven.state = ravens.WAITING
1282
+
1283
+ if event.final_response is not None:
1284
+ self._end_thinking()
1285
+ transcript.flush_stream()
1286
+ if event.stop_reason and event.stop_reason != "complete":
1287
+ transcript.write_system(f"[stopped early: {event.stop_reason}]")
1288
+
1289
+ def _snapshot(self, params) -> "str | None":
1290
+ """What the file holds right now, or None when there is nothing
1291
+ usable to diff against (§41, X4/X6).
1292
+
1293
+ Resolved through `file_ops.resolve_path`, the tool's own rule,
1294
+ rather than re-derived here -- a second path computation would
1295
+ mean a diff of one file beside an edit to another.
1296
+
1297
+ None for every reason a snapshot can fail: no such file (a
1298
+ `write` creating one, which is the common case), a directory, one
1299
+ past DIFF_SNAPSHOT_MAX_BYTES, an unreadable one. Every one of
1300
+ those degrades the block rather than losing it, so none of them is
1301
+ worth an error line -- and this runs on the UI thread, where an
1302
+ exception escaping would take the app's message pump with it.
1303
+ """
1304
+ path = (params or {}).get("path")
1305
+ if not isinstance(path, str) or not path:
1306
+ return None
1307
+ try:
1308
+ resolved = file_ops.resolve_path(path)
1309
+ if not os.path.isfile(resolved):
1310
+ return None
1311
+ if os.path.getsize(resolved) > DIFF_SNAPSHOT_MAX_BYTES:
1312
+ return None
1313
+ with open(resolved, "r", encoding="utf-8", errors="replace") as f:
1314
+ return f.read()
1315
+ except Exception: # noqa: BLE001 -- see the docstring
1316
+ return None
1317
+
1318
+ def _write_file_diff(self, transcript, name: str, params: dict,
1319
+ pre: "str | None") -> None:
1320
+ """The diff for one finished `write` or `edit`.
1321
+
1322
+ The post-image is RECONSTRUCTED from the call's own arguments
1323
+ rather than read back off disk: `write_run` writes `content`
1324
+ verbatim and `edit_run` replaces a span the tool has already
1325
+ guaranteed unique, so the reconstruction is exact -- and it cannot
1326
+ pick up a change some other process made between the call
1327
+ returning and this line running.
1328
+
1329
+ Redaction runs through `redact_output_text`, the same path
1330
+ `param_digest` takes: a `write` renders the content the tool put
1331
+ on disk, which is tool output by any reading, and `redact_secrets`
1332
+ alone catches the vendor tokens but not the three credential
1333
+ SHAPES (#167) -- so the narrower function would have made this
1334
+ block redact LESS than the digest line it replaces.
1335
+
1336
+ It runs on the WHOLE texts, because the redactor works on whole
1337
+ strings and a secret that reached the block would be just as
1338
+ readable split across two wrapped rows as on one. And it runs
1339
+ AFTER the reconstruction, because doing it first means matching a
1340
+ redacted `old_text` inside a separately-redacted file:
1341
+ `redact_output_text` sees more context in the file than in the
1342
+ argument, so it can match a longer span there (measured:
1343
+ `ci:pw@host` is untouched alone and redacted inside
1344
+ `https://ci:pw@host`, since the userinfo pattern anchors on `//`),
1345
+ the replace finds nothing, and the block comes back empty.
1346
+
1347
+ WHICH LEAVES ONE HONEST GAP, AND IT IS ANNOUNCED. Redacting both
1348
+ sides with the same substitution is what stops an unchanged secret
1349
+ reading as a spurious edit -- and it also collapses a change that
1350
+ was ENTIRELY inside a secret, which is exactly what rotating a
1351
+ credential is. The block is empty and the file did change, so a
1352
+ line says so. Rendering nothing would be M14's silent cap on the
1353
+ one edit a reader is most likely to be checking.
1354
+ """
1355
+ path = params.get("path") or ""
1356
+ if name == "write":
1357
+ post = params.get("content")
1358
+ if not isinstance(post, str):
1359
+ return
1360
+ block = diffs.build_block(
1361
+ path, redact_output_text(pre) if pre is not None else None,
1362
+ redact_output_text(post))
1363
+ changed = pre != post
1364
+ else:
1365
+ old, new = params.get("old_text"), params.get("new_text")
1366
+ if not isinstance(old, str) or not isinstance(new, str):
1367
+ return
1368
+ if pre is None or old not in pre:
1369
+ # X6. The snapshot is missing, or it does not contain what
1370
+ # the tool replaced -- a file that changed between the
1371
+ # call and the result. Reconstructing from it would be a
1372
+ # guess presented as a diff, and the arguments are true
1373
+ # whatever the file did.
1374
+ block = diffs.build_replacement_block(
1375
+ path, redact_output_text(old), redact_output_text(new))
1376
+ changed = True
1377
+ else:
1378
+ # `.replace(old, new)` with no count, matching `edit_run`
1379
+ # exactly rather than approximating it. The tool has
1380
+ # already refused the call unless `old` appeared once, so
1381
+ # the two are the same operation -- and writing the same
1382
+ # call is what keeps them the same operation if that
1383
+ # guarantee ever moves.
1384
+ post = pre.replace(old, new)
1385
+ block = diffs.build_block(path, redact_output_text(pre),
1386
+ redact_output_text(post))
1387
+ changed = pre != post
1388
+ if block:
1389
+ transcript.write_role("diff", block)
1390
+ elif changed:
1391
+ transcript.write_role(
1392
+ "system",
1393
+ f" {path}: the change is entirely inside redacted content")
1394
+
1395
+ def _release_permission_channel(self) -> None:
1396
+ """Unblock a worker parked on permission_channel.get(), denying.
1397
+
1398
+ ARCHITECTURE §4.14 already states the invariant -- every
1399
+ permission dismissal path must put a boolean on the channel --
1400
+ but listed only the modal's own paths. Exiting is a dismissal
1401
+ too, and it was the uncovered one: the worker blocks in
1402
+ Queue.get() for up to ATTENDED_APPROVAL_TIMEOUT_S -- 600s, long
1403
+ enough that a quit would read as a hang -- Textual cannot
1404
+ interrupt a thread blocked there, and it runs thread workers on
1405
+ NON-daemon executor threads. (This said "with no timeout", which
1406
+ was true when written and stopped being true when _blocking_modal
1407
+ acquired one; the conclusion is unchanged, and it is the sentence
1408
+ someone would rely on when deciding whether this release is still
1409
+ load-bearing -- audit #108.) So quitting with a prompt open left App.run() unable to
1410
+ return and the interpreter unable to exit -- a hang, not an error.
1411
+ """
1412
+ channel = self._permission_channel
1413
+ self._permission_channel = None
1414
+ if channel is not None:
1415
+ channel.put(False)
1416
+
1417
+ def exit(self, *args, **kwargs):
1418
+ # Every exit route funnels through here (action_quit, ctrl+c, and
1419
+ # any programmatic exit), which is why the release lives here
1420
+ # rather than on the quit binding alone.
1421
+ if self._busy:
1422
+ # #105, D4. Say what quitting does to a run rather than
1423
+ # leaving it mysterious: the worker stops forwarding at its
1424
+ # next event (#105's fix), so this is a bounded goodbye, and
1425
+ # the line tells the user what became of the run.
1426
+ #
1427
+ # Best-effort twice over (#104's rule): quitting from under a
1428
+ # modal means query_one finds no #transcript at all -- it
1429
+ # searches the ACTIVE screen (§27) -- and an unrenderable
1430
+ # goodbye must not block the goodbye.
1431
+ try:
1432
+ self._transcript.write_system(
1433
+ "[quitting — the active work is abandoned at its next "
1434
+ "event; its checkpoints are kept.]")
1435
+ except NoMatches:
1436
+ pass
1437
+ self._shutting_down = True
1438
+ self._release_permission_channel()
1439
+ return super().exit(*args, **kwargs)
1440
+
1441
+ def response_channel(self, honour_run_scope: bool = True):
1442
+ """This app's one way of being asked anything (§23 AC1).
1443
+
1444
+ ONE object for the chat turn, an attended research pass, and every
1445
+ tool that needs a human -- replacing a bare queue.Queue for chat
1446
+ and an ApprovalProvider for research, which were the same exchange
1447
+ with two sets of plumbing and could not agree on a question with
1448
+ more than two answers.
1449
+
1450
+ honour_run_scope=False for attended research (§25 R11): a mode
1451
+ whose purpose is per-call supervision must not let one yes cover
1452
+ later calls.
1453
+ """
1454
+ from core import interaction
1455
+
1456
+ return interaction.ResponseChannel(
1457
+ ask=self._ask_blocking, honour_run_scope=honour_run_scope)
1458
+
1459
+ def _ask_blocking(self, request):
1460
+ """Route one Request to its modal and BLOCK. Runs on a worker.
1461
+
1462
+ Dispatch by kind lives here rather than in each caller, so a new
1463
+ kind is a branch in one method instead of a new field, a new
1464
+ parameter, and a new release path -- which is how there came to be
1465
+ five of these.
1466
+ """
1467
+ from core import interaction
1468
+
1469
+ if request.kind == interaction.APPROVAL:
1470
+ return self.ask_permission_blocking(
1471
+ request.payload.get("tool_name"),
1472
+ request.payload.get("params") or {},
1473
+ request.notice,
1474
+ request.payload.get("rationale"),
1475
+ request.payload.get("headline"))
1476
+ if request.kind == interaction.REVIEW:
1477
+ return self.ask_review_blocking(
1478
+ request.payload.get("finding") or {},
1479
+ request.payload.get("round", 0))
1480
+ if request.kind == interaction.CONFIRM:
1481
+ return self.ask_confirm_blocking(
1482
+ request.payload.get("title", ""),
1483
+ request.payload.get("body", ""),
1484
+ request.payload.get("confirm_label", "Yes"))
1485
+ if request.kind == interaction.CHOICE:
1486
+ return self.ask_choice_blocking(request.payload)
1487
+ if request.kind == interaction.QUESTION:
1488
+ return self.ask_question_blocking(request.payload)
1489
+ if request.kind == interaction.SUBAGENT_SIGNOFF:
1490
+ return self.ask_signoff_blocking(
1491
+ request.payload.get("agent", "this subagent"),
1492
+ request.payload.get("candidates") or [])
1493
+ # An unrecognised kind is a bug in whoever built the Request;
1494
+ # interaction.decode raises on one, and falling through lets that
1495
+ # happen rather than answering a question this app cannot render.
1496
+ return None
1497
+
1498
+ def ask_permission_blocking(self, tool_name: str, params: dict,
1499
+ notice, rationale=None,
1500
+ headline=None) -> bool:
1501
+ """Show the permission modal and BLOCK until answered.
1502
+
1503
+ Called from a worker thread, never the UI thread -- both the chat
1504
+ turn and an attended research pass reach it through
1505
+ `_ask_blocking`. §23 unified those: the chat path used to push its
1506
+ modal from on_loop_event while the worker parked on a queue the
1507
+ loop held, which was a second mechanism for one exchange.
1508
+
1509
+ `_release_permission_channel` covers this: quitting with a prompt
1510
+ open must not leave a non-daemon worker parked on a Queue.get()
1511
+ nothing will ever answer (review f10).
1512
+ """
1513
+ if self._shutting_down:
1514
+ # The one-shot release already fired; parking here would hang
1515
+ # the worker (and the interpreter) forever (review r1-1).
1516
+ return False
1517
+ # Deny and keep going on a timeout (R9). Leaving the modal on
1518
+ # screen would also leave the user answering a question whose
1519
+ # answer no longer goes anywhere.
1520
+ return self._blocking_modal(
1521
+ PermissionScreen(tool_name, params, notice, rationale,
1522
+ headline),
1523
+ on_timeout=lambda screen: self._timed_out_ask(
1524
+ screen,
1525
+ dismiss_with=False,
1526
+ on_timeout_line=(
1527
+ f"[no answer for {tool_name} — denied; "
1528
+ f"the run continues]"),
1529
+ after_line=("[answer arrived after the timeout — that call "
1530
+ "was denied; the run continues]")))
1531
+
1532
+ def ask_confirm_blocking(self, title: str, body: str,
1533
+ confirm_label: str = "Yes") -> bool:
1534
+ """Show a yes/no and BLOCK until answered (§24).
1535
+
1536
+ Called from the /init worker, and shaped exactly like
1537
+ ask_permission_blocking for the same reason: the generator is
1538
+ plain synchronous code draining nothing, so no LoopEvent carries
1539
+ its question to the UI.
1540
+
1541
+ The SAME `_permission_channel` field, so
1542
+ `_release_permission_channel` already covers it -- quitting with
1543
+ this modal open must not leave a non-daemon worker parked on a
1544
+ Queue nobody will answer. That release puts a bare False, which
1545
+ decodes here as "no", which is the safe direction: nothing is
1546
+ written.
1547
+ """
1548
+ if self._shutting_down:
1549
+ return False
1550
+ return self._blocking_modal(
1551
+ ConfirmScreen(title, body, confirm_label),
1552
+ on_timeout=lambda screen: self._timed_out_ask(
1553
+ screen,
1554
+ dismiss_with=False,
1555
+ on_timeout_line="[no answer — nothing was written]",
1556
+ after_line=("[answer arrived after the timeout — "
1557
+ "nothing was written]")))
1558
+
1559
+ def _blocking_modal(self, screen, *, on_timeout):
1560
+ """Push `screen` from a worker thread and park until it dismisses.
1561
+
1562
+ THE MECHANICS, ONCE. Four asks did this identically -- make a
1563
+ queue, publish it on `_permission_channel` so the shutdown release
1564
+ can find it, push from the UI thread, wait with a timeout, clear
1565
+ the field. Each copy was a chance to forget the `finally`, and the
1566
+ field is what `_release_permission_channel` reaches for when the
1567
+ app exits with a modal open.
1568
+
1569
+ Returns the dismissal value RAW, including None on timeout.
1570
+ interaction.decode turns anything unusable into that kind's
1571
+ declining default, which is why nothing here fabricates an answer.
1572
+ """
1573
+ channel: queue.Queue = queue.Queue()
1574
+ self._permission_channel = channel
1575
+ self.call_from_thread(
1576
+ self.push_screen, screen, lambda answer: channel.put(answer))
1577
+ try:
1578
+ return channel.get(timeout=config.ATTENDED_APPROVAL_TIMEOUT_S)
1579
+ except queue.Empty:
1580
+ self.call_from_thread(on_timeout, screen)
1581
+ return None
1582
+ finally:
1583
+ self._permission_channel = None
1584
+
1585
+ def ask_choice_blocking(self, payload: dict):
1586
+ """Pick one of a set of offered options. Blocks; returns whatever
1587
+ the modal dismissed with, RAW.
1588
+
1589
+ §23: this no longer validates. It used to end with
1590
+ `answer if answer in PROJECT_KINDS else None`, which was the one
1591
+ guard §24 shipped untested -- and the check belongs where the
1592
+ options are known to be the ones that were OFFERED, which is
1593
+ interaction.decode reading them off the request. This method's job
1594
+ is to render and to block.
1595
+ """
1596
+ if self._shutting_down:
1597
+ return None
1598
+ screen = ProjectKindScreen(payload.get("proposal"),
1599
+ payload.get("reason", ""),
1600
+ payload.get("blank", False))
1601
+ return self._blocking_modal(
1602
+ screen,
1603
+ on_timeout=lambda screen: self._timed_out_ask(
1604
+ screen,
1605
+ dismiss_with=False,
1606
+ # CHOICE's only caller is /init's project-kind picker, so
1607
+ # the sentence confirm uses is true here too (#107).
1608
+ on_timeout_line="[no answer — nothing was written]",
1609
+ after_line=("[answer arrived after the timeout — "
1610
+ "nothing was written]")))
1611
+
1612
+ def ask_question_blocking(self, payload: dict):
1613
+ """Put the model's question to the user (§23 slice 2). Blocks;
1614
+ returns the dismissal RAW.
1615
+
1616
+ Raw, like every other ask here: interaction.decode supplies the
1617
+ declining default for a timeout and intersects the chosen options
1618
+ with the ones that were offered. This method renders and blocks.
1619
+ """
1620
+ if self._shutting_down:
1621
+ return None
1622
+ screen = QuestionScreen(
1623
+ payload.get("question", ""),
1624
+ payload.get("options") or (),
1625
+ payload.get("multi_select", False),
1626
+ payload.get("allow_text", True))
1627
+ return self._blocking_modal(
1628
+ screen,
1629
+ on_timeout=lambda screen: self._timed_out_ask(
1630
+ screen,
1631
+ dismiss_with=False,
1632
+ on_timeout_line=(
1633
+ "[no answer — the model was told nobody answered]"),
1634
+ after_line=("[answer arrived after the timeout — the model "
1635
+ "was told nobody answered]")))
1636
+
1637
+ def ask_signoff_blocking(self, agent: str, candidates: list):
1638
+ """Which of a subagent's gated tools it may use unprompted (§23
1639
+ AC1b). Blocks; returns a set, or None to refuse the spawn.
1640
+
1641
+ Returns the dismissal RAW, including None on timeout, because
1642
+ interaction.decode both supplies the declining default and
1643
+ intersects the answer with the candidates that were offered.
1644
+ """
1645
+ if self._shutting_down:
1646
+ return None
1647
+ return self._blocking_modal(
1648
+ SubagentSignoffScreen(agent, candidates),
1649
+ on_timeout=lambda screen: self._timed_out_ask(
1650
+ screen,
1651
+ dismiss_with=False,
1652
+ on_timeout_line=(
1653
+ f"[no answer for {agent} (subagent sign-off) — "
1654
+ f"denied; the spawn was refused]"),
1655
+ after_line=("[answer arrived after the timeout — the spawn "
1656
+ "was refused]")))
1657
+
1658
+ def ask_review_blocking(self, finding: dict, round_index: int):
1659
+ """Show the review modal and BLOCK until answered. §20 V4.
1660
+
1661
+ Called from the /research worker thread, and structured exactly
1662
+ like ask_permission_blocking for the same reason: the pipeline
1663
+ drains its passes through run_to_completion(), so no LoopEvent
1664
+ carries this question to the UI.
1665
+
1666
+ The SAME `_permission_channel` field, so `_release_permission_channel`
1667
+ already covers it -- quitting with a review modal open must not
1668
+ leave a non-daemon worker parked on a Queue nobody will ever
1669
+ answer. That release puts a bare False.
1670
+
1671
+ §23: this method no longer decodes. Every value it can return --
1672
+ the modal's tuple, the shutdown release's bare False, the
1673
+ timeout's None -- goes back to interaction.decode, which turns
1674
+ anything that is not a well-formed (decision, notes) pair into a
1675
+ rejection. There used to be a local `_decode_review_answer` here
1676
+ AND a second normaliser in review.py, and they disagreed about
1677
+ whether a bare "accept" string counted.
1678
+ """
1679
+ if self._shutting_down:
1680
+ # Same hang as ask_permission_blocking: exit()'s release is
1681
+ # one-shot, and this ask would re-arm a queue nobody answers
1682
+ # (review r1-1). None rather than a hand-built rejection, so
1683
+ # this path uses the same decoder as every other.
1684
+ return None
1685
+ # The timeout returns None rather than a hand-built rejection:
1686
+ # interaction.decode turns it into one, the same way it does for
1687
+ # the modal and the shutdown-release paths. §23 removed the local
1688
+ # decoder this used to call, so there is now genuinely one rule
1689
+ # rather than a promise that three paths share one (review f25).
1690
+ return self._blocking_modal(
1691
+ ReviewScreen(finding, round_index, config.MAX_REVIEW_REFINEMENTS),
1692
+ on_timeout=lambda screen: self._timed_out_ask(
1693
+ screen,
1694
+ dismiss_with=("reject", ""),
1695
+ on_timeout_line=(
1696
+ "[no answer — correction rejected; the review continues]"),
1697
+ after_line=("[answer arrived after the timeout — that "
1698
+ "correction was already rejected; the review "
1699
+ "continues]")))
1700
+
1701
+ def _timed_out_ask(self, screen, *, on_timeout_line: str,
1702
+ after_line: str, dismiss_with) -> None:
1703
+ """One timeout callback for all six asks (#107).
1704
+
1705
+ THE MECHANICS, ONCE. There were three of these for six kinds, and
1706
+ they disagreed about the same race: _timed_out_review handled
1707
+ answered-just-after-the-timeout correctly, _timed_out_permission
1708
+ guarded the dismissal but wrote "no answer" outside the guard,
1709
+ contradicting a click that landed microseconds late, and
1710
+ _timed_out_confirm sat entirely inside the guard, saying nothing
1711
+ at all in exactly that case.
1712
+
1713
+ Both branches now exist for every kind, and each kind supplies its
1714
+ own truthful sentences -- QUESTION's no-answer line says what
1715
+ actually happened (the model was told nobody answered), not what
1716
+ confirm's used to claim ("nothing was written"). The lines arrive
1717
+ WHOLE rather than as an interpolated subject so review's two
1718
+ strings stay byte-identical with what
1719
+ test_the_no_answer_line_only_prints_when_there_was_no_answer pins.
1720
+
1721
+ `dismiss_with` carries the same raw value the old callbacks used:
1722
+ False for permission/signoff/confirm/choice/question (decode turns
1723
+ it into that kind's declining default) and ("reject", "") for
1724
+ review. interaction.decode is untouched; this method changes only
1725
+ what the human is told.
1726
+ """
1727
+ # #105's family: after a quit there is nobody listening, and the
1728
+ # widgets this writes to may already be gone -- exit() released
1729
+ # the channel with a value, so the worker is not parked and the
1730
+ # narration would only describe an app that has closed.
1731
+ if self._shutting_down:
1732
+ return
1733
+ # Only say "no answer" when there genuinely was none: if the user
1734
+ # clicked between the get() timeout and this callback, the screen
1735
+ # is gone and the message would contradict what they just did
1736
+ # (review §19-20 f15).
1737
+ if screen in self.screen_stack:
1738
+ screen.dismiss(dismiss_with)
1739
+ self._transcript.write_system(on_timeout_line)
1740
+ else:
1741
+ # They DID answer, microseconds after the timeout claimed the
1742
+ # slot, and their answer went nowhere. Saying nothing leaves
1743
+ # them to discover it in the run's summary and conclude the
1744
+ # button is broken.
1745
+ self._transcript.write_system(after_line)
1746
+
1747
+ def on_turn_finished(self, message: TurnFinished) -> None:
1748
+ self._busy = False
1749
+ self._permission_channel = None
1750
+ self._tool_names.clear()
1751
+ self._file_calls.clear()
1752
+ # §38: close a thinking span before the answer's, so a turn that
1753
+ # ends mid-reasoning (a stop condition, an error) still gets its
1754
+ # closing delimiter and drops the indicator.
1755
+ self._end_thinking()
1756
+ # Committing what is left of the span, and nothing else. This used
1757
+ # to capture flush_stream()'s return into `_last_response` for
1758
+ # /copy -- which never fired, because the terminal `final_response`
1759
+ # event in on_loop_event_message has already flushed by the time
1760
+ # this runs and a second flush returns "". The entry log is the
1761
+ # record now (Transcript.last_answer), so there is no second buffer
1762
+ # to keep in step and no flush site that has to remember to.
1763
+ self._transcript.flush_stream()
1764
+ self._raven.resume_animation()
1765
+ self._raven.state = ravens.IDLE
1766
+ if message.error is not None:
1767
+ self._transcript.write_error(f"[error: {message.error}]")
1768
+
1769
+ def on_pipeline_event_message(self, message: PipelineEventMessage) -> None:
1770
+ """Render one PipelineEvent (§22 AC2).
1771
+
1772
+ Reads run.trace nowhere and the database nowhere: everything here
1773
+ arrives as an event, which is what makes the view live rather
1774
+ than a summary drawn after the fact.
1775
+ """
1776
+ event = message.event
1777
+ panel = self._research_progress
1778
+
1779
+ if event.kind == "pass_start":
1780
+ self._raven.state = ravens.THINKING
1781
+ self._transcript.write_role("pass", f"→ {system_prompts.pass_label(event.pass_id)}")
1782
+ panel.pass_started(event.pass_id)
1783
+ elif event.kind == "pass_complete" and event.ok is False:
1784
+ # E14/#115. The row resolves as FAILED -- the whole point of
1785
+ # this event, so a skipped ensemble candidate stops showing
1786
+ # as running forever beside a transcript that says it was
1787
+ # dropped. NO transcript line here: the trace_line naming
1788
+ # the cause arrives beside it, and printing again would say
1789
+ # everything twice. Panel only, per the batch's display
1790
+ # contract.
1791
+ panel.pass_completed(event.pass_id, ok=False)
1792
+ elif event.kind == "pass_complete":
1793
+ self._transcript.write_role("pass_done", f"← {system_prompts.pass_label(event.pass_id)}")
1794
+ panel.pass_completed(event.pass_id, ok=True)
1795
+ elif event.kind == "stage":
1796
+ # §26. No arrow: a zero-LLM stage is over by the time it is
1797
+ # announced, and an arrow would promise something starting.
1798
+ self._transcript.write_role("pass_done", f"· {system_prompts.pass_label(event.pass_id)}")
1799
+ panel.stage_completed(event.pass_id)
1800
+ elif event.kind == "tool_call":
1801
+ # §26, the thing §22 P2 made invisible. Indented under its
1802
+ # pass, so a run reads as a tree rather than a flat log.
1803
+ detail = f" {event.text}" if event.text else ""
1804
+ self._transcript.write_role("tool", f" ▸ {event.tool}{detail}")
1805
+ panel.tool_called(event.pass_id)
1806
+ elif event.kind == "tool_result":
1807
+ # Only failures. A line per successful call doubles the volume
1808
+ # to say what the absence of an error line already says.
1809
+ if not event.ok:
1810
+ self._transcript.write_role(
1811
+ "tool_error", f" ✗ {event.tool} {event.text}")
1812
+ elif event.kind == "pass_activity":
1813
+ # Panel only. This is a running total that changes constantly;
1814
+ # in an append-only transcript it would be a column of
1815
+ # near-identical lines.
1816
+ panel.activity(event.pass_id, event.chars)
1817
+ elif event.kind == "trace_line":
1818
+ # Same format the end-of-run dump used, so a run reads the
1819
+ # same whether you watched it or scrolled back to it.
1820
+ self._transcript.write_system(f" {event.text}")
1821
+ elif event.kind == "claim_extracted":
1822
+ # §26: kept for the claims view, so /claims says something
1823
+ # useful while the run is still going rather than only after.
1824
+ self._live_claims.setdefault(
1825
+ event.claim_id, {"id": event.claim_id, "text": event.text})
1826
+ panel.claim_extracted()
1827
+ elif event.kind == "claim_tiered":
1828
+ self._live_claims.setdefault(
1829
+ event.claim_id, {"id": event.claim_id})["confidence_tier"] = event.tier
1830
+ panel.claim_tiered(event.claim_id, event.tier)
1831
+ elif event.kind == "retry":
1832
+ claim = self._live_claims.setdefault(
1833
+ event.claim_id, {"id": event.claim_id})
1834
+ claim["retry_count"] = event.attempt
1835
+ panel.retried()
1836
+
1837
+ def on_research_finished(self, message: ResearchFinished) -> None:
1838
+ self._busy = False
1839
+ self._raven.state = ravens.IDLE
1840
+ if getattr(message, "abandoned", False):
1841
+ # #105. A deliberate quit is not a pipeline failure: say what
1842
+ # actually happened to the run. §22's wording -- abandoned,
1843
+ # checkpoints kept, record left 'running' -- is the honest
1844
+ # summary of the state the record is in.
1845
+ self._transcript.write_system(
1846
+ "[run abandoned — quit requested. Checkpoints so far are "
1847
+ "kept; the run's record stays 'running' rather than "
1848
+ "claiming completion.]")
1849
+ return
1850
+ if message.error is not None:
1851
+ self._transcript.write_error(f"[pipeline failed: {message.error}]")
1852
+ return
1853
+ run = message.run
1854
+ self._last_run = run
1855
+ # §22: the trace is NOT re-printed here. Every line already
1856
+ # arrived as a trace_line event and was written as it happened;
1857
+ # dumping run.trace again would print the whole run twice.
1858
+ self._transcript.write_answer(run.final_report or "")
1859
+ if run.claims:
1860
+ # §26. The report is a synthesis; the claims are what it was
1861
+ # synthesised from, with the tiers and grounding that decided
1862
+ # how much of it to believe. Advertised rather than dumped --
1863
+ # a dozen claims with full metadata would bury the report
1864
+ # directly beneath it.
1865
+ self._transcript.write_system(
1866
+ f"{len(run.claims)} claim(s) — /claims or ctrl+l to expand")
1867
+ if run.subagent_reviews:
1868
+ accepted = sum(1 for d in run.subagent_reviews
1869
+ if d.get("decision") == "accept")
1870
+ record = ("full record in 07_review.json"
1871
+ if message.artifacts_ok
1872
+ else "artifact write FAILED — no 07_review.json")
1873
+ self._transcript.write_system(
1874
+ f"[review: {len(run.subagent_reviews)} finding(s), "
1875
+ f"{accepted} applied — {record}]")
1876
+ if run.run_id:
1877
+ self._transcript.write_system(f"[run id: {run.run_id}]")
1878
+
1879
+ def on_worker_state_changed(self, event: Worker.StateChanged) -> None:
1880
+ """§16 AC3. Required alongside exit_on_error=False: without a handler the
1881
+ exception is available on the worker and reported nowhere."""
1882
+ if event.worker.state is WorkerState.ERROR:
1883
+ self.notify(f"Turn failed: {event.worker.error}", severity="error")
1884
+
1885
+ # -- actions -------------------------------------------------------------
1886
+
1887
+ def action_pick_thread(self) -> None:
1888
+ # Swapping self.memory mid-turn leaves the worker running _run()
1889
+ # against the OLD memory: its response and tool results persist
1890
+ # into the abandoned thread while rendering under the new one, so
1891
+ # transcript and stored history diverge. Plain chat, /research and
1892
+ # /grill-me all enforce this guard already.
1893
+ if self._busy:
1894
+ self._transcript.write_error(
1895
+ "Still working — wait for this turn to finish.")
1896
+ return
1897
+ # #104. Every storage read from here down runs on the UI THREAD,
1898
+ # inside a screen-dismiss callback, so an uncaught exception does
1899
+ # not fail the command -- it reaches the message pump and takes
1900
+ # the app down, losing the session. `main._print_replay` has
1901
+ # carried this rule since §27 ("the thread is loaded and usable
1902
+ # whether or not it can be drawn") and unit 13's mutation batch
1903
+ # pins it; the TUI is the shell where the consequence is worse and
1904
+ # it was the shell without the guard.
1905
+ #
1906
+ # Reachable without anything being wrong with the data: app.db is
1907
+ # one SQLite file and nothing stops a CLI research run and a TUI
1908
+ # session sharing it, so `database is locked` on a read needs no
1909
+ # corruption at all.
1910
+ try:
1911
+ threads = storage.list_threads(limit=PICKER_THREAD_LIMIT)
1912
+ except Exception as e: # noqa: BLE001
1913
+ self._transcript.write_error(f"Could not list threads: {e}")
1914
+ return
1915
+
1916
+ # #30/#32. The cap is real, so it says so (M14's rule): a picker
1917
+ # that silently shows 200 of 400 reads as complete. Older
1918
+ # conversations stay reachable by id -- /resume takes any id, and
1919
+ # this note names it rather than leaving the boundary invisible.
1920
+ note = ""
1921
+ if len(threads) == PICKER_THREAD_LIMIT:
1922
+ note = (f"Showing the {PICKER_THREAD_LIMIT} most recently active. "
1923
+ f"Use /resume <thread-id> for older conversations.")
1924
+
1925
+ def chosen(thread_id) -> None:
1926
+ if thread_id is None:
1927
+ return
1928
+ resolved = thread_id if isinstance(thread_id, UUID) else UUID(str(thread_id))
1929
+ self.switch_to_thread(resolved)
1930
+
1931
+ self.push_screen(ThreadPickerScreen(threads, note), chosen)
1932
+
1933
+ def switch_to_thread(self, thread_id: UUID) -> None:
1934
+ """Open `thread_id` in this session: load, reset per-thread state,
1935
+ replay. ONE site for the whole move (the picker's chosen() and
1936
+ /resume both land here), because every step below exists to keep
1937
+ the two halves of a switch -- teardown and rebuild -- from being
1938
+ separated by a failure. A second copy of this sequence would have
1939
+ to re-learn each comment the hard way."""
1940
+ resolved = thread_id if isinstance(thread_id, UUID) else UUID(str(thread_id))
1941
+ if self._busy:
1942
+ self._transcript.write_error(
1943
+ "Still working — wait for this turn to finish.")
1944
+ return
1945
+ # BEFORE anything is torn down, deliberately. A failure here means
1946
+ # the switch does not happen at all and the session continues on
1947
+ # the thread it was already on -- which is only true while this
1948
+ # read stays above the reset below.
1949
+ try:
1950
+ memory = ConversationMemory(thread_id=resolved)
1951
+ except Exception as e: # noqa: BLE001
1952
+ self._transcript.write_error(
1953
+ f"Could not open thread {resolved}: {e}")
1954
+ return
1955
+ self.memory = memory
1956
+ # The banner is per-thread state; without this it kept showing
1957
+ # the PREVIOUS thread's objective, misrepresenting what
1958
+ # governs the session. /goal was the only path that refreshed.
1959
+ self.refresh_goal_banner()
1960
+ # §23 slice 2, the same reasoning one tier along: a checklist is
1961
+ # per-thread state too, and without this a resume showed the
1962
+ # previous thread's list.
1963
+ self.refresh_todo_panel()
1964
+ # §27 AC4, and the same class of bug the banner above already
1965
+ # fixed in this same callback: `_last_run` and `_live_claims`
1966
+ # survived a thread switch, so /claims or ctrl+l after a resume
1967
+ # showed the PREVIOUS thread's research run under the new
1968
+ # thread's id. Cleared before the replay, so a failure below
1969
+ # cannot leave stale state pointing at the wrong thread. The last
1970
+ # ANSWER is on this list by a different route now: it lives in the
1971
+ # transcript's entry log, which `reset()` below drops.
1972
+ self._last_run = None
1973
+ self._live_claims = {}
1974
+ self._tool_names.clear()
1975
+ self._file_calls.clear()
1976
+ # CLEAR, then replay. Swapping memory without clearing left the
1977
+ # previous conversation on screen beneath the new thread's id --
1978
+ # bug 1's worst half, since a blank panel is merely unhelpful
1979
+ # while a stale one is wrong.
1980
+ self._transcript.reset()
1981
+ self._transcript.write_system(f"Resumed thread {resolved}.")
1982
+ # The DISPLAY half, and it is contained rather than fatal --
1983
+ # §27's rule, which main.py has and this did not. The thread
1984
+ # is already loaded and usable at this point; a replay that
1985
+ # raises would turn a cosmetic problem into "resuming is
1986
+ # broken", and it raises AFTER the reset above, so the app
1987
+ # died having just cleared the screen and written "Resumed
1988
+ # thread <uuid>."
1989
+ #
1990
+ # Read after the reset, not before: a failure here leaves an
1991
+ # empty transcript plus an error, which is honest. Reading
1992
+ # first would leave the PREVIOUS thread's transcript on screen
1993
+ # under the new thread's id, and a stale panel is wrong where
1994
+ # a blank one is merely unhelpful.
1995
+ try:
1996
+ entries = replay_entries(resolved)
1997
+ except Exception as e: # noqa: BLE001
1998
+ self._transcript.write_error(
1999
+ f"Could not replay this thread: {e}. The thread is "
2000
+ f"open and usable — only its history could not be "
2001
+ f"drawn.")
2002
+ return
2003
+ for role, text in entries:
2004
+ if role == "user":
2005
+ self._transcript.write_user(text)
2006
+ elif role == "assistant":
2007
+ self._transcript.write_answer(text)
2008
+ elif role == "thinking":
2009
+ # §44. Skipped rather than dimmed when the setting is off:
2010
+ # /thinking is about whether reasoning is shown at all, and
2011
+ # a replay that showed what a live turn had hidden would be
2012
+ # the same conversation rendered two ways -- which is the
2013
+ # defect this whole commit exists to remove, arriving
2014
+ # through the other door.
2015
+ #
2016
+ # write_role, not a new method: Transcript._render_entry
2017
+ # has known the "thinking" role since §38 and already draws
2018
+ # the bar block and opens §43's turn label above it, so a
2019
+ # replayed span and a streamed one go through one renderer.
2020
+ if self._show_thinking:
2021
+ self._transcript.write_role(role, text)
2022
+ else:
2023
+ self._transcript.write_role(role, text)
2024
+ if entries:
2025
+ noun = "entry" if len(entries) == 1 else "entries"
2026
+ self._transcript.write_system(
2027
+ f"— end of {len(entries)} replayed {noun} —")
2028
+ else:
2029
+ self._transcript.write_system("This thread has no messages yet.")
2030
+
2031
+ def action_show_claims(self) -> None:
2032
+ self.show_claims("")
2033
+
2034
+ def show_claims(self, run_id: str = "") -> None:
2035
+ """Open the claims view (§26), for this session's run or a stored
2036
+ one. Shared by /claims and the ctrl+l binding so the two cannot
2037
+ drift into showing different things."""
2038
+ if run_id:
2039
+ claims, title, partial = self._stored_claims(run_id)
2040
+ if claims is None:
2041
+ return
2042
+ elif self._last_run is not None:
2043
+ claims = [vars(c) for c in self._last_run.claims]
2044
+ title = f"Claims — run {self._last_run.run_id}"
2045
+ partial = False
2046
+ elif self._live_claims:
2047
+ # Mid-run. Only id, text and tier have been broadcast so far,
2048
+ # which is thin but is genuinely more than nothing when the
2049
+ # question is "what has it found so far".
2050
+ claims = list(self._live_claims.values())
2051
+ title = "Claims — run in progress"
2052
+ partial = True
2053
+ else:
2054
+ self._transcript.write_system(
2055
+ "No research run in this session yet. /research <query> "
2056
+ "starts one, or /claims <run id> opens a stored run.")
2057
+ return
2058
+ self.push_screen(ClaimsScreen(claims, title, partial))
2059
+
2060
+ def _stored_claims(self, run_id: str):
2061
+ """(claims, title, partial) for a persisted run, or (None, ...)
2062
+ after reporting why not."""
2063
+ from core.reasoning.pipeline_storage import load_pipeline_run
2064
+
2065
+ try:
2066
+ record = load_pipeline_run(UUID(str(run_id)))
2067
+ except ValueError as e:
2068
+ # Covers both a malformed UUID and a run id that is not in the
2069
+ # database; load_pipeline_run raises ValueError for the latter
2070
+ # by its own documented convention.
2071
+ self._transcript.write_error(f"/claims: {e}")
2072
+ return None, "", False
2073
+ except Exception as e: # noqa: BLE001
2074
+ # #104, one command along and the same shape: catching only
2075
+ # ValueError meant a STORAGE-level failure -- a locked
2076
+ # database, an unreadable row -- reached the message pump and
2077
+ # took the app down, from a read-only command whose worst
2078
+ # honest outcome is "I could not show you that run".
2079
+ self._transcript.write_error(f"/claims: could not load run: {e}")
2080
+ return None, "", False
2081
+ return (record["claims"],
2082
+ f"Claims — run {run_id} ({record['status']})",
2083
+ record["status"] == "running")
2084
+
2085
+
2086
+ # ---------------------------------------------------------------------------
2087
+ # ---- Built-in slash commands ----------------------------------------------
2088
+ # ---------------------------------------------------------------------------
2089
+ # Registered here rather than matched inside the app so §19's /skill, §18's
2090
+ # /agent, and §21's /compact register the same way.
2091
+
2092
+ def _cmd_help(app: VenastineApp, args: str) -> None:
2093
+ app._transcript.write_system("Commands:")
2094
+ for command in commands.all():
2095
+ usage = f" {command.usage}" if command.usage else ""
2096
+ app._transcript.write_system(f" /{command.name}{usage} — {command.summary}")
2097
+ # §26. Worth saying plainly: the pinned textual has no text selection,
2098
+ # so someone trying to select with the mouse gets nothing and has no
2099
+ # way to know why. Most terminals let shift+drag bypass the app's
2100
+ # mouse capture and select natively.
2101
+ app._transcript.write_system(
2102
+ "Text selection is not supported by this Textual version — hold "
2103
+ "shift while dragging to select with the terminal itself, or use "
2104
+ "/copy.")
2105
+
2106
+
2107
+ def _cmd_theme(app: VenastineApp, args: str) -> None:
2108
+ if not args:
2109
+ app._transcript.write_system(
2110
+ f"Current theme: {app.theme}. Available: {', '.join(themes.THEME_NAMES)}"
2111
+ )
2112
+ # #14's discoverability note. With standalone tinted themes this
2113
+ # is truer than ever: /theme is not a border tweak.
2114
+ app._transcript.write_system(
2115
+ "Themes restyle panels, transcript roles, and code blocks."
2116
+ )
2117
+ return
2118
+ if args not in themes.THEME_NAMES:
2119
+ app._transcript.write_error(
2120
+ f"Unknown theme {args!r}. Available: {', '.join(themes.THEME_NAMES)}"
2121
+ )
2122
+ return
2123
+ app.theme = args
2124
+ # §26. RichLog stores rendered segments, not source, so everything
2125
+ # already on screen keeps the OLD palette unless it is replayed --
2126
+ # which would leave the session split between two colour schemes at
2127
+ # the exact line this command was typed.
2128
+ app._transcript.rerender()
2129
+ # #183. The sidebar's Rich-styled widgets are in the same boat as the
2130
+ # transcript -- resolved per draw, invisible to tcss -- so they get
2131
+ # the same treatment instead of keeping the old palette until their
2132
+ # next event happened to fire.
2133
+ app.restyle_sidebar()
2134
+ app._transcript.write_system(f"Theme set to {args}.")
2135
+ # Only on a write that actually landed. The save happened up at
2136
+ # `app.theme = args`, which fires watch_theme synchronously, so the
2137
+ # answer is already in; a failure WARNED there and reaches the
2138
+ # transcript through TranscriptLogHandler. Saying nothing here is
2139
+ # therefore neither silent nor a duplicate, and claiming a save that
2140
+ # did not happen is the one thing this must not do. The theme itself
2141
+ # applies either way.
2142
+ if app._theme_remembered:
2143
+ app._transcript.write_system("Remembered for the next launch.")
2144
+
2145
+
2146
+ def _cmd_model(app: VenastineApp, args: str) -> None:
2147
+ """Switch provider and/or model for the rest of the session.
2148
+
2149
+ `/model <name>` keeps the current provider; `/model <PROVIDER> <name>`
2150
+ switches both. Bare `/model` reports where things stand.
2151
+
2152
+ REMEMBERED for the next launch, and still not written back to
2153
+ settings.json (§43, RM3). That file is the one config file where a
2154
+ trusted project tier beats the user tier (D29) -- a session quietly
2155
+ rewriting it is a decision, not a convenience -- and the project copy
2156
+ is inside D17's trust content hash, so writing default_model there
2157
+ would re-trigger the trust prompt at the next launch. The pair goes
2158
+ into the user-tier store /theme already uses, BESIDE that file. See
2159
+ _startup_model for what brings it back and what outranks it.
2160
+
2161
+ The switch takes effect on the NEXT turn: run_agent_turn and
2162
+ _cmd_research both read app.model / app.provider_name when they
2163
+ start, so a turn already in flight keeps the model it began with.
2164
+ That is also why this refuses while busy -- swapping underneath a
2165
+ running worker would leave the transcript claiming one model and the
2166
+ thread recording another.
2167
+ """
2168
+ from credentials import load_provider_data
2169
+
2170
+ providers = load_provider_data()
2171
+
2172
+ def _configured() -> str:
2173
+ named = sorted(p for p, e in providers.items() if e.get("API_KEY"))
2174
+ return ", ".join(named) if named else "none (add a key to providers.json)"
2175
+
2176
+ if not args:
2177
+ app._transcript.write_system(
2178
+ f"Provider: {app.provider_name} | model: {app.model}")
2179
+ app._transcript.write_system(f"Providers with a key: {_configured()}")
2180
+ app._transcript.write_system(
2181
+ "Usage: /model <name>, or /model <PROVIDER> <name>.")
2182
+ return
2183
+
2184
+ if app._busy:
2185
+ app._transcript.write_error(
2186
+ "Still working — wait for this turn to finish.")
2187
+ return
2188
+
2189
+ parts = args.split()
2190
+ if len(parts) == 1:
2191
+ provider, model = app.provider_name, parts[0]
2192
+ elif len(parts) == 2:
2193
+ provider, model = parts[0].upper(), parts[1]
2194
+ else:
2195
+ app._transcript.write_error(
2196
+ "Usage: /model <name>, or /model <PROVIDER> <name>.")
2197
+ return
2198
+
2199
+ # Unknown provider REFUSES: api_initialization would raise the same
2200
+ # ValueError on the next turn, a long way from the typo that caused it.
2201
+ if provider not in providers:
2202
+ app._transcript.write_error(
2203
+ f"Unknown provider {provider!r}. Configured: "
2204
+ f"{', '.join(sorted(providers)) or 'none'}.")
2205
+ return
2206
+
2207
+ app.provider_name = provider
2208
+ app.model = model
2209
+ # §43 (RM3). The banner's marker describes the LAUNCH -- "this pair
2210
+ # came back from the store rather than from a config file". A pair
2211
+ # chosen a moment ago in this session is not that, whatever the
2212
+ # store now holds, so /new after a switch says the pair plainly.
2213
+ app._model_restored = False
2214
+ app.refresh_status()
2215
+ app._transcript.write_system(f"Now using {provider} | {model}.")
2216
+
2217
+ # §21's session overrides are per-model numbers, and a window tuned
2218
+ # for one model feeds the summarizer's truncation gate on the next.
2219
+ # Cleared rather than carried, and SAID rather than dropped quietly --
2220
+ # the same call the effort revalidation below makes, for the same
2221
+ # reason. Switching back does not restore them: that is the point of
2222
+ # clearing here rather than relying on the (provider, model) binding
2223
+ # alone, which would make them reappear.
2224
+ from core import session as _session
2225
+
2226
+ dropped = _session.clear()
2227
+ if dropped:
2228
+ app._transcript.write_system(
2229
+ f"Session {' and '.join(dropped)} override(s) cleared by the "
2230
+ f"switch — set them again if this model wants them.")
2231
+
2232
+ # WARN, don't refuse, on a missing key. An OpenAI-compatible endpoint
2233
+ # running locally legitimately takes no key, so refusing would block a
2234
+ # real configuration -- but every call to a hosted provider will fail
2235
+ # auth, and finding that out one turn later is the worse trade.
2236
+ if not providers[provider].get("API_KEY"):
2237
+ from credentials import missing_key_message
2238
+
2239
+ app._transcript.write_error(missing_key_message(provider))
2240
+
2241
+ # An active agent may name its own model/provider (§18), and those win
2242
+ # in run_agent_turn. Without this the switch is a silent no-op for as
2243
+ # long as that agent is active -- the failure shape this project keeps
2244
+ # producing.
2245
+ agent = app.active_agent
2246
+ if agent is not None and (agent.model or agent.provider):
2247
+ app._transcript.write_system(
2248
+ f"Note: agent {agent.name!r} pins "
2249
+ f"{agent.provider or app.provider_name} | "
2250
+ f"{agent.model or app.model} for chat turns, so this applies to "
2251
+ f"/research and to turns after /agent clear.")
2252
+
2253
+ # §43 (RM3). Remembered for the next launch, in the user-tier store
2254
+ # BESIDE settings.json -- never in it. Written here rather than in a
2255
+ # watcher (the theme's route, which exists because ctrl+p's command
2256
+ # palette sets App.theme directly): this command is the only thing
2257
+ # that changes the session's pair, so there is no second route to
2258
+ # miss.
2259
+ #
2260
+ # The confirmation is printed only on a write that landed, matching
2261
+ # /theme: a failure WARNED inside remember_model and reaches the
2262
+ # transcript through TranscriptLogHandler, and claiming a save that
2263
+ # did not happen is the one thing this must not do. The switch
2264
+ # itself applies either way.
2265
+ if preferences.remember_model(
2266
+ provider, model,
2267
+ app._settings.get("default_provider"),
2268
+ app._settings.get("default_model")):
2269
+ app._transcript.write_system("Remembered for the next launch.")
2270
+
2271
+ # Effort is per-model: a level the old model accepted may be rejected
2272
+ # outright by the new one, and every turn would then fail with a
2273
+ # provider 400. Same check the mount path runs on a persisted level.
2274
+ if app.effort:
2275
+ app.start_effort_lookup(None, validate_only=True)
2276
+
2277
+
2278
+ def _cmd_effort(app: VenastineApp, args: str) -> None:
2279
+ """Switch reasoning effort, offering only levels this model accepts.
2280
+
2281
+ The level set comes from effort_levels_for_model(), which QUERIES the
2282
+ Anthropic Models API and falls back to a static table elsewhere -- so a
2283
+ newly released Anthropic model needs no entry anywhere in this repo.
2284
+ The query runs in a worker (see start_effort_lookup); the answer comes
2285
+ back as an EffortLevelsReady message, so the UI stays live while a
2286
+ slow or unreachable Models API is waited on.
2287
+ """
2288
+ app.start_effort_lookup(args)
2289
+
2290
+
2291
+ def _cmd_research(app: VenastineApp, args: str) -> None:
2292
+ """Run the deep-research pipeline on a query, off the UI thread.
2293
+
2294
+ LIVE, not coarse. _start_research ITERATES
2295
+ stream_deep_research_pipeline() and forwards each PipelineEvent, so
2296
+ pass boundaries, trace lines, claim tiers and retry rounds arrive as
2297
+ they happen. The worker keeps the app responsive and the raven
2298
+ animating.
2299
+
2300
+ This docstring described the pre-§22 world in the present tense until
2301
+ audit #108 -- "coarse by construction ... the trace and report land
2302
+ when it returns" -- while _start_research 190 lines below said the
2303
+ opposite and explained why: draining would still work, but the DRAINER
2304
+ is exactly what throws every intermediate event away, which is what
2305
+ made this view coarse for two sections. (The synchronous wrapper that
2306
+ sentence named is retired; run_pipeline_to_completion is the drainer.)
2307
+
2308
+ §25: --grant [names] takes the same values as the CLI flag and goes
2309
+ through the same parser, so the two shells cannot offer different
2310
+ sets. Bare --grant opens the picker.
2311
+ """
2312
+ from core.reasoning.authorization import (
2313
+ candidates, parse_grant_spec, GrantSpecError,
2314
+ )
2315
+
2316
+ attended, review, grant_spec, query = _split_research_flags(args)
2317
+ if not attended:
2318
+ attended = app._settings.get("research", {}).get(
2319
+ "approval_mode") == "attended"
2320
+ if review is None:
2321
+ persisted = app._settings.get("research", {}).get("subagent_review")
2322
+ review = bool(persisted) if persisted is not None \
2323
+ else bool(config.SUBAGENT_REVIEW)
2324
+ app._research_attended = attended
2325
+ app._research_review = review
2326
+ if not query:
2327
+ app._transcript.write_error(
2328
+ "Usage: /research [--attended] [--review|--no-review] "
2329
+ "[--grant[=a,b]] <query>")
2330
+ return
2331
+ if app._busy:
2332
+ app._transcript.write_error("Still working — wait for this turn to finish.")
2333
+ return
2334
+
2335
+ offered = candidates()
2336
+ if grant_spec is GRANT_PICKER:
2337
+ if not offered:
2338
+ # #106. TWO independent axes (§25): a grant set, possibly
2339
+ # empty, and an ApprovalProvider, possibly absent. Passing
2340
+ # None collapses them -- §25 documents None as the pre-§25
2341
+ # status quo, "no grants, nobody to ask, every gated tool
2342
+ # hidden from every pass" -- so adding --grant to an
2343
+ # --attended run turned attended OFF.
2344
+ #
2345
+ # _authorization_for already returns None when attended is
2346
+ # off, so the no-flags case is unchanged, and the sibling
2347
+ # path below has always done exactly this.
2348
+ #
2349
+ # R13 made this branch the DEFAULT rather than a corner: with
2350
+ # every built-in either ungated, param-dependent or excluded
2351
+ # by policy, candidates() is empty until an MCP server
2352
+ # connects. What was config-dependent is now what happens on
2353
+ # a fresh clone.
2354
+ app._transcript.write_system(NOTHING_TO_GRANT)
2355
+ _start_research(app, query, _authorization_for(app, set()))
2356
+ return
2357
+
2358
+ def _picked(selected) -> None:
2359
+ # None means the user cancelled the RUN; an empty set means
2360
+ # "run, granting nothing". Two different answers.
2361
+ if selected is None:
2362
+ app._transcript.write_system("Research cancelled.")
2363
+ return
2364
+ _start_research(app, query, _authorization_for(app, selected))
2365
+
2366
+ app.push_screen(GrantPickerScreen(offered), _picked)
2367
+ return
2368
+
2369
+ granted = set()
2370
+ if grant_spec is not None:
2371
+ try:
2372
+ granted = parse_grant_spec(grant_spec, offered)
2373
+ except GrantSpecError as e:
2374
+ app._transcript.write_error(f"/research --grant: {e}")
2375
+ return
2376
+ _start_research(app, query, _authorization_for(app, granted))
2377
+
2378
+
2379
+ def _authorization_for(app: VenastineApp, granted: set):
2380
+ """A RunAuthorization for this run, or None when there is no
2381
+ authorization of any kind (the pre-§25 status quo)."""
2382
+ from core.approval import GrantBudget, RunAuthorization
2383
+
2384
+ provider = None
2385
+ if getattr(app, "_research_attended", False):
2386
+ # honour_run_scope=False (R11): a mode whose purpose is per-call
2387
+ # supervision must not let one yes cover later calls.
2388
+ provider = app.response_channel(honour_run_scope=False)
2389
+ app._transcript.write_system(
2390
+ "Attended: every approval-gated call will be asked about as it "
2391
+ f"happens; {config.ATTENDED_APPROVAL_TIMEOUT_S}s with no answer "
2392
+ "denies that call and the run continues.")
2393
+ if not granted:
2394
+ return RunAuthorization(provider=provider) if provider else None
2395
+ app._transcript.write_system(
2396
+ f"Authorised for this run only: {', '.join(sorted(granted))}. "
2397
+ f"Ceiling {config.MAX_GRANTED_TOOL_CALLS} granted calls; every use "
2398
+ f"is recorded in granted_calls.json.")
2399
+ return RunAuthorization(
2400
+ granted_tools=set(granted),
2401
+ provider=provider,
2402
+ budget=GrantBudget(config.MAX_GRANTED_TOOL_CALLS),
2403
+ )
2404
+
2405
+
2406
+ def _split_research_flags(args: str):
2407
+ """Strip leading /research flags off the query.
2408
+
2409
+ Returns (attended, review, grant_spec, query), where grant_spec is
2410
+ None (absent), GRANT_PICKER (bare flag), or the raw comma-separated
2411
+ string, and review is None (defer to settings) / True / False.
2412
+
2413
+ A LOOP over leading tokens, so --grant and --attended compose in
2414
+ either written order -- R10 makes the combination the useful case, and
2415
+ handling one flag then the other in a fixed sequence left
2416
+ `--grant --attended q` with "--attended q" as the research question.
2417
+
2418
+ Leading tokens only. `/research what does --grant do` stays a research
2419
+ question about the flag; treating it as an invocation would silently
2420
+ swallow the query. --grant-tools= is accepted as an alias for --grant=
2421
+ because that is the CLI's spelling for the same thing (the CLI needs
2422
+ two flag names because argparse would eat the query as an optional
2423
+ value; here the value is attached with =, so both names can mean one
2424
+ thing and muscle memory from either shell works).
2425
+ """
2426
+ text = (args or "").strip()
2427
+ attended = False
2428
+ review = None
2429
+ grant_spec = None
2430
+ while text:
2431
+ head, _sep, rest = text.partition(" ")
2432
+ if head == "--attended":
2433
+ attended = True
2434
+ elif head == "--review":
2435
+ review = True
2436
+ elif head == "--no-review":
2437
+ review = False
2438
+ elif head in ("--grant", "--grant-tools"):
2439
+ grant_spec = GRANT_PICKER
2440
+ elif head.startswith("--grant=") or head.startswith("--grant-tools="):
2441
+ grant_spec = head.split("=", 1)[1]
2442
+ else:
2443
+ break
2444
+ text = rest.strip()
2445
+ return attended, review, grant_spec, text
2446
+
2447
+
2448
+ def _review_consent_for(app: VenastineApp):
2449
+ """A ResponseChannel backed by the review modal, or None when the
2450
+ review is off. §20 V4/V6, §23 AC1.
2451
+
2452
+ A separate channel object from the approval one even though both route
2453
+ into `_ask_blocking`: §20 keeps "may this edit be applied?" apart from
2454
+ "may this call proceed?" because /research --review without --attended
2455
+ is a legitimate combination, and one shared object would make it
2456
+ unexpressible. §23 unified the mechanism, not the two parameters.
2457
+ """
2458
+ if not getattr(app, "_research_review", False):
2459
+ return None
2460
+ app._transcript.write_system(
2461
+ "Review: after the pipeline finishes, a reviewer checks its claims "
2462
+ "and report. Each proposed correction is yours to accept, reject or "
2463
+ f"refine; {config.ATTENDED_APPROVAL_TIMEOUT_S}s with no answer "
2464
+ "rejects that one and the review continues.")
2465
+ return app.response_channel()
2466
+
2467
+
2468
+ def _forwarding(app: "VenastineApp", events, outcome: dict):
2469
+ """Post every PipelineEvent to the UI thread, then pass it on.
2470
+
2471
+ A pass-through rather than a consumption loop, so the run's terminal
2472
+ event still reaches run_pipeline_to_completion() and the worker keeps
2473
+ receiving a finished PipelineRun. Forwarding and draining in two
2474
+ separate loops would mean either buffering the whole run before
2475
+ rendering any of it, or reimplementing the drainer here.
2476
+
2477
+ #105: when the app is shutting down, stop at the NEXT event rather
2478
+ than draining the remaining twenty minutes of pipeline. `outcome`
2479
+ records the abandonment for work(), which cannot otherwise
2480
+ distinguish this early StopIteration from a bug; closing the
2481
+ generator HERE makes the §22 semantics deterministic -- GeneratorExit
2482
+ at the current yield, so the record stays status='running' with every
2483
+ checkpoint it took, neither complete nor failed.
2484
+ """
2485
+ for event in events:
2486
+ if app._shutting_down:
2487
+ outcome["abandoned"] = True
2488
+ events.close()
2489
+ return
2490
+ app.post_message(PipelineEventMessage(event))
2491
+ yield event
2492
+
2493
+
2494
+ def _start_research(app: VenastineApp, query: str, authorization) -> None:
2495
+ """Kick off the worker. Split from _cmd_research because the picker
2496
+ path resolves asynchronously and lands here from a callback."""
2497
+ app._busy = True
2498
+ app._transcript.write_user(f"/research {query}")
2499
+ app._transcript.write_system("Running the ten-pass pipeline. This takes a while.")
2500
+ app._raven.state = ravens.THINKING
2501
+ app._research_progress.start_run()
2502
+ review_on = bool(getattr(app, "_research_review", False))
2503
+ consent = _review_consent_for(app)
2504
+
2505
+ def work() -> None:
2506
+ from core.reasoning.orchestrator import (
2507
+ run_pipeline_to_completion, stream_deep_research_pipeline,
2508
+ )
2509
+ from core.reasoning.output_writer import write_run_artifacts
2510
+ error = None
2511
+ try:
2512
+ # §22: ITERATED, not drained. A drainer would
2513
+ # still work and would still return the same run -- it is the
2514
+ # drainer applied to this generator -- but the drainer is
2515
+ # exactly what throws every intermediate event away, which is
2516
+ # what made this view coarse for two sections.
2517
+ events = stream_deep_research_pipeline(
2518
+ user_query=query,
2519
+ model=app.model,
2520
+ provider_name=app.provider_name,
2521
+ ensemble_mode=app._settings.get("ensemble_mode"),
2522
+ ensemble_n=app._settings.get("ensemble_n"),
2523
+ authorization=authorization,
2524
+ review=consent,
2525
+ subagent_review=review_on,
2526
+ # #139. The pipeline runs at the effort the session shows
2527
+ # in the status bar -- captured HERE, so a mid-run /effort
2528
+ # affects the next run, exactly like model/provider.
2529
+ effort=app.effort,
2530
+ )
2531
+ outcome = {}
2532
+ run = None
2533
+ try:
2534
+ run = run_pipeline_to_completion(
2535
+ _forwarding(app, events, outcome))
2536
+ except RuntimeError:
2537
+ if not outcome.get("abandoned"):
2538
+ raise
2539
+ # #105. The user quit; _forwarding stopped at its next
2540
+ # event and closed the generator, so the drainer saw no
2541
+ # terminal event -- §22's abandoned run, recorded
2542
+ # honestly as status='running'. NOT an error.
2543
+ if outcome.get("abandoned"):
2544
+ app.post_message(ResearchFinished(None, None,
2545
+ abandoned=True))
2546
+ return
2547
+ # §20 V9. write_run_artifacts had ONE production call site
2548
+ # (main.py), so a TUI research run produced no /output/<run_id>/
2549
+ # at all -- the shipped consequence of leaving a post-pipeline
2550
+ # stage to whichever shell remembers it. Best-effort, matching
2551
+ # the CLI: a disk failure must not discard a completed run --
2552
+ # but the outcome rides on the message so the summary cannot
2553
+ # assert a record that was never written (review r4-3).
2554
+ artifacts_ok = True
2555
+ try:
2556
+ write_run_artifacts(run)
2557
+ except Exception:
2558
+ logger.exception("Could not write artifacts")
2559
+ artifacts_ok = False
2560
+ app.post_message(ResearchFinished(run, None, artifacts_ok))
2561
+ except BaseException as e: # noqa: BLE001 — reported, then re-raised
2562
+ error = e
2563
+ app.post_message(ResearchFinished(None, e))
2564
+ if error is not None:
2565
+ raise error
2566
+
2567
+ app.run_worker(work, thread=True, exit_on_error=False, name="research")
2568
+
2569
+
2570
+ def _cmd_threads(app: VenastineApp, args: str) -> None:
2571
+ app.action_pick_thread()
2572
+
2573
+
2574
+ def _cmd_resume(app: VenastineApp, args: str) -> None:
2575
+ """#30/#32's other half. The picker caps at PICKER_THREAD_LIMIT, so
2576
+ "older conversations stay reachable" needs a by-id path in THIS shell
2577
+ -- the CLI has --thread <uuid> and the TUI had nothing. Goes through
2578
+ switch_to_thread, so a /resume gets exactly the load-reset-replay
2579
+ sequence, guards and all, that the picker's chosen() gets."""
2580
+ text = args.strip()
2581
+ if not text:
2582
+ app._transcript.write_error(
2583
+ "Usage: /resume <thread-id>. /threads lists recent ones.")
2584
+ return
2585
+ try:
2586
+ resolved = UUID(text)
2587
+ except ValueError:
2588
+ app._transcript.write_error(
2589
+ f"{text!r} is not a thread id (expected a uuid).")
2590
+ return
2591
+ app.switch_to_thread(resolved)
2592
+
2593
+
2594
+ def _cmd_new(app: VenastineApp, args: str) -> None:
2595
+ """Start a fresh thread and REDRAW the window (§43, RM2).
2596
+
2597
+ This used to swap the memory and write one line, leaving the
2598
+ previous conversation on screen under it -- two conversations
2599
+ concatenated, separated by a sentence, with only the second of them
2600
+ in the model's context. `switch_to_thread` had already solved
2601
+ exactly this for a resume ("CLEAR, then replay", §27 bug 1) and
2602
+ /new had none of it: not the transcript, and not the per-thread
2603
+ state beside it, so /copy all and /claims went on answering for the
2604
+ thread the session had left.
2605
+
2606
+ The refusal stays FIRST. Nothing is cleared on a turn that is still
2607
+ running, so a refused /new leaves the session exactly as it was.
2608
+
2609
+ What deliberately survives is the session: the active agent, the
2610
+ active skills (K5 -- a skill is a working mode, not a property of
2611
+ the thread), the effort level, the theme, and the provider/model a
2612
+ /model switch chose. That is why the banner is reprinted rather
2613
+ than remembered from mount: it states the pair the NEXT turn will
2614
+ use, which after a switch is not the pair the app launched with.
2615
+ The /ref attachments are thread state and leave with the thread.
2616
+ """
2617
+ if app._busy:
2618
+ app._transcript.write_error(
2619
+ "Still working — wait for this turn to finish.")
2620
+ return
2621
+ # None, not a fresh ConversationMemory: /new followed by /new should
2622
+ # not leave two empty threads behind. The next turn creates it.
2623
+ app.memory = None
2624
+ app.refresh_goal_banner()
2625
+ app.refresh_todo_panel()
2626
+ # switch_to_thread's list, for switch_to_thread's reasons: `/claims`
2627
+ # reads these, and a stale panel pointing at the wrong thread is
2628
+ # wrong where a blank one is merely unhelpful. `/copy last` is on the
2629
+ # same list through `_transcript.reset()` below, which drops the entry
2630
+ # log it reads.
2631
+ app._last_run = None
2632
+ app._live_claims = {}
2633
+ app._tool_names.clear()
2634
+ app._file_calls.clear()
2635
+ # State first, then the screen, then anything written -- so a
2636
+ # failure cannot leave the transcript cleared while the panels still
2637
+ # describe the previous thread.
2638
+ app._transcript.reset()
2639
+ app._write_session_banner()
2640
+ app._transcript.write_system("Started a new thread.")
2641
+
2642
+
2643
+ def _parse_token_count(text: str):
2644
+ """(tokens, error). Accepts 40000, 40k, 1m -- case-insensitively.
2645
+
2646
+ ONE parser for both commands, because two spellings of "how many
2647
+ tokens" is exactly how `/window 200k` and `/trigger 200000` end up
2648
+ meaning different things. Rejects anything it does not fully
2649
+ understand rather than salvaging a prefix: `/trigger 40kb` is a typo,
2650
+ and reading it as 40k would set a number the user did not ask for and
2651
+ then report success.
2652
+ """
2653
+ raw = text.strip().lower()
2654
+ if not raw:
2655
+ return None, "needs a number of tokens, e.g. 200000, 200k or 1m."
2656
+ multiplier = 1
2657
+ if raw[-1] in ("k", "m"):
2658
+ multiplier = 1_000 if raw[-1] == "k" else 1_000_000
2659
+ raw = raw[:-1]
2660
+ try:
2661
+ value = float(raw) if "." in raw else int(raw)
2662
+ except ValueError:
2663
+ return None, f"needs a number of tokens, got {text.strip()!r}."
2664
+ tokens = int(value * multiplier)
2665
+ if tokens < 1:
2666
+ return None, f"needs a positive number of tokens, got {tokens}."
2667
+ return tokens, None
2668
+
2669
+
2670
+ def _k(n: int) -> str:
2671
+ """Token counts the way the usage line writes them."""
2672
+ if n >= 1_000_000 and n % 100_000 == 0:
2673
+ return f"{n / 1_000_000:g}m"
2674
+ if n >= 1_000 and n % 100 == 0:
2675
+ return f"{n / 1_000:g}k"
2676
+ return f"{n:,}"
2677
+
2678
+
2679
+ def _cmd_window(app: VenastineApp, args: str) -> None:
2680
+ """Say what this model's context window really is, and remember it.
2681
+
2682
+ REMEMBERED AND BOUND TO THIS (provider, model), since batch 44. It is
2683
+ written to core/model_windows.py's user-tier store and survives a
2684
+ /model switch and a restart, because a context window is a FACT about
2685
+ a deployment rather than a preference about a session -- and a fact
2686
+ re-entered every launch is one nobody enters. Every pair is kept, so
2687
+ switching between two models does not ask again about either. A run on
2688
+ any other model -- an agent that pins its own (§18), a critic-routed
2689
+ pass (§11) -- uses that model's own window rather than this number.
2690
+
2691
+ WHAT IT MOVES, and this is more than it used to be: the chat
2692
+ compaction trigger, which batch 44 made a fraction of this number
2693
+ rather than a flat 40k; the research-pass backstop (context_limit -
2694
+ COMPACTION_PIPELINE_BACKSTOP_TOKENS); and the summarizer's one-call
2695
+ input budget. /trigger still overrides the first of those directly.
2696
+ """
2697
+ from core import model_windows
2698
+
2699
+ if not args:
2700
+ _report_override(app, "window")
2701
+ return
2702
+ if args.strip().lower() in ("off", "clear", "auto"):
2703
+ outcome = model_windows.forget_window(app.provider_name, app.model)
2704
+ if outcome == "removed":
2705
+ app._transcript.write_system(
2706
+ f"Remembered context window cleared for "
2707
+ f"{app.provider_name} | {app.model}.")
2708
+ elif outcome == "absent":
2709
+ app._transcript.write_system(
2710
+ "No remembered context window was set for this model.")
2711
+ else:
2712
+ # The WARNING inside forget_window has already reached the
2713
+ # transcript through TranscriptLogHandler; saying "cleared"
2714
+ # here would contradict a file the user can go and read.
2715
+ app._transcript.write_error(
2716
+ "The remembered context window could not be cleared.")
2717
+ return
2718
+
2719
+ tokens, error = _parse_token_count(args)
2720
+ if error:
2721
+ app._transcript.write_error(f"/window {error}")
2722
+ return
2723
+
2724
+ # Refused rather than warned: at or below the backstop margin,
2725
+ # compact_at clamps to its floor of 1 and every evaluation of a
2726
+ # research pass compacts. That is not a window anyone means to set.
2727
+ if tokens <= config.COMPACTION_PIPELINE_BACKSTOP_TOKENS:
2728
+ app._transcript.write_error(
2729
+ f"/window must exceed the pipeline backstop margin "
2730
+ f"({config.COMPACTION_PIPELINE_BACKSTOP_TOKENS:,}), or a research "
2731
+ f"pass would compact on every step. Got {tokens:,}.")
2732
+ return
2733
+
2734
+ saved = model_windows.remember_window(
2735
+ app.provider_name, app.model, tokens)
2736
+ app._transcript.write_system(
2737
+ f"Context window {_k(tokens)} for {app.provider_name} | "
2738
+ f"{app.model}.")
2739
+
2740
+ # WARN, never refuse, above what the provider reports. Raising it is
2741
+ # the best reason to have this command -- a gateway or a self-hosted
2742
+ # endpoint can report its own default rather than the deployment's
2743
+ # real window -- so refusing would block precisely the case it exists
2744
+ # for. The risk is named in the same terms config.py uses for the qwen
2745
+ # entry: erring high means a hard context-limit error mid-run.
2746
+ reported = _reported_window(app)
2747
+ if reported and tokens > reported:
2748
+ app._transcript.write_error(
2749
+ f"{app.provider_name} reports {reported:,} for this model. Above "
2750
+ f"the real window a run can fail with a hard context-limit error "
2751
+ f"mid-pass rather than compacting.")
2752
+
2753
+ # Claimed only on a write that landed, matching /theme and /model: a
2754
+ # failure has already WARNED inside remember_window and reached the
2755
+ # transcript through TranscriptLogHandler, so the command must not
2756
+ # also announce something it did not do.
2757
+ if saved:
2758
+ app._transcript.write_system(
2759
+ "Remembered for this model. /window off restores the derived "
2760
+ "value.")
2761
+
2762
+
2763
+ def _cmd_trigger(app: VenastineApp, args: str) -> None:
2764
+ """Override the working-set compaction ceiling for this session.
2765
+
2766
+ THE NUMBER THAT DECIDES WHEN THIS CHAT COMPACTS, as an ABSOLUTE size.
2767
+ Since batch 44 the DEFAULT it overrides is a fraction of the model's
2768
+ context window rather than a flat 40k, so setting an absolute here is
2769
+ now the exception rather than the shape of the thing. It is measured
2770
+ against the whole prompt the provider was sent -- system prompt, tool
2771
+ schemas, catalogs, memories, then the conversation -- not against the
2772
+ conversation alone.
2773
+
2774
+ EPHEMERAL, unlike /window, and that is the difference between them: a
2775
+ window is a fact about a deployment and is remembered, while this is a
2776
+ knob for a thread that is behaving badly. Bound to this
2777
+ (provider, model), cleared by /model, never written to disk.
2778
+ """
2779
+ from core import session
2780
+
2781
+ if not args:
2782
+ _report_override(app, session.TRIGGER)
2783
+ return
2784
+ if args.strip().lower() in ("off", "clear", "auto"):
2785
+ dropped = session.clear(session.TRIGGER)
2786
+ app._transcript.write_system(
2787
+ "Compaction-trigger override cleared." if dropped
2788
+ else "No compaction-trigger override was set.")
2789
+ return
2790
+
2791
+ tokens, error = _parse_token_count(args)
2792
+ if error:
2793
+ app._transcript.write_error(f"/trigger {error}")
2794
+ return
2795
+
2796
+ # Validated EAGERLY, against the same function the automatic path
2797
+ # uses, exactly as /compact does. Without this a too-small value is
2798
+ # accepted here and raises ValueError later inside should_compact() --
2799
+ # on the hot path, mid-turn, a long way from the command that caused
2800
+ # it. The message names which dependent floor blocks it.
2801
+ try:
2802
+ config_loader.effective_compaction({"trigger_tokens": tokens})
2803
+ except ValueError as e:
2804
+ app._transcript.write_error(f"/trigger {tokens:,} rejected: {e}")
2805
+ return
2806
+
2807
+ session.set_trigger(app.provider_name, app.model, tokens)
2808
+ app._transcript.write_system(
2809
+ f"Compaction trigger {_k(tokens)} for {app.provider_name} | "
2810
+ f"{app.model}, this session only.")
2811
+
2812
+ # Say it out loud when the thread is ALREADY over the new number. The
2813
+ # fold is legitimate and costs one compaction -- compact() returns
2814
+ # "no-progress" on every evaluation after it, so there is no runaway --
2815
+ # but arriving unannounced would read as the command having done
2816
+ # something it did not.
2817
+ # app._memory, NOT app.memory: the property CREATES a thread on first
2818
+ # use and persists a ConversationThread row. Setting a trigger before
2819
+ # the first message is a supported thing to do -- it is half of what
2820
+ # this command is for -- and doing it through the property would leave
2821
+ # the phantom empty thread that property's own docstring exists to
2822
+ # describe having fixed.
2823
+ used = app._memory.last_input_tokens if app._memory is not None else 0
2824
+ if used and used >= tokens:
2825
+ app._transcript.write_system(
2826
+ f"This thread is at {_k(used)}, so expect one compaction on the "
2827
+ f"next step.")
2828
+
2829
+ app._transcript.write_system(
2830
+ "Cleared by /model, or by /trigger off. Never saved.")
2831
+
2832
+
2833
+ def _reported_window(app: VenastineApp):
2834
+ """What the provider said for the mounted model, or None.
2835
+
2836
+ Cache-only (batch 30's known_context_window), so this never makes a
2837
+ call from a command handler on the UI thread.
2838
+ """
2839
+ try:
2840
+ from core.client import known_context_window
2841
+
2842
+ return known_context_window(app.provider_name, app.model)
2843
+ except Exception: # noqa: BLE001 -- a report must not fail the command
2844
+ return None
2845
+
2846
+
2847
+ def _report_override(app: VenastineApp, key: str) -> None:
2848
+ """The bare `/window` and `/trigger` form: the value AND where it came
2849
+ from.
2850
+
2851
+ Provenance is the point. Four sources can answer for the window and
2852
+ three for the trigger, and a number with no source attached is what
2853
+ makes someone edit the wrong one.
2854
+ """
2855
+ from core import compaction, session
2856
+
2857
+ if key == "window":
2858
+ from core import model_windows
2859
+
2860
+ effective = compaction.context_limit(app.model, app.provider_name)
2861
+ if model_windows.window_for(app.provider_name, app.model):
2862
+ source = f"remembered for {app.provider_name} | {app.model}"
2863
+ elif _reported_window(app) is not None:
2864
+ source = f"reported by {app.provider_name}"
2865
+ elif compaction._normalized(app.model) in config.MODEL_CONTEXT_WINDOWS:
2866
+ source = "config.MODEL_CONTEXT_WINDOWS"
2867
+ else:
2868
+ source = "config.DEFAULT_CONTEXT_WINDOW (no entry for this model)"
2869
+ app._transcript.write_system(
2870
+ f"Context window: {effective:,} — {source}.")
2871
+ app._transcript.write_system(
2872
+ "Usage: /window <tokens|off>. Moves the chat compaction "
2873
+ "trigger, the research-pass backstop and the summarizer's "
2874
+ "input budget.")
2875
+ return
2876
+
2877
+ entry = session.state().get(key)
2878
+
2879
+ _, compact_at = compaction.thresholds(
2880
+ app.model, provider_name=app.provider_name)
2881
+ source = (f"session override for {entry[0]} | {entry[1]}" if entry
2882
+ else "config/settings default")
2883
+ app._transcript.write_system(
2884
+ f"Compaction trigger: {compact_at:,} — {source}.")
2885
+ app._transcript.write_system(
2886
+ "Usage: /trigger <tokens|off>. An absolute prompt size, not a "
2887
+ "margin below the window.")
2888
+
2889
+
2890
+ def _parse_compact_args(args: str) -> tuple:
2891
+ """(overrides, error). ROADMAP_v2 §21's per-invocation override --
2892
+ applies to this one run and persists nothing, which is the last step
2893
+ of D27's resolution order.
2894
+
2895
+ An unrecognised flag is an ERROR, not something to ignore. Silently
2896
+ dropping `--strenght 4` would compact at the default strength while
2897
+ the user believes they asked for something else, and the result looks
2898
+ exactly like a compaction that obeyed them.
2899
+ """
2900
+ overrides: dict = {}
2901
+ tokens = args.split()
2902
+ index = 0
2903
+ while index < len(tokens):
2904
+ token = tokens[index]
2905
+ if token in ("--strength", "-s"):
2906
+ index += 1
2907
+ if index >= len(tokens):
2908
+ return None, "--strength needs a value from 1 to 5."
2909
+ try:
2910
+ overrides["strength"] = int(tokens[index])
2911
+ except ValueError:
2912
+ return None, f"--strength needs a number, got {tokens[index]!r}."
2913
+ elif token.startswith("--strength="):
2914
+ value = token.split("=", 1)[1]
2915
+ try:
2916
+ overrides["strength"] = int(value)
2917
+ except ValueError:
2918
+ return None, f"--strength needs a number, got {value!r}."
2919
+ else:
2920
+ return None, f"Unknown option {token!r}. Usage: /compact [--strength N]"
2921
+ index += 1
2922
+ return overrides, None
2923
+
2924
+
2925
+ def _cmd_compact(app: VenastineApp, args: str) -> None:
2926
+ """Compact the current thread now, rather than waiting for the
2927
+ trigger. §21: a user-facing summary is the same machinery invoked
2928
+ deliberately instead of by a token threshold.
2929
+
2930
+ Runs on a worker because it is a model call. Nothing here bypasses the
2931
+ floors -- a manual compaction protects the recent turns exactly as an
2932
+ automatic one does, since "summarize this conversation" and "throw
2933
+ away what I just said" are different requests.
2934
+ """
2935
+ if app._busy:
2936
+ app._transcript.write_error(
2937
+ "Still working — wait for this turn to finish.")
2938
+ return
2939
+ if app._memory is None:
2940
+ app._transcript.write_error("Nothing to compact — this thread is empty.")
2941
+ return
2942
+
2943
+ overrides, error = _parse_compact_args(args)
2944
+ if error:
2945
+ app._transcript.write_error(error)
2946
+ return
2947
+ try:
2948
+ # Validate BEFORE spending a model call, and against the same
2949
+ # function the automatic path uses, so `/compact --strength 9`
2950
+ # reports the range rather than failing inside a worker.
2951
+ config_loader.effective_compaction(overrides)
2952
+ except ValueError as e:
2953
+ app._transcript.write_error(str(e))
2954
+ return
2955
+
2956
+ memory = app.memory
2957
+ app._busy = True
2958
+ app._transcript.write_system("Compacting this conversation…")
2959
+
2960
+ def _work() -> None:
2961
+ from core import compaction
2962
+ try:
2963
+ outcome = compaction.compact(
2964
+ memory, app.model, app.provider_name, overrides=overrides)
2965
+ except Exception as e: # noqa: BLE001 — same containment as the loop's
2966
+ app.call_from_thread(
2967
+ app._transcript.write_error, f"Compaction failed: {e}")
2968
+ return
2969
+ finally:
2970
+ app.call_from_thread(setattr, app, "_busy", False)
2971
+ # Batch 16 (#44): compact() reports EVERY outcome as data now --
2972
+ # folded, blocked, all-pinned, missing-agent, no-progress,
2973
+ # reentrant, failed (#136: the empty-summary outcome, which also
2974
+ # carries kind=compaction_failed now) -- each carrying its own
2975
+ # line, so a manual /compact can never answer "nothing happened"
2976
+ # for five different reasons.
2977
+ app.call_from_thread(app._transcript.write_system,
2978
+ f"— {outcome['text']} —")
2979
+
2980
+ app.run_worker(_work, thread=True, exit_on_error=False, name="compact")
2981
+
2982
+
2983
+ def _cmd_claims(app: VenastineApp, args: str) -> None:
2984
+ """Open the claims view for this session's run, or a stored one."""
2985
+ app.show_claims(args.strip())
2986
+
2987
+
2988
+ # Narrow to broad, which is the order /help prints them in. `all` stays
2989
+ # last because it is the superset (#140): the transcript entire, plus the
2990
+ # report and the claims that never reach it.
2991
+ _COPY_TARGETS = ("last", "report", "claims", "conversation", "all")
2992
+
2993
+ # (#30/#32) The picker caps its list and says so; older threads stay
2994
+ # reachable by id through /resume. A modal listing thousands of rows is
2995
+ # its own usability defect, and with activity ordering the cap costs the
2996
+ # least it can -- the threads most likely to be wanted survive it.
2997
+ PICKER_THREAD_LIMIT = 200
2998
+
2999
+
3000
+ def _cmd_copy(app: VenastineApp, args: str) -> None:
3001
+ """Copy something out of the session (§26).
3002
+
3003
+ Exists because the pinned textual (1.0.0) has NO text selection --
3004
+ App.ALLOW_SELECT and RichLog.allow_select arrived in 3.x -- so there
3005
+ is no way to get text out of the transcript at all. That is a
3006
+ dependency ceiling rather than a styling problem, which is why the
3007
+ answer is a command rather than a widget setting.
3008
+
3009
+ App.copy_to_clipboard writes OSC 52, and OSC 52 CANNOT BE CONFIRMED:
3010
+ the terminal either honours the escape sequence or silently ignores
3011
+ it, and nothing comes back either way. Windows Terminal supports it;
3012
+ some multiplexers strip it. So the message below says what was sent
3013
+ rather than claiming it arrived, and --file is the route that provably
3014
+ worked -- reporting a false success with no recourse is the worse
3015
+ failure, since the user only finds out when they paste.
3016
+ """
3017
+ target, path, error = _parse_copy_args(args)
3018
+ if error:
3019
+ app._transcript.write_error(error)
3020
+ return
3021
+
3022
+ text, described = _copy_payload(app, target)
3023
+ if text is None:
3024
+ app._transcript.write_error(f"Nothing to copy: {described}.")
3025
+ return
3026
+
3027
+ if path is not None:
3028
+ try:
3029
+ written = Path(path).expanduser()
3030
+ written.write_text(text, encoding="utf-8")
3031
+ except OSError as e:
3032
+ app._transcript.write_error(f"Could not write {path}: {e}")
3033
+ return
3034
+ app._transcript.write_system(
3035
+ f"Wrote {described} ({len(text)} chars) to {written}.")
3036
+ return
3037
+
3038
+ app.copy_to_clipboard(text)
3039
+ app._transcript.write_system(
3040
+ f"Sent {described} ({len(text)} chars) to the clipboard. If nothing "
3041
+ f"pastes, this terminal is dropping OSC 52 — use "
3042
+ f"/copy {target} --file <path>.")
3043
+
3044
+
3045
+ _COPY_USAGE = (f"Usage: /copy [{'|'.join(_COPY_TARGETS)}] [--file <path>]")
3046
+
3047
+
3048
+ def _parse_copy_args(args: str):
3049
+ """(target, path, error). `path` is None when --file was not given.
3050
+
3051
+ Same shape as _parse_compact_args above, including that an
3052
+ unrecognised option is an ERROR rather than something to ignore --
3053
+ silently dropping `--fiel out.txt` would send the text to a clipboard
3054
+ the user has just said they cannot use, and report success.
3055
+ """
3056
+ tokens = args.split()
3057
+ target = "last"
3058
+ index = 0
3059
+ if tokens and not tokens[0].startswith("--"):
3060
+ target = tokens[0].lower()
3061
+ index = 1
3062
+ path = None
3063
+ while index < len(tokens):
3064
+ token = tokens[index]
3065
+ if token == "--file":
3066
+ index += 1
3067
+ if index >= len(tokens):
3068
+ return None, None, f"--file needs a path. {_COPY_USAGE}"
3069
+ path = tokens[index]
3070
+ elif token.startswith("--file="):
3071
+ path = token.split("=", 1)[1]
3072
+ if not path:
3073
+ return None, None, f"--file needs a path. {_COPY_USAGE}"
3074
+ else:
3075
+ return None, None, f"Unknown option {token!r}. {_COPY_USAGE}"
3076
+ index += 1
3077
+ if target not in _COPY_TARGETS:
3078
+ return None, None, f"Unknown copy target {target!r}. {_COPY_USAGE}"
3079
+ return target, path, None
3080
+
3081
+
3082
+ def _copy_payload(app: VenastineApp, target: str):
3083
+ """(text, description), with text None when there is nothing."""
3084
+ if target == "last":
3085
+ # From the transcript's entry log, not from a field beside it --
3086
+ # see Transcript.last_answer for what the field got wrong.
3087
+ return (app._transcript.last_answer() or None), "the last response"
3088
+ if target == "report":
3089
+ run = app._last_run
3090
+ return ((run.final_report if run and run.final_report else None),
3091
+ "the research report")
3092
+ if target == "conversation":
3093
+ # Batch 48. `/copy all` is everything on screen, harness lines
3094
+ # included, and that is what its name promises and what #140
3095
+ # settled. But the thing most often wanted is the exchange
3096
+ # without /help's output, without `Resumed thread <uuid>.`,
3097
+ # without `— end of N replayed entries —` and without the
3098
+ # banner -- so that is a target of its own rather than a
3099
+ # narrowing of the one whose name says everything.
3100
+ return (app._transcript.as_text(CONVERSATION_ROLES).strip() or None,
3101
+ "this conversation")
3102
+ if target == "claims":
3103
+ run = app._last_run
3104
+ claims = ([vars(c) for c in run.claims] if run and run.claims
3105
+ else list(app._live_claims.values()))
3106
+ if not claims:
3107
+ return None, "the claim list"
3108
+ return json.dumps(claims, indent=2, default=str), "the claim list"
3109
+ # all
3110
+ # #140: "all" is a SUPERSET, not just the transcript. The transcript
3111
+ # never carries the claims (on_research_finished advertises them as
3112
+ # one line pointing at /claims), and it carries the report only as
3113
+ # rendered answer text -- so before this change the one target whose
3114
+ # name promised everything carried the least. Sections are omitted
3115
+ # when there is nothing in them; with no run at all this is exactly
3116
+ # the payload it always produced.
3117
+ parts = [app._transcript.as_text() or ""]
3118
+ run = app._last_run
3119
+ if run is not None and run.final_report:
3120
+ parts.append("\n\n## Report\n\n" + run.final_report)
3121
+ claims = ([vars(c) for c in run.claims] if run is not None and run.claims
3122
+ else list(app._live_claims.values()))
3123
+ if claims:
3124
+ parts.append("\n\n## Claims\n\n"
3125
+ + json.dumps(claims, indent=2, default=str))
3126
+ return ("".join(parts).strip() or None), "this session"
3127
+
3128
+
3129
+ def _cmd_thinking(app: VenastineApp, args: str) -> None:
3130
+ """Show or hide reasoning inline for this session (§38).
3131
+
3132
+ Persists nothing, matching /effort and /model -- `tui.show_thinking`
3133
+ in settings.json is the durable answer, and batch 36's rule is that
3134
+ nothing writes to that file. Unlike /effort this is safe mid-turn, so
3135
+ there is no _busy refusal: it takes effect on the next span, and the
3136
+ current one is closed cleanly in whichever form it was being shown.
3137
+ """
3138
+ word = args.strip().lower()
3139
+ if not word:
3140
+ state = "shown" if app._show_thinking else "hidden"
3141
+ app._transcript.write_system(
3142
+ f"[thinking is {state} — /thinking on|off]")
3143
+ return
3144
+ if word in ("on", "show", "true"):
3145
+ wanted = True
3146
+ elif word in ("off", "hide", "false"):
3147
+ wanted = False
3148
+ else:
3149
+ app._transcript.write_error(
3150
+ f"[unknown option {word!r} — /thinking [on|off]]")
3151
+ return
3152
+ if wanted == app._show_thinking:
3153
+ app._transcript.write_system(
3154
+ f"[thinking already {'shown' if wanted else 'hidden'}]")
3155
+ return
3156
+ # Close the live span BEFORE the flag moves, so it ends in the form it
3157
+ # was drawn in rather than half in each.
3158
+ app._end_thinking()
3159
+ app._show_thinking = wanted
3160
+ app._transcript.write_system(
3161
+ f"[thinking {'shown' if wanted else 'hidden'} for this session; "
3162
+ f"set tui.show_thinking in settings.json to keep it]")
3163
+
3164
+
3165
+ def _cmd_quit(app: VenastineApp, args: str) -> None:
3166
+ app.exit()
3167
+
3168
+
3169
+ # ---------------------------------------------------------------------------
3170
+ # ---- §45 (SQ7): the two pipeline model roles that are not the session model
3171
+ # ---------------------------------------------------------------------------
3172
+ #
3173
+ # `/critic` and `/embedder` are `_cmd_model` with one difference each, so
3174
+ # the parsing, the provider check and the busy refusal are shared rather
3175
+ # than written twice. What differs is what a role MEANS when it is unset:
3176
+ # an absent critic silently routes every pass to the generator, which is
3177
+ # the thing §11 exists to prevent; an absent embedder falls back to the
3178
+ # grounding model's own similarity, which §45 designed for and warns about
3179
+ # once per run.
3180
+
3181
+
3182
+ def _pipeline_role_args(app: VenastineApp, args: str, command: str):
3183
+ """(provider, model) for a `/critic`-shaped command, or None.
3184
+
3185
+ None means the handler has already written the reason. Shared with
3186
+ `_cmd_model`'s rules verbatim -- an unknown provider REFUSES, because
3187
+ api_initialization would raise the same ValueError on the next run, a
3188
+ long way from the typo that caused it.
3189
+ """
3190
+ from credentials import load_provider_data
3191
+
3192
+ parts = args.split()
3193
+ if len(parts) == 1:
3194
+ provider, model = app.provider_name, parts[0]
3195
+ elif len(parts) == 2:
3196
+ provider, model = parts[0].upper(), parts[1]
3197
+ else:
3198
+ app._transcript.write_error(
3199
+ f"Usage: /{command} <name>, or /{command} <PROVIDER> <name>, "
3200
+ f"or /{command} off.")
3201
+ return None
3202
+
3203
+ providers = load_provider_data()
3204
+ if provider not in providers:
3205
+ app._transcript.write_error(
3206
+ f"Unknown provider {provider!r}. Configured: "
3207
+ f"{', '.join(sorted(providers)) or 'none'}.")
3208
+ return None
3209
+ if not providers[provider].get("API_KEY"):
3210
+ # WARN, don't refuse -- _cmd_model's rule. An OpenAI-compatible
3211
+ # endpoint running locally legitimately takes no key.
3212
+ from credentials import missing_key_message
3213
+
3214
+ app._transcript.write_error(missing_key_message(provider))
3215
+ return provider, model
3216
+
3217
+
3218
+ def _clear_pipeline_role(app: VenastineApp, role: str, label: str) -> None:
3219
+ """`/critic off`. Three outcomes, because the store has three.
3220
+
3221
+ "Cleared" is not the same as "unset": config.py may still answer, and
3222
+ saying otherwise would be a lie about behaviour the next run will
3223
+ show. So the sentence names what is in force AFTERWARDS.
3224
+ """
3225
+ from core import pipeline_models
3226
+
3227
+ outcome = pipeline_models.forget(role)
3228
+ if outcome == "failed":
3229
+ # The WARNING inside forget() has already reached the transcript
3230
+ # through TranscriptLogHandler.
3231
+ app._transcript.write_error(f"The remembered {label} could not be cleared.")
3232
+ return
3233
+ if outcome == "absent":
3234
+ app._transcript.write_system(f"No {label} was remembered.")
3235
+ else:
3236
+ app._transcript.write_system(f"Remembered {label} cleared.")
3237
+ remaining = pipeline_models.resolve(role)
3238
+ if remaining:
3239
+ app._transcript.write_system(
3240
+ f"config.py still sets {label}: {remaining['provider_name']} | "
3241
+ f"{remaining['model']}.")
3242
+
3243
+
3244
+ def _cmd_critic(app: VenastineApp, args: str) -> None:
3245
+ """Route the grounding and critic passes to a different model.
3246
+
3247
+ §11's routing, finally reachable without editing the checkout (§45,
3248
+ SQ7). It has always been `config.CRITIC_MODEL` and nothing else, which
3249
+ made this project's own stated methodology -- "a model checking its
3250
+ own output for errors shares that model's blind spots" -- available
3251
+ only to whoever could edit installed source.
3252
+
3253
+ Applies to Pass 3a, Pass 3b and Pass 6b. It takes effect on the NEXT
3254
+ run: the pipeline resolves the pair when it starts, so a run already
3255
+ in flight keeps the critic it began with. That is also why this
3256
+ refuses while busy.
3257
+
3258
+ NOT cleared by /model, unlike §21's per-model session overrides. The
3259
+ whole point of a critic is that it is a DIFFERENT model from the
3260
+ generator; clearing it when the generator changes would silently
3261
+ restore the arrangement it exists to avoid.
3262
+ """
3263
+ from core import pipeline_models
3264
+
3265
+ if not args:
3266
+ current = pipeline_models.resolve("critic")
3267
+ if current:
3268
+ source = ("remembered" if pipeline_models.remembered("critic")
3269
+ else "config.py")
3270
+ app._transcript.write_system(
3271
+ f"Critic model: {current['provider_name']} | "
3272
+ f"{current['model']} ({source}).")
3273
+ else:
3274
+ app._transcript.write_system(
3275
+ f"No critic model set — passes 3a, 3b and 6b run on "
3276
+ f"{app.provider_name} | {app.model}, the same model that "
3277
+ f"generated the claims.")
3278
+ app._transcript.write_system(
3279
+ "Usage: /critic <name>, or /critic <PROVIDER> <name>, or "
3280
+ "/critic off.")
3281
+ return
3282
+
3283
+ if app._busy:
3284
+ app._transcript.write_error(
3285
+ "Still working — wait for this turn to finish.")
3286
+ return
3287
+
3288
+ if args.strip().lower() in ("off", "clear", "auto", "none"):
3289
+ _clear_pipeline_role(app, "critic", "critic model")
3290
+ return
3291
+
3292
+ resolved = _pipeline_role_args(app, args, "critic")
3293
+ if resolved is None:
3294
+ return
3295
+ provider, model = resolved
3296
+
3297
+ app._transcript.write_system(
3298
+ f"Critic model set to {provider} | {model}. Passes 3a, 3b and 6b "
3299
+ f"will use it from the next research run.")
3300
+ if provider == app.provider_name and model == app.model:
3301
+ # Said, not refused. A single-model setup is a legitimate thing to
3302
+ # want; silently accepting it while §11's rationale says the
3303
+ # opposite is what would be wrong.
3304
+ app._transcript.write_error(
3305
+ "That is the same model that generates the claims, so the "
3306
+ "critic passes will share its blind spots — which is the "
3307
+ "arrangement critic routing exists to avoid.")
3308
+ if pipeline_models.remember("critic", provider, model):
3309
+ app._transcript.write_system("Remembered for the next launch.")
3310
+
3311
+
3312
+ def _cmd_embedder(app: VenastineApp, args: str) -> None:
3313
+ """Choose the model that scores how close a source is to a claim.
3314
+
3315
+ §45 (SQ2). Without one, `similarity_score` is the grounding model's
3316
+ own estimate of how well a source it chose supports a claim it is
3317
+ checking, under an anchored rubric. With one, it is a cosine between
3318
+ the claim and the passage the source actually contains.
3319
+
3320
+ THE SELECTION IS PROBED, not looked up in a table. A one-token
3321
+ embedding validates the provider, the model slug and the key in a
3322
+ single measurement and reports the dimension; a static
3323
+ `supports_embeddings` list would be a guess that goes stale as
3324
+ providers add endpoints, and the failure it guesses wrong about
3325
+ arrives three passes into a research run. The probe runs in a worker
3326
+ for `start_effort_lookup`'s reason -- an HTTP call on the UI thread
3327
+ freezes the whole app until it returns.
3328
+ """
3329
+ from core import pipeline_models
3330
+
3331
+ if not args:
3332
+ current = pipeline_models.resolve("embedder")
3333
+ if current:
3334
+ source = ("remembered" if pipeline_models.remembered("embedder")
3335
+ else "config.py")
3336
+ app._transcript.write_system(
3337
+ f"Embedder: {current['provider_name']} | {current['model']} "
3338
+ f"({source}).")
3339
+ else:
3340
+ app._transcript.write_system(
3341
+ "No embedder set — source similarity is scored by the "
3342
+ "grounding model itself, which is a self-report. Set one "
3343
+ "for an objective cosine.")
3344
+ app._transcript.write_system(
3345
+ "Usage: /embedder <name>, or /embedder <PROVIDER> <name>, or "
3346
+ "/embedder off.")
3347
+ return
3348
+
3349
+ if app._busy:
3350
+ app._transcript.write_error(
3351
+ "Still working — wait for this turn to finish.")
3352
+ return
3353
+
3354
+ if args.strip().lower() in ("off", "clear", "auto", "none"):
3355
+ _clear_pipeline_role(app, "embedder", "embedder")
3356
+ return
3357
+
3358
+ resolved = _pipeline_role_args(app, args, "embedder")
3359
+ if resolved is None:
3360
+ return
3361
+ provider, model = resolved
3362
+
3363
+ app._transcript.write_system(f"Checking {provider} | {model}…")
3364
+ app.start_embedder_probe(provider, model)
3365
+
3366
+
3367
+ def register_builtin_commands() -> None:
3368
+ """Idempotent — registering by name overwrites, so a re-import or a
3369
+ second app instance in the test suite does not duplicate entries."""
3370
+ for command in (
3371
+ SlashCommand("help", "list commands", _cmd_help),
3372
+ SlashCommand("theme", "switch colour theme", _cmd_theme, "[name]"),
3373
+ SlashCommand("effort", "switch reasoning effort", _cmd_effort, "[level|auto]"),
3374
+ SlashCommand("thinking", "show or hide reasoning inline",
3375
+ _cmd_thinking, "[on|off]"),
3376
+ SlashCommand("model", "switch provider and/or model for this session",
3377
+ _cmd_model, "[[PROVIDER] name]"),
3378
+ SlashCommand("critic", "route the grounding and critic passes to another model",
3379
+ _cmd_critic, "[[PROVIDER] name|off]"),
3380
+ SlashCommand("embedder", "choose the model that scores source similarity",
3381
+ _cmd_embedder, "[[PROVIDER] name|off]"),
3382
+ SlashCommand("research", "run the deep-research pipeline",
3383
+ _cmd_research,
3384
+ "[--attended] [--review|--no-review] "
3385
+ "[--grant[=a,b]] <query>"),
3386
+ SlashCommand("compact", "summarize this conversation's older turns now",
3387
+ _cmd_compact, "[--strength 1-5]"),
3388
+ SlashCommand("window", "override this model's context window for the session",
3389
+ _cmd_window, "[tokens|off]"),
3390
+ SlashCommand("trigger", "override when this chat compacts, for the session",
3391
+ _cmd_trigger, "[tokens|off]"),
3392
+ SlashCommand("claims", "show a research run's claims and their tiers",
3393
+ _cmd_claims, "[run id]"),
3394
+ SlashCommand("copy", "copy text out of the session", _cmd_copy,
3395
+ f"[{'|'.join(_COPY_TARGETS)}] [--file <path>]"),
3396
+ SlashCommand("threads", "resume a saved thread", _cmd_threads),
3397
+ SlashCommand("resume", "resume a thread by id, even an old one",
3398
+ _cmd_resume, "<thread-id>"),
3399
+ SlashCommand("new", "start a new thread", _cmd_new),
3400
+ SlashCommand("quit", "exit", _cmd_quit),
3401
+ ):
3402
+ commands.register(command)
3403
+
3404
+
3405
+ register_builtin_commands()
3406
+ register_agent_commands() # §18: /agent, /goal, /grill-me
3407
+ register_skill_commands() # §19: /skill
3408
+ register_memory_commands() # §21b: /memories, /forget
3409
+ register_init_commands() # §24: /init
3410
+
3411
+
3412
+ def run(provider_name: str, model: str, settings: dict | None = None,
3413
+ cli_pinned: bool = False) -> None:
3414
+ """Entry point used by main.py --tui.
3415
+
3416
+ `cli_pinned` says whether --provider/--model named this launch's
3417
+ pair (§43, RM3). main.resolve_runtime_defaults has already collapsed
3418
+ the flags into `provider_name`/`model` by here, so the app cannot
3419
+ tell by looking -- and a flag has to outrank a remembered choice.
3420
+ """
3421
+ config_loader_settings = settings if settings is not None else config_loader.get_settings()
3422
+ VenastineApp(provider_name, model, config_loader_settings,
3423
+ cli_pinned=cli_pinned).run()