@yahyahammad/venastine 0.2.0 → 0.3.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (129) hide show
  1. package/.env.example +19 -14
  2. package/CONFIG_ARCHITECTURE.md +2002 -0
  3. package/NOTICE +1 -1
  4. package/README.md +233 -94
  5. package/agents/builtin/build.md +73 -0
  6. package/agents/builtin/general.md +80 -0
  7. package/agents/builtin/plan.md +23 -5
  8. package/agents/builtin/test.md +65 -0
  9. package/agents/builtin/writer.md +67 -0
  10. package/agents/manager.py +261 -195
  11. package/agents/subagent_tool.py +277 -43
  12. package/agents/tui_commands.py +7 -12
  13. package/bin/venastine.mjs +528 -382
  14. package/bin/venastine.py +71 -0
  15. package/cli_commands.py +835 -0
  16. package/config.py +95 -1198
  17. package/config.yaml +1090 -0
  18. package/config_edit.py +1301 -0
  19. package/config_schema.py +966 -0
  20. package/config_update.py +749 -0
  21. package/core/agent_activity.py +158 -20
  22. package/core/ansi.py +452 -0
  23. package/core/approval.py +27 -5
  24. package/core/call_view.py +364 -0
  25. package/core/cancel.py +121 -0
  26. package/core/chatgpt_auth.py +747 -0
  27. package/core/claims_view.py +107 -0
  28. package/core/client.py +1238 -82
  29. package/core/commands.py +454 -0
  30. package/core/compaction.py +830 -66
  31. package/core/config_loader.py +516 -97
  32. package/core/connect.py +686 -0
  33. package/core/events.py +68 -6
  34. package/core/file_mentions.py +280 -0
  35. package/core/interaction.py +87 -4
  36. package/core/line_pattern.py +128 -0
  37. package/core/loop.py +1516 -440
  38. package/core/memory.py +120 -8
  39. package/core/pipeline_models.py +23 -9
  40. package/core/provider_errors.py +234 -0
  41. package/core/reasoning/confidence_scoring.py +70 -54
  42. package/core/reasoning/json_retry.py +19 -1
  43. package/core/reasoning/orchestrator.py +232 -53
  44. package/core/reasoning/output_writer.py +90 -31
  45. package/core/reasoning/payload_validation.py +133 -7
  46. package/core/reasoning/pipeline_storage.py +427 -361
  47. package/core/reasoning/review.py +659 -615
  48. package/core/reasoning/scholar.py +38 -14
  49. package/core/reasoning/source_corpus.py +110 -4
  50. package/core/replay.py +158 -26
  51. package/core/session.py +36 -12
  52. package/core/session_view.py +259 -0
  53. package/core/session_wake.py +259 -0
  54. package/core/shell_sessions.py +1553 -0
  55. package/core/workspace_trust.py +1 -1
  56. package/credentials.py +308 -180
  57. package/database.py +82 -1
  58. package/{PRIVACY.md → docs/PRIVACY.md} +19 -7
  59. package/docs/SECURITY.md +108 -0
  60. package/docs/THIRD_PARTY_NOTICES.md +148 -0
  61. package/env_secrets.py +118 -77
  62. package/json_store.py +236 -16
  63. package/logging_setup.py +121 -11
  64. package/main.py +1671 -199
  65. package/mcp_client/client.py +257 -23
  66. package/mcp_client/config.py +484 -379
  67. package/mcp_client/registration.py +163 -2
  68. package/memories/manager.py +15 -0
  69. package/memories/tui_commands.py +7 -12
  70. package/package.json +234 -4
  71. package/project_init/config_files.py +4 -0
  72. package/project_init/generator.py +201 -37
  73. package/project_init/manifest.py +418 -406
  74. package/project_init/tui_commands.py +7 -4
  75. package/prompts/revalidate.md +1 -1
  76. package/prompts/revise.md +17 -15
  77. package/prompts/system_prompts.py +64 -10
  78. package/providers.json.example +94 -92
  79. package/pyproject.toml +51 -2
  80. package/requirements.txt +252 -29
  81. package/safety/policy_enforcement.py +353 -17
  82. package/security/askpass.py +419 -0
  83. package/security/capability.py +37 -7
  84. package/security/confine.py +484 -0
  85. package/security/hosted.py +182 -0
  86. package/security/permissions.py +54 -7
  87. package/security/posture.py +124 -12
  88. package/security/protected_paths.py +198 -6
  89. package/security/sandbox.py +3262 -139
  90. package/security/secrets.py +855 -0
  91. package/skills/tui_commands.py +3 -4
  92. package/storage.py +368 -35
  93. package/tools/base.py +465 -305
  94. package/tools/builtin/_math_common.py +306 -16
  95. package/tools/builtin/_net_common.py +267 -61
  96. package/tools/builtin/arxiv.py +681 -223
  97. package/tools/builtin/ask_user.py +231 -213
  98. package/tools/builtin/discrete_math.py +35 -4
  99. package/tools/builtin/fetch_url.py +239 -21
  100. package/tools/builtin/file_ops.py +341 -33
  101. package/tools/builtin/geometry.py +184 -148
  102. package/tools/builtin/get_time.py +2 -2
  103. package/tools/builtin/linear_algebra.py +66 -23
  104. package/tools/builtin/load_skill.py +10 -0
  105. package/tools/builtin/logic.py +171 -12
  106. package/tools/builtin/pin.py +46 -12
  107. package/tools/builtin/probability_stats.py +224 -228
  108. package/tools/builtin/project_docs.py +80 -21
  109. package/tools/builtin/remember.py +21 -4
  110. package/tools/builtin/shell.py +586 -67
  111. package/tools/builtin/shell_sessions.py +613 -0
  112. package/tools/builtin/symbolic_math.py +80 -10
  113. package/tools/builtin/todo.py +5 -3
  114. package/tools/builtin/web_search.py +329 -151
  115. package/tools/context.py +23 -0
  116. package/tools/isolation.py +387 -314
  117. package/tools/registry.py +347 -30
  118. package/tui/app.py +4645 -438
  119. package/tui/app.tcss +185 -2
  120. package/tui/commands.py +10 -154
  121. package/tui/diffs.py +286 -265
  122. package/tui/hosted_driver.py +102 -0
  123. package/tui/markdown.py +60 -10
  124. package/tui/meters.py +103 -7
  125. package/tui/screens.py +346 -92
  126. package/tui/themes.py +59 -19
  127. package/tui/widgets.py +1575 -111
  128. package/SECURITY.md +0 -88
  129. package/THIRD_PARTY_NOTICES.md +0 -100
@@ -0,0 +1,835 @@
1
+ """
2
+ cli_commands.py
3
+
4
+ The CLI's slash commands (ROADMAP_v3 §89, #8; TECHNICAL_DEBT register
5
+ item 45).
6
+
7
+ Until §89 every line typed at the CLI's prompt went to the model, so
8
+ `/help` spent a model turn, and each feature that wanted the CLI shipped a
9
+ flag instead (`--summary`, `--ref`, `--memories`, `--init`, ...), which
10
+ cannot be used mid-conversation. The CLI now binds handlers to
11
+ `core/commands.py`'s catalog, the same entries the TUI binds to: the names,
12
+ summaries, usage and aliases are the catalog's, a command the CLI does not
13
+ have is answered with the catalog's reason, and a `/` line that names
14
+ nothing is refused rather than sent (the TUI's rule since §16).
15
+
16
+ THE HANDLERS ARE THIN, and that is the design rather than a shortcut. What
17
+ a command DOES is a core function the TUI's handler calls too --
18
+ `model_switch`, `effort_choice`, `parse_compact_args`, `compact`,
19
+ `summarize_thread`, `attach_ref`, `render_claims`, `agent_turn`,
20
+ `call_entries`, `stored_entries` -- and what is here is reading a line and
21
+ printing an answer.
22
+
23
+ THIS MODULE MUST NOT IMPORT `main`. main.py runs as `__main__`, so an
24
+ `import main` here would load a second copy of it, with a second stdin
25
+ reader beside the one that owns the terminal. `run_chat` hands the session
26
+ the three things it needs from there instead: `ask` (a line from that one
27
+ reader), `replay` (print a stored thread) and `show` (print one entry,
28
+ labelled the way a turn is).
29
+
30
+ A handler takes (session, argument_string) and returns None. It runs on the
31
+ chat loop's thread, between turns.
32
+ """
33
+
34
+ from __future__ import annotations
35
+
36
+ import logging
37
+ from collections.abc import Callable
38
+ from dataclasses import dataclass, field
39
+ from typing import Optional
40
+ from uuid import UUID
41
+
42
+ from core import ansi
43
+ from core.commands import CATALOG, CLI, CommandRegistry, absent_reason, bind
44
+
45
+ logger = logging.getLogger(__name__)
46
+
47
+ #: How many threads `/threads` and `/ref` list. A line-based list longer
48
+ #: than a screen scrolls its first rows away, and they are the newest; an
49
+ #: older thread is still reachable by typing its id at the same prompt.
50
+ THREAD_ROWS = 20
51
+
52
+ #: How many tool calls a bare `/call` lists, newest last. The numbers stay
53
+ #: the thread's own, so `/call 3` opens the third call whether or not it
54
+ #: was listed.
55
+ CALL_ROWS = 30
56
+
57
+
58
+ def _ask_nothing(prompt: str) -> str:
59
+ return ""
60
+
61
+
62
+ @dataclass
63
+ class ChatSession:
64
+ """What one CLI conversation holds between turns.
65
+
66
+ The CLI's twin of the app attributes the TUI's handlers read --
67
+ `provider_name`, `model`, `effort`, `active_agent`, `active_skills`
68
+ and the thread -- plus two requests a handler leaves for `run_chat`,
69
+ which owns the loop: to quit, and to run one turn under an agent.
70
+ """
71
+
72
+ provider_name: str
73
+ model: str
74
+ effort: Optional[str] = None
75
+ thread_id: Optional[UUID] = None
76
+ printed_thread_id: bool = False
77
+ # §18 and §19 K5: session-scoped and unpersisted, as in the TUI.
78
+ active_agent: object = None
79
+ active_skills: list = field(default_factory=list)
80
+ authorization: object = None
81
+ ask: Callable[[str], str] = _ask_nothing
82
+ replay: Callable[[UUID], None] = lambda thread_id: None
83
+ show: Callable[[str, str], None] = lambda role, text: print(text)
84
+ # Left for run_chat by /quit and /grill-me.
85
+ quit_requested: bool = False
86
+ one_shot: object = None
87
+
88
+ def memory(self):
89
+ """The current thread, created if there is none yet.
90
+
91
+ For a command that puts state ON a thread -- a goal, a reference
92
+ -- which is the TUI's `app.memory` rule: constructing a
93
+ ConversationMemory writes the thread row, so only a command that
94
+ needs one may create one.
95
+ """
96
+ from core.memory import ConversationMemory
97
+
98
+ memory = ConversationMemory(thread_id=self.thread_id)
99
+ self.thread_id = memory.thread_id
100
+ return memory
101
+
102
+
103
+ def _out(text: str = "") -> None:
104
+ """One line of a command's answer.
105
+
106
+ Through `ansi.for_display` whatever it is, because most of these lines
107
+ carry somebody else's text -- a thread's preview, a memory, a model's
108
+ claim, a name typed after the slash.
109
+ """
110
+ print(ansi.for_display(text))
111
+
112
+
113
+ # ---- the loop's entry point ---------------------------------------------------
114
+
115
+ def run_command(session: ChatSession, line: str) -> None:
116
+ """Run one `/` line, and contain whatever the command does.
117
+
118
+ CONTAINED HERE, as the TUI contains its own dispatch (batch 135): a
119
+ handler that raises must not end the conversation, and the traceback
120
+ goes to logs/app.log where a real bug stays findable. Ctrl+C during a
121
+ command -- a summary or a compaction is a model call -- returns to the
122
+ prompt rather than leaving the harness, which is what it does during a
123
+ turn.
124
+ """
125
+ name = line[1:].split(" ")[0]
126
+ try:
127
+ handled = registry.dispatch(session, line)
128
+ except KeyboardInterrupt:
129
+ _out(f"\n[/{name} interrupted]")
130
+ return
131
+ except Exception: # noqa: BLE001 -- see the docstring
132
+ logger.exception("The /%s command handler raised.", name)
133
+ _out(f"[/{name} failed. The error is in logs/app.log; the session "
134
+ f"is intact.]")
135
+ return
136
+ if not handled:
137
+ _out(absent_reason(name, CLI) or f"Unknown command /{name}. Try /help.")
138
+
139
+
140
+ # ---- /help /quit ----------------------------------------------------------
141
+
142
+ def _cmd_help(session: ChatSession, args: str) -> None:
143
+ _out("Commands:")
144
+ for command in registry.all():
145
+ usage = f" {command.usage}" if command.usage else ""
146
+ also = (f" (also {', '.join('/' + a for a in command.aliases)})"
147
+ if command.aliases else "")
148
+ _out(f" /{command.name}{usage} — {command.summary}{also}")
149
+ # The TUI's commands this shell lacks, each with the reason, so a
150
+ # reader who knows /config from the other shell is told where it is
151
+ # rather than left to conclude it does not exist.
152
+ missing = sorted((s for s in CATALOG.values() if not s.in_shell(CLI)),
153
+ key=lambda spec: spec.name)
154
+ if missing:
155
+ _out("Not in the CLI:")
156
+ for spec in missing:
157
+ _out(f" /{spec.name} — {spec.absent[CLI]}")
158
+
159
+
160
+ def _cmd_quit(session: ChatSession, args: str) -> None:
161
+ # run_chat asks about running sessions and leaves; Ctrl+D's route.
162
+ session.quit_requested = True
163
+
164
+
165
+ # ---- threads --------------------------------------------------------------
166
+
167
+ def _pick_thread(session: ChatSession, threads: list, verb: str):
168
+ """A thread chosen from `threads` by its row number or its id.
169
+
170
+ The TUI's picker, as a list and a question: the rows are
171
+ `core.replay.thread_row`'s, the same the picker draws. An id typed here
172
+ reaches a thread the list did not show, which is `/resume`'s purpose
173
+ and the reason the list can stay short.
174
+ """
175
+ from core.replay import thread_row
176
+
177
+ for index, thread in enumerate(threads, 1):
178
+ _out(f" {index:>2} {thread_row(thread)}")
179
+ if len(threads) >= THREAD_ROWS:
180
+ _out(f"The {THREAD_ROWS} most recently active; an older thread is "
181
+ f"reachable by its id.")
182
+ try:
183
+ answer = session.ask(
184
+ f"Number or thread id to {verb} (Enter cancels): ").strip()
185
+ except (EOFError, KeyboardInterrupt):
186
+ answer = ""
187
+ if not answer:
188
+ _out("Nothing chosen.")
189
+ return None
190
+ if answer.isdigit():
191
+ number = int(answer)
192
+ if 1 <= number <= len(threads):
193
+ return threads[number - 1]["id"]
194
+ _out(f"There is no row {number}.")
195
+ return None
196
+ try:
197
+ return UUID(answer)
198
+ except ValueError:
199
+ _out(f"{answer!r} is neither a row number nor a thread id.")
200
+ return None
201
+
202
+
203
+ def _resume(session: ChatSession, thread_id: UUID) -> None:
204
+ """Switch to `thread_id` and print it, as `--thread` does at launch."""
205
+ import storage
206
+
207
+ if thread_id == session.thread_id:
208
+ _out("That is the conversation you are in.")
209
+ return
210
+ if storage.get_thread(thread_id) is None:
211
+ _out(f"No thread {thread_id}.")
212
+ return
213
+ session.thread_id = thread_id
214
+ session.printed_thread_id = True
215
+ _out(f"Resuming thread: {thread_id}")
216
+ session.replay(thread_id)
217
+
218
+
219
+ def _cmd_threads(session: ChatSession, args: str) -> None:
220
+ import storage
221
+
222
+ threads = storage.list_threads(limit=THREAD_ROWS)
223
+ if not threads:
224
+ _out("No saved conversations yet.")
225
+ return
226
+ _out("Saved conversations, most recently active first:")
227
+ chosen = _pick_thread(session, threads, "resume")
228
+ if chosen is not None:
229
+ _resume(session, chosen)
230
+
231
+
232
+ def _cmd_resume(session: ChatSession, args: str) -> None:
233
+ text = args.strip()
234
+ if not text:
235
+ _out("Usage: /resume <thread-id>. /threads lists recent ones.")
236
+ return
237
+ try:
238
+ resolved = UUID(text)
239
+ except ValueError:
240
+ _out(f"{text!r} is not a thread id (expected a uuid).")
241
+ return
242
+ _resume(session, resolved)
243
+
244
+
245
+ def _cmd_new(session: ChatSession, args: str) -> None:
246
+ session.thread_id = None
247
+ session.printed_thread_id = False
248
+ _out("Starting a new conversation thread.")
249
+
250
+
251
+ # ---- goal, agent, skill ---------------------------------------------------
252
+
253
+ def _cmd_goal(session: ChatSession, args: str) -> None:
254
+ """The thread's persistent objective (§18 goal mode).
255
+
256
+ The TUI's rule (#113): reading or clearing never creates a thread, and
257
+ only SETTING a goal does -- the user is putting state on one.
258
+ """
259
+ from core.memory import ConversationMemory
260
+
261
+ current = (ConversationMemory(thread_id=session.thread_id)
262
+ if session.thread_id is not None else None)
263
+ if args == "clear":
264
+ if current is None:
265
+ _out("No goal set.")
266
+ else:
267
+ current.set_extra("goal", None)
268
+ _out("Goal cleared.")
269
+ elif args:
270
+ session.memory().set_extra("goal", args)
271
+ _out(f"Goal set: {args}")
272
+ else:
273
+ goal = current.extra.get("goal") if current is not None else None
274
+ _out(f"Current goal: {goal}" if goal else
275
+ "No goal set. /goal <text> to set one, /goal clear to remove.")
276
+
277
+
278
+ def _note_skills(session: ChatSession) -> None:
279
+ """What an /agent switch makes unavailable to an active skill.
280
+
281
+ Advisory, as in the TUI (review §19-20 f21): enforcement still happens
282
+ per call, and a note now beats the model finding out as a denied call.
283
+ """
284
+ from agents.manager import manager as agents
285
+ from skills.manager import manager as skills
286
+
287
+ agent = session.active_agent
288
+ context = agents.active_context(agent) if agent is not None else None
289
+ label = agent.name if agent is not None else "default"
290
+ for name in session.active_skills:
291
+ skill = skills.get(name)
292
+ if skill is None:
293
+ continue
294
+ missing = skills.missing_tools(skill, context)
295
+ if missing:
296
+ _out(f"Note: {name} expects {', '.join(missing)}, which are not "
297
+ f"available under agent {label}.")
298
+
299
+
300
+ def _cmd_agent(session: ChatSession, args: str) -> None:
301
+ """The session's active agent (§18): its prompt, ToolContext and
302
+ model overrides apply to every turn until /agent default, through
303
+ `core.loop.agent_turn`, which the TUI's turn calls too."""
304
+ from agents.manager import manager
305
+
306
+ available = ", ".join(manager.names()) or "none"
307
+ if not args:
308
+ current = session.active_agent.name if session.active_agent else "default"
309
+ _out(f"Active agent: {current}. Available: {available}. "
310
+ "/agent <name> to switch, /agent default to clear.")
311
+ return
312
+ if args == "default":
313
+ session.active_agent = None
314
+ _out("Active agent cleared — default harness.")
315
+ _note_skills(session)
316
+ return
317
+ agent = manager.get(args)
318
+ if agent is None:
319
+ _out(f"Unknown agent {args!r}. Available: {available}.")
320
+ return
321
+ session.active_agent = agent
322
+ _out(f"Active agent: {agent.name} — {agent.description}")
323
+ _note_skills(session)
324
+
325
+
326
+ def _cmd_skill(session: ChatSession, args: str) -> None:
327
+ """Activate a skill for this session: its full body is pinned into
328
+ every later turn's prompt until deactivated (§19 K1)."""
329
+ from agents.manager import manager as agents
330
+ from skills.manager import manager as skills
331
+
332
+ args = (args or "").strip()
333
+ if not args:
334
+ grouped = skills.by_category()
335
+ if not grouped:
336
+ _out("No skills discovered.")
337
+ return
338
+ _out("Skills (* = active):")
339
+ for category in sorted(grouped):
340
+ if category:
341
+ _out(f" [{category}]")
342
+ for skill in grouped[category]:
343
+ mark = "*" if skill.name in session.active_skills else "-"
344
+ _out(f" {mark} {skill.name}: {skill.description}")
345
+ _out(f"Active: {', '.join(session.active_skills) or 'none'}.")
346
+ _out("/skill <name> to activate, /skill off <name>, /skill clear.")
347
+ return
348
+ if args == "clear":
349
+ session.active_skills = []
350
+ _out("All skills deactivated.")
351
+ return
352
+ if args.startswith("off "):
353
+ name = args[4:].strip()
354
+ if name not in session.active_skills:
355
+ _out(f"{name!r} is not active.")
356
+ return
357
+ session.active_skills = skills.deactivate(name, session.active_skills)
358
+ _out(f"Deactivated {name}.")
359
+ return
360
+
361
+ skill = skills.get(args)
362
+ if skill is None:
363
+ _out(f"Unknown skill {args!r}. "
364
+ f"Available: {', '.join(skills.names()) or 'none'}.")
365
+ return
366
+ already = args in session.active_skills
367
+ session.active_skills = skills.activate(args, session.active_skills)
368
+ if already:
369
+ _out(f"{skill.name} is already active.")
370
+ return
371
+ _out(f"Activated {skill.name} — {skill.description}. Its full "
372
+ "instructions now apply to every turn until /skill off.")
373
+ # K2: report, do not refuse -- the TUI's reasoning, unchanged.
374
+ context = (agents.active_context(session.active_agent)
375
+ if session.active_agent is not None else None)
376
+ missing = skills.missing_tools(skill, context)
377
+ if missing:
378
+ _out(f"Note: {skill.name} expects {', '.join(missing)}, which "
379
+ f"{'is' if len(missing) == 1 else 'are'} not available in this "
380
+ "session. The skill is active; those steps will not be.")
381
+
382
+
383
+ def _cmd_grill(session: ChatSession, args: str) -> None:
384
+ """One turn in this thread under the grill-me agent's prompt (§18).
385
+ run_chat runs it as it runs a typed message, so it prints live and
386
+ Ctrl+C stops it the same way."""
387
+ from agents.manager import manager
388
+
389
+ agent = manager.get("grill-me")
390
+ if agent is None:
391
+ _out("grill-me agent not found.")
392
+ return
393
+ session.one_shot = agent
394
+
395
+
396
+ # ---- model and effort -----------------------------------------------------
397
+
398
+ def _effort_levels(session: ChatSession, provider: str, model: str):
399
+ from core.client import api_initialization, effort_levels_for_model
400
+
401
+ return effort_levels_for_model(api_initialization(provider), provider,
402
+ model)
403
+
404
+
405
+ def _cmd_effort(session: ChatSession, args: str) -> None:
406
+ """Switch reasoning effort, offering only levels this model accepts.
407
+ The decision is `core.client.effort_choice`, the TUI's own."""
408
+ from core.client import effort_choice
409
+
410
+ try:
411
+ levels = _effort_levels(session, session.provider_name, session.model)
412
+ except Exception as e: # noqa: BLE001 -- reported, as in the TUI
413
+ _out(f"Could not read effort levels: {e}")
414
+ return
415
+ effort, line, refused = effort_choice(levels, args, session.effort,
416
+ session.model)
417
+ if not refused:
418
+ session.effort = effort
419
+ _out(line)
420
+
421
+
422
+ def _cmd_model(session: ChatSession, args: str) -> None:
423
+ """Switch provider and/or model for the rest of this session.
424
+
425
+ What may be switched to is `core.connect.model_switch`'s to say, for
426
+ both shells. NOT remembered for the next launch, unlike the TUI's:
427
+ that memory is the TUI's preference store, which the CLI does not
428
+ read -- `--model` or settings.json is where this shell starts.
429
+ """
430
+ from core import connect
431
+ from credentials import load_provider_data, missing_credential_message
432
+
433
+ if not args:
434
+ _out(f"Provider: {session.provider_name} | model: {session.model}")
435
+ _out("Providers with a key: "
436
+ f"{connect.configured_providers(load_provider_data())}")
437
+ _out(connect.MODEL_USAGE)
438
+ return
439
+ provider, model, providers, error = connect.model_switch(
440
+ args, session.provider_name)
441
+ if error:
442
+ _out(error)
443
+ return
444
+ session.provider_name, session.model = provider, model
445
+ _out(f"Now using {provider} | {model} for this session.")
446
+ missing = missing_credential_message(provider, providers[provider])
447
+ if missing:
448
+ _out(missing)
449
+ note = connect.agent_pin_note(session.active_agent, provider, model)
450
+ if note:
451
+ _out(note)
452
+ if session.effort:
453
+ _revalidate_effort(session)
454
+
455
+
456
+ def _cmd_submodel(session: ChatSession, args: str) -> None:
457
+ """Choose the model spawned subagents run on (ROADMAP_v3 §57, SM11).
458
+
459
+ `core.connect.submodel_command` decides and says it, for both shells.
460
+ REMEMBERED, unlike this shell's /model, and not inconsistently: the
461
+ pair lives in core/pipeline_models.py's store, which a spawn reads in
462
+ either shell, so a choice made in the TUI already reaches this shell's
463
+ children. The command is how this shell sees it and clears it.
464
+ """
465
+ from core import connect
466
+
467
+ for _kind, text in connect.submodel_command(args, session.provider_name):
468
+ _out(text)
469
+
470
+
471
+ def _revalidate_effort(session: ChatSession) -> None:
472
+ """Effort is per-model: a level the old model took may be refused
473
+ outright by the new one, and every turn would then fail with a
474
+ provider 400. The TUI runs the same check after its /model."""
475
+ try:
476
+ levels = _effort_levels(session, session.provider_name, session.model)
477
+ except Exception as e: # noqa: BLE001 -- keep a deliberate choice
478
+ _out(f"Could not verify effort {session.effort!r} ({e}); keeping it.")
479
+ return
480
+ if session.effort in levels:
481
+ return
482
+ detail = (f"{session.model} accepts {', '.join(levels)}" if levels
483
+ else f"{session.model} exposes no reasoning-effort control")
484
+ _out(f"Effort {session.effort!r} is not usable: {detail}. Falling back "
485
+ f"to auto.")
486
+ session.effort = None
487
+
488
+
489
+ # ---- compaction, summaries, references ------------------------------------
490
+
491
+ def _cmd_compact(session: ChatSession, args: str) -> None:
492
+ """Compact this thread now (§21). A model call, announced first; the
493
+ floors hold, as for an automatic compaction."""
494
+ from core import compaction, config_loader
495
+
496
+ if session.thread_id is None:
497
+ _out("Nothing to compact — this thread is empty.")
498
+ return
499
+ overrides, error = compaction.parse_compact_args(args)
500
+ if error:
501
+ _out(error)
502
+ return
503
+ try:
504
+ # Validated before a model call is spent, by the function the
505
+ # automatic path uses.
506
+ config_loader.effective_compaction(overrides)
507
+ except ValueError as e:
508
+ _out(str(e))
509
+ return
510
+ _out("Compacting this conversation…")
511
+ try:
512
+ outcome = compaction.compact(
513
+ session.memory(), session.model, session.provider_name,
514
+ overrides=overrides, activity=None, depth=0)
515
+ except Exception as e: # noqa: BLE001 -- the TUI's containment
516
+ _out(f"Compaction failed: {e}")
517
+ return
518
+ _out(f"— {outcome['text']} —")
519
+
520
+
521
+ def _cmd_summary(session: ChatSession, args: str) -> None:
522
+ """Distil this conversation and show it (§21c). Describes, does not
523
+ fold (M20)."""
524
+ from core import compaction
525
+
526
+ if session.thread_id is None:
527
+ _out("Nothing to summarise — this thread is empty.")
528
+ return
529
+ _out("Summarising this conversation…")
530
+ try:
531
+ notice = compaction.summarize_thread(
532
+ session.thread_id, session.model, session.provider_name,
533
+ activity=None, depth=0)
534
+ except Exception as e: # noqa: BLE001 -- the TUI's containment
535
+ _out(f"Summary failed: {e}")
536
+ return
537
+ if notice is None:
538
+ _out("Could not summarise this thread.")
539
+ return
540
+ _out("Summary:")
541
+ session.show("assistant", notice["text"])
542
+
543
+
544
+ def attach_summary(memory, source: UUID, model: str,
545
+ provider_name: str) -> tuple:
546
+ """Summarise `source` and attach it to `memory`'s thread: `(ok, text)`.
547
+
548
+ The one route for `--ref` and `/ref` in this shell, through the writer
549
+ the TUI's /ref uses (`core.loop.attach_ref`), so the shells cannot
550
+ disagree about the cap or the stored shape. The label is the thread's
551
+ first-message preview, as the TUI's picker attaches (#171). Raises
552
+ whatever summarising raises; the caller says so in its own words.
553
+ """
554
+ from core import compaction
555
+ from core.loop import attach_ref
556
+ from storage import thread_preview
557
+
558
+ notice = compaction.summarize_thread(source, model, provider_name)
559
+ if notice is None:
560
+ return False, f"nothing to summarise in {source}"
561
+ return attach_ref(memory, source, notice["text"], thread_preview(source))
562
+
563
+
564
+ def _cmd_ref(session: ChatSession, args: str) -> None:
565
+ """Attach another conversation's summary to this one (§21c).
566
+
567
+ User-initiated by construction, which is §21's locked decision: the
568
+ person picks what crosses between threads.
569
+ """
570
+ import storage
571
+ from core.loop import clear_refs
572
+ from core.memory import ConversationMemory
573
+
574
+ flag = args.strip().lower()
575
+ current = (ConversationMemory(thread_id=session.thread_id)
576
+ if session.thread_id is not None else None)
577
+ if flag in ("--list", "list"):
578
+ refs = (current.extra.get("refs") or []) if current else []
579
+ if not refs:
580
+ _out("This thread references nothing.")
581
+ return
582
+ _out(f"Referencing {len(refs)} conversation(s):")
583
+ for ref in refs:
584
+ _out(f" {ref['thread_id']} {ref.get('label') or '(no preview)'}")
585
+ return
586
+ if flag in ("--clear", "clear"):
587
+ dropped = clear_refs(current) if current else 0
588
+ _out(f"Dropped {dropped} reference{'' if dropped == 1 else 's'}."
589
+ if dropped else "This thread references nothing.")
590
+ return
591
+ if flag:
592
+ _out(f"Unknown option {args.strip()!r}. Usage: /ref [--list|--clear].")
593
+ return
594
+
595
+ # The CURRENT thread is excluded, as in the TUI: referencing yourself
596
+ # spends a model call to inject what the model is already reading.
597
+ threads = [t for t in storage.list_threads(limit=THREAD_ROWS + 1)
598
+ if t["id"] != session.thread_id][:THREAD_ROWS]
599
+ if not threads:
600
+ _out("No other conversations to reference yet.")
601
+ return
602
+ _out("Conversations to reference:")
603
+ chosen = _pick_thread(session, threads, "reference")
604
+ if chosen is None:
605
+ return
606
+ if chosen == session.thread_id:
607
+ _out("That is this conversation; nothing to reference.")
608
+ return
609
+ _out(f"Summarising thread {chosen}…")
610
+ try:
611
+ ok, message = attach_summary(session.memory(), chosen, session.model,
612
+ session.provider_name)
613
+ except Exception as e: # noqa: BLE001 -- the TUI's containment
614
+ _out(f"Reference failed: {e}")
615
+ return
616
+ _out(message if ok else f"Could not reference it: {message}")
617
+
618
+
619
+ # ---- memories ---------------------------------------------------------------
620
+
621
+ def print_memories() -> None:
622
+ """The durable memories visible here, with ids and scope (§21b M15).
623
+
624
+ `--memories` and `/memories` both print this, so the flag and the
625
+ command list one way. The SCOPE is on every row because "which of
626
+ these follows me to another project" is the question a person pruning
627
+ memories is asking.
628
+ """
629
+ from memories.manager import manager as memory_manager
630
+
631
+ rows = memory_manager.visible()
632
+ if not rows:
633
+ where = memory_manager.scope_path() or "(no project resolved)"
634
+ _out(f"No durable memories visible from {where}.")
635
+ return
636
+ for row in rows:
637
+ marker = "global " if row["scope"] == "global" else "project"
638
+ category = f" [{row['category']}]" if row.get("category") else ""
639
+ _out(f"{row['id']} {marker}{category} {row['content']}")
640
+
641
+
642
+ def forget_memory(raw: str, listing: str) -> bool:
643
+ """Delete one memory by id; `listing` names how to see the ids.
644
+
645
+ By ID and never by substring: a substring that hit two memories would
646
+ have to pick one, and picking silently deletes something nobody named.
647
+ """
648
+ from storage import forget_memory as _forget
649
+
650
+ try:
651
+ memory_id = UUID(raw)
652
+ except ValueError:
653
+ _out(f"Not a memory id: {raw!r}. Run {listing} to list them.")
654
+ return False
655
+ if _forget(memory_id):
656
+ _out(f"Forgot {memory_id}.")
657
+ return True
658
+ _out(f"No memory with id {memory_id}.")
659
+ return False
660
+
661
+
662
+ def _cmd_memories(session: ChatSession, args: str) -> None:
663
+ print_memories()
664
+
665
+
666
+ def _cmd_forget(session: ChatSession, args: str) -> None:
667
+ raw = args.strip()
668
+ if not raw:
669
+ _out("Usage: /forget <id>. Run /memories to see the ids.")
670
+ return
671
+ forget_memory(raw, "/memories")
672
+
673
+
674
+ # ---- claims -----------------------------------------------------------------
675
+
676
+ def _cmd_claims(session: ChatSession, args: str) -> None:
677
+ """A stored research run's claims and tiers (§26), drawn by
678
+ `core.claims_view`, which the TUI's claims screen draws too.
679
+
680
+ The CLI's chat holds no run of its own -- research runs from
681
+ `--mode research`, which prints the run id this takes.
682
+ """
683
+ from core.claims_view import claims_header, render_claims
684
+ from core.reasoning.pipeline_storage import load_pipeline_run
685
+
686
+ run_id = args.strip()
687
+ if not run_id:
688
+ _out("Usage: /claims <run id>. A research run (venastine --mode "
689
+ "research) prints its run id.")
690
+ return
691
+ try:
692
+ record = load_pipeline_run(UUID(run_id))
693
+ except ValueError as e:
694
+ # A malformed id and an unknown run alike: load_pipeline_run
695
+ # raises ValueError for the second by its own convention.
696
+ _out(f"/claims: {e}")
697
+ return
698
+ except Exception as e: # noqa: BLE001 -- #104's shape, as in the TUI
699
+ _out(f"/claims: could not load run: {e}")
700
+ return
701
+ claims = record["claims"] or []
702
+ _out(claims_header(f"Claims — run {run_id} ({record['status']})",
703
+ len(claims), record["status"] == "running"))
704
+ _out(render_claims(claims))
705
+
706
+
707
+ # ---- calls and sessions (register item 45) ---------------------------------
708
+
709
+ def _show_call(session: ChatSession, thread_id: UUID, kind: str,
710
+ call_id: str) -> None:
711
+ """Print what the TUI opens when this call's line is clicked.
712
+
713
+ `on_call_selected`'s routing, kind by kind: a session-starting call
714
+ shows its SESSION -- from the manager while this process holds it,
715
+ else rebuilt from the archive (SS18) -- a spawn shows the run it
716
+ started, and everything else, including either of those whose target
717
+ cannot be found, shows the call itself (TR12). The entries are
718
+ `core/session_view.py`'s and `core/call_view.py`'s, which the TUI
719
+ paints, so the two shells show one call the same way.
720
+ """
721
+ from core import shell_sessions
722
+ from core.call_view import call_entries
723
+ from core.session_view import live_entries, stored_entries
724
+ from tools.base import OPENS_SESSION, OPENS_THREAD
725
+
726
+ if kind == OPENS_SESSION:
727
+ row = next((r for r in shell_sessions.sessions.rows()
728
+ if str(r.call_id) == call_id), None)
729
+ if row is not None:
730
+ buffer = shell_sessions.sessions.buffer(row.id)
731
+ tail, truncated = (buffer.last() if buffer is not None
732
+ else ("", False))
733
+ entries = live_entries(row, tail, truncated)
734
+ else:
735
+ entries = stored_entries(thread_id, call_id)
736
+ if entries:
737
+ _print_view(session, entries)
738
+ return
739
+ elif kind == OPENS_THREAD:
740
+ import storage
741
+
742
+ child = next((c for c in storage.child_threads(thread_id)
743
+ if str(c.get("parent_call_id")) == call_id), None)
744
+ if child is not None:
745
+ agent = child.get("agent_name") or "subagent"
746
+ _out(f"The run this call started ({agent}), thread {child['id']}:")
747
+ session.replay(child["id"])
748
+ return
749
+ entries = call_entries(thread_id, call_id)
750
+ if not entries:
751
+ _out("That call is not in this conversation's record — there is "
752
+ "nothing stored to show.")
753
+ return
754
+ _print_view(session, entries)
755
+
756
+
757
+ def _print_view(session: ChatSession, entries) -> None:
758
+ for role, text in entries:
759
+ session.show(role, text)
760
+ _out("--- end of view ---")
761
+
762
+
763
+ def _cmd_call(session: ChatSession, args: str) -> None:
764
+ """List this thread's tool calls, or show one (register item 45).
765
+
766
+ The TUI opens a call by ctrl+clicking its `▸` line, and the CLI's
767
+ lines carry nothing to click, so they are numbered here instead --
768
+ off `core.replay.tool_lines`, the lines a replay prints, so the
769
+ number names the line the reader is looking at.
770
+ """
771
+ from core.replay import tool_lines
772
+
773
+ if session.thread_id is None:
774
+ _out("No tool calls yet — this conversation is empty.")
775
+ return
776
+ lines = tool_lines(session.thread_id)
777
+ if not lines:
778
+ _out("No tool calls in this conversation yet.")
779
+ return
780
+ raw = args.strip()
781
+ if not raw:
782
+ start = max(0, len(lines) - CALL_ROWS)
783
+ if start:
784
+ _out(f"({start} earlier call{'s' if start != 1 else ''} not "
785
+ f"listed; /call <number> opens any of them.)")
786
+ for number, (line, _opens) in enumerate(lines[start:], start + 1):
787
+ _out(f" {number:>3} {line}")
788
+ _out("/call <number> shows one.")
789
+ return
790
+ if not raw.isdigit() or not 1 <= int(raw) <= len(lines):
791
+ _out(f"Usage: /call <number>, from 1 to {len(lines)}.")
792
+ return
793
+ line, opens = lines[int(raw) - 1]
794
+ if not opens:
795
+ _out("That call was stored without an id, so there is nothing to "
796
+ "look it up by.")
797
+ return
798
+ kind, call_id = opens
799
+ _show_call(session, session.thread_id, kind, call_id)
800
+
801
+
802
+ # ---- the registry -----------------------------------------------------------
803
+
804
+ registry = CommandRegistry(CLI)
805
+
806
+
807
+ def register_cli_commands() -> None:
808
+ """Idempotent, as the TUI's registrars are. One handler per command
809
+ the catalog declares for the CLI; the census test fails if this list
810
+ and the catalog disagree."""
811
+ for command in (
812
+ bind("agent", _cmd_agent),
813
+ bind("call", _cmd_call),
814
+ bind("claims", _cmd_claims),
815
+ bind("compact", _cmd_compact),
816
+ bind("effort", _cmd_effort),
817
+ bind("forget", _cmd_forget),
818
+ bind("goal", _cmd_goal),
819
+ bind("grill-me", _cmd_grill),
820
+ bind("help", _cmd_help),
821
+ bind("memories", _cmd_memories),
822
+ bind("model", _cmd_model),
823
+ bind("new", _cmd_new),
824
+ bind("quit", _cmd_quit),
825
+ bind("ref", _cmd_ref),
826
+ bind("resume", _cmd_resume),
827
+ bind("skill", _cmd_skill),
828
+ bind("submodel", _cmd_submodel),
829
+ bind("summary", _cmd_summary),
830
+ bind("threads", _cmd_threads),
831
+ ):
832
+ registry.register(command)
833
+
834
+
835
+ register_cli_commands()