@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/main.py ADDED
@@ -0,0 +1,1959 @@
1
+ """
2
+ main.py
3
+
4
+ Interactive CLI entry point (ROADMAP §1). Two modes:
5
+
6
+ $ python main.py # new chat thread
7
+ $ python main.py --thread <uuid> # resume a thread
8
+ $ python main.py --mode research "some query" # deep-research pipeline
9
+ $ python main.py --provider OPENAI --model gpt-5.1 # override defaults
10
+
11
+ Chat mode runs a read/print loop with tool use, reading through the one
12
+ _StdinReader every prompt in this module shares (§29 N1). Ctrl+C or Ctrl+D
13
+ to exit. The thread id is printed after the first response so it can be
14
+ resumed later with --thread.
15
+
16
+ Research mode runs the full ten-pass pipeline and prints the final
17
+ report + trace log.
18
+
19
+ A feature-rich Textual TUI is planned as a separate effort; this CLI is
20
+ the permanent fallback entry point.
21
+ """
22
+
23
+ import argparse
24
+ import logging
25
+ import os
26
+ import sys
27
+ from uuid import UUID
28
+
29
+ import config
30
+ from core import config_loader, workspace_trust
31
+ from core.loop import RunAgentLoop, DEFAULT_PROVIDER
32
+ from core.reasoning.authorization import GRANT_PICKER
33
+ from core.replay import replay_entries
34
+ from database import create_db_and_tables, engine
35
+ from logging_setup import configure_logging
36
+ from security import posture, protected_paths
37
+
38
+ # Importing these for their SIDE EFFECT, and the side effect is load-bearing:
39
+ # a SQLModel table class registers on SQLModel.metadata when its module is
40
+ # imported, and create_db_and_tables() creates only what is registered by the
41
+ # time it runs. database.py deliberately knows nothing about what tables exist
42
+ # (ARCHITECTURE §4.4), so declaring them is the entry point's job.
43
+ #
44
+ # storage was already reaching metadata by luck -- core.loop -> core.memory ->
45
+ # storage, above. pipeline_storage was NOT: main.py imports the orchestrator
46
+ # lazily inside run_research(), which is after create_db_and_tables() has
47
+ # already run, so a FRESH database never got a pipelinerunrecord table and the
48
+ # first research run died on "no such table". Do not "tidy" these away.
49
+ import storage # noqa: F401 -- registers ConversationThread, MessageLog
50
+ import core.reasoning.pipeline_storage # noqa: F401 -- registers PipelineRunRecord
51
+
52
+ logger = logging.getLogger(__name__)
53
+
54
+
55
+ def _uuid_type(value: str) -> UUID:
56
+ """Argparse type validator for --thread. Produces a clear CLI error
57
+ for a malformed UUID instead of a traceback from deep in storage."""
58
+ try:
59
+ return UUID(value)
60
+ except ValueError:
61
+ raise argparse.ArgumentTypeError(
62
+ f"'{value}' is not a valid UUID. "
63
+ f"Thread ids look like: 550e8400-e29b-41d4-a716-446655440000"
64
+ )
65
+
66
+
67
+ def _print_replay(thread_id: UUID) -> None:
68
+ """Print a resumed thread's history (§27 T5).
69
+
70
+ Labels match the live chat loop's own -- "You:" / "Agent:" -- so a
71
+ replayed turn and a fresh one are not two different-looking things in
72
+ the same scrollback. What may be shown is core/replay.py's decision,
73
+ not this function's; the shells must not disagree about that.
74
+
75
+ §44's reasoning entries get a label of their own. Unlabelled they
76
+ would arrive under the same anonymous indent as a tool line, and a
77
+ paragraph of prose reading as a tool call is worse than not showing
78
+ it. D12 keeps this shell a real fallback, so it renders what the TUI
79
+ renders -- it simply has no tui.show_thinking to consult.
80
+ """
81
+ try:
82
+ entries = replay_entries(thread_id)
83
+ except Exception as e: # noqa: BLE001 -- a display failure must not
84
+ # stop the session: the thread is loaded and usable either way.
85
+ logger.warning("Could not replay thread %s: %s", thread_id, e)
86
+ print(f"[could not replay this thread's history: {e}]")
87
+ return
88
+ if not entries:
89
+ print("(this thread has no messages yet)")
90
+ return
91
+ print()
92
+ for role, text in entries:
93
+ if role == "user":
94
+ print(f"You: {text}")
95
+ elif role == "assistant":
96
+ print(f"\nAgent: {text}\n")
97
+ elif role == "thinking":
98
+ print(f"\nThinking: {text}")
99
+ else:
100
+ print(f" {text}")
101
+ noun = "entry" if len(entries) == 1 else "entries"
102
+ print(f"--- end of {len(entries)} replayed {noun} ---")
103
+
104
+
105
+
106
+ def _announce_posture() -> None:
107
+ """Say, at every launch, which shipped protections are off (§40 UN3).
108
+
109
+ Two sinks because they reach different people. The WARNING goes to
110
+ app.log and, on the CLI, to stderr through the root handler -- it is
111
+ the record a bug report is triaged against. The stderr banner is for
112
+ the human at the terminal, who may have set one of these months ago
113
+ and forgotten, or may have inherited a config.py from somewhere.
114
+
115
+ Silent when the posture is shipped, so this costs nothing in the case
116
+ that needs nothing said. That is also why it reads `unsafe_reasons()`
117
+ rather than testing the flags here: three surfaces describing one
118
+ state in three slightly different ways is how a user ends up
119
+ trusting whichever is wrong, and §37 F4 already made this argument
120
+ for the per-server auto-approve warning.
121
+ """
122
+ reasons = posture.current().unsafe_reasons()
123
+ if not reasons:
124
+ return
125
+ print("", file=sys.stderr)
126
+ print(" !! REDUCED SECURITY POSTURE -- set in config.py", file=sys.stderr)
127
+ for _label, detail in reasons:
128
+ logger.warning("Reduced security posture: %s", detail)
129
+ print(f" - {detail}", file=sys.stderr)
130
+ print("", file=sys.stderr)
131
+
132
+
133
+ def run_chat(
134
+ thread_id: UUID | None,
135
+ provider_name: str,
136
+ model: str,
137
+ first_message: str | None = None,
138
+ effort: str | None = None,
139
+ ) -> None:
140
+ """Interactive chat loop. If first_message is given (positional arg
141
+ in chat mode), it's sent as the first user turn before dropping into
142
+ the interactive loop.
143
+
144
+ Batch 25 (#139): `effort` is the resolved level (resolve_effort). It
145
+ rides every run_agent_conversation call and is printed in the header,
146
+ because a setting that shapes every answer should be visible where the
147
+ provider and model are."""
148
+ current_thread_id = thread_id
149
+ printed_thread_id = False
150
+ # §21b M16. Built once for the session rather than per turn: the
151
+ # provider wraps the single _stdin_reader, and building one per turn
152
+ # would be a new object round the same reader for no gain. None on a
153
+ # non-tty, which keeps a piped run headless exactly as before.
154
+ authorization = build_chat_authorization()
155
+
156
+ print("Venastine Research Harness — chat mode.")
157
+ print(f"Provider: {provider_name} | Model: {model} | "
158
+ f"Effort: {effort or 'auto'}")
159
+ if current_thread_id:
160
+ print(f"Resuming thread: {current_thread_id}")
161
+ # §27 AC4/T5. --thread had the same gap as the TUI picker: the
162
+ # history loaded and nothing showed it, so a resumed conversation
163
+ # was indistinguishable from a new one until the model answered
164
+ # with context the user could not see. D12 makes the CLI a
165
+ # permanent fallback, so it replays too rather than this being a
166
+ # TUI feature.
167
+ _print_replay(current_thread_id)
168
+ else:
169
+ print("Starting a new conversation thread.")
170
+ print("Ctrl+C or Ctrl+D to exit.\n")
171
+
172
+ while True:
173
+ if first_message is not None:
174
+ user_input = first_message
175
+ first_message = None
176
+ else:
177
+ try:
178
+ # §29 (N1). Audit #100: this was input(), a SECOND reader
179
+ # on the stdin the approval pump already owns, so from the
180
+ # first gated call onwards the pump took this line and
181
+ # input() blocked forever. EOFError still arrives here --
182
+ # readline() raises it on Ctrl+D exactly as input() did.
183
+ user_input = _stdin_reader().readline("You: ").strip()
184
+ except (KeyboardInterrupt, EOFError):
185
+ print("\nExiting.")
186
+ break
187
+
188
+ if not user_input:
189
+ continue
190
+
191
+ try:
192
+ response = RunAgentLoop.run_agent_conversation(
193
+ user_goal=user_input,
194
+ model=model,
195
+ provider_name=provider_name,
196
+ thread_id=current_thread_id,
197
+ authorization=authorization,
198
+ effort=effort,
199
+ )
200
+ except Exception as e:
201
+ logger.exception("Chat turn failed")
202
+ print(f"\n[Error: {e}]")
203
+ continue
204
+
205
+ current_thread_id = response.thread_id
206
+
207
+ if not printed_thread_id and current_thread_id:
208
+ print(f"[thread: {current_thread_id}]")
209
+ printed_thread_id = True
210
+
211
+ # ROADMAP_v2 §21's "no silent compaction, ever". The CLI drains
212
+ # the generator through run_to_completion(), which discards every
213
+ # non-final event -- so these arrive on the response rather than as
214
+ # LoopEvents. Printed BEFORE the answer, because that is when they
215
+ # happened.
216
+ for notice in getattr(response, "notices", ()):
217
+ print(f"— {notice['text']} —")
218
+
219
+ print(f"\nAgent: {response.text}")
220
+ if response.stop_reason != "complete":
221
+ # #4: name the figures, not just the reason. A user who sees
222
+ # "token_budget_exceeded" reads it as a size problem -- the
223
+ # exact misreading item 9 recorded -- so the line now says
224
+ # what actually happened (spend this turn) alongside the
225
+ # thread's real size (the provider's own last count). Rare
226
+ # path, so a storage read for the ctx figure costs nothing.
227
+ billed = getattr(response, "turn_billed_tokens", None)
228
+ ctx = 0
229
+ if current_thread_id:
230
+ row = storage.get_thread(current_thread_id) or {}
231
+ ctx = int((row.get("extra_data") or {}).get(
232
+ "last_input_tokens") or 0)
233
+ figures = f" — billed {billed:,} this turn · ctx ~{ctx:,}" \
234
+ if billed is not None else ""
235
+ print(f"[stopped early: {response.stop_reason}{figures}]")
236
+ print()
237
+
238
+
239
+ def build_research_authorization(grant_spec, attended: bool = False):
240
+ """Turn --grant/--grant-tools/--attended into a RunAuthorization.
241
+
242
+ ROADMAP_v2 §25. Lives here rather than in the orchestrator because it
243
+ is a SHELL concern -- knowing how to reach the human is exactly what
244
+ distinguishes main.py from tui/app.py, and the pipeline is deliberately
245
+ ignorant of both. The policy about what may be offered is shared
246
+ (core/reasoning/authorization.py), so the CLI and the TUI cannot drift
247
+ into presenting different sets.
248
+
249
+ Returns None when nothing was granted, which keeps the whole feature
250
+ absent from every run that did not ask for it.
251
+ """
252
+ from core.approval import GrantBudget, RunAuthorization
253
+ from core.reasoning.authorization import (
254
+ NOTHING_TO_GRANT, candidates, parse_grant_spec, GrantSpecError,
255
+ )
256
+
257
+ if grant_spec is None and not attended:
258
+ return None
259
+
260
+ provider = build_attended_provider() if attended else None
261
+ offered = candidates()
262
+ if not offered:
263
+ # Attended mode is still worth building: `candidates()` lists only
264
+ # what is GRANTABLE, and a provider can answer for the per-call
265
+ # tools a grant could never cover.
266
+ #
267
+ # #106: the TUI collapsed the two axes here and said something
268
+ # false while doing it. The message is now one shared constant so
269
+ # they cannot say different things about the same empty answer --
270
+ # the module already kept them from offering different SETS.
271
+ if grant_spec is not None:
272
+ print(f"[grant] {NOTHING_TO_GRANT}", file=sys.stderr)
273
+ return _attended_only(provider)
274
+
275
+ if grant_spec is None:
276
+ return _attended_only(provider)
277
+
278
+ if grant_spec is GRANT_PICKER:
279
+ if not sys.stdin.isatty():
280
+ # Same shape as the trust prompt and the MCP confirmation: a
281
+ # non-TTY run declines rather than hanging on input(), and says
282
+ # what it skipped instead of proceeding as though asked.
283
+ print("[grant] --grant-tools needs a terminal to show the "
284
+ "picker; pass the names explicitly to grant them in a "
285
+ "script. Skipping:", file=sys.stderr)
286
+ for name, description in offered:
287
+ print(f" - {name}", file=sys.stderr)
288
+ return _attended_only(provider)
289
+ granted = _pick_tools_to_grant(offered)
290
+ else:
291
+ try:
292
+ granted = parse_grant_spec(grant_spec, offered)
293
+ except GrantSpecError as e:
294
+ raise SystemExit(f"--grant-tools: {e}")
295
+
296
+ if not granted:
297
+ if provider is None:
298
+ print("[grant] nothing granted; approval-gated tools stay "
299
+ "hidden from this run.\n")
300
+ return _attended_only(provider)
301
+
302
+ print(f"[grant] authorised for this run only: {', '.join(sorted(granted))}")
303
+ print(f"[grant] ceiling: {config.MAX_GRANTED_TOOL_CALLS} granted calls; "
304
+ f"every use is recorded in granted_calls.json.")
305
+ if provider is not None:
306
+ # R10: the two compose. A grant covers what you do not want to be
307
+ # asked about; everything else raises a live prompt instead of
308
+ # being silently denied, which is strictly more useful AND
309
+ # strictly safer than a grant alone.
310
+ print("[grant] attended: anything not granted will be asked about "
311
+ "as it happens.")
312
+ print()
313
+ return RunAuthorization(
314
+ granted_tools=granted,
315
+ provider=provider,
316
+ budget=GrantBudget(config.MAX_GRANTED_TOOL_CALLS),
317
+ )
318
+
319
+
320
+ def _attended_only(provider):
321
+ """A bundle carrying just a provider, or None when there is no
322
+ authorization of any kind -- which is the pre-§25 status quo."""
323
+ from core.approval import RunAuthorization
324
+
325
+ if provider is None:
326
+ return None
327
+ print("[attended] every approval-gated call will be asked about as it "
328
+ f"happens; {config.ATTENDED_APPROVAL_TIMEOUT_S}s with no answer "
329
+ "denies that call and the run continues.\n")
330
+ return RunAuthorization(provider=provider)
331
+
332
+
333
+ # N2's "unset", distinct from None because None is a real answer here:
334
+ # it means "wait indefinitely". A plain
335
+ # `timeout=config.ATTENDED_APPROVAL_TIMEOUT_S` default would be evaluated
336
+ # at IMPORT, which silently defeats tests/conftest.py's
337
+ # shrink_approval_timeout -- a fixture whose docstring says "read at call
338
+ # time, so patching the module attribute is enough", and which exists so
339
+ # an unanswered prompt fails the suite instead of stalling it for ten
340
+ # minutes.
341
+ _DEFAULT_TIMEOUT = object()
342
+
343
+
344
+ class _StdinReader:
345
+ """The ONE reader of stdin in this process (ROADMAP_v2 §29, N1).
346
+
347
+ input() cannot be interrupted, and spawning a reader per prompt would
348
+ leave several threads racing for the same stdin after the first
349
+ timeout -- whichever won would answer the wrong question. One
350
+ long-lived daemon reader with a queue keeps that single-threaded.
351
+
352
+ §29 (N1) finishes that argument, because it used to stop one caller
353
+ short: **input() is a second reader too**. Audit #100 is what that
354
+ cost. After the first approval prompt the pump is parked in
355
+ sys.stdin.readline() forever, so it takes the next chat line and
356
+ run_chat's input() waits for one that will never arrive -- a silent
357
+ wedge on the default shell, indistinguishable from the model
358
+ thinking. Every stdin read in this module now comes through here.
359
+
360
+ TWO methods, because the two callers want different disciplines and
361
+ the difference is a safety property rather than a preference:
362
+
363
+ ask() drains stale input first, and may expire.
364
+ readline() keeps type-ahead, and blocks.
365
+
366
+ Stale input is dropped before each ask(): a line typed after a
367
+ question timed out was an answer to THAT question, and letting it
368
+ fall through would approve the next call on the strength of it.
369
+ readline() must NOT drain, for the mirror-image reason -- a line
370
+ typed while the model was streaming is an answer to the prompt about
371
+ to appear, which the terminal line-buffers and input() returned
372
+ immediately. A `drain=` flag would put that safety rule one keyword
373
+ argument away from being switched off at an approval prompt, which
374
+ is why these are two methods and not one.
375
+ """
376
+
377
+ # N3. The end of stdin is invisible to a queue consumer: input()
378
+ # raised EOFError on Ctrl+D and run_chat caught it to exit, but a
379
+ # reader blocked on a queue only sees a pump that stopped putting
380
+ # things. So EOF is published twice -- as a sentinel, to wake anyone
381
+ # already waiting, and as a latch, because ask()'s drain would
382
+ # otherwise swallow the sentinel and strand the next reader forever.
383
+ _EOF = object()
384
+
385
+ def __init__(self):
386
+ import queue
387
+ import threading
388
+ self._lines = queue.Queue()
389
+ self._thread = None
390
+ self._eof = threading.Event()
391
+
392
+ def _pump(self):
393
+ try:
394
+ for line in sys.stdin:
395
+ self._lines.put(line)
396
+ except Exception as e:
397
+ # A stdin that cannot be READ is, to everyone waiting here, a
398
+ # stdin that has ENDED -- and the difference has to be
399
+ # invisible, because the `finally` below is the only thing
400
+ # that unblocks them. Nothing needed this before §29: a dead
401
+ # pump merely meant ask()'s deadline fired, and every read had
402
+ # one. readline() has none (N2), so the same dead pump is a
403
+ # permanent hang instead. Found by the suite, whose captured
404
+ # stdin raises on the first read.
405
+ logger.debug("stdin reader stopped: %s", e)
406
+ finally:
407
+ self._eof.set()
408
+ self._lines.put(self._EOF)
409
+
410
+ def _start(self) -> None:
411
+ if self._thread is None:
412
+ import threading
413
+ self._thread = threading.Thread(target=self._pump, daemon=True)
414
+ self._thread.start()
415
+
416
+ def _ended(self) -> bool:
417
+ """stdin is closed AND nothing typed before it closed is left."""
418
+ return self._eof.is_set() and self._lines.empty()
419
+
420
+ def ask(self, prompt: str, timeout: float | None = None):
421
+ """Returns the typed line, or None if nobody answered in time.
422
+
423
+ timeout=None waits indefinitely (N2). Whether a prompt may expire
424
+ belongs to the CHANNEL that asked -- there has to be a run to keep
425
+ moving for a deadline to mean anything -- rather than to the kind
426
+ of question. See build_attended_provider.
427
+ """
428
+ import queue as _queue
429
+
430
+ self._start()
431
+ while True: # drop anything typed too late
432
+ try:
433
+ self._lines.get_nowait()
434
+ except _queue.Empty:
435
+ break
436
+ print(prompt, end="", flush=True)
437
+ if self._ended():
438
+ # Nobody can answer, so waiting out a 600s deadline for an
439
+ # answer that cannot come is just a slower version of this.
440
+ print()
441
+ return None
442
+ try:
443
+ line = self._lines.get(timeout=timeout)
444
+ except _queue.Empty:
445
+ print()
446
+ return None
447
+ if line is self._EOF:
448
+ print()
449
+ return None
450
+ return line
451
+
452
+ def readline(self, prompt: str) -> str:
453
+ """The chat prompt and the one-shot startup prompts.
454
+
455
+ input()'s contract, on the one reader: blocks with no deadline,
456
+ keeps whatever was typed ahead, strips the trailing newline, and
457
+ raises EOFError on Ctrl+D so run_chat's existing handler and
458
+ _ask's default-No path are unchanged.
459
+ """
460
+ self._start()
461
+ print(prompt, end="", flush=True)
462
+ if self._ended():
463
+ raise EOFError
464
+ line = self._lines.get()
465
+ if line is self._EOF:
466
+ raise EOFError
467
+ return line.rstrip("\r\n")
468
+
469
+
470
+ _STDIN_READER: "_StdinReader | None" = None
471
+
472
+
473
+ def _stdin_reader() -> _StdinReader:
474
+ """ONE reader per process (review §19-20 f3). Two _StdinReader pumps
475
+ racing for one stdin is exactly the shape the class docstring
476
+ forbids: with --attended --review the attended pump swallows the
477
+ review walk's answers and every consent question times out to a
478
+ reject. Both builders share this instance."""
479
+ global _STDIN_READER
480
+ if _STDIN_READER is None:
481
+ _STDIN_READER = _StdinReader()
482
+ return _STDIN_READER
483
+
484
+
485
+ def build_attended_provider(honour_run_scope: bool = False,
486
+ timeout=_DEFAULT_TIMEOUT):
487
+ """A ResponseChannel that asks at the terminal (§25 R9, §23 AC1).
488
+
489
+ ONE channel for every kind of question the CLI can be asked, replacing
490
+ §25's ApprovalProvider. `ask` dispatches on request.kind; adding a kind
491
+ means adding a branch here, not a second builder and a second parameter
492
+ threaded through four layers.
493
+
494
+ honour_run_scope=False for ATTENDED RESEARCH: that mode exists for
495
+ per-call supervision, so one yes must not silently cover later calls of
496
+ the same tool -- the shortcut §18 added for chat turns is exactly wrong
497
+ there.
498
+
499
+ True for CHAT (§21b M16), where the shortcut is exactly right: being
500
+ asked about the same tool three times in one turn is the noise §18
501
+ added grant_scope to remove.
502
+
503
+ `timeout` is §29's N2: the deadline belongs to the CHANNEL, not to
504
+ the kind of question. What decides whether a prompt may expire is
505
+ whether there is a RUN waiting on the answer -- so the two run-backed
506
+ builders pass ATTENDED_APPROVAL_TIMEOUT_S and are unchanged, while
507
+ --init builds one with timeout=None and its prompts wait as long as
508
+ the user needs. Reading the constant inside each handler instead
509
+ would let the KIND decide, which gets it wrong in both directions: a
510
+ startup prompt would expire on someone who stepped away, and a
511
+ mid-run CONFIRM would block the run forever -- #100's own defect,
512
+ in the batch that fixes #100.
513
+ """
514
+ from core import interaction
515
+
516
+ if timeout is _DEFAULT_TIMEOUT:
517
+ timeout = config.ATTENDED_APPROVAL_TIMEOUT_S
518
+ reader = _stdin_reader()
519
+ # Rendered into the prompts, so one cannot promise a deadline it does
520
+ # not have. QUESTION never showed one and still does not.
521
+ clock = f" ({timeout}s)" if timeout else ""
522
+
523
+ def _render_params(params: dict) -> None:
524
+ import json as _json
525
+ try:
526
+ rendered = _json.dumps(params, indent=2, default=str)
527
+ except (TypeError, ValueError):
528
+ rendered = repr(params)
529
+ for line in rendered.splitlines():
530
+ print(f" {line}")
531
+
532
+ def _approval(request) -> bool:
533
+ print(f"\n[approval] {request.payload.get('tool_name')}")
534
+ # §46 (EP1). The subject of the question, first. The TUI pins it
535
+ # because a modal has a bottom edge; a terminal does not, so
536
+ # here it is placement rather than rescue -- but a kind one
537
+ # shell renders and the other drops is D12's wired-up-but-
538
+ # invisible gap, the same argument that put the reason below in
539
+ # both. None for every tool that declares no headline.
540
+ headline = request.payload.get("headline")
541
+ if headline:
542
+ for line in str(headline).splitlines():
543
+ print(f" $ {line}")
544
+ if request.notice:
545
+ print(f" {request.notice}")
546
+ # §42 (RA6). Same order as the modal -- the computed notice,
547
+ # then the agent's own claim, then the payload. Shown here as
548
+ # well as in the TUI because a kind one shell renders and the
549
+ # other silently drops is D12's wired-up-but-invisible gap,
550
+ # and the CLI is where an unattended-looking run is watched
551
+ # from.
552
+ reason = request.payload.get("rationale")
553
+ print(f" reason (the agent's own words, unverified): {reason or '(none given)'}")
554
+ _render_params(request.payload.get("params") or {})
555
+ answer = reader.ask(f" Allow? [y/N]{clock}: ", timeout)
556
+ if answer is None:
557
+ print(" [no answer — denied; the run continues]")
558
+ return False
559
+ return answer.strip().lower() in ("y", "yes")
560
+
561
+ def _question(request):
562
+ """Put the model's question to a terminal (§23 slice 2).
563
+
564
+ D12 makes this mandatory, not optional: a kind the CLI does not
565
+ render falls through `ask` to None, which interaction.decode turns
566
+ into the declining default -- so the tool would report "the user did
567
+ not answer" on every CLI run while looking wired up. CONFIRM and
568
+ CHOICE are in exactly that state today, reachable only because
569
+ /init supplies its own callbacks instead of using the channel.
570
+
571
+ All four affordances, and the same three-way answer the modal gives:
572
+ numbers choose, free text answers in the user's own words, `d`
573
+ defers, and an empty line is no answer at all.
574
+ """
575
+ payload = request.payload
576
+ options = [str(o) for o in (payload.get("options") or ())]
577
+ multi = bool(payload.get("multi_select"))
578
+ allow_text = payload.get("allow_text", True) is not False
579
+
580
+ print(f"\n[question] {payload.get('question', '')}")
581
+ for index, option in enumerate(options, start=1):
582
+ print(f" {index}. {option}")
583
+ how = []
584
+ if options:
585
+ how.append("numbers separated by spaces" if multi else "a number")
586
+ if allow_text:
587
+ how.append("your own answer")
588
+ how.append("'d' to discuss it instead")
589
+ prompt = f" {', or '.join(how)} (blank to skip): "
590
+
591
+ answer = reader.ask(prompt, timeout)
592
+ if answer is None:
593
+ print(" [no answer — the model will be told nobody replied]")
594
+ return None
595
+ cleaned = answer.strip()
596
+ if not cleaned:
597
+ return None
598
+ if cleaned.lower() in ("d", "discuss"):
599
+ return {"defer": True}
600
+
601
+ # Numbers pick options; anything else is the user's own words. A
602
+ # mixed line is read as text rather than half-parsed -- "2 but only
603
+ # if X" is a sentence, not a selection, and treating it as option 2
604
+ # would drop the condition the user attached to it.
605
+ pieces = cleaned.replace(",", " ").split()
606
+ if pieces and all(p.isdigit() for p in pieces):
607
+ chosen = [options[int(p) - 1] for p in pieces
608
+ if 1 <= int(p) <= len(options)]
609
+ if chosen:
610
+ return {"options": chosen[:1] if not multi else chosen,
611
+ "text": ""}
612
+ print(" [none of those were option numbers — treating it as text]")
613
+ if not allow_text:
614
+ return None
615
+ return {"options": [], "text": cleaned}
616
+
617
+ def _signoff(request):
618
+ """Per-tool subagent sign-off (§23 AC1b).
619
+
620
+ Three answers, and the terminal has to offer all three: a name
621
+ list grants those, empty grants none but still spawns, and a
622
+ refusal denies the spawn. None for anything unparsed is
623
+ belt-and-braces -- interaction.decode does it too -- but saying
624
+ so out loud beats leaving the user to infer it from a spawn that
625
+ quietly did not happen.
626
+ """
627
+ agent = request.payload.get("agent", "the subagent")
628
+ candidates = list(request.payload.get("candidates") or [])
629
+ if not candidates:
630
+ print(f"\n[subagent] {agent} needs no approval-gated tools.")
631
+ answer = reader.ask(f" Run it? [y/N]{clock}: ", timeout)
632
+ if answer and answer.strip().lower() in ("y", "yes"):
633
+ return set()
634
+ print(" [the spawn was refused]")
635
+ return None
636
+ print(f"\n[subagent] {agent} may be granted, for this turn only:")
637
+ for index, name in enumerate(candidates, 1):
638
+ print(f" {index}. {name}")
639
+ answer = reader.ask(
640
+ " Grant which? [numbers / 'all' / 'none' / blank to refuse]"
641
+ f"{clock}: ", timeout)
642
+ if answer is None:
643
+ print(" [no answer — the spawn was refused]")
644
+ return None
645
+ cleaned = answer.strip().lower()
646
+ if not cleaned:
647
+ return None
648
+ if cleaned == "all":
649
+ return set(candidates)
650
+ if cleaned == "none":
651
+ return set()
652
+ chosen = set()
653
+ for piece in cleaned.replace(",", " ").split():
654
+ if piece.isdigit() and 1 <= int(piece) <= len(candidates):
655
+ chosen.add(candidates[int(piece) - 1])
656
+ else:
657
+ print(f" [ignoring {piece!r} — not one of the numbers above]")
658
+ return chosen
659
+
660
+ def _confirm(request):
661
+ """A titled yes/no over a block of text the caller composed.
662
+
663
+ §29 (N4), audit #7. CONFIRM and APPROVAL both answer with a bool
664
+ and are still separate kinds, because the KIND is what tells a
665
+ shell how to render: an approval is a gated tool call with params,
666
+ this is prose someone wants signed off.
667
+ """
668
+ payload = request.payload
669
+ body = payload.get("body", "")
670
+ if body:
671
+ print(f"\n{body}")
672
+ answer = reader.ask(
673
+ f" {payload.get('title', 'Proceed?')} [y/N]{clock}: ", timeout)
674
+ if answer is None:
675
+ print(" [no answer — nothing was done]")
676
+ return False
677
+ return answer.strip().lower() in ("y", "yes")
678
+
679
+ def _choice(request):
680
+ """Exactly one of the options offered, or nothing.
681
+
682
+ Renders from the payload the TUI already established rather than
683
+ from anything --init-shaped, so the two shells put the same
684
+ question. Three ways in, because the terminal should not be worse
685
+ at this than the modal: a number, a unique prefix (which is what
686
+ makes `s` mean software without anything hard-coding it), or a
687
+ bare Enter to take the suggestion.
688
+ """
689
+ payload = request.payload
690
+ options = [str(o) for o in (payload.get("options") or ())]
691
+ proposal = payload.get("proposal")
692
+ if payload.get("blank"):
693
+ print("\nThis folder is empty, so there is nothing to go on.")
694
+ elif proposal:
695
+ print(f"\nThis looks like a {proposal} project — "
696
+ f"{payload.get('reason', 'no reason given')}.")
697
+ labels = " or ".join(f"[{o[:1]}]{o[1:]}" for o in options)
698
+ accepts = " (enter accepts the suggestion)" if proposal else ""
699
+ answer = reader.ask(f" {labels}?{accepts}{clock}: ", timeout)
700
+ if answer is None:
701
+ print(" [no answer — nothing was chosen]")
702
+ return None
703
+ cleaned = answer.strip()
704
+ if not cleaned:
705
+ # None when there was no proposal, which decode reads as the
706
+ # declining default -- not as a pick made on the user's behalf.
707
+ return proposal
708
+ if cleaned.isdigit() and 1 <= int(cleaned) <= len(options):
709
+ return options[int(cleaned) - 1]
710
+ matched = [o for o in options
711
+ if o.lower().startswith(cleaned.lower())]
712
+ if len(matched) == 1:
713
+ return matched[0]
714
+ print(f" [{cleaned!r} is not one of: {', '.join(options)}]")
715
+ return None
716
+
717
+ def _review(request):
718
+ return _prompt_review_decision(
719
+ reader, request.payload.get("finding") or {},
720
+ request.payload.get("round", 0), timeout)
721
+
722
+ # §29 (N4). A TABLE, not an if-chain, so the set of kinds this shell
723
+ # can render is a value a test can compare against
724
+ # interaction.SAFE_DEFAULTS -- which is already the canonical registry,
725
+ # since decode() raises on anything not in it.
726
+ #
727
+ # Audit #7 is what a missing branch costs: the kind falls through to
728
+ # None, decode turns that into the declining default, and the feature
729
+ # reports "the user did not answer" on every CLI run while looking
730
+ # perfectly wired up. CONFIRM and CHOICE sat in that state through two
731
+ # sections. A runtime warning would only fire once someone reached the
732
+ # branch, which is exactly the condition nobody noticed.
733
+ handlers = {
734
+ interaction.APPROVAL: _approval,
735
+ interaction.SUBAGENT_SIGNOFF: _signoff,
736
+ interaction.QUESTION: _question,
737
+ interaction.REVIEW: _review,
738
+ interaction.CONFIRM: _confirm,
739
+ interaction.CHOICE: _choice,
740
+ }
741
+
742
+ def ask(request):
743
+ handler = handlers.get(request.kind)
744
+ if handler is None:
745
+ # An unrecognised kind is a bug in whoever built the Request,
746
+ # and interaction.decode raises on one. Returning None here
747
+ # lets that happen rather than inventing an answer for a
748
+ # question this shell does not know how to put.
749
+ return None
750
+ return handler(request)
751
+
752
+ channel = interaction.ResponseChannel(
753
+ ask=ask, honour_run_scope=honour_run_scope)
754
+ # Read by the parity test; nothing in production branches on it.
755
+ channel.rendered_kinds = frozenset(handlers)
756
+ return channel
757
+
758
+
759
+ def run_memory_command(args) -> int:
760
+ """`--memories` / `--forget`, ROADMAP_v2 §21b (M15).
761
+
762
+ Listing exists to make removal usable: the model never shows ids, so
763
+ without it `--forget` has nothing to be given. Both print the SCOPE of
764
+ each row, because "which of these follows me to another project" is the
765
+ question a user pruning memories is actually asking.
766
+ """
767
+ from memories.manager import manager as memory_manager
768
+ from storage import forget_memory
769
+
770
+ if args.forget:
771
+ try:
772
+ memory_id = UUID(args.forget)
773
+ except ValueError:
774
+ print(f"Not a memory id: {args.forget!r}. Run --memories to list them.")
775
+ return 1
776
+ if forget_memory(memory_id):
777
+ print(f"Forgot {memory_id}.")
778
+ return 0
779
+ print(f"No memory with id {memory_id}.")
780
+ return 1
781
+
782
+ rows = memory_manager.visible()
783
+ if not rows:
784
+ where = memory_manager.scope_path() or "(no project resolved)"
785
+ print(f"No durable memories visible from {where}.")
786
+ return 0
787
+ for row in rows:
788
+ marker = "global " if row["scope"] == "global" else "project"
789
+ category = f" [{row['category']}]" if row.get("category") else ""
790
+ print(f"{row['id']} {marker}{category} {row['content']}")
791
+ return 0
792
+
793
+
794
+ def run_summary_command(args, provider_name: str, model: str) -> int:
795
+ """`--summary [thread]`, ROADMAP_v2 §21c (M21).
796
+
797
+ Prints one thread's distilled summary and exits. DESCRIBES, DOES NOT FOLD
798
+ (M20): the thread is left exactly as it is, unlike the automatic
799
+ compaction a chat session performs on itself.
800
+
801
+ Falls back to `--thread` when no id is given, so `--thread <id> --summary`
802
+ reads the way it sounds.
803
+ """
804
+ from core import compaction
805
+
806
+ raw = (args.summary or "").strip() or (str(args.thread) if args.thread else "")
807
+ if not raw:
808
+ print("--summary needs a thread id, or a --thread to take one from.")
809
+ return 1
810
+ try:
811
+ thread_id = UUID(raw)
812
+ except ValueError:
813
+ print(f"Not a thread id: {raw!r}.")
814
+ return 1
815
+
816
+ notice = compaction.summarize_thread(thread_id, model, provider_name)
817
+ if notice is None:
818
+ print(f"Nothing to summarise in thread {thread_id}.")
819
+ return 1
820
+ if not notice.get("fresh"):
821
+ print(f"[stored summary of {thread_id}; the thread has not changed "
822
+ f"since]")
823
+ print(notice["text"])
824
+ return 0
825
+
826
+
827
+ def run_init_command(args, provider_name: str, model: str) -> int:
828
+ """`--init`, ROADMAP_v2 §24 (M21's precedent again).
829
+
830
+ A flag rather than a slash command because the CLI has no command layer;
831
+ everything else -- which document set, whether an existing file is
832
+ overwritten, whether workspace trust is re-granted -- is decided in
833
+ project_init.generator, exactly as it is for the TUI's /init.
834
+
835
+ The two shell-supplied capabilities are consent and rendering. On a pipe
836
+ there is no consent route, so `confirm` stays None and the generator
837
+ reports what it WOULD write without writing it (I5/V6).
838
+ """
839
+ from core import interaction
840
+ from project_init import doc_sets
841
+ from project_init.generator import InitError, generate
842
+
843
+ kind = None
844
+ if args.research_project and args.software_project:
845
+ print("Pass at most one of --research-project / --software-project.")
846
+ return 1
847
+ if args.research_project:
848
+ kind = doc_sets.RESEARCH
849
+ elif args.software_project:
850
+ kind = doc_sets.SOFTWARE
851
+
852
+ # `--project-config` alone is the configuration and nothing else: no
853
+ # kind question, no initializer, no spend. Named with a kind, it is
854
+ # both under one consent. Same rule as the TUI's `/init --config`,
855
+ # because it is the same command.
856
+ scaffold_docs = not args.project_config or kind is not None
857
+
858
+ interactive = sys.stdin.isatty()
859
+
860
+ # §29 (N5). Down the same channel as every other CLI question, with
861
+ # the shared decoder instead of two guards written by hand here.
862
+ # §23 slice 1 said this was the design -- "generate()'s
863
+ # confirm/choose_kind parameters are unchanged, they are a
864
+ # shell-agnostic API the CLI implements too" -- and moved the TUI. The
865
+ # CLI is the half that was never moved, which is audit #7.
866
+ #
867
+ # timeout=None (N2) because there is no run waiting on the answer. A
868
+ # 600s deadline here would discard the answer of someone who stepped
869
+ # away mid-decision and came back, and there is nothing it would keep
870
+ # moving in the meantime.
871
+ channel = build_attended_provider(timeout=None) if interactive else None
872
+
873
+ def _confirm(summary: str) -> bool:
874
+ return interaction.ask(channel, interaction.Request(
875
+ kind=interaction.CONFIRM,
876
+ payload={"title": "Write these files?", "body": summary,
877
+ "confirm_label": "Write"}))
878
+
879
+ def _choose_kind(proposal, reason, blank):
880
+ return interaction.ask(channel, interaction.Request(
881
+ kind=interaction.CHOICE,
882
+ payload={"options": list(doc_sets.PROJECT_KINDS),
883
+ "proposal": proposal, "reason": reason,
884
+ "blank": blank}))
885
+
886
+ try:
887
+ notice = generate(
888
+ model=model,
889
+ provider_name=provider_name,
890
+ kind=kind,
891
+ confirm=_confirm if interactive else None,
892
+ notify=print,
893
+ choose_kind=_choose_kind if interactive else None,
894
+ scaffold_docs=scaffold_docs,
895
+ scaffold_config=args.project_config,
896
+ )
897
+ except InitError as e:
898
+ print(f"\n{e}")
899
+ return 1
900
+ print(f"\n{notice['text']}")
901
+ return 0
902
+
903
+
904
+ def attach_cli_refs(thread_id, specs, provider_name: str, model: str) -> None:
905
+ """Attach each `--ref <thread>` to `thread_id` (§21c, M21).
906
+
907
+ Reports every outcome and refuses none of the session: a mistyped id or a
908
+ reference past the cap is worth saying out loud, and is not a reason to
909
+ decline to start the conversation the user asked for.
910
+
911
+ Goes through core.loop.attach_ref, the same writer the TUI's /ref uses, so
912
+ the two shells cannot disagree about the cap or the stored shape.
913
+ """
914
+ from core import compaction
915
+ from core.loop import attach_ref
916
+ from core.memory import ConversationMemory
917
+ from storage import thread_preview
918
+
919
+ memory = ConversationMemory(thread_id=thread_id)
920
+ for spec in specs:
921
+ try:
922
+ source = UUID(str(spec).strip())
923
+ except ValueError:
924
+ print(f"[--ref: not a thread id: {spec!r}]")
925
+ continue
926
+ if source == thread_id:
927
+ print("[--ref: that is this thread; skipped]")
928
+ continue
929
+ try:
930
+ notice = compaction.summarize_thread(source, model, provider_name)
931
+ except Exception as e: # noqa: BLE001 -- a failed reference must not
932
+ # stop the session from starting.
933
+ logger.warning("Could not summarise thread %s: %s", source, e)
934
+ print(f"[--ref: could not summarise {source}: {e}]")
935
+ continue
936
+ if notice is None:
937
+ print(f"[--ref: nothing to summarise in {source}]")
938
+ continue
939
+ # #171. The label the TUI's picker has always attached: the same
940
+ # first-user-message preview, so both shells store identical rows
941
+ # and the prompt tier names what the material IS instead of
942
+ # "(no preview)". Computed only after the summarise succeeded --
943
+ # a failed reference stores no row to label.
944
+ ok, message = attach_ref(memory, source, notice["text"],
945
+ thread_preview(source))
946
+ print(f"[--ref: {message}]")
947
+
948
+
949
+ def build_chat_authorization():
950
+ """Authorization for a CLI chat turn: nobody granted anything, but
951
+ someone is here to ask (ROADMAP_v2 §21b, M16).
952
+
953
+ WHAT THIS CHANGES, named rather than discovered. §13 does not merely
954
+ DENY an approval-gated tool where nothing can answer -- it stops
955
+ advertising it. So until now CLI chat could not see `shell`,
956
+ `spawn_subagent`, `remember`, or any MCP tool at all. A provider makes
957
+ all of them advertised and promptable, which is what the TUI has always
958
+ done and is the intended outcome; it is also a real change to the
959
+ default shell's posture, larger than the one tool §21b needed it for.
960
+
961
+ A RunAuthorization with an empty grant set rather than a second
962
+ channel parameter on run_agent_conversation: the bundle already
963
+ threads through _authorization_kwargs, and a second spelling of the
964
+ same argument is what that function exists to prevent.
965
+
966
+ None on a non-tty, matching build_review_consent. A piped run has
967
+ nobody to ask, so it stays headless and behaves exactly as before --
968
+ which also means `remember` cannot fire there, per D26's consequence 1.
969
+ """
970
+ if not sys.stdin.isatty():
971
+ return None
972
+
973
+ from core.approval import RunAuthorization
974
+
975
+ return RunAuthorization(provider=build_attended_provider(
976
+ honour_run_scope=True))
977
+
978
+
979
+ def _pick_tools_to_grant(offered) -> set:
980
+ """One y/N per tool, showing what each one says it does.
981
+
982
+ Per-tool rather than one prompt for the set (R1): the harness cannot
983
+ tell a read-only tool from one that writes or sends -- MCP exposes no
984
+ such metadata -- so the description and the individual choice are the
985
+ entire substance of informed consent here.
986
+ """
987
+ print("\nThese tools need approval, which nothing can give during an "
988
+ "unattended run.")
989
+ print("Granting one authorises it for THIS RUN ONLY. Nothing is saved.\n")
990
+ granted = set()
991
+ for name, description in offered:
992
+ print(f" {name}")
993
+ if description:
994
+ print(f" {description}")
995
+ if _ask(f" Grant {name} for this run? [y/N]: ").strip().lower() in ("y", "yes"):
996
+ granted.add(name)
997
+ print()
998
+ return granted
999
+
1000
+
1001
+ def run_research(
1002
+ query: str,
1003
+ provider_name: str,
1004
+ model: str,
1005
+ ensemble_mode: bool | None = None,
1006
+ ensemble_n: int | None = None,
1007
+ authorization=None,
1008
+ review=None,
1009
+ subagent_review=None,
1010
+ effort: str | None = None,
1011
+ ) -> None:
1012
+ """Run the full deep-research pipeline, write artifacts to disk,
1013
+ and print the results. ensemble_mode/ensemble_n come from
1014
+ settings.json (§14); None means the pipeline falls back to the
1015
+ config.py defaults. authorization (§25) comes from
1016
+ build_research_authorization(); None means no gated tool is reachable,
1017
+ which is the behaviour every research run had before §25.
1018
+
1019
+ review (§20) comes from build_review_consent(); None means the review
1020
+ may still run but applies nothing (V6). subagent_review is whether it
1021
+ runs at all -- separate, because --review on a piped run has no
1022
+ consent object and must still report.
1023
+
1024
+ effort (batch 25, #139) is the resolved level from resolve_effort();
1025
+ it reaches every pass and the reviewer, and is printed in the header.
1026
+
1027
+ §22: the pipeline is ITERATED, not called, so a run that takes many
1028
+ minutes says what it is doing while it does it. The CLI is where that
1029
+ matters most -- it is the shell an unattended run is usually launched
1030
+ from, and it had nothing at all to show until the run ended."""
1031
+ from core.reasoning.orchestrator import stream_deep_research_pipeline
1032
+ from core.reasoning.output_writer import write_run_artifacts
1033
+
1034
+ print(f"Running deep-research pipeline on: {query!r}")
1035
+ print(f"Provider: {provider_name} | Model: {model} | "
1036
+ f"Effort: {effort or 'auto'}\n")
1037
+
1038
+ run = None
1039
+ try:
1040
+ for event in stream_deep_research_pipeline(
1041
+ user_query=query, model=model, provider_name=provider_name,
1042
+ ensemble_mode=ensemble_mode, ensemble_n=ensemble_n,
1043
+ authorization=authorization, review=review,
1044
+ subagent_review=subagent_review, effort=effort,
1045
+ ):
1046
+ # §26: tool calls and code stages print here too. The CLI is
1047
+ # the shell an unattended run is launched from, so a
1048
+ # capability visible only in the TUI is the split this
1049
+ # project keeps warning about -- and it is the CLI that goes
1050
+ # silent for minutes inside a tool-heavy pass.
1051
+ if event.kind == "pass_start":
1052
+ print(f"-> {event.pass_id}", flush=True)
1053
+ elif event.kind == "pass_complete" and event.ok is False:
1054
+ # E14/#115, L6's both-shells rule. Deliberately prints
1055
+ # nothing: the CLI's narrative for this failure is the
1056
+ # trace_line below ("ensemble candidate on X failed --
1057
+ # skipped"), which arrives beside it, and a second line
1058
+ # would say everything twice. This event's capability is
1059
+ # the TUI sidebar resolving its row; the branch exists so
1060
+ # that is a decision rather than an omission.
1061
+ pass
1062
+ elif event.kind == "stage":
1063
+ # Same column as a pass, different marker: a stage that
1064
+ # made no model call is done the moment it is announced,
1065
+ # so an arrow promising something is starting would be
1066
+ # wrong.
1067
+ print(f".. {event.pass_id}", flush=True)
1068
+ elif event.kind == "tool_call":
1069
+ detail = f" {event.text}" if event.text else ""
1070
+ print(f" > {event.tool}{detail}", flush=True)
1071
+ elif event.kind == "tool_result" and not event.ok:
1072
+ # Successful results print nothing: one line per call is
1073
+ # already the volume, and "it worked" is what the absence
1074
+ # of a failure line says.
1075
+ print(f" x {event.tool} {event.text}", flush=True)
1076
+ elif event.kind == "pass_activity":
1077
+ # For the passes that call no tools at all -- Pass 1 and
1078
+ # final synthesis -- this is the only sign of life
1079
+ # between the start line and the end line, and those are
1080
+ # the two longest passes in the run.
1081
+ print(f" .. {event.chars // 1000}k chars", flush=True)
1082
+ elif event.kind == "trace_line":
1083
+ print(f"- {event.text}", flush=True)
1084
+ elif event.kind == "run_complete":
1085
+ run = event.run
1086
+ if run is None:
1087
+ # Same contract as run_pipeline_to_completion's RuntimeError:
1088
+ # a generator that ended without its terminal event has a bug,
1089
+ # and carrying on would fail later on a None run instead.
1090
+ raise RuntimeError(
1091
+ "Pipeline generator completed without yielding a "
1092
+ "run_complete event")
1093
+ except Exception as e:
1094
+ logger.exception("Research pipeline failed")
1095
+ print(f"\nPipeline failed: {e}")
1096
+ print("If any partial results were persisted, they can be "
1097
+ "inspected via the database.")
1098
+ raise SystemExit(1)
1099
+
1100
+ output_dir = None
1101
+ try:
1102
+ output_dir = write_run_artifacts(run)
1103
+ except Exception as e:
1104
+ logger.exception("Could not write artifacts")
1105
+ print(f"\n[Warning: could not write artifacts: {e}]")
1106
+
1107
+ # §22: no "--- Trace ---" block here any more. Every line was printed
1108
+ # as it happened, above; reprinting them would show the whole run
1109
+ # twice, with the second copy looking like a different artifact.
1110
+ print("\n--- Report ---")
1111
+ print(run.final_report)
1112
+
1113
+ if run.run_id:
1114
+ print(f"\n[run id: {run.run_id}]")
1115
+ if output_dir:
1116
+ print(f"Full artifacts written to: {output_dir}")
1117
+
1118
+
1119
+ def build_parser() -> argparse.ArgumentParser:
1120
+ """Builds the CLI argument parser. Separated from main() so tests
1121
+ can exercise argument parsing without side effects.
1122
+
1123
+ That was true of this function and false of everything around it
1124
+ until §29 (N7): there WAS no main(), so the startup sequence this
1125
+ sentence implies is testable sat under `if __name__` and no test
1126
+ could reach any of it. See main()."""
1127
+ parser = argparse.ArgumentParser(
1128
+ description="Venastine Research Harness — interactive CLI",
1129
+ )
1130
+ parser.add_argument(
1131
+ "query",
1132
+ nargs="?",
1133
+ default=None,
1134
+ help="Research query (required for --mode research). "
1135
+ "In chat mode, if given, sent as the first message.",
1136
+ )
1137
+ parser.add_argument(
1138
+ "--thread",
1139
+ type=_uuid_type,
1140
+ default=None,
1141
+ metavar="UUID",
1142
+ help="Resume an existing conversation thread by its UUID.",
1143
+ )
1144
+ parser.add_argument(
1145
+ "--mode",
1146
+ choices=["chat", "research"],
1147
+ default="chat",
1148
+ help="chat (default) or research (deep-research pipeline).",
1149
+ )
1150
+ # Defaults are None so that after parsing we can tell an explicit
1151
+ # CLI choice from argparse fill-in; resolution happens in main via
1152
+ # resolve_runtime_defaults (CLI > settings.json > config.py).
1153
+ parser.add_argument(
1154
+ "--provider",
1155
+ default=None,
1156
+ help=f"LLM provider name (default: settings.json, else "
1157
+ f"{DEFAULT_PROVIDER}).",
1158
+ )
1159
+ parser.add_argument(
1160
+ "--model",
1161
+ default=None,
1162
+ help=f"Model name (default: settings.json, else "
1163
+ f"{config.MODEL_NAME}).",
1164
+ )
1165
+ # Batch 25 (#139). A free string, not choices=: the vocabulary lives at
1166
+ # effort_for(), which validates against the RECEIVING model (a static
1167
+ # argparse list would reject a level a custom endpoint accepts and
1168
+ # accept one it does not). "auto" is the explicit off switch -- it
1169
+ # clears even a settings.json level, which matters now that
1170
+ # config.DEFAULT_EFFORT defaults to "high". Resolution in main via
1171
+ # resolve_effort, same mechanism as provider/model.
1172
+ parser.add_argument(
1173
+ "--effort",
1174
+ default=None,
1175
+ metavar="LEVEL",
1176
+ help="Reasoning effort for chat AND research (typically "
1177
+ "low|medium|high; 'auto' sends none). Default: settings.json "
1178
+ "'effort' key, else config.DEFAULT_EFFORT.",
1179
+ )
1180
+ # ROADMAP_v2 §25. TWO flags onto ONE dest, in a mutually exclusive
1181
+ # group, rather than a single nargs="?" flag with an optional value.
1182
+ # nargs="?" reads the NEXT TOKEN as its value when one is present, so
1183
+ # --mode research --grant-tools "what is entropy"
1184
+ # consumed the query as the grant list and then failed with "--mode
1185
+ # research requires a positional query argument" -- an error about the
1186
+ # wrong thing entirely, on the documented spelling of the common case.
1187
+ #
1188
+ # Absent means no grants, which is what every invocation before §25 did
1189
+ # and still does: no prompt appears unless one is asked for.
1190
+ #
1191
+ # NOT persistable: a settings.json equivalent would turn a per-run
1192
+ # decision into standing authorization, carried by any repo you clone
1193
+ # (R12). The MODE is persistable precisely because it can only ever ADD
1194
+ # prompts, where a grant list can only ever remove them.
1195
+ grant = parser.add_mutually_exclusive_group()
1196
+ grant.add_argument(
1197
+ "--grant",
1198
+ dest="grant_tools",
1199
+ action="store_const",
1200
+ const=GRANT_PICKER,
1201
+ default=None,
1202
+ help="Research mode: pick approval-gated tools to authorise for "
1203
+ "this run, interactively. Needs a terminal. Never persisted.",
1204
+ )
1205
+ grant.add_argument(
1206
+ "--grant-tools",
1207
+ dest="grant_tools",
1208
+ default=None,
1209
+ metavar="NAMES",
1210
+ help="Research mode: authorise exactly these approval-gated tools "
1211
+ "(comma-separated) for this run. Works without a terminal. "
1212
+ "Never persisted.",
1213
+ )
1214
+ # R9/R12. Default None so settings.json can supply it and an explicit
1215
+ # flag still wins (§14's CLI > settings.json > config.py precedence,
1216
+ # which only works because argparse defaults stay None).
1217
+ #
1218
+ # The MODE is persistable where the grant list is not, and the
1219
+ # asymmetry is the point: a persisted mode can only ever ADD prompts,
1220
+ # so a hostile settings.json makes your runs more annoying and never
1221
+ # more permissive. A persisted grant list could only ever remove them.
1222
+ parser.add_argument(
1223
+ "--attended",
1224
+ dest="attended",
1225
+ action="store_const",
1226
+ const=True,
1227
+ default=None,
1228
+ help="Research mode: ask about every approval-gated call as it "
1229
+ "happens, instead of hiding those tools. Combines with "
1230
+ "--grant, which covers the tools you do not want asked about.",
1231
+ )
1232
+ # §20 (D9). Same None-default precedence as --attended, and for the
1233
+ # same reason: the MODE is persistable, so settings.json can turn the
1234
+ # review on and an explicit flag still wins either way. --no-review
1235
+ # exists because a persisted `true` otherwise has no per-run escape.
1236
+ review_group = parser.add_mutually_exclusive_group()
1237
+ review_group.add_argument(
1238
+ "--review",
1239
+ dest="review",
1240
+ action="store_const",
1241
+ const=True,
1242
+ default=None,
1243
+ help="Research mode: after the pipeline finishes, have a reviewer "
1244
+ "agent check its claims and report, and offer each proposed "
1245
+ "correction for you to accept, reject or refine. Nothing is "
1246
+ "changed without your say-so.",
1247
+ )
1248
+ review_group.add_argument(
1249
+ "--no-review",
1250
+ dest="review",
1251
+ action="store_const",
1252
+ const=False,
1253
+ help="Research mode: skip the post-pipeline review even if "
1254
+ "settings.json or config.py turns it on.",
1255
+ )
1256
+ parser.add_argument(
1257
+ "--tui",
1258
+ action="store_true",
1259
+ help="Launch the Textual TUI (ROADMAP_v2 §16) instead of the "
1260
+ "line-based CLI. The CLI remains the default and is a "
1261
+ "permanent fallback (D12) -- it is never removed.",
1262
+ )
1263
+ parser.add_argument(
1264
+ "--trust-project",
1265
+ action="store_true",
1266
+ help="Grant workspace trust (D17) for the current directory's "
1267
+ ".venastine/ content -- intended for scripts/CI where the "
1268
+ "interactive prompt is unavailable.",
1269
+ )
1270
+ # ROADMAP_v2 §21b (M15). The CLI has no slash-command layer, so these
1271
+ # are flags rather than /memories and /forget -- and they exist for the
1272
+ # CLI specifically because M16 makes a CLI-only user able to WRITE a
1273
+ # durable memory, and they would otherwise have no way to remove one.
1274
+ parser.add_argument(
1275
+ "--memories",
1276
+ action="store_true",
1277
+ help="List durable memories visible from this directory and exit "
1278
+ "(ROADMAP_v2 §21b).",
1279
+ )
1280
+ parser.add_argument(
1281
+ "--forget",
1282
+ metavar="ID",
1283
+ help="Delete one durable memory by id (see --memories) and exit.",
1284
+ )
1285
+ # ROADMAP_v2 §21c (M21). Flags rather than /summary and /ref for the same
1286
+ # reason --memories is a flag: the CLI has no slash-command layer, and
1287
+ # adding one is §23's business rather than this section's. The accepted
1288
+ # limit is that a CLI user attaches a reference at LAUNCH -- mid-conversation
1289
+ # referencing is the TUI's.
1290
+ parser.add_argument(
1291
+ "--summary",
1292
+ metavar="THREAD",
1293
+ nargs="?",
1294
+ const="",
1295
+ help="Print a thread's distilled summary and exit (ROADMAP_v2 §21c). "
1296
+ "Defaults to the thread given by --thread.",
1297
+ )
1298
+ parser.add_argument(
1299
+ "--ref",
1300
+ metavar="THREAD",
1301
+ action="append",
1302
+ help="Attach another thread's summary to this session as context. "
1303
+ "Repeatable, up to config.MAX_INJECTED_REFS.",
1304
+ )
1305
+ # ROADMAP_v2 §24. A flag for M21's reason, and the two kind flags exist
1306
+ # so a piped run can skip the question rather than being refused.
1307
+ parser.add_argument(
1308
+ "--init",
1309
+ action="store_true",
1310
+ help="Generate this project's documentation set -- a root AGENTS.md "
1311
+ "plus the stubs it links -- and exit.",
1312
+ )
1313
+ parser.add_argument(
1314
+ "--software-project",
1315
+ action="store_true",
1316
+ help="With --init: scaffold the software document set without asking.",
1317
+ )
1318
+ parser.add_argument(
1319
+ "--research-project",
1320
+ action="store_true",
1321
+ help="With --init: scaffold the research document set without asking.",
1322
+ )
1323
+ # §24 I17. Spelled out for the same reason as the two above: a bare
1324
+ # `--config` at top level reads as "the path to a config file", which
1325
+ # is not what it does.
1326
+ parser.add_argument(
1327
+ "--project-config",
1328
+ action="store_true",
1329
+ help="With --init: create .venastine/settings.json and mcp.json "
1330
+ "with default values, plus the agents/ and skills/ "
1331
+ "directories. On its own -- with neither --software-project "
1332
+ "nor --research-project -- it is the whole command, and runs "
1333
+ "no model call.",
1334
+ )
1335
+ return parser
1336
+
1337
+
1338
+ def resolve_runtime_defaults(args, settings: dict) -> tuple[str, str]:
1339
+ """Provider/model precedence: explicit CLI flag > settings.json
1340
+ (trusted project tier already beat user tier inside the loader) >
1341
+ config.py constants."""
1342
+ provider = args.provider or settings.get("default_provider") or DEFAULT_PROVIDER
1343
+ model = args.model or settings.get("default_model") or config.MODEL_NAME
1344
+ return provider, model
1345
+
1346
+
1347
+ def resolve_effort(args, settings: dict) -> str | None:
1348
+ """Batch 25 (#139). Effort precedence: --effort > settings.json
1349
+ top-level 'effort' > config.DEFAULT_EFFORT.
1350
+
1351
+ Same mechanism as resolve_attended/resolve_review: it only works
1352
+ because the argparse default is None, so "flag absent" is
1353
+ distinguishable from "flag given".
1354
+
1355
+ 'auto' is the explicit OFF switch at either layer: with
1356
+ DEFAULT_EFFORT now "high", a user who wants the pre-batch behaviour
1357
+ says --effort auto and gets exactly None. A settings.json "auto"
1358
+ clears too; JSON null cannot be distinguished from an absent key via
1359
+ .get(), so null falls through to the next layer by design."""
1360
+ raw = args.effort if args.effort is not None else settings.get("effort")
1361
+ if raw is None:
1362
+ return config.DEFAULT_EFFORT
1363
+ return None if raw == "auto" else raw
1364
+
1365
+
1366
+ def resolve_attended(args, settings: dict) -> bool:
1367
+ """§25 R12. --attended > settings.json research.approval_mode > off.
1368
+
1369
+ Same precedence and the same mechanism as provider/model: it only
1370
+ works because the argparse default is None, so "flag absent" is
1371
+ distinguishable from "flag given as false"."""
1372
+ if args.attended is not None:
1373
+ return bool(args.attended)
1374
+ return settings.get("research", {}).get("approval_mode") == "attended"
1375
+
1376
+
1377
+ def resolve_review(args, settings: dict) -> bool:
1378
+ """§20 (D9). --review/--no-review > settings.json
1379
+ research.subagent_review > config.SUBAGENT_REVIEW.
1380
+
1381
+ Same mechanism as resolve_attended: it only works because the argparse
1382
+ default is None, so "flag absent" stays distinguishable from "flag
1383
+ given as false" -- and --no-review has to be able to beat a persisted
1384
+ true, or a project setting could not be escaped for one run."""
1385
+ if args.review is not None:
1386
+ return bool(args.review)
1387
+ persisted = settings.get("research", {}).get("subagent_review")
1388
+ if persisted is not None:
1389
+ return bool(persisted)
1390
+ return bool(config.SUBAGENT_REVIEW)
1391
+
1392
+
1393
+ def _prompt_review_decision(reader, finding, round_index,
1394
+ timeout=_DEFAULT_TIMEOUT):
1395
+ """Put one proposed correction to the terminal. (decision, notes).
1396
+
1397
+ Extracted from build_review_consent so the review-only channel and the
1398
+ general one can share it -- §23's whole point is that there is one way
1399
+ to ask, and two copies of the prompt would be the same divergence one
1400
+ layer up.
1401
+
1402
+ `timeout` follows N2: the caller's channel owns the deadline. It
1403
+ defaults to the attended one because both of this function's callers
1404
+ are mid-run, and a review nobody is watching has to degrade rather
1405
+ than wait.
1406
+ """
1407
+ if timeout is _DEFAULT_TIMEOUT:
1408
+ timeout = config.ATTENDED_APPROVAL_TIMEOUT_S
1409
+ kind = finding.get("kind")
1410
+ target = finding.get("claim_id") or "the report"
1411
+ print(f"\n[review] {kind} correction to {target} "
1412
+ f"(severity: {finding.get('severity', 'unknown')})")
1413
+ print(f" why: {finding.get('reason', '(no reason given)')}")
1414
+ print(f" proposed: {finding.get('proposed')}")
1415
+ if round_index:
1416
+ print(f" (refinement {round_index} of "
1417
+ f"{config.MAX_REVIEW_REFINEMENTS})")
1418
+ clock = f" ({timeout}s)" if timeout else ""
1419
+ answer = reader.ask(
1420
+ " [a]ccept / [r]eject / [f] refine <note> / [!] reject the "
1421
+ f"rest{clock}: ", timeout)
1422
+ if answer is None:
1423
+ # Same direction as an unanswered approval prompt: declining is
1424
+ # safe and continuing is useful, so walking away from a review
1425
+ # degrades it rather than wedging the run.
1426
+ print(" [no answer — rejected; the review continues]")
1427
+ return ("reject", "")
1428
+ answer = answer.strip()
1429
+ head, _, note = answer.partition(" ")
1430
+ head = head.lower()
1431
+ if head in ("a", "accept"):
1432
+ return ("accept", "")
1433
+ if head in ("f", "refine"):
1434
+ return ("refine", note.strip())
1435
+ if head in ("!", "reject-all"):
1436
+ return ("reject_all", "")
1437
+ return ("reject", "")
1438
+
1439
+
1440
+ def build_review_consent():
1441
+ """A ResponseChannel that asks about corrections at the terminal (§20
1442
+ V4, §23 AC1).
1443
+
1444
+ A SEPARATE channel from the approval one, and deliberately so. §20
1445
+ kept "may this edit be applied?" apart from "may this call proceed?"
1446
+ because they are different questions a user can answer differently:
1447
+ `--review` without `--attended` is a legitimate combination, and one
1448
+ shared object would make it unexpressible. §23 unified the MECHANISM,
1449
+ not the two parameters.
1450
+
1451
+ Returns None when stdin is not a terminal, and that is load-bearing
1452
+ rather than defensive: V6 says nothing is applied without a consent
1453
+ route, so a piped or cron-driven run is advisory BY CONSTRUCTION
1454
+ instead of by a check somewhere downstream that could be forgotten.
1455
+ Reading a decision off a pipe would also be answering on the user's
1456
+ behalf with whatever bytes happened to be there.
1457
+ """
1458
+ from core import interaction
1459
+
1460
+ if not sys.stdin.isatty():
1461
+ return None
1462
+
1463
+ reader = _stdin_reader()
1464
+
1465
+ def ask(request):
1466
+ if request.kind != interaction.REVIEW:
1467
+ # This channel answers one kind. Anything else falls through
1468
+ # to interaction.decode's declining default rather than being
1469
+ # answered by a prompt written for a different question.
1470
+ return None
1471
+ return _prompt_review_decision(
1472
+ reader, request.payload.get("finding") or {},
1473
+ request.payload.get("round", 0))
1474
+
1475
+ return interaction.ResponseChannel(ask=ask)
1476
+
1477
+
1478
+ def _ask(prompt: str) -> str:
1479
+ """A blocking terminal read that treats EOF as an empty answer.
1480
+
1481
+ Ctrl+D (Ctrl+Z on Windows) at a startup prompt raised EOFError out of
1482
+ a bare input(), giving a traceback where the default-No path was
1483
+ wanted. run_chat's loop already handles this; the one-shot startup
1484
+ prompts did not. Every caller here defaults to No, so "" declines.
1485
+
1486
+ §29 (N1): goes through the one reader rather than calling input().
1487
+ Its callers all happen to run before the approval pump starts today,
1488
+ so #100 could not reach them -- but that is an ordering coincidence
1489
+ between setup_mcp and run_chat, not a property anyone stated, and it
1490
+ would break the first time a startup prompt moved.
1491
+ """
1492
+ try:
1493
+ return _stdin_reader().readline(prompt)
1494
+ except EOFError:
1495
+ print()
1496
+ return ""
1497
+
1498
+
1499
+ def _ensure_workspace_trust(project_path: str, trust_flag: bool) -> None:
1500
+ """D17 one-time confirmation. Shows what would load (file list plus
1501
+ settings.json verbatim -- a project's settings can pick the provider
1502
+ and multiply pipeline cost via ensemble_n, so approval must be
1503
+ informed). Interactive y/N on a TTY; --trust-project grants for
1504
+ scripts/CI; non-TTY without the flag skips project content with a
1505
+ notice instead of hanging on input()."""
1506
+ if workspace_trust.is_trusted(project_path):
1507
+ return
1508
+ summary = config_loader.describe_project_content(project_path)
1509
+ if trust_flag:
1510
+ print(summary)
1511
+ workspace_trust.grant_trust(project_path)
1512
+ print("Trust granted for this project.\n")
1513
+ return
1514
+ if sys.stdin.isatty():
1515
+ print(summary)
1516
+ answer = _ask("Trust this project's .venastine/ content? [y/N]: ")
1517
+ if answer.strip().lower() in ("y", "yes"):
1518
+ workspace_trust.grant_trust(project_path)
1519
+ print("Trust granted for this project.\n")
1520
+ else:
1521
+ print("Proceeding without project-level content.\n")
1522
+ else:
1523
+ print("[notice] .venastine/ present but not trusted; skipping "
1524
+ "project-level content. Run once with --trust-project to "
1525
+ "grant trust.\n")
1526
+
1527
+
1528
+ def load_project_config(project_path: str, trust_flag: bool) -> dict:
1529
+ """Runs the trust gate then config discovery, and reports a bad
1530
+ configuration file as one line rather than a traceback.
1531
+
1532
+ The loud failure itself is deliberate and stays -- an unknown
1533
+ settings.json key must never masquerade as a setting (ROADMAP_v2 §14
1534
+ amendment 1). But the thing being reported is a typo in a file the
1535
+ user wrote, not an internal error: a stack trace ending in ValueError
1536
+ buries the one line that says which key in which file. Covers
1537
+ ValueError (unknown key, wrong type, and json.JSONDecodeError, which
1538
+ subclasses it -- so a corrupt settings.json or trusted_projects.json
1539
+ lands here too) and OSError (an unreadable AGENTS.md or config dir).
1540
+ """
1541
+ try:
1542
+ _ensure_workspace_trust(project_path, trust_flag)
1543
+ config_loader.initialize(project_path)
1544
+ except (ValueError, OSError) as e:
1545
+ # DEBUG, not exception(): the root logger's StreamHandler writes to
1546
+ # stderr, so logger.exception() here would print the very traceback
1547
+ # this function exists to replace -- the clean message would just
1548
+ # appear underneath it. At DEBUG the trace is still one
1549
+ # AGENT_LOG_LEVEL=DEBUG away when someone actually wants it.
1550
+ logger.debug("Configuration load failed", exc_info=True)
1551
+ print(f"\nConfiguration error: {e}\n", file=sys.stderr)
1552
+ raise SystemExit(1)
1553
+ return config_loader.get_settings()
1554
+
1555
+
1556
+ def _confirm_user_level_servers(configs: dict) -> dict:
1557
+ """First-run acknowledgement for user-level MCP servers (§17, D31).
1558
+
1559
+ Project-level servers are covered by D17's trust prompt. User-level
1560
+ ones have no gate at all, on the assumption you authored them -- which
1561
+ is exactly wrong when an installer or another tool appended to the
1562
+ file. Keyed by name + a hash of the entry, the same way workspace
1563
+ trust is keyed, so an edited command re-asks instead of inheriting an
1564
+ old acknowledgement.
1565
+
1566
+ Returns the configs cleared to connect. Non-TTY skips rather than
1567
+ hanging on input(), matching _ensure_workspace_trust's shape.
1568
+ """
1569
+ from mcp_client import config as mcp_config
1570
+
1571
+ pending = [c for c in configs.values()
1572
+ if c.tier == "user" and not mcp_config.is_known(c)]
1573
+ if not pending:
1574
+ return configs
1575
+
1576
+ approved = dict(configs)
1577
+ interactive = sys.stdin.isatty()
1578
+ if not interactive:
1579
+ print("[notice] new user-level MCP server(s) present but this is not "
1580
+ "an interactive session; skipping them:", file=sys.stderr)
1581
+
1582
+ for cfg in pending:
1583
+ if not interactive:
1584
+ print(f" - {cfg.describe()}", file=sys.stderr)
1585
+ approved.pop(cfg.name, None)
1586
+ continue
1587
+ print(f"\nNew MCP server in your user config:\n {cfg.describe()}")
1588
+ answer = _ask("Connect to it? [y/N]: ")
1589
+ if answer.strip().lower() in ("y", "yes"):
1590
+ mcp_config.remember_server(cfg)
1591
+ else:
1592
+ print(f"Skipping {cfg.name}.")
1593
+ approved.pop(cfg.name, None)
1594
+ return approved
1595
+
1596
+
1597
+ def setup_mcp(project_path: str):
1598
+ """Discover, confirm, connect and register MCP servers (§17).
1599
+
1600
+ Returns the MCPClient so the caller can shut it down, or None. Never
1601
+ raises: MCP is an optional integration, and a bad server entry must
1602
+ not stop the harness from starting -- individual failures are already
1603
+ reported per server by connect_all().
1604
+ """
1605
+ client = None
1606
+ try:
1607
+ from mcp_client import config as mcp_config
1608
+ from mcp_client import registration
1609
+ from mcp_client.client import MCPClient
1610
+ from tools.registry import registry
1611
+
1612
+ trusted = workspace_trust.is_trusted(project_path)
1613
+ configs = mcp_config.load_server_configs(project_path, trusted)
1614
+ if not configs:
1615
+ return None
1616
+
1617
+ configs = _confirm_user_level_servers(configs)
1618
+ if not configs:
1619
+ return None
1620
+
1621
+ client = MCPClient(configs)
1622
+ client.connect_all()
1623
+ names = registration.register_all(client, registry)
1624
+ if names:
1625
+ print(f"[mcp] {len(names)} tool(s) from "
1626
+ f"{len(client.clients)} server(s).")
1627
+ for name, why in client.failures.items():
1628
+ print(f"[mcp] server {name!r} unavailable: {why}", file=sys.stderr)
1629
+ return client
1630
+ except Exception as e:
1631
+ logger.debug("MCP setup failed", exc_info=True)
1632
+ print(f"[mcp] setup failed, continuing without MCP: {e}", file=sys.stderr)
1633
+ # Returning None here without unwinding is how spawned stdio
1634
+ # servers become orphans: teardown_mcp(None) is a no-op, so a
1635
+ # failure AFTER connect_all() (registration raising, a partial
1636
+ # connect timing out) left live child processes with no owner and
1637
+ # nothing left holding a reference to close them.
1638
+ from tools.registry import registry
1639
+ teardown_mcp(client, registry)
1640
+ return None
1641
+
1642
+
1643
+ def teardown_mcp(client, registry=None) -> None:
1644
+ """Not tidiness. stdio servers are child processes THIS harness
1645
+ spawned; the MCP thread is a daemon and dies at interpreter exit
1646
+ without unwinding the exit stack, so skipping this orphans them and
1647
+ they accumulate across sessions.
1648
+
1649
+ F7 (#65): the server's TOOLS leave with it -- unregister_all removes
1650
+ exactly what register_all put in, approval defaults included. This is
1651
+ the disconnect handling ARCHITECTURE.md always claimed justified
1652
+ unregister_all's idempotency; until now nothing called it. Sequencing
1653
+ lives here in the shell rather than inside client.disconnect_all()
1654
+ for the same reason §20's consent does: mcp_client owns transport,
1655
+ not registry policy.
1656
+ """
1657
+ if client is None:
1658
+ return
1659
+ try:
1660
+ client.disconnect_all()
1661
+ except Exception:
1662
+ logger.debug("MCP teardown failed", exc_info=True)
1663
+ if registry is not None:
1664
+ try:
1665
+ from mcp_client import registration
1666
+ registration.unregister_all(registry)
1667
+ except Exception:
1668
+ logger.debug("MCP unregistration failed", exc_info=True)
1669
+
1670
+
1671
+ def _classify_legacy_threads() -> None:
1672
+ """Label pre-§27 pass threads, once per launch (§27 AC3).
1673
+
1674
+ SEPARATE from create_db_and_tables' migration, deliberately.
1675
+ ensure_columns() is additive only and never backfills (§21 M7), so the
1676
+ `kind` column arrives with every existing row defaulted to 'chat' --
1677
+ including the hundreds of pass threads that made the picker unusable in
1678
+ the first place. Backfilling inside a schema migrator would put data
1679
+ policy in the one function every launch depends on.
1680
+
1681
+ Idempotent by construction rather than by a marker, so a database last
1682
+ opened by an older build is still classified. Non-fatal: an unreadable
1683
+ or locked database here means a cluttered picker, which is not worth
1684
+ refusing to start over.
1685
+ """
1686
+ from core.reasoning.pipeline_storage import classify_legacy_pass_threads
1687
+ connection = engine.raw_connection()
1688
+ try:
1689
+ classify_legacy_pass_threads(connection)
1690
+ except Exception: # noqa: BLE001
1691
+ logger.warning("Could not classify legacy threads", exc_info=True)
1692
+ finally:
1693
+ connection.close()
1694
+
1695
+
1696
+ def main(argv=None) -> int:
1697
+ """The CLI, as a function (ROADMAP_v2 §29, N7). Returns an exit code.
1698
+
1699
+ Audit #102: everything below used to sit under `if __name__ ==
1700
+ "__main__":`, so nothing in the startup sequence was importable --
1701
+ not the four parser.error() validations, each carrying a comment
1702
+ about a real bug it fixed; not the ordering of the early-exit
1703
+ commands; not the `finally: teardown_mcp`, which is `finally` rather
1704
+ than "at the end" for a reason worth a test. build_parser's docstring
1705
+ already claimed it was "separated from main() so tests can exercise
1706
+ argument parsing without side effects", naming a function that did
1707
+ not exist.
1708
+
1709
+ SystemExit still propagates rather than being converted: parser.error
1710
+ raises it with code 2, and run_research with code 1 on a failed
1711
+ pipeline. This returns a code only where it decides one.
1712
+ """
1713
+ parser = build_parser()
1714
+ args = parser.parse_args(argv)
1715
+
1716
+ # Below parse_args for #101's other half: this creates the log
1717
+ # DIRECTORY, so --help left one behind too. Nothing above logs
1718
+ # anything -- argparse reports its own errors on stderr and exits.
1719
+ configure_logging()
1720
+
1721
+ # A workspace overlapping the harness's own tree -- or the user-tier
1722
+ # state that decides what it trusts and what it spawns -- is refused
1723
+ # here AND inside the sandbox. security/sandbox.py is the boundary,
1724
+ # because it is the one thing no tool can route around; this is the
1725
+ # legibility half. Finding out that AGENT_WORKSPACE is misconfigured
1726
+ # through a failed tool call in the middle of a task is a bad way to
1727
+ # learn it, so it is a launch failure as well.
1728
+ #
1729
+ # Below configure_logging so the reason can be logged, and above
1730
+ # create_db_and_tables so a refused launch does not leave a database
1731
+ # behind -- the same argument audit #101 makes one line down.
1732
+ # §40 (UN2). ABOVE check_workspace, and that ordering is not
1733
+ # cosmetic: the posture is what a later batch lets decide whether the
1734
+ # workspace guard runs at all, and `apply_cli` RAISES if anything has
1735
+ # already read the posture -- so a reader creeping above this line is
1736
+ # a loud startup failure rather than a run that quietly used the
1737
+ # config-only value. Below parse_args because the command line feeds
1738
+ # it; below configure_logging so the warnings below have somewhere to
1739
+ # go.
1740
+ posture.apply_cli()
1741
+ _announce_posture()
1742
+
1743
+ workspace_refusal = protected_paths.check_workspace(config.WORKSPACE_DIR)
1744
+ if workspace_refusal:
1745
+ logger.error("%s", workspace_refusal)
1746
+ print(f"[error] {workspace_refusal}", file=sys.stderr)
1747
+ return 2
1748
+
1749
+ # §29 (N6), audit #101. BELOW parse_args, which is where --help and a
1750
+ # typo'd flag exit -- both of which used to create a 77 KB six-table
1751
+ # SQLite database and a log directory in whatever directory they were
1752
+ # run from, for output that touches no data at all. The file already
1753
+ # made exactly this argument one level down, about MCP: "argument
1754
+ # validation before connecting anything: parser.error() exits, and
1755
+ # doing it after setup_mcp() would spawn stdio server subprocesses
1756
+ # only to abandon them on the way out."
1757
+ #
1758
+ # Everything that SURVIVES parse_args does need the schema, contrary
1759
+ # to #101's own text: --memories reads usermemory, --summary reads
1760
+ # threadsummary, and --init runs a real model turn through
1761
+ # RunAgentLoop.run_agent_conversation, which logs messages. So one
1762
+ # relocation covers it, rather than an _ensure_storage() that a new
1763
+ # path can forget to call.
1764
+ create_db_and_tables()
1765
+
1766
+ # THE PROJECT IS THE WORKSPACE WHEN ONE WAS NAMED (batch 44, reversing
1767
+ # RM6). Everything downstream follows from this one line, because
1768
+ # config_loader.get_project_path() is the single resolver: /init's
1769
+ # destination (project_init.generator and, decisively,
1770
+ # write_project_doc's own _project_root), D17 workspace trust, the
1771
+ # `.venastine/` config tier, and UserMemory's project scope (D25/M12).
1772
+ #
1773
+ # RM6 said the opposite -- trust keys off cwd, AGENT_WORKSPACE is a
1774
+ # permission boundary and "deliberately not a project path" -- and the
1775
+ # report that reopened it is what that split actually looks like in
1776
+ # use: with AGENT_WORKSPACE set, read/write/edit/shell were correctly
1777
+ # confined to the project while /init scaffolded documentation into
1778
+ # the HARNESS. One session, two different ideas of where the work was.
1779
+ #
1780
+ # SAFE BY AN ORDERING THAT ALREADY EXISTED: check_workspace() ran a
1781
+ # few lines above and refuses a workspace that is, or sits inside, the
1782
+ # harness install tree. So the project can never become the harness by
1783
+ # this route -- and that guard is now load-bearing for a second
1784
+ # reason, which is why the launcher must still never set the variable.
1785
+ project_path = (os.path.realpath(config.WORKSPACE_DIR)
1786
+ if config.WORKSPACE_DIR_EXPLICIT else os.getcwd())
1787
+ settings = load_project_config(project_path, args.trust_project)
1788
+ provider, model = resolve_runtime_defaults(args, settings)
1789
+ effort = resolve_effort(args, settings)
1790
+
1791
+ # #138. Say at launch what /model says on a switch -- the file, the
1792
+ # provider, the key -- because both shells otherwise print
1793
+ # "Provider: ANTHROPIC" and discover at the FIRST MODEL CALL that no
1794
+ # providers.json exists, in a message that names neither the file nor
1795
+ # the key. Warn-only, per /model's own split: a local endpoint takes
1796
+ # no key, so refusing would block a real configuration. Skipped for
1797
+ # the two pure-data commands that run no model call; kept for
1798
+ # --summary and --init, which do.
1799
+ #
1800
+ # Batch 44: the TUI path no longer computes these here. `provider` is
1801
+ # resolve_runtime_defaults' answer, and §43's remembered /model pair is
1802
+ # restored later, inside VenastineApp.__init__ -- so a list frozen at
1803
+ # this line named the CONFIG provider while the banner one row above it
1804
+ # named the restored one. The app computes its own against the pair it
1805
+ # will actually call. Fixed at the producer: the check was right and
1806
+ # its input was wrong.
1807
+ if not (args.memories or args.forget or args.tui):
1808
+ from credentials import provider_startup_issues
1809
+ for warning in provider_startup_issues(provider):
1810
+ print(f"[warning] {warning}")
1811
+
1812
+ # §21b M15. AFTER load_project_config, because scoping needs the
1813
+ # resolved project path -- and before any MCP setup, since neither
1814
+ # command runs a model or needs a tool.
1815
+ if args.memories or args.forget:
1816
+ return run_memory_command(args)
1817
+
1818
+ # §21c (M21). Beside the memory commands and for the same reasons: it
1819
+ # needs the resolved project path for nothing, but it DOES need the
1820
+ # resolved provider/model, and it runs no tool and needs no MCP server.
1821
+ if args.summary is not None:
1822
+ return run_summary_command(args, provider, model)
1823
+
1824
+ # §24. Beside the others, and AFTER load_project_config for a reason the
1825
+ # rest do not share: the generator resolves its destination through
1826
+ # config_loader.get_project_path(), and reads the trust state that
1827
+ # initialize() has just settled.
1828
+ if args.init:
1829
+ return run_init_command(args, provider, model)
1830
+ if args.project_config:
1831
+ # REFUSED rather than ignored, unlike its two siblings above.
1832
+ # Someone who types this and gets an ordinary chat session has
1833
+ # been told nothing about why their project has no settings.json.
1834
+ # The older two keep their silence: changing them is a behaviour
1835
+ # change, and this one has no users yet to surprise.
1836
+ print("--project-config is part of --init. "
1837
+ "Re-run as: --init --project-config")
1838
+ return 1
1839
+
1840
+ # Argument validation before connecting anything: parser.error() exits,
1841
+ # and doing it after setup_mcp() would spawn stdio server subprocesses
1842
+ # only to abandon them on the way out.
1843
+ if args.tui and args.mode == "research":
1844
+ # §16 ships the chat shell; research mode's coarse progress view
1845
+ # is driven from inside the TUI, not from a launch flag.
1846
+ parser.error("--tui does not take --mode research; use /research inside the TUI.")
1847
+ if args.mode == "research" and not args.tui and not args.query:
1848
+ parser.error("--mode research requires a positional query argument.")
1849
+ if args.tui and args.query:
1850
+ # The parser help says a positional query is "sent as the first
1851
+ # message", and tui.app.run() has no first-message parameter --
1852
+ # so this combination silently dropped it. Refusing is honest;
1853
+ # adding a first-message path to the TUI is §16 scope.
1854
+ parser.error(
1855
+ "--tui does not take a positional query; start the TUI and "
1856
+ "type your message, or drop --tui to send it directly.")
1857
+ if (args.grant_tools is not None or args.attended is not None
1858
+ or args.review is not None) and args.mode != "research":
1859
+ # Chat is interactive by definition, so a pre-flight grant there
1860
+ # would be authorising up front what is about to be asked anyway --
1861
+ # and silently widening chat is not what a flag documented for
1862
+ # research should do. --tui lands here too (its mode is chat),
1863
+ # which is why the message names the in-TUI spelling.
1864
+ #
1865
+ # §29 (N8), audit #141: --review and --no-review are documented
1866
+ # the same way -- --help renders both as "Research mode: ..." --
1867
+ # and were not in this condition, so resolve_review() computed a
1868
+ # value that run_chat has no parameter for and nothing was said.
1869
+ # `is not None` covers both spellings: --no-review in chat is
1870
+ # equally meaningless, and refusing one while tolerating the
1871
+ # other makes the guard a special case instead of a rule.
1872
+ parser.error(
1873
+ "--grant/--grant-tools/--attended/--review apply to "
1874
+ "--mode research. Inside the TUI, use "
1875
+ "/research --grant --attended --review <query>.")
1876
+
1877
+ # §29 (N6). BELOW the early-exit commands, because this exists to keep
1878
+ # the THREAD PICKER uncluttered and none of them shows one -- while
1879
+ # #82 measured the sweep at 441ms on a 2000x2000 database, per launch.
1880
+ # Still AFTER create_db_and_tables, which is what ensures the column
1881
+ # it reads.
1882
+ _classify_legacy_threads()
1883
+
1884
+ mcp = setup_mcp(project_path)
1885
+ try:
1886
+ if args.tui:
1887
+ # Detach the stderr handler before Textual takes the screen.
1888
+ # Everything logged up to this point -- database creation, the
1889
+ # trust prompt, MCP server connections -- is pre-mount and
1890
+ # belongs on stderr, which is why this re-configures HERE
1891
+ # rather than at the top of main(): the flag isn't parsed yet
1892
+ # up there, and those messages genuinely want a terminal.
1893
+ #
1894
+ # From here on stderr would paint over the rendered UI, so the
1895
+ # rotating file keeps everything and tui/app.py routes
1896
+ # WARNING+ into the transcript. configure_logging is
1897
+ # documented idempotent and clears handlers first, so this is
1898
+ # a re-attach rather than a second stack.
1899
+ configure_logging(stderr=False)
1900
+ from tui.app import run as run_tui
1901
+ # #138. The warnings travel INTO the app rather than being
1902
+ # printed: anything on stdout before Textual takes the screen
1903
+ # vanishes the moment it renders, and TranscriptLogHandler is
1904
+ # attached only at mount -- so this pre-mount print would be
1905
+ # seen by nobody. on_mount writes each into the transcript.
1906
+ # §43 (RM3). Whether a FLAG named the pair, which the
1907
+ # resolved values above can no longer say -- and the TUI
1908
+ # needs it to know whether a remembered /model choice may
1909
+ # apply. Computed from args rather than by comparing the
1910
+ # resolved pair against settings.json, which would read a
1911
+ # flag that happens to match the configured value as absent.
1912
+ run_tui(provider, model, settings,
1913
+ cli_pinned=args.provider is not None
1914
+ or args.model is not None)
1915
+ elif args.mode == "research":
1916
+ # AFTER setup_mcp: the tools a grant can cover are named at
1917
+ # connection time, so asking any earlier would offer a list
1918
+ # that is empty for exactly the servers this exists to reach.
1919
+ review_on = resolve_review(args, settings)
1920
+ run_research(
1921
+ args.query, provider, model,
1922
+ ensemble_mode=settings.get("ensemble_mode"),
1923
+ ensemble_n=settings.get("ensemble_n"),
1924
+ authorization=build_research_authorization(
1925
+ args.grant_tools, resolve_attended(args, settings)),
1926
+ # Two facts, deliberately: whether the review runs, and
1927
+ # whether anyone can be asked about it. build_review_consent
1928
+ # returns None on a non-tty stdin, so a piped run still
1929
+ # gets the findings and still changes nothing (V6).
1930
+ subagent_review=review_on,
1931
+ review=build_review_consent() if review_on else None,
1932
+ effort=effort,
1933
+ )
1934
+ else:
1935
+ thread_id = args.thread
1936
+ if args.ref:
1937
+ # §21c (M21). A reference needs a thread to attach TO, and the
1938
+ # CLI otherwise creates one lazily on the first turn -- so with
1939
+ # --ref the thread is created here and printed, which is also
1940
+ # what makes it resumable. The cost of --ref with no message is
1941
+ # one empty thread, the same cost /new already carries.
1942
+ if thread_id is None:
1943
+ from core.memory import ConversationMemory
1944
+ thread_id = ConversationMemory().thread_id
1945
+ print(f"[thread: {thread_id}]")
1946
+ attach_cli_refs(thread_id, args.ref, provider, model)
1947
+ run_chat(thread_id, provider, model, first_message=args.query,
1948
+ effort=effort)
1949
+ finally:
1950
+ # finally, not "at the end": run_research raises SystemExit(1) on a
1951
+ # failed pipeline, and Ctrl+C reaches here as KeyboardInterrupt.
1952
+ # Both are ordinary exits that must still reap child processes.
1953
+ from tools.registry import registry
1954
+ teardown_mcp(mcp, registry)
1955
+ return 0
1956
+
1957
+
1958
+ if __name__ == "__main__":
1959
+ raise SystemExit(main())