@yahyahammad/venastine 0.3.8 → 0.3.10

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 (130) hide show
  1. package/.env.example +19 -19
  2. package/CONFIG_ARCHITECTURE.md +2139 -2002
  3. package/LICENSE +201 -201
  4. package/README.md +1043 -1034
  5. package/agents/builtin/compactor.md +75 -75
  6. package/agents/builtin/explore.md +77 -77
  7. package/agents/builtin/pipeline-reviewer.md +100 -100
  8. package/agents/builtin/plan.md +106 -106
  9. package/agents/builtin/review.md +74 -74
  10. package/agents/manager.py +261 -261
  11. package/agents/subagent_tool.py +472 -472
  12. package/agents/tui_commands.py +238 -146
  13. package/bin/venastine.mjs +584 -528
  14. package/bin/venastine.py +73 -71
  15. package/cli_commands.py +848 -835
  16. package/config.yaml +64 -0
  17. package/config_edit.py +1301 -1301
  18. package/config_schema.py +987 -966
  19. package/config_update.py +749 -749
  20. package/core/agent_activity.py +256 -256
  21. package/core/ansi.py +452 -452
  22. package/core/approval.py +137 -137
  23. package/core/call_view.py +364 -364
  24. package/core/cancel.py +121 -121
  25. package/core/chatgpt_auth.py +747 -747
  26. package/core/claims_view.py +107 -107
  27. package/core/client.py +2756 -2715
  28. package/core/commands.py +464 -454
  29. package/core/compaction.py +1735 -1735
  30. package/core/config_loader.py +1982 -1982
  31. package/core/connect.py +686 -686
  32. package/core/events.py +123 -123
  33. package/core/file_mentions.py +280 -280
  34. package/core/interaction.py +411 -411
  35. package/core/loop.py +2566 -2566
  36. package/core/memory.py +482 -482
  37. package/core/pipeline_models.py +190 -190
  38. package/core/provider_errors.py +274 -234
  39. package/core/reasoning/authorization.py +130 -130
  40. package/core/reasoning/base.py +219 -219
  41. package/core/reasoning/confidence_scoring.py +484 -484
  42. package/core/reasoning/events.py +149 -149
  43. package/core/reasoning/orchestrator.py +1561 -1561
  44. package/core/reasoning/output_writer.py +345 -345
  45. package/core/reasoning/payload_validation.py +524 -524
  46. package/core/reasoning/pipeline_storage.py +427 -427
  47. package/core/reasoning/scholar.py +467 -458
  48. package/core/reasoning/source_corpus.py +433 -433
  49. package/core/reasoning/source_scoring.py +855 -855
  50. package/core/replay.py +315 -315
  51. package/core/shell_sessions.py +1553 -1553
  52. package/credentials.py +307 -307
  53. package/database.py +333 -333
  54. package/docs/PRIVACY.md +78 -78
  55. package/docs/SECURITY.md +114 -108
  56. package/docs/THIRD_PARTY_NOTICES.md +148 -148
  57. package/env_secrets.py +118 -118
  58. package/json_store.py +343 -343
  59. package/logging_setup.py +295 -295
  60. package/main.py +3433 -3433
  61. package/mcp_client/client.py +780 -733
  62. package/mcp_client/config.py +484 -484
  63. package/mcp_client/registration.py +343 -343
  64. package/memories/manager.py +147 -147
  65. package/memories/tui_commands.py +319 -239
  66. package/package.json +303 -303
  67. package/project_init/config_files.py +282 -282
  68. package/project_init/generator.py +728 -728
  69. package/project_init/manifest.py +418 -418
  70. package/project_init/tui_commands.py +147 -147
  71. package/prompts/critic_pass.md +24 -24
  72. package/prompts/revalidate.md +25 -25
  73. package/prompts/revise.md +17 -17
  74. package/prompts/source_grounding.md +66 -66
  75. package/prompts/system_prompts.py +316 -316
  76. package/providers.json.example +94 -94
  77. package/pyproject.toml +149 -149
  78. package/requirements.txt +314 -295
  79. package/safety/policy_enforcement.py +1082 -1082
  80. package/security/askpass.py +419 -419
  81. package/security/capability.py +207 -207
  82. package/security/confine.py +484 -484
  83. package/security/hosted.py +182 -182
  84. package/security/permissions.py +237 -237
  85. package/security/protected_paths.py +501 -501
  86. package/security/sandbox.py +4108 -4108
  87. package/skills/builtin/math/formal-specification.md +67 -67
  88. package/skills/builtin/math/numerical-methods.md +66 -66
  89. package/skills/builtin/research/experiment-design.md +62 -62
  90. package/skills/builtin/research/reproducibility.md +55 -55
  91. package/skills/builtin/research/source-evaluation.md +70 -70
  92. package/skills/builtin/research/statistical-inference.md +63 -63
  93. package/skills/builtin/research/technical-writing.md +59 -59
  94. package/skills/builtin/software/code-review.md +61 -61
  95. package/skills/builtin/software/debugging.md +61 -61
  96. package/skills/builtin/software/test-design.md +67 -67
  97. package/skills/tui_commands.py +110 -110
  98. package/storage.py +1338 -1338
  99. package/tools/base.py +465 -465
  100. package/tools/builtin/_math_common.py +667 -667
  101. package/tools/builtin/_net_common.py +1145 -267
  102. package/tools/builtin/_page_text.py +490 -0
  103. package/tools/builtin/_pdf_text.py +113 -0
  104. package/tools/builtin/arxiv.py +685 -681
  105. package/tools/builtin/fetch_url.py +639 -371
  106. package/tools/builtin/file_ops.py +720 -720
  107. package/tools/builtin/geometry.py +184 -184
  108. package/tools/builtin/load_skill.py +76 -76
  109. package/tools/builtin/pin.py +227 -227
  110. package/tools/builtin/probability_stats.py +224 -224
  111. package/tools/builtin/project_docs.py +464 -464
  112. package/tools/builtin/remember.py +175 -175
  113. package/tools/builtin/shell.py +980 -980
  114. package/tools/builtin/todo.py +149 -149
  115. package/tools/builtin/web_search.py +402 -328
  116. package/tools/context.py +159 -159
  117. package/tools/isolation.py +387 -387
  118. package/tools/registry.py +1252 -1242
  119. package/tui/app.py +8372 -8307
  120. package/tui/app.tcss +754 -739
  121. package/tui/commands.py +26 -26
  122. package/tui/diffs.py +286 -286
  123. package/tui/history.py +128 -128
  124. package/tui/hosted_driver.py +102 -102
  125. package/tui/markdown.py +1329 -1329
  126. package/tui/meters.py +364 -364
  127. package/tui/ravens.py +146 -146
  128. package/tui/screens.py +1255 -1197
  129. package/tui/themes.py +599 -599
  130. package/tui/widgets.py +3861 -3796
@@ -1,728 +1,728 @@
1
- """
2
- project_init/generator.py
3
-
4
- ROADMAP_v2 §24: the one place that decides what `/init` does.
5
-
6
- BOTH SHELLS CALL THIS. §26's L6 and §27's T5 again: a per-shell
7
- implementation is how the CLI and the TUI come to disagree about whether an
8
- existing document is overwritten, which is a policy question and not a
9
- painting one. The shells supply consent and rendering as callbacks; every
10
- decision about what happens lives here.
11
-
12
- THE AGENT PRODUCES TEXT; THIS MODULE WRITES (I8). The initializer gets
13
- `read_project_doc` and nothing else, and returns the hub document's prose as its
14
- final answer. Diffing, asking and dispatching `write_project_doc` happen
15
- here, because consent belongs to the shell (§20's V3) and a tool writing
16
- from inside the loop could not show a human a diff first.
17
-
18
- ONE CONSENT, A NAMED LIST. `write_project_doc` is approval-gated, so a naive
19
- implementation would prompt eight times for one command -- which is the
20
- shape of consent that gets clicked through. The user is asked once, shown
21
- the hub's diff and the exact list of files that will be created, and
22
- that answer is then passed as `approval_callback` to each dispatch. Same
23
- move core/loop.py makes after a channel approval, and for the same reason.
24
- """
25
-
26
- from __future__ import annotations
27
-
28
- import difflib
29
- import logging
30
- import os
31
- from collections.abc import Callable
32
- from typing import Optional
33
-
34
- import config
35
- from core import config_loader, workspace_trust
36
- from json_store import read_regular_text
37
- from project_init import config_files, doc_sets
38
- from project_init import manifest as manifest_mod
39
-
40
- logger = logging.getLogger(__name__)
41
-
42
-
43
- class InitError(Exception):
44
- """Something /init cannot proceed past. Carries a message meant for a
45
- human, not a traceback; both shells print it verbatim.
46
-
47
- It may be several lines. A write that fails partway through has to say
48
- what it already did (#95), and one line cannot carry "this failed" and
49
- "these eight files exist now" without losing one of them.
50
- """
51
-
52
-
53
- def propose_kind(project_path: str) -> tuple:
54
- """(kind, reason) for an established project (I13).
55
-
56
- A PYTHON HEURISTIC, NOT A MODEL CALL, and confirmed by the user either
57
- way. A code manifest is a strong, checkable signal; the alternative --
58
- an extra round trip so a model can read the same filename this function
59
- reads -- spends a call to reach the same place with less certainty
60
- about how it got there. The reason is returned so the confirmation
61
- prompt can show its working.
62
-
63
- IT BRANCHES ON THE MANIFEST SET, NOT ON THE STACK (#96). Those are two
64
- questions -- "is this a codebase" and "what is it written in" -- and
65
- answering the first with the second is what made a Java, Ruby, Gradle,
66
- C or container project `research` with "no code manifests found"
67
- printed as the reason, while the manifest shown to the agent listed the
68
- manifest. `Makefile` and `Dockerfile` still carry no stack, which is
69
- the point: they answer the first question and not the second.
70
-
71
- The reason now names the files it found, because I13 asked for working
72
- that can be shown and a filename is the whole of the evidence.
73
- """
74
- facts = manifest_mod.detect_facts(project_path)
75
- found = facts.get("code_manifests")
76
- if not found:
77
- return (doc_sets.RESEARCH,
78
- "no code manifests found, so this looks like written work "
79
- "rather than a codebase")
80
- named = ", ".join(found)
81
- if facts.get("stack"):
82
- return (doc_sets.SOFTWARE,
83
- f"{facts['stack']} project files are present ({named})")
84
- return doc_sets.SOFTWARE, f"code manifests are present ({named})"
85
-
86
-
87
- def _existing_documents(project_path: str, kind: str) -> set:
88
- """Which documents in the set the project ALREADY has (I12)."""
89
- from tools.builtin.project_docs import doc_path
90
- return {name for name in doc_sets.document_set(kind)
91
- if os.path.exists(doc_path(project_path, name))}
92
-
93
-
94
- def _config_plan(project_path: str) -> dict:
95
- """What `--config` would create here: `{"files", "dirs", "existing"}`.
96
-
97
- AN EXISTING FILE IS NEVER OVERWRITTEN (I12, applied to the file it was
98
- written for). The document rule -- only the hub is diffed and asked
99
- about, because it is the only file /init claims to author -- reads
100
- even harder here: settings.json and mcp.json are configuration
101
- somebody tuned, and a scaffold of defaults landing on top of a tuned
102
- file would be this command destroying the thing it exists to help you
103
- start. Left alone and reported, per file, so a project with a
104
- settings.json and no mcp.json still gets the mcp.json.
105
-
106
- Directories are listed separately because creating one is not writing
107
- anything: they carry nothing into the D17 hash (`content_files()`
108
- walks files) and git does not track an empty directory, so they are a
109
- hint on this machine and never part of what a clone receives.
110
- """
111
- root = workspace_trust.venastine_dir(project_path)
112
- names = (config_files.SETTINGS_FILENAME, config_files.MCP_FILENAME)
113
- return {
114
- "files": [name for name in names
115
- if not os.path.exists(os.path.join(root, name))],
116
- "existing": [name for name in names
117
- if os.path.exists(os.path.join(root, name))],
118
- "dirs": [name for name in config_files.TIER_DIRS
119
- if not os.path.isdir(os.path.join(root, name))],
120
- }
121
-
122
-
123
- def _write_config(project_path: str, name: str) -> None:
124
- """One configuration file, written DIRECTLY (I14).
125
-
126
- Not through `write_project_doc`, which denies `.venastine/` by path
127
- segment and names these two files as the reason. Extending that
128
- allowlist was the alternative and is rejected in the record: it would
129
- advertise, to every run and all ten research passes, a tool that can
130
- author a file naming a local command to execute. What replaces the
131
- tool's approval gate is the same single consent that already covers
132
- the document set -- the shape `_settle_trust` already uses to write
133
- the trust store from here.
134
-
135
- OSError becomes InitError, so a full disk or a read-only mount takes
136
- the same reporting path as a failed document write (#95) rather than
137
- escaping as a traceback.
138
- """
139
- from json_store import write_json_atomic
140
-
141
- payload = (config_files.render_settings()
142
- if name == config_files.SETTINGS_FILENAME
143
- else config_files.render_mcp())
144
- path = os.path.join(workspace_trust.venastine_dir(project_path), name)
145
- try:
146
- write_json_atomic(path, payload, trailing_newline=True)
147
- except OSError as e:
148
- raise InitError(f"Could not write {path}: {e}")
149
-
150
-
151
- def _shadow_lines() -> list:
152
- """What the scaffolded settings.json takes over from the user's own.
153
-
154
- A project settings.json beats the user's (D29) by PRESENCE and not by
155
- difference, so even a file of pure defaults starts deciding every key
156
- it names. Said BEFORE the consent, where it can still change the
157
- answer, rather than in the report afterwards.
158
- """
159
- shadowed = config_files.shadowed(config_loader.user_settings())
160
- if not shadowed:
161
- return []
162
- lines = ["This project's settings.json will now decide "
163
- f"{len(shadowed)} key{'' if len(shadowed) == 1 else 's'} your "
164
- f"own settings.json was deciding:"]
165
- lines += [f" {path}: {theirs!r} -> {ours!r}"
166
- for path, theirs, ours in shadowed]
167
- lines.append("Delete those lines from the new file to go back to "
168
- "yours.")
169
- return lines
170
-
171
-
172
- def _read_existing_context(project_path: str) -> Optional[str]:
173
- """The current hub, or None to generate a fresh one.
174
-
175
- BOUNDED SINCE BATCH 221 (#226). It was read, diffed, embedded in the
176
- model's task and printed whole: measured, a 5.4 MB hub went into a
177
- 5.4 MB task and a 5.4 MB diff. Head-plus-a-notice was the other shape,
178
- and it is wrong here: the initializer's reply BECOMES the whole hub, so
179
- a model shown the head would rewrite the file without its tail. So a
180
- hub past `init_max_hub_chars` is refused with nothing sent anywhere,
181
- and the owner sized that at about three times this repository's own
182
- 347 KB hub. The size is checked before the read, in bytes, where four
183
- bytes per character makes the comparison safe; the count is checked
184
- after it. And the read itself is regular-files-only (batch 219).
185
- """
186
- from tools.builtin.project_docs import HUB_FILENAME, doc_path
187
- path = doc_path(project_path, HUB_FILENAME)
188
- if not os.path.exists(path):
189
- return None
190
- cap = config.INIT_MAX_HUB_CHARS
191
- try:
192
- if os.path.getsize(path) > 4 * cap:
193
- raise InitError(_too_large(HUB_FILENAME, os.path.getsize(path),
194
- "bytes", cap))
195
- text = read_regular_text(path)
196
- except (OSError, UnicodeDecodeError) as e:
197
- # Degrade like config_loader does with an unreadable hub document.
198
- # An undecodable existing file must not stop /init from writing a
199
- # good one -- but it is also not something to revise, so the run
200
- # proceeds as if there were none.
201
- logger.warning("Could not read the existing %s at %s; "
202
- "generating a fresh one: %s", HUB_FILENAME, path, e)
203
- return None
204
- if len(text) > cap:
205
- raise InitError(_too_large(HUB_FILENAME, len(text), "characters",
206
- cap))
207
- return text
208
-
209
-
210
- def _too_large(name: str, size: int, unit: str, cap: int) -> str:
211
- return (f"{name} is {size:,} {unit}, more than /init revises "
212
- f"({cap:,} characters, init_max_hub_chars in config.yaml). "
213
- f"Nothing has been changed: trim it, or edit it by hand.")
214
-
215
-
216
- def _shown(diff: str) -> str:
217
- """The diff as the shell shows it: at most `init_diff_shown_lines`
218
- lines, and a line saying how many more there are (#226). The whole
219
- diff still decides whether anything changed; only the print is cut,
220
- because a megabyte-scale row freezes the transcript it is printed to."""
221
- lines = diff.splitlines(keepends=True)
222
- cap = config.INIT_DIFF_SHOWN_LINES
223
- if len(lines) <= cap:
224
- return diff
225
- return ("".join(lines[:cap]).rstrip("\n")
226
- + f"\n... {len(lines) - cap:,} more line(s) of the diff are not "
227
- f"shown ({cap:,} of {len(lines):,}; init_diff_shown_lines in "
228
- f"config.yaml).")
229
-
230
-
231
- def _task(manifest_text: str, existing: Optional[str], kind: str) -> str:
232
- """The user message: the manifest, plus the current file if there is
233
- one (I4). Both go HERE and not in the system prompt -- see
234
- project_init/manifest.py on why that distinction is load-bearing.
235
-
236
- THE HUB'S NAME IS INTERPOLATED, NEVER SPELLED (§44 WS8). This function
237
- said "Write CONTEXT.md" for two batches after the hub became the root
238
- AGENTS.md: the shell wrote to the right path, and the model drafted a
239
- document that called itself by the old name. Reading the constant means
240
- the next relocation cannot leave the prompt behind again.
241
- """
242
- from tools.builtin.project_docs import HUB_FILENAME
243
-
244
- parts = [
245
- f"Write {HUB_FILENAME} for this {kind} project.",
246
- "",
247
- manifest_text,
248
- ]
249
- if existing:
250
- parts += [
251
- f"## The current {HUB_FILENAME}",
252
- "",
253
- "This already exists and may contain hand edits. Revise it: keep "
254
- "everything still true, correct what the project has outgrown, "
255
- "add what is missing. Do not reword something merely to phrase "
256
- "it your way.",
257
- "",
258
- existing,
259
- "",
260
- ]
261
- return "\n".join(parts)
262
-
263
-
264
- def _run_initializer(project_path: str, kind: str, existing: Optional[str],
265
- model: str, provider_name: str, activity=None) -> str:
266
- from agents.manager import manager
267
- from core import agent_activity
268
- from core.loop import DEFAULT_SYSTEM_PROMPT, RunAgentLoop, advertisement_facts
269
- from storage import THREAD_KIND_SUBAGENT
270
-
271
- agent = manager.get(config.INITIALIZER_AGENT)
272
- if agent is None:
273
- raise InitError(
274
- f"The {config.INITIALIZER_AGENT!r} agent is not available, so "
275
- f"there is nothing to generate the hub document with.")
276
-
277
- context = manager.active_context(agent)
278
- # #228: the run below is given no authorization, so it is HEADLESS --
279
- # nothing can answer an approval -- and the prompt says what THAT run
280
- # can call, the reviewer's rule (core/reasoning/review.py). With
281
- # system_prompt_for's attended defaults this was right only while
282
- # initializer.md's allowed_tools kept both catalog tools out.
283
- callable_only, granted = advertisement_facts()
284
- system_prompt = manager.system_prompt_for(
285
- agent, DEFAULT_SYSTEM_PROMPT, context=context,
286
- callable_only=callable_only, granted=granted)
287
-
288
- # §47, the span batch 59 named as a follow-on and did not build. /init
289
- # is a long agent-shaped run -- it reads the project and drafts a
290
- # document -- and until now a shell watching the agent stack saw
291
- # nothing at all while it happened.
292
- #
293
- # `context.subagent_depth + 1` rather than a literal 1, which is
294
- # core/loop._compactor_depth's rule one command over: the number is
295
- # derived from the depth the run actually starts at, so a second
296
- # count cannot disagree with the first.
297
- with agent_activity.span(activity, agent.name,
298
- context.subagent_depth + 1):
299
- response = RunAgentLoop.run_agent_conversation(
300
- user_goal=_task(manifest_mod.build_manifest(project_path),
301
- existing, kind),
302
- model=agent.model or model,
303
- provider_name=agent.provider or provider_name,
304
- max_steps=agent.max_steps or config.INIT_MAX_STEPS,
305
- # #4: no separate /init ceiling any more -- the wrapper
306
- # resolves the configured spend cap, same as every other path.
307
- context=context,
308
- system_prompt=system_prompt,
309
- # §27: the initializer is a SIXTH thread source. Left
310
- # unlabelled it clutters the picker with a thread nobody
311
- # will ever resume.
312
- thread_kind=THREAD_KIND_SUBAGENT,
313
- # §47. NO parent thread, deliberately: /init scaffolds a
314
- # project, it is not a child of the conversation the command
315
- # was typed in -- and `generate()` is shell-agnostic and has
316
- # no conversation to name anyway. Reachable from the panel
317
- # while it runs, which is what the span is for.
318
- thread_agent=agent.name,
319
- )
320
- body = (response.text or "").strip()
321
- if not body:
322
- raise InitError(
323
- "The initializer returned nothing, so there is no hub document "
324
- "to write. Nothing has been changed.")
325
- return body
326
-
327
-
328
- def build_diff(old: Optional[str], new: str, path: str) -> str:
329
- """Unified diff of what /init would change (I5). Empty string when the
330
- file would be identical, which the caller reports rather than writing."""
331
- old_lines = (old or "").splitlines(keepends=True)
332
- new_lines = new.splitlines(keepends=True)
333
- label = os.path.basename(path)
334
- return "".join(difflib.unified_diff(
335
- old_lines, new_lines,
336
- fromfile=f"{label} (current)" if old else "/dev/null",
337
- tofile=f"{label} (proposed)"))
338
-
339
-
340
- def generate(
341
- project_path: Optional[str] = None,
342
- model: Optional[str] = None,
343
- provider_name: Optional[str] = None,
344
- *,
345
- kind: Optional[str] = None,
346
- confirm: Optional[Callable] = None,
347
- notify: Optional[Callable] = None,
348
- choose_kind: Optional[Callable] = None,
349
- scaffold_docs: bool = True,
350
- scaffold_config: bool = False,
351
- activity=None,
352
- ) -> dict:
353
- """Scaffold this project's documentation set, its configuration, or both.
354
-
355
- confirm(summary) -> bool the one consent (I5). None means there is no
356
- way to ask, and therefore nothing is written.
357
- notify(text) -> None progress and the diff, rendered by the shell.
358
- choose_kind(proposal, reason, blank) -> str | None
359
- resolves the project kind. Called with
360
- blank=True when there is nothing to infer
361
- from (I13), in which case `proposal` is None.
362
- scaffold_docs the AGENTS.md hub and the stubs it links.
363
- scaffold_config `.venastine/settings.json`, `mcp.json` and
364
- the two tier directories (§24 I17).
365
-
366
- TWO FLAGS RATHER THAN TWO FUNCTIONS. `--config` on its own is a
367
- different OPERATION -- no kind question, no initializer, no spend --
368
- but it is not a different set of decisions, and the decisions are
369
- what this module exists to hold in one place. A config-only entry
370
- point beside this one would be a second answer to "is an existing
371
- file overwritten" and a second place to forget the trust settle.
372
-
373
- Returns a notice dict in the {"kind", "text"} shape both shells render.
374
- """
375
- from tools.builtin.project_docs import HUB_FILENAME, doc_path
376
- from tools.registry import ToolCallDenied, registry
377
-
378
- root = project_path or config_loader.get_project_path()
379
- if root is None:
380
- raise InitError("No project directory has been resolved.")
381
- root = os.path.realpath(root)
382
- say = notify or (lambda _text: None)
383
- if not scaffold_docs and not scaffold_config:
384
- raise InitError("/init was asked to scaffold nothing.")
385
-
386
- body = None
387
- diff = ""
388
- to_create = []
389
- already_there = set()
390
- context_path = doc_path(root, HUB_FILENAME)
391
-
392
- # ---- 1. Which set --------------------------------------------------
393
- # Only when there is a set. `--config` alone asks nothing and spends
394
- # nothing, which is the whole of why it is a separate flag rather
395
- # than an addition to a run that always costs a model call.
396
- if scaffold_docs:
397
- if kind is None:
398
- # Both walk the project (#255, batch 213). An OSError here --
399
- # a directory nobody may list, a path that stopped being one --
400
- # left as itself, and the CLI catches InitError only, so it was
401
- # a traceback there and an error line in the TUI.
402
- try:
403
- blank = manifest_mod.is_blank(root)
404
- proposal, reason = ((None, "") if blank
405
- else propose_kind(root))
406
- except OSError as e:
407
- raise InitError(
408
- f"Could not read the project directory to work out its "
409
- f"type ({e}). Re-run with --software or --research, or "
410
- f"fix the directory's permissions.") from e
411
- if choose_kind is None:
412
- # No way to ask. Refusing beats scaffolding seven files of
413
- # the wrong kind into someone's project -- V6's rule, and
414
- # the wrong answer here is expensive to undo by hand.
415
- raise InitError(
416
- "The project type could not be determined and there is "
417
- "no way to ask. Re-run with --software or --research.")
418
- kind = choose_kind(proposal, reason, blank)
419
- if kind is None:
420
- return {"kind": "init",
421
- "text": "Cancelled — nothing was written."}
422
- if kind not in doc_sets.PROJECT_KINDS:
423
- raise InitError(f"Unknown project type {kind!r}; expected one of "
424
- f"{', '.join(doc_sets.PROJECT_KINDS)}.")
425
-
426
- # ---- 2. Generate -----------------------------------------------
427
- existing_context = _read_existing_context(root)
428
- say(f"Reading the project and drafting {HUB_FILENAME}…")
429
- body = _run_initializer(root, kind, existing_context, model,
430
- provider_name, activity)
431
-
432
- already_there = _existing_documents(root, kind)
433
- body = f"{body.rstrip()}\n\n{doc_sets.render_index(kind)}"
434
-
435
- to_create = [name for name in doc_sets.document_set(kind)
436
- if name not in already_there]
437
- diff = build_diff(existing_context, body, context_path)
438
-
439
- # ---- 3. Show, then ask once ----------------------------------------
440
- plan = _config_plan(root) if scaffold_config else {"files": [],
441
- "existing": [],
442
- "dirs": []}
443
- if not diff and not to_create and not plan["files"] and not plan["dirs"]:
444
- return {"kind": "init", "text": _nothing_to_do(kind, scaffold_docs,
445
- scaffold_config)}
446
-
447
- if scaffold_docs:
448
- if diff:
449
- say(_shown(diff))
450
- else:
451
- say(f"{HUB_FILENAME} is unchanged.")
452
- if to_create:
453
- say("Will also create, as stubs: " + ", ".join(to_create))
454
- if already_there:
455
- say("Leaving existing documents untouched: "
456
- + ", ".join(sorted(already_there)))
457
- if plan["files"]:
458
- say("Will create, with default values: "
459
- + ", ".join(".venastine/" + name for name in plan["files"]))
460
- if config_files.SETTINGS_FILENAME in plan["files"]:
461
- for line in _shadow_lines():
462
- say(line)
463
- if plan["existing"]:
464
- say("Leaving existing configuration untouched: "
465
- + ", ".join(".venastine/" + name for name in plan["existing"]))
466
-
467
- if confirm is None:
468
- # §25's V6, and the same rule §20 applies to review corrections: the
469
- # inability to ask is not permission to proceed. A piped `--init`
470
- # reports what it would do and writes nothing.
471
- return {"kind": "init",
472
- "text": "Nothing was written: there is no way to confirm "
473
- "these changes here. Re-run on a terminal."}
474
- if not confirm(_consent_summary(context_path, to_create, bool(diff),
475
- plan)):
476
- return {"kind": "init", "text": "Declined — nothing was written."}
477
-
478
- # ---- 4. Write ------------------------------------------------------
479
- # Captured BEFORE the write (I6). Afterwards the content hash has moved
480
- # and is_trusted() answers False for a project that WAS trusted, which
481
- # is exactly the state this distinction exists to tell apart.
482
- #
483
- # TOTAL SINCE BATCH 153, because the capture itself reads files (A47).
484
- was_trusted, trust_problem = _trust_before(root)
485
-
486
- granted = lambda _name, _params: True # noqa: E731 -- consent is above
487
- written = []
488
- made = []
489
-
490
- failure = None
491
- try:
492
- if scaffold_docs:
493
- facts = manifest_mod.detect_facts(root)
494
- if diff:
495
- _write(registry, granted, HUB_FILENAME, body)
496
- written.append(HUB_FILENAME)
497
- for name in to_create:
498
- _write(registry, granted, name,
499
- doc_sets.render_stub(name, facts))
500
- written.append(name)
501
- # The directories first, so a failure to write settings.json still
502
- # leaves a `.venastine/` whose shape says where the rest goes.
503
- for name in plan["dirs"]:
504
- os.makedirs(
505
- os.path.join(workspace_trust.venastine_dir(root), name),
506
- exist_ok=True)
507
- made.append(".venastine/" + name + "/")
508
- for name in plan["files"]:
509
- _write_config(root, name)
510
- written.append(".venastine/" + name)
511
- except OSError as e:
512
- failure = f"Could not create a directory under .venastine/: {e}"
513
- except ToolCallDenied as e:
514
- failure = f"The write was denied: {e}"
515
- except InitError as e:
516
- # THE REACHABLE FAILURE, and the one that had no handler (#95).
517
- # `ToolCallDenied` cannot arrive here -- consent is granted a few
518
- # lines up -- while `_write` raises `InitError` for every error
519
- # dict `write_run` returns, and `write_run` turns ANY OSError into
520
- # one. Disk full, permissions, a read-only mount: all of them took
521
- # this path, and this path did not exist.
522
- failure = str(e)
523
-
524
- # ---- 5. Trust ------------------------------------------------------
525
- # ON BOTH PATHS (#95). The partial write has already moved the D17
526
- # content hash, so a project the user trusted a moment ago is untrusted
527
- # now -- exactly the state I6 exists to prevent, reached by the route
528
- # I6 was not looking at. Its precondition is unchanged by the failure:
529
- # they just authored this content, and that is as true after five of
530
- # eight writes as after eight. Skipping this made the failure wrong
531
- # about two things instead of one, and silent about the second.
532
- trust_note, trust_ok = _settle_trust(root, was_trusted, trust_problem)
533
-
534
- if failure is not None:
535
- # NAME WHAT WAS CREATED. The success path reports the files so the
536
- # user knows what changed; the failure path reported the single
537
- # file that did NOT change -- the one thing they could already see
538
- # -- and discarded the list of the ones that did. "Could not write
539
- # TECHNICAL_DEBT.md" left no way to tell whether nothing had
540
- # happened or most of it had.
541
- #
542
- # NOTHING IS ROLLED BACK, deliberately. The hub's previous
543
- # content was overwritten at the first step and cannot be restored,
544
- # so "rolled back" would be true of the stubs and false of the one
545
- # file that mattered -- and deleting documents out of someone's
546
- # project on an error path is a worse failure than the one being
547
- # reported.
548
- lines = [failure]
549
- if written:
550
- lines.append(f"Wrote {len(written)} file"
551
- f"{'' if len(written) == 1 else 's'} before that: "
552
- + ", ".join(written))
553
- else:
554
- lines.append("Nothing was written.")
555
- lines.append(trust_note)
556
- raise InitError("\n".join(line for line in lines if line))
557
-
558
- # THE WARNING LEADS, when there is one (A46). The files are on disk and
559
- # the user can see them; what they cannot see is that the next launch
560
- # will ask about this project again, so the half that did NOT happen is
561
- # the half that goes first. A run whose trust settled as intended keeps
562
- # the note where it has always been -- last, as the footnote it is.
563
- lines = [] if trust_ok else [trust_note]
564
- lines.append(f"Wrote {len(written)} file"
565
- f"{'' if len(written) == 1 else 's'}: " + ", ".join(written))
566
- if made:
567
- lines.append("Created: " + ", ".join(made))
568
- if already_there:
569
- lines.append("Left alone: " + ", ".join(sorted(already_there)))
570
- if plan["existing"]:
571
- lines.append("Left alone: "
572
- + ", ".join(".venastine/" + name
573
- for name in plan["existing"]))
574
- if trust_ok:
575
- lines.append(trust_note)
576
- return {"kind": "init", "text": "\n".join(line for line in lines if line)}
577
-
578
-
579
- def _nothing_to_do(kind, scaffold_docs: bool, scaffold_config: bool) -> str:
580
- """The message for a run that found everything already in place.
581
-
582
- Assembled from the halves that actually ran, so a `--config` run in a
583
- configured project does not report on a document set it never looked
584
- at -- which is the same complaint #95 makes about a failure naming
585
- the one file that did NOT change.
586
- """
587
- from tools.builtin.project_docs import HUB_FILENAME
588
-
589
- parts = []
590
- if scaffold_docs:
591
- parts.append(f"{HUB_FILENAME} is already up to date and every "
592
- f"document in the {kind} set exists")
593
- if scaffold_config:
594
- parts.append(".venastine/ already has its settings.json and "
595
- "mcp.json")
596
- return " and ".join(parts) + ". Nothing to do."
597
-
598
-
599
- def _consent_summary(context_path: str, to_create: list, changing: bool,
600
- plan: Optional[dict] = None) -> str:
601
- """ONE consent covering everything the run will touch (I5).
602
-
603
- The configuration files are named in it rather than asked about
604
- separately: eight prompts for one command is the shape of consent that
605
- gets clicked through, which is the reason this summary exists at all.
606
- """
607
- plan = plan or {"files": [], "dirs": []}
608
- parts = []
609
- if changing:
610
- parts.append(f"write {context_path}")
611
- if to_create:
612
- parts.append(f"create {len(to_create)} stub document"
613
- f"{'' if len(to_create) == 1 else 's'} "
614
- f"({', '.join(to_create)})")
615
- if plan["files"]:
616
- parts.append("create " + ", ".join(".venastine/" + name
617
- for name in plan["files"])
618
- + " with default values")
619
- if plan["dirs"]:
620
- parts.append("create " + ", ".join(".venastine/" + name + "/"
621
- for name in plan["dirs"]))
622
- return "/init will " + " and ".join(parts) + ". Proceed?"
623
-
624
-
625
- def _write(registry, granted, name: str, content: str) -> None:
626
- result = registry.dispatch(
627
- "write_project_doc", {"name": name, "content": content},
628
- approval_callback=granted)
629
- if isinstance(result, dict) and result.get("error"):
630
- raise InitError(result["error"])
631
-
632
-
633
- def _trust_before(project_path: str) -> tuple:
634
- """`is_trusted()`, made total. Returns (was_trusted, problem).
635
-
636
- THE CAPTURE READS FILES, which is the half of I6 nobody was looking at
637
- (batch 153). `is_trusted` hashes every path `content_files()`
638
- lists -- the root `AGENTS.md` and everything under `.venastine/` -- and
639
- `open` on any one of them can fail: a file an editor holds, a sync
640
- client mid-write, a mode the user changed by hand. That read sits
641
- before the `try`, so a single unreadable file killed `/init` as a raw
642
- `PermissionError` before it wrote anything, and on the CLI
643
- (`except InitError` only) as a traceback.
644
-
645
- DEGRADES, and the precedent is three functions up in this same module:
646
- `_read_existing_context` catches `OSError` on the SAME file for the
647
- SAME reason and says "Degrade like config_loader does with an
648
- unreadable hub document". One function answering one error two ways is
649
- what this closes (A47).
650
-
651
- `False` rather than `True` for an unanswerable question, which is
652
- `core/workspace_trust.py`'s own posture -- `_load_trust_store` returns
653
- `{}` for anything unreadable and says it fails CLOSED in both senses.
654
- Read as untrusted, `_settle_trust` attempts no re-grant, and the
655
- problem is REPORTED rather than inferred from a trust prompt arriving
656
- on the next launch.
657
-
658
- NOT fixed in `is_trusted` itself, deliberately (A48). Its other callers
659
- are contained -- `main.load_project_config` catches `OSError` and exits
660
- 1 with one clean line -- and making a security control answer "not
661
- trusted" where it currently refuses to start is a change to D17's
662
- posture, not to this command's. `docs/TECHNICAL_DEBT.md` carries it.
663
- """
664
- try:
665
- return workspace_trust.is_trusted(project_path), ""
666
- except OSError as e:
667
- logger.warning("Could not read the trust state of %s; proceeding as "
668
- "untrusted: %s", project_path, e)
669
- return False, (
670
- f"This project's trust state could not be read ({e}), so the run "
671
- f"proceeded as if it were untrusted and no re-grant was "
672
- f"attempted. You will be asked about its .venastine/ content on "
673
- f"the next launch.")
674
-
675
-
676
- def _settle_trust(project_path: str, was_trusted: bool,
677
- problem: str = "") -> tuple:
678
- """I6. Re-grant only for a project that was ALREADY trusted.
679
-
680
- Writing the hub changes the D17 content hash, so a project the user
681
- had approved becomes untrusted purely because they ran this command --
682
- the trust system working as designed, producing a bad outcome. Since
683
- they just authored the content, re-granting is unambiguous.
684
-
685
- But ONLY then. In an untrusted project, `.venastine/` may already hold
686
- agents, skills and an mcp.json that arrived with a repo someone cloned.
687
- Granting trust as a side effect of /init would launder all of it in --
688
- a hole in D17 opened from a direction the trust prompt never sees.
689
- The hub is never special-cased out of the hash either; that would be
690
- the same hole with a smaller mouth.
691
-
692
- TOTAL SINCE BATCH 153. Returns (note, settled_as_intended),
693
- and the note is the whole of what the user is told about trust -- so
694
- this function raising discarded it, along with everything `generate`
695
- had assembled around it. #95 put the settle on both paths; the settle
696
- then sat outside every handler on both of them, so a trust-store I/O
697
- failure took the success path's notice and the failure path's "wrote N
698
- files before that" accounting down with it. Measured: both config
699
- files on disk, `is_trusted` True -> False, and a raw `OSError` out.
700
-
701
- `grant_trust` raises from either half -- `_content_hash` re-reads the
702
- files just written, `_save_trust_store` writes the store -- and
703
- `OSError` is both. `json_store` argues that a trust grant which
704
- silently did not persist is worse than a crash, and that argument is
705
- about SILENCE: the grant still either persists or is named, and the
706
- naming now reaches the user instead of the traceback handler.
707
-
708
- `False` is returned for the grant failure and for an unreadable
709
- pre-write state, and `True` for a project that was untrusted and
710
- stayed that way -- nothing went wrong there, and that note is a
711
- footnote rather than a warning.
712
- """
713
- if problem:
714
- return problem, False
715
- if not was_trusted:
716
- return ("This project is not trusted, so nothing here has changed "
717
- "that. You will be asked about its .venastine/ content on "
718
- "the next launch."), True
719
- try:
720
- workspace_trust.grant_trust(project_path)
721
- except OSError as e:
722
- logger.warning("Could not re-grant workspace trust for %s: %s",
723
- project_path, e)
724
- return (f"Workspace trust could NOT be re-granted ({e}), so the next "
725
- f"launch will ask about this project's .venastine/ content "
726
- f"again."), False
727
- return ("Workspace trust re-granted for the updated .venastine/ content, "
728
- "so the next launch will not re-ask."), True
1
+ """
2
+ project_init/generator.py
3
+
4
+ ROADMAP_v2 §24: the one place that decides what `/init` does.
5
+
6
+ BOTH SHELLS CALL THIS. §26's L6 and §27's T5 again: a per-shell
7
+ implementation is how the CLI and the TUI come to disagree about whether an
8
+ existing document is overwritten, which is a policy question and not a
9
+ painting one. The shells supply consent and rendering as callbacks; every
10
+ decision about what happens lives here.
11
+
12
+ THE AGENT PRODUCES TEXT; THIS MODULE WRITES (I8). The initializer gets
13
+ `read_project_doc` and nothing else, and returns the hub document's prose as its
14
+ final answer. Diffing, asking and dispatching `write_project_doc` happen
15
+ here, because consent belongs to the shell (§20's V3) and a tool writing
16
+ from inside the loop could not show a human a diff first.
17
+
18
+ ONE CONSENT, A NAMED LIST. `write_project_doc` is approval-gated, so a naive
19
+ implementation would prompt eight times for one command -- which is the
20
+ shape of consent that gets clicked through. The user is asked once, shown
21
+ the hub's diff and the exact list of files that will be created, and
22
+ that answer is then passed as `approval_callback` to each dispatch. Same
23
+ move core/loop.py makes after a channel approval, and for the same reason.
24
+ """
25
+
26
+ from __future__ import annotations
27
+
28
+ import difflib
29
+ import logging
30
+ import os
31
+ from collections.abc import Callable
32
+ from typing import Optional
33
+
34
+ import config
35
+ from core import config_loader, workspace_trust
36
+ from json_store import read_regular_text
37
+ from project_init import config_files, doc_sets
38
+ from project_init import manifest as manifest_mod
39
+
40
+ logger = logging.getLogger(__name__)
41
+
42
+
43
+ class InitError(Exception):
44
+ """Something /init cannot proceed past. Carries a message meant for a
45
+ human, not a traceback; both shells print it verbatim.
46
+
47
+ It may be several lines. A write that fails partway through has to say
48
+ what it already did (#95), and one line cannot carry "this failed" and
49
+ "these eight files exist now" without losing one of them.
50
+ """
51
+
52
+
53
+ def propose_kind(project_path: str) -> tuple:
54
+ """(kind, reason) for an established project (I13).
55
+
56
+ A PYTHON HEURISTIC, NOT A MODEL CALL, and confirmed by the user either
57
+ way. A code manifest is a strong, checkable signal; the alternative --
58
+ an extra round trip so a model can read the same filename this function
59
+ reads -- spends a call to reach the same place with less certainty
60
+ about how it got there. The reason is returned so the confirmation
61
+ prompt can show its working.
62
+
63
+ IT BRANCHES ON THE MANIFEST SET, NOT ON THE STACK (#96). Those are two
64
+ questions -- "is this a codebase" and "what is it written in" -- and
65
+ answering the first with the second is what made a Java, Ruby, Gradle,
66
+ C or container project `research` with "no code manifests found"
67
+ printed as the reason, while the manifest shown to the agent listed the
68
+ manifest. `Makefile` and `Dockerfile` still carry no stack, which is
69
+ the point: they answer the first question and not the second.
70
+
71
+ The reason now names the files it found, because I13 asked for working
72
+ that can be shown and a filename is the whole of the evidence.
73
+ """
74
+ facts = manifest_mod.detect_facts(project_path)
75
+ found = facts.get("code_manifests")
76
+ if not found:
77
+ return (doc_sets.RESEARCH,
78
+ "no code manifests found, so this looks like written work "
79
+ "rather than a codebase")
80
+ named = ", ".join(found)
81
+ if facts.get("stack"):
82
+ return (doc_sets.SOFTWARE,
83
+ f"{facts['stack']} project files are present ({named})")
84
+ return doc_sets.SOFTWARE, f"code manifests are present ({named})"
85
+
86
+
87
+ def _existing_documents(project_path: str, kind: str) -> set:
88
+ """Which documents in the set the project ALREADY has (I12)."""
89
+ from tools.builtin.project_docs import doc_path
90
+ return {name for name in doc_sets.document_set(kind)
91
+ if os.path.exists(doc_path(project_path, name))}
92
+
93
+
94
+ def _config_plan(project_path: str) -> dict:
95
+ """What `--config` would create here: `{"files", "dirs", "existing"}`.
96
+
97
+ AN EXISTING FILE IS NEVER OVERWRITTEN (I12, applied to the file it was
98
+ written for). The document rule -- only the hub is diffed and asked
99
+ about, because it is the only file /init claims to author -- reads
100
+ even harder here: settings.json and mcp.json are configuration
101
+ somebody tuned, and a scaffold of defaults landing on top of a tuned
102
+ file would be this command destroying the thing it exists to help you
103
+ start. Left alone and reported, per file, so a project with a
104
+ settings.json and no mcp.json still gets the mcp.json.
105
+
106
+ Directories are listed separately because creating one is not writing
107
+ anything: they carry nothing into the D17 hash (`content_files()`
108
+ walks files) and git does not track an empty directory, so they are a
109
+ hint on this machine and never part of what a clone receives.
110
+ """
111
+ root = workspace_trust.venastine_dir(project_path)
112
+ names = (config_files.SETTINGS_FILENAME, config_files.MCP_FILENAME)
113
+ return {
114
+ "files": [name for name in names
115
+ if not os.path.exists(os.path.join(root, name))],
116
+ "existing": [name for name in names
117
+ if os.path.exists(os.path.join(root, name))],
118
+ "dirs": [name for name in config_files.TIER_DIRS
119
+ if not os.path.isdir(os.path.join(root, name))],
120
+ }
121
+
122
+
123
+ def _write_config(project_path: str, name: str) -> None:
124
+ """One configuration file, written DIRECTLY (I14).
125
+
126
+ Not through `write_project_doc`, which denies `.venastine/` by path
127
+ segment and names these two files as the reason. Extending that
128
+ allowlist was the alternative and is rejected in the record: it would
129
+ advertise, to every run and all ten research passes, a tool that can
130
+ author a file naming a local command to execute. What replaces the
131
+ tool's approval gate is the same single consent that already covers
132
+ the document set -- the shape `_settle_trust` already uses to write
133
+ the trust store from here.
134
+
135
+ OSError becomes InitError, so a full disk or a read-only mount takes
136
+ the same reporting path as a failed document write (#95) rather than
137
+ escaping as a traceback.
138
+ """
139
+ from json_store import write_json_atomic
140
+
141
+ payload = (config_files.render_settings()
142
+ if name == config_files.SETTINGS_FILENAME
143
+ else config_files.render_mcp())
144
+ path = os.path.join(workspace_trust.venastine_dir(project_path), name)
145
+ try:
146
+ write_json_atomic(path, payload, trailing_newline=True)
147
+ except OSError as e:
148
+ raise InitError(f"Could not write {path}: {e}")
149
+
150
+
151
+ def _shadow_lines() -> list:
152
+ """What the scaffolded settings.json takes over from the user's own.
153
+
154
+ A project settings.json beats the user's (D29) by PRESENCE and not by
155
+ difference, so even a file of pure defaults starts deciding every key
156
+ it names. Said BEFORE the consent, where it can still change the
157
+ answer, rather than in the report afterwards.
158
+ """
159
+ shadowed = config_files.shadowed(config_loader.user_settings())
160
+ if not shadowed:
161
+ return []
162
+ lines = ["This project's settings.json will now decide "
163
+ f"{len(shadowed)} key{'' if len(shadowed) == 1 else 's'} your "
164
+ f"own settings.json was deciding:"]
165
+ lines += [f" {path}: {theirs!r} -> {ours!r}"
166
+ for path, theirs, ours in shadowed]
167
+ lines.append("Delete those lines from the new file to go back to "
168
+ "yours.")
169
+ return lines
170
+
171
+
172
+ def _read_existing_context(project_path: str) -> Optional[str]:
173
+ """The current hub, or None to generate a fresh one.
174
+
175
+ BOUNDED SINCE BATCH 221 (#226). It was read, diffed, embedded in the
176
+ model's task and printed whole: measured, a 5.4 MB hub went into a
177
+ 5.4 MB task and a 5.4 MB diff. Head-plus-a-notice was the other shape,
178
+ and it is wrong here: the initializer's reply BECOMES the whole hub, so
179
+ a model shown the head would rewrite the file without its tail. So a
180
+ hub past `init_max_hub_chars` is refused with nothing sent anywhere,
181
+ and the owner sized that at about three times this repository's own
182
+ 347 KB hub. The size is checked before the read, in bytes, where four
183
+ bytes per character makes the comparison safe; the count is checked
184
+ after it. And the read itself is regular-files-only (batch 219).
185
+ """
186
+ from tools.builtin.project_docs import HUB_FILENAME, doc_path
187
+ path = doc_path(project_path, HUB_FILENAME)
188
+ if not os.path.exists(path):
189
+ return None
190
+ cap = config.INIT_MAX_HUB_CHARS
191
+ try:
192
+ if os.path.getsize(path) > 4 * cap:
193
+ raise InitError(_too_large(HUB_FILENAME, os.path.getsize(path),
194
+ "bytes", cap))
195
+ text = read_regular_text(path)
196
+ except (OSError, UnicodeDecodeError) as e:
197
+ # Degrade like config_loader does with an unreadable hub document.
198
+ # An undecodable existing file must not stop /init from writing a
199
+ # good one -- but it is also not something to revise, so the run
200
+ # proceeds as if there were none.
201
+ logger.warning("Could not read the existing %s at %s; "
202
+ "generating a fresh one: %s", HUB_FILENAME, path, e)
203
+ return None
204
+ if len(text) > cap:
205
+ raise InitError(_too_large(HUB_FILENAME, len(text), "characters",
206
+ cap))
207
+ return text
208
+
209
+
210
+ def _too_large(name: str, size: int, unit: str, cap: int) -> str:
211
+ return (f"{name} is {size:,} {unit}, more than /init revises "
212
+ f"({cap:,} characters, init_max_hub_chars in config.yaml). "
213
+ f"Nothing has been changed: trim it, or edit it by hand.")
214
+
215
+
216
+ def _shown(diff: str) -> str:
217
+ """The diff as the shell shows it: at most `init_diff_shown_lines`
218
+ lines, and a line saying how many more there are (#226). The whole
219
+ diff still decides whether anything changed; only the print is cut,
220
+ because a megabyte-scale row freezes the transcript it is printed to."""
221
+ lines = diff.splitlines(keepends=True)
222
+ cap = config.INIT_DIFF_SHOWN_LINES
223
+ if len(lines) <= cap:
224
+ return diff
225
+ return ("".join(lines[:cap]).rstrip("\n")
226
+ + f"\n... {len(lines) - cap:,} more line(s) of the diff are not "
227
+ f"shown ({cap:,} of {len(lines):,}; init_diff_shown_lines in "
228
+ f"config.yaml).")
229
+
230
+
231
+ def _task(manifest_text: str, existing: Optional[str], kind: str) -> str:
232
+ """The user message: the manifest, plus the current file if there is
233
+ one (I4). Both go HERE and not in the system prompt -- see
234
+ project_init/manifest.py on why that distinction is load-bearing.
235
+
236
+ THE HUB'S NAME IS INTERPOLATED, NEVER SPELLED (§44 WS8). This function
237
+ said "Write CONTEXT.md" for two batches after the hub became the root
238
+ AGENTS.md: the shell wrote to the right path, and the model drafted a
239
+ document that called itself by the old name. Reading the constant means
240
+ the next relocation cannot leave the prompt behind again.
241
+ """
242
+ from tools.builtin.project_docs import HUB_FILENAME
243
+
244
+ parts = [
245
+ f"Write {HUB_FILENAME} for this {kind} project.",
246
+ "",
247
+ manifest_text,
248
+ ]
249
+ if existing:
250
+ parts += [
251
+ f"## The current {HUB_FILENAME}",
252
+ "",
253
+ "This already exists and may contain hand edits. Revise it: keep "
254
+ "everything still true, correct what the project has outgrown, "
255
+ "add what is missing. Do not reword something merely to phrase "
256
+ "it your way.",
257
+ "",
258
+ existing,
259
+ "",
260
+ ]
261
+ return "\n".join(parts)
262
+
263
+
264
+ def _run_initializer(project_path: str, kind: str, existing: Optional[str],
265
+ model: str, provider_name: str, activity=None) -> str:
266
+ from agents.manager import manager
267
+ from core import agent_activity
268
+ from core.loop import DEFAULT_SYSTEM_PROMPT, RunAgentLoop, advertisement_facts
269
+ from storage import THREAD_KIND_SUBAGENT
270
+
271
+ agent = manager.get(config.INITIALIZER_AGENT)
272
+ if agent is None:
273
+ raise InitError(
274
+ f"The {config.INITIALIZER_AGENT!r} agent is not available, so "
275
+ f"there is nothing to generate the hub document with.")
276
+
277
+ context = manager.active_context(agent)
278
+ # #228: the run below is given no authorization, so it is HEADLESS --
279
+ # nothing can answer an approval -- and the prompt says what THAT run
280
+ # can call, the reviewer's rule (core/reasoning/review.py). With
281
+ # system_prompt_for's attended defaults this was right only while
282
+ # initializer.md's allowed_tools kept both catalog tools out.
283
+ callable_only, granted = advertisement_facts()
284
+ system_prompt = manager.system_prompt_for(
285
+ agent, DEFAULT_SYSTEM_PROMPT, context=context,
286
+ callable_only=callable_only, granted=granted)
287
+
288
+ # §47, the span batch 59 named as a follow-on and did not build. /init
289
+ # is a long agent-shaped run -- it reads the project and drafts a
290
+ # document -- and until now a shell watching the agent stack saw
291
+ # nothing at all while it happened.
292
+ #
293
+ # `context.subagent_depth + 1` rather than a literal 1, which is
294
+ # core/loop._compactor_depth's rule one command over: the number is
295
+ # derived from the depth the run actually starts at, so a second
296
+ # count cannot disagree with the first.
297
+ with agent_activity.span(activity, agent.name,
298
+ context.subagent_depth + 1):
299
+ response = RunAgentLoop.run_agent_conversation(
300
+ user_goal=_task(manifest_mod.build_manifest(project_path),
301
+ existing, kind),
302
+ model=agent.model or model,
303
+ provider_name=agent.provider or provider_name,
304
+ max_steps=agent.max_steps or config.INIT_MAX_STEPS,
305
+ # #4: no separate /init ceiling any more -- the wrapper
306
+ # resolves the configured spend cap, same as every other path.
307
+ context=context,
308
+ system_prompt=system_prompt,
309
+ # §27: the initializer is a SIXTH thread source. Left
310
+ # unlabelled it clutters the picker with a thread nobody
311
+ # will ever resume.
312
+ thread_kind=THREAD_KIND_SUBAGENT,
313
+ # §47. NO parent thread, deliberately: /init scaffolds a
314
+ # project, it is not a child of the conversation the command
315
+ # was typed in -- and `generate()` is shell-agnostic and has
316
+ # no conversation to name anyway. Reachable from the panel
317
+ # while it runs, which is what the span is for.
318
+ thread_agent=agent.name,
319
+ )
320
+ body = (response.text or "").strip()
321
+ if not body:
322
+ raise InitError(
323
+ "The initializer returned nothing, so there is no hub document "
324
+ "to write. Nothing has been changed.")
325
+ return body
326
+
327
+
328
+ def build_diff(old: Optional[str], new: str, path: str) -> str:
329
+ """Unified diff of what /init would change (I5). Empty string when the
330
+ file would be identical, which the caller reports rather than writing."""
331
+ old_lines = (old or "").splitlines(keepends=True)
332
+ new_lines = new.splitlines(keepends=True)
333
+ label = os.path.basename(path)
334
+ return "".join(difflib.unified_diff(
335
+ old_lines, new_lines,
336
+ fromfile=f"{label} (current)" if old else "/dev/null",
337
+ tofile=f"{label} (proposed)"))
338
+
339
+
340
+ def generate(
341
+ project_path: Optional[str] = None,
342
+ model: Optional[str] = None,
343
+ provider_name: Optional[str] = None,
344
+ *,
345
+ kind: Optional[str] = None,
346
+ confirm: Optional[Callable] = None,
347
+ notify: Optional[Callable] = None,
348
+ choose_kind: Optional[Callable] = None,
349
+ scaffold_docs: bool = True,
350
+ scaffold_config: bool = False,
351
+ activity=None,
352
+ ) -> dict:
353
+ """Scaffold this project's documentation set, its configuration, or both.
354
+
355
+ confirm(summary) -> bool the one consent (I5). None means there is no
356
+ way to ask, and therefore nothing is written.
357
+ notify(text) -> None progress and the diff, rendered by the shell.
358
+ choose_kind(proposal, reason, blank) -> str | None
359
+ resolves the project kind. Called with
360
+ blank=True when there is nothing to infer
361
+ from (I13), in which case `proposal` is None.
362
+ scaffold_docs the AGENTS.md hub and the stubs it links.
363
+ scaffold_config `.venastine/settings.json`, `mcp.json` and
364
+ the two tier directories (§24 I17).
365
+
366
+ TWO FLAGS RATHER THAN TWO FUNCTIONS. `--config` on its own is a
367
+ different OPERATION -- no kind question, no initializer, no spend --
368
+ but it is not a different set of decisions, and the decisions are
369
+ what this module exists to hold in one place. A config-only entry
370
+ point beside this one would be a second answer to "is an existing
371
+ file overwritten" and a second place to forget the trust settle.
372
+
373
+ Returns a notice dict in the {"kind", "text"} shape both shells render.
374
+ """
375
+ from tools.builtin.project_docs import HUB_FILENAME, doc_path
376
+ from tools.registry import ToolCallDenied, registry
377
+
378
+ root = project_path or config_loader.get_project_path()
379
+ if root is None:
380
+ raise InitError("No project directory has been resolved.")
381
+ root = os.path.realpath(root)
382
+ say = notify or (lambda _text: None)
383
+ if not scaffold_docs and not scaffold_config:
384
+ raise InitError("/init was asked to scaffold nothing.")
385
+
386
+ body = None
387
+ diff = ""
388
+ to_create = []
389
+ already_there = set()
390
+ context_path = doc_path(root, HUB_FILENAME)
391
+
392
+ # ---- 1. Which set --------------------------------------------------
393
+ # Only when there is a set. `--config` alone asks nothing and spends
394
+ # nothing, which is the whole of why it is a separate flag rather
395
+ # than an addition to a run that always costs a model call.
396
+ if scaffold_docs:
397
+ if kind is None:
398
+ # Both walk the project (#255, batch 213). An OSError here --
399
+ # a directory nobody may list, a path that stopped being one --
400
+ # left as itself, and the CLI catches InitError only, so it was
401
+ # a traceback there and an error line in the TUI.
402
+ try:
403
+ blank = manifest_mod.is_blank(root)
404
+ proposal, reason = ((None, "") if blank
405
+ else propose_kind(root))
406
+ except OSError as e:
407
+ raise InitError(
408
+ f"Could not read the project directory to work out its "
409
+ f"type ({e}). Re-run with --software or --research, or "
410
+ f"fix the directory's permissions.") from e
411
+ if choose_kind is None:
412
+ # No way to ask. Refusing beats scaffolding seven files of
413
+ # the wrong kind into someone's project -- V6's rule, and
414
+ # the wrong answer here is expensive to undo by hand.
415
+ raise InitError(
416
+ "The project type could not be determined and there is "
417
+ "no way to ask. Re-run with --software or --research.")
418
+ kind = choose_kind(proposal, reason, blank)
419
+ if kind is None:
420
+ return {"kind": "init",
421
+ "text": "Cancelled — nothing was written."}
422
+ if kind not in doc_sets.PROJECT_KINDS:
423
+ raise InitError(f"Unknown project type {kind!r}; expected one of "
424
+ f"{', '.join(doc_sets.PROJECT_KINDS)}.")
425
+
426
+ # ---- 2. Generate -----------------------------------------------
427
+ existing_context = _read_existing_context(root)
428
+ say(f"Reading the project and drafting {HUB_FILENAME}…")
429
+ body = _run_initializer(root, kind, existing_context, model,
430
+ provider_name, activity)
431
+
432
+ already_there = _existing_documents(root, kind)
433
+ body = f"{body.rstrip()}\n\n{doc_sets.render_index(kind)}"
434
+
435
+ to_create = [name for name in doc_sets.document_set(kind)
436
+ if name not in already_there]
437
+ diff = build_diff(existing_context, body, context_path)
438
+
439
+ # ---- 3. Show, then ask once ----------------------------------------
440
+ plan = _config_plan(root) if scaffold_config else {"files": [],
441
+ "existing": [],
442
+ "dirs": []}
443
+ if not diff and not to_create and not plan["files"] and not plan["dirs"]:
444
+ return {"kind": "init", "text": _nothing_to_do(kind, scaffold_docs,
445
+ scaffold_config)}
446
+
447
+ if scaffold_docs:
448
+ if diff:
449
+ say(_shown(diff))
450
+ else:
451
+ say(f"{HUB_FILENAME} is unchanged.")
452
+ if to_create:
453
+ say("Will also create, as stubs: " + ", ".join(to_create))
454
+ if already_there:
455
+ say("Leaving existing documents untouched: "
456
+ + ", ".join(sorted(already_there)))
457
+ if plan["files"]:
458
+ say("Will create, with default values: "
459
+ + ", ".join(".venastine/" + name for name in plan["files"]))
460
+ if config_files.SETTINGS_FILENAME in plan["files"]:
461
+ for line in _shadow_lines():
462
+ say(line)
463
+ if plan["existing"]:
464
+ say("Leaving existing configuration untouched: "
465
+ + ", ".join(".venastine/" + name for name in plan["existing"]))
466
+
467
+ if confirm is None:
468
+ # §25's V6, and the same rule §20 applies to review corrections: the
469
+ # inability to ask is not permission to proceed. A piped `--init`
470
+ # reports what it would do and writes nothing.
471
+ return {"kind": "init",
472
+ "text": "Nothing was written: there is no way to confirm "
473
+ "these changes here. Re-run on a terminal."}
474
+ if not confirm(_consent_summary(context_path, to_create, bool(diff),
475
+ plan)):
476
+ return {"kind": "init", "text": "Declined — nothing was written."}
477
+
478
+ # ---- 4. Write ------------------------------------------------------
479
+ # Captured BEFORE the write (I6). Afterwards the content hash has moved
480
+ # and is_trusted() answers False for a project that WAS trusted, which
481
+ # is exactly the state this distinction exists to tell apart.
482
+ #
483
+ # TOTAL SINCE BATCH 153, because the capture itself reads files (A47).
484
+ was_trusted, trust_problem = _trust_before(root)
485
+
486
+ granted = lambda _name, _params: True # noqa: E731 -- consent is above
487
+ written = []
488
+ made = []
489
+
490
+ failure = None
491
+ try:
492
+ if scaffold_docs:
493
+ facts = manifest_mod.detect_facts(root)
494
+ if diff:
495
+ _write(registry, granted, HUB_FILENAME, body)
496
+ written.append(HUB_FILENAME)
497
+ for name in to_create:
498
+ _write(registry, granted, name,
499
+ doc_sets.render_stub(name, facts))
500
+ written.append(name)
501
+ # The directories first, so a failure to write settings.json still
502
+ # leaves a `.venastine/` whose shape says where the rest goes.
503
+ for name in plan["dirs"]:
504
+ os.makedirs(
505
+ os.path.join(workspace_trust.venastine_dir(root), name),
506
+ exist_ok=True)
507
+ made.append(".venastine/" + name + "/")
508
+ for name in plan["files"]:
509
+ _write_config(root, name)
510
+ written.append(".venastine/" + name)
511
+ except OSError as e:
512
+ failure = f"Could not create a directory under .venastine/: {e}"
513
+ except ToolCallDenied as e:
514
+ failure = f"The write was denied: {e}"
515
+ except InitError as e:
516
+ # THE REACHABLE FAILURE, and the one that had no handler (#95).
517
+ # `ToolCallDenied` cannot arrive here -- consent is granted a few
518
+ # lines up -- while `_write` raises `InitError` for every error
519
+ # dict `write_run` returns, and `write_run` turns ANY OSError into
520
+ # one. Disk full, permissions, a read-only mount: all of them took
521
+ # this path, and this path did not exist.
522
+ failure = str(e)
523
+
524
+ # ---- 5. Trust ------------------------------------------------------
525
+ # ON BOTH PATHS (#95). The partial write has already moved the D17
526
+ # content hash, so a project the user trusted a moment ago is untrusted
527
+ # now -- exactly the state I6 exists to prevent, reached by the route
528
+ # I6 was not looking at. Its precondition is unchanged by the failure:
529
+ # they just authored this content, and that is as true after five of
530
+ # eight writes as after eight. Skipping this made the failure wrong
531
+ # about two things instead of one, and silent about the second.
532
+ trust_note, trust_ok = _settle_trust(root, was_trusted, trust_problem)
533
+
534
+ if failure is not None:
535
+ # NAME WHAT WAS CREATED. The success path reports the files so the
536
+ # user knows what changed; the failure path reported the single
537
+ # file that did NOT change -- the one thing they could already see
538
+ # -- and discarded the list of the ones that did. "Could not write
539
+ # TECHNICAL_DEBT.md" left no way to tell whether nothing had
540
+ # happened or most of it had.
541
+ #
542
+ # NOTHING IS ROLLED BACK, deliberately. The hub's previous
543
+ # content was overwritten at the first step and cannot be restored,
544
+ # so "rolled back" would be true of the stubs and false of the one
545
+ # file that mattered -- and deleting documents out of someone's
546
+ # project on an error path is a worse failure than the one being
547
+ # reported.
548
+ lines = [failure]
549
+ if written:
550
+ lines.append(f"Wrote {len(written)} file"
551
+ f"{'' if len(written) == 1 else 's'} before that: "
552
+ + ", ".join(written))
553
+ else:
554
+ lines.append("Nothing was written.")
555
+ lines.append(trust_note)
556
+ raise InitError("\n".join(line for line in lines if line))
557
+
558
+ # THE WARNING LEADS, when there is one (A46). The files are on disk and
559
+ # the user can see them; what they cannot see is that the next launch
560
+ # will ask about this project again, so the half that did NOT happen is
561
+ # the half that goes first. A run whose trust settled as intended keeps
562
+ # the note where it has always been -- last, as the footnote it is.
563
+ lines = [] if trust_ok else [trust_note]
564
+ lines.append(f"Wrote {len(written)} file"
565
+ f"{'' if len(written) == 1 else 's'}: " + ", ".join(written))
566
+ if made:
567
+ lines.append("Created: " + ", ".join(made))
568
+ if already_there:
569
+ lines.append("Left alone: " + ", ".join(sorted(already_there)))
570
+ if plan["existing"]:
571
+ lines.append("Left alone: "
572
+ + ", ".join(".venastine/" + name
573
+ for name in plan["existing"]))
574
+ if trust_ok:
575
+ lines.append(trust_note)
576
+ return {"kind": "init", "text": "\n".join(line for line in lines if line)}
577
+
578
+
579
+ def _nothing_to_do(kind, scaffold_docs: bool, scaffold_config: bool) -> str:
580
+ """The message for a run that found everything already in place.
581
+
582
+ Assembled from the halves that actually ran, so a `--config` run in a
583
+ configured project does not report on a document set it never looked
584
+ at -- which is the same complaint #95 makes about a failure naming
585
+ the one file that did NOT change.
586
+ """
587
+ from tools.builtin.project_docs import HUB_FILENAME
588
+
589
+ parts = []
590
+ if scaffold_docs:
591
+ parts.append(f"{HUB_FILENAME} is already up to date and every "
592
+ f"document in the {kind} set exists")
593
+ if scaffold_config:
594
+ parts.append(".venastine/ already has its settings.json and "
595
+ "mcp.json")
596
+ return " and ".join(parts) + ". Nothing to do."
597
+
598
+
599
+ def _consent_summary(context_path: str, to_create: list, changing: bool,
600
+ plan: Optional[dict] = None) -> str:
601
+ """ONE consent covering everything the run will touch (I5).
602
+
603
+ The configuration files are named in it rather than asked about
604
+ separately: eight prompts for one command is the shape of consent that
605
+ gets clicked through, which is the reason this summary exists at all.
606
+ """
607
+ plan = plan or {"files": [], "dirs": []}
608
+ parts = []
609
+ if changing:
610
+ parts.append(f"write {context_path}")
611
+ if to_create:
612
+ parts.append(f"create {len(to_create)} stub document"
613
+ f"{'' if len(to_create) == 1 else 's'} "
614
+ f"({', '.join(to_create)})")
615
+ if plan["files"]:
616
+ parts.append("create " + ", ".join(".venastine/" + name
617
+ for name in plan["files"])
618
+ + " with default values")
619
+ if plan["dirs"]:
620
+ parts.append("create " + ", ".join(".venastine/" + name + "/"
621
+ for name in plan["dirs"]))
622
+ return "/init will " + " and ".join(parts) + ". Proceed?"
623
+
624
+
625
+ def _write(registry, granted, name: str, content: str) -> None:
626
+ result = registry.dispatch(
627
+ "write_project_doc", {"name": name, "content": content},
628
+ approval_callback=granted)
629
+ if isinstance(result, dict) and result.get("error"):
630
+ raise InitError(result["error"])
631
+
632
+
633
+ def _trust_before(project_path: str) -> tuple:
634
+ """`is_trusted()`, made total. Returns (was_trusted, problem).
635
+
636
+ THE CAPTURE READS FILES, which is the half of I6 nobody was looking at
637
+ (batch 153). `is_trusted` hashes every path `content_files()`
638
+ lists -- the root `AGENTS.md` and everything under `.venastine/` -- and
639
+ `open` on any one of them can fail: a file an editor holds, a sync
640
+ client mid-write, a mode the user changed by hand. That read sits
641
+ before the `try`, so a single unreadable file killed `/init` as a raw
642
+ `PermissionError` before it wrote anything, and on the CLI
643
+ (`except InitError` only) as a traceback.
644
+
645
+ DEGRADES, and the precedent is three functions up in this same module:
646
+ `_read_existing_context` catches `OSError` on the SAME file for the
647
+ SAME reason and says "Degrade like config_loader does with an
648
+ unreadable hub document". One function answering one error two ways is
649
+ what this closes (A47).
650
+
651
+ `False` rather than `True` for an unanswerable question, which is
652
+ `core/workspace_trust.py`'s own posture -- `_load_trust_store` returns
653
+ `{}` for anything unreadable and says it fails CLOSED in both senses.
654
+ Read as untrusted, `_settle_trust` attempts no re-grant, and the
655
+ problem is REPORTED rather than inferred from a trust prompt arriving
656
+ on the next launch.
657
+
658
+ NOT fixed in `is_trusted` itself, deliberately (A48). Its other callers
659
+ are contained -- `main.load_project_config` catches `OSError` and exits
660
+ 1 with one clean line -- and making a security control answer "not
661
+ trusted" where it currently refuses to start is a change to D17's
662
+ posture, not to this command's. `docs/TECHNICAL_DEBT.md` carries it.
663
+ """
664
+ try:
665
+ return workspace_trust.is_trusted(project_path), ""
666
+ except OSError as e:
667
+ logger.warning("Could not read the trust state of %s; proceeding as "
668
+ "untrusted: %s", project_path, e)
669
+ return False, (
670
+ f"This project's trust state could not be read ({e}), so the run "
671
+ f"proceeded as if it were untrusted and no re-grant was "
672
+ f"attempted. You will be asked about its .venastine/ content on "
673
+ f"the next launch.")
674
+
675
+
676
+ def _settle_trust(project_path: str, was_trusted: bool,
677
+ problem: str = "") -> tuple:
678
+ """I6. Re-grant only for a project that was ALREADY trusted.
679
+
680
+ Writing the hub changes the D17 content hash, so a project the user
681
+ had approved becomes untrusted purely because they ran this command --
682
+ the trust system working as designed, producing a bad outcome. Since
683
+ they just authored the content, re-granting is unambiguous.
684
+
685
+ But ONLY then. In an untrusted project, `.venastine/` may already hold
686
+ agents, skills and an mcp.json that arrived with a repo someone cloned.
687
+ Granting trust as a side effect of /init would launder all of it in --
688
+ a hole in D17 opened from a direction the trust prompt never sees.
689
+ The hub is never special-cased out of the hash either; that would be
690
+ the same hole with a smaller mouth.
691
+
692
+ TOTAL SINCE BATCH 153. Returns (note, settled_as_intended),
693
+ and the note is the whole of what the user is told about trust -- so
694
+ this function raising discarded it, along with everything `generate`
695
+ had assembled around it. #95 put the settle on both paths; the settle
696
+ then sat outside every handler on both of them, so a trust-store I/O
697
+ failure took the success path's notice and the failure path's "wrote N
698
+ files before that" accounting down with it. Measured: both config
699
+ files on disk, `is_trusted` True -> False, and a raw `OSError` out.
700
+
701
+ `grant_trust` raises from either half -- `_content_hash` re-reads the
702
+ files just written, `_save_trust_store` writes the store -- and
703
+ `OSError` is both. `json_store` argues that a trust grant which
704
+ silently did not persist is worse than a crash, and that argument is
705
+ about SILENCE: the grant still either persists or is named, and the
706
+ naming now reaches the user instead of the traceback handler.
707
+
708
+ `False` is returned for the grant failure and for an unreadable
709
+ pre-write state, and `True` for a project that was untrusted and
710
+ stayed that way -- nothing went wrong there, and that note is a
711
+ footnote rather than a warning.
712
+ """
713
+ if problem:
714
+ return problem, False
715
+ if not was_trusted:
716
+ return ("This project is not trusted, so nothing here has changed "
717
+ "that. You will be asked about its .venastine/ content on "
718
+ "the next launch."), True
719
+ try:
720
+ workspace_trust.grant_trust(project_path)
721
+ except OSError as e:
722
+ logger.warning("Could not re-grant workspace trust for %s: %s",
723
+ project_path, e)
724
+ return (f"Workspace trust could NOT be re-granted ({e}), so the next "
725
+ f"launch will ask about this project's .venastine/ content "
726
+ f"again."), False
727
+ return ("Workspace trust re-granted for the updated .venastine/ content, "
728
+ "so the next launch will not re-ask."), True