@yahyahammad/venastine 0.2.0 → 0.3.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (152) hide show
  1. package/.env.example +9 -4
  2. package/CONFIG_ARCHITECTURE.md +2030 -0
  3. package/LICENSE +201 -201
  4. package/NOTICE +1 -1
  5. package/README.md +1034 -895
  6. package/agents/builtin/build.md +73 -0
  7. package/agents/builtin/compactor.md +75 -75
  8. package/agents/builtin/explore.md +77 -77
  9. package/agents/builtin/general.md +80 -0
  10. package/agents/builtin/pipeline-reviewer.md +100 -100
  11. package/agents/builtin/plan.md +106 -88
  12. package/agents/builtin/review.md +74 -74
  13. package/agents/builtin/test.md +65 -0
  14. package/agents/builtin/writer.md +67 -0
  15. package/agents/manager.py +68 -2
  16. package/agents/subagent_tool.py +472 -238
  17. package/agents/tui_commands.py +238 -151
  18. package/bin/venastine.mjs +150 -4
  19. package/bin/venastine.py +71 -0
  20. package/cli_commands.py +838 -0
  21. package/config.py +95 -1198
  22. package/config.yaml +1103 -0
  23. package/config_edit.py +1301 -0
  24. package/config_schema.py +971 -0
  25. package/config_update.py +749 -0
  26. package/core/agent_activity.py +256 -118
  27. package/core/ansi.py +452 -0
  28. package/core/approval.py +137 -115
  29. package/core/call_view.py +364 -0
  30. package/core/cancel.py +121 -0
  31. package/core/chatgpt_auth.py +747 -0
  32. package/core/claims_view.py +107 -0
  33. package/core/client.py +2715 -1559
  34. package/core/commands.py +460 -0
  35. package/core/compaction.py +1735 -971
  36. package/core/config_loader.py +1982 -1563
  37. package/core/connect.py +686 -0
  38. package/core/events.py +123 -61
  39. package/core/file_mentions.py +280 -0
  40. package/core/interaction.py +411 -328
  41. package/core/line_pattern.py +128 -0
  42. package/core/loop.py +2566 -1490
  43. package/core/memory.py +482 -370
  44. package/core/pipeline_models.py +190 -176
  45. package/core/provider_errors.py +234 -0
  46. package/core/reasoning/authorization.py +130 -130
  47. package/core/reasoning/base.py +219 -219
  48. package/core/reasoning/confidence_scoring.py +484 -468
  49. package/core/reasoning/events.py +149 -149
  50. package/core/reasoning/json_retry.py +19 -1
  51. package/core/reasoning/orchestrator.py +1561 -1382
  52. package/core/reasoning/output_writer.py +345 -286
  53. package/core/reasoning/payload_validation.py +524 -398
  54. package/core/reasoning/pipeline_storage.py +88 -22
  55. package/core/reasoning/review.py +659 -615
  56. package/core/reasoning/scholar.py +458 -434
  57. package/core/reasoning/source_corpus.py +433 -327
  58. package/core/reasoning/source_scoring.py +855 -855
  59. package/core/replay.py +315 -183
  60. package/core/session.py +36 -12
  61. package/core/session_view.py +259 -0
  62. package/core/session_wake.py +259 -0
  63. package/core/shell_sessions.py +1553 -0
  64. package/core/workspace_trust.py +1 -1
  65. package/credentials.py +148 -20
  66. package/database.py +333 -252
  67. package/{PRIVACY.md → docs/PRIVACY.md} +78 -66
  68. package/docs/SECURITY.md +108 -0
  69. package/docs/THIRD_PARTY_NOTICES.md +148 -0
  70. package/env_secrets.py +50 -9
  71. package/json_store.py +343 -123
  72. package/logging_setup.py +295 -185
  73. package/main.py +3433 -1961
  74. package/mcp_client/client.py +733 -499
  75. package/mcp_client/config.py +126 -21
  76. package/mcp_client/registration.py +343 -182
  77. package/memories/manager.py +147 -132
  78. package/memories/tui_commands.py +319 -244
  79. package/package.json +303 -73
  80. package/project_init/config_files.py +282 -278
  81. package/project_init/generator.py +728 -564
  82. package/project_init/manifest.py +18 -6
  83. package/project_init/tui_commands.py +147 -144
  84. package/prompts/critic_pass.md +24 -24
  85. package/prompts/revalidate.md +25 -25
  86. package/prompts/revise.md +2 -0
  87. package/prompts/source_grounding.md +66 -66
  88. package/prompts/system_prompts.py +316 -262
  89. package/providers.json.example +4 -2
  90. package/pyproject.toml +149 -100
  91. package/requirements.txt +295 -72
  92. package/safety/policy_enforcement.py +1082 -746
  93. package/security/askpass.py +419 -0
  94. package/security/capability.py +207 -177
  95. package/security/confine.py +484 -0
  96. package/security/hosted.py +182 -0
  97. package/security/permissions.py +237 -190
  98. package/security/posture.py +124 -12
  99. package/security/protected_paths.py +501 -309
  100. package/security/sandbox.py +4108 -985
  101. package/security/secrets.py +855 -0
  102. package/skills/builtin/math/formal-specification.md +67 -67
  103. package/skills/builtin/math/numerical-methods.md +66 -66
  104. package/skills/builtin/research/experiment-design.md +62 -62
  105. package/skills/builtin/research/reproducibility.md +55 -55
  106. package/skills/builtin/research/source-evaluation.md +70 -70
  107. package/skills/builtin/research/statistical-inference.md +63 -63
  108. package/skills/builtin/research/technical-writing.md +59 -59
  109. package/skills/builtin/software/code-review.md +61 -61
  110. package/skills/builtin/software/debugging.md +61 -61
  111. package/skills/builtin/software/test-design.md +67 -67
  112. package/skills/tui_commands.py +110 -111
  113. package/storage.py +1338 -1005
  114. package/tools/base.py +161 -1
  115. package/tools/builtin/_math_common.py +667 -377
  116. package/tools/builtin/_net_common.py +225 -19
  117. package/tools/builtin/arxiv.py +497 -39
  118. package/tools/builtin/ask_user.py +231 -213
  119. package/tools/builtin/discrete_math.py +35 -4
  120. package/tools/builtin/fetch_url.py +371 -153
  121. package/tools/builtin/file_ops.py +720 -412
  122. package/tools/builtin/geometry.py +48 -12
  123. package/tools/builtin/get_time.py +2 -2
  124. package/tools/builtin/linear_algebra.py +66 -23
  125. package/tools/builtin/load_skill.py +76 -66
  126. package/tools/builtin/logic.py +171 -12
  127. package/tools/builtin/pin.py +227 -193
  128. package/tools/builtin/probability_stats.py +12 -16
  129. package/tools/builtin/project_docs.py +464 -405
  130. package/tools/builtin/remember.py +175 -158
  131. package/tools/builtin/shell.py +980 -461
  132. package/tools/builtin/shell_sessions.py +613 -0
  133. package/tools/builtin/symbolic_math.py +80 -10
  134. package/tools/builtin/todo.py +149 -147
  135. package/tools/builtin/web_search.py +191 -13
  136. package/tools/context.py +159 -136
  137. package/tools/isolation.py +107 -34
  138. package/tools/registry.py +1242 -925
  139. package/tui/app.py +8318 -4100
  140. package/tui/app.tcss +747 -556
  141. package/tui/commands.py +26 -170
  142. package/tui/diffs.py +34 -13
  143. package/tui/history.py +128 -128
  144. package/tui/hosted_driver.py +102 -0
  145. package/tui/markdown.py +1329 -1279
  146. package/tui/meters.py +364 -268
  147. package/tui/ravens.py +146 -146
  148. package/tui/screens.py +1255 -943
  149. package/tui/themes.py +599 -559
  150. package/tui/widgets.py +3813 -2332
  151. package/SECURITY.md +0 -88
  152. package/THIRD_PARTY_NOTICES.md +0 -100
@@ -1,405 +1,464 @@
1
- """
2
- tools/builtin/project_docs.py
3
-
4
- ROADMAP_v2 §24: the two narrowly-scoped file tools `/init` runs on --
5
- `read_project_doc` (I2) and `write_project_doc` (I1).
6
-
7
- WHY NOT `read` AND `write`. Both are `False` in config.ToolPermissions, and
8
- that is not a default anyone can change: is_tool_allowed() reads the
9
- dataclass directly, settings.json has no `permissions` section (and
10
- _KNOWN_SETTINGS *raises* on an unknown key), and D14 forbids a ToolContext
11
- widening anything -- the global check runs first and unconditionally. So
12
- registry.dispatch("write", ...) raises ToolCallDenied BEFORE the
13
- approval_callback is ever consulted, for every user, out of the box.
14
-
15
- The two ways out were flipping those globals or scoping new tools. Flipping
16
- `write` hands the model unprompted write access anywhere inside
17
- WORKSPACE_DIR permanently, and flipping `read` hands every agent and all ten
18
- research passes file-read access by default -- a standing posture change to
19
- serve one command. These tools instead do exactly what /init needs and
20
- nothing else, so §24 adds no capability that outlives it.
21
-
22
- BOTH TOOLS LIVE IN ONE MODULE because they resolve paths against the same
23
- root. A second copy of that resolver is precisely how the two would drift
24
- apart -- the project's "fix at the producer" rule, applied before the bug.
25
-
26
- CONSEQUENCE, NAMED RATHER THAN DISCOVERED: a registered tool with permission
27
- True is advertised to EVERY run, not only to /init's. The initializer agent's
28
- `allowed_tools` narrows that agent; it does not stop plain chat or a research
29
- pass from calling `read_project_doc`. That is why the readable set here is
30
- DOCUMENTATION, not "text files": a doc/manifest allowlist plus a hard deny of
31
- `.venastine/`, `.git/`, `.env*` and `providers.json` means the most a
32
- prompt-injected research pass gains is the project's own README. Widening
33
- this to source files would quietly turn it into `read` with no approval gate.
34
-
35
- THE FIVE BUILD MANIFESTS, AND WHY THEY ARE ROOT-ONLY (#94). `setup.py`,
36
- `setup.cfg`, `Gemfile`, `pom.xml` and `build.gradle` were on neither list
37
- while `pyproject.toml`, `package.json`, `Cargo.toml`, `go.mod`, `Makefile`
38
- and `Dockerfile` were on the first -- an incomplete enumeration rather than
39
- a judgement, and `requirements.txt` got in by accident through `.txt`. The
40
- manifest /init shows its agent advertised all of them as readable, so the
41
- agent spent steps out of a budget of twelve discovering that six were not.
42
-
43
- They are added BY EXACT NAME. That is what keeps the paragraph above true:
44
- `.py` never enters `_DOC_EXTENSIONS`, so `main.py`, `config.py` and
45
- `credentials.py` stay refused, and this is five filenames rather than a
46
- class of file. Driven, not assumed, before the decision was taken.
47
-
48
- They are also the first entries that match at the project ROOT only.
49
- Everything in `_DOC_FILENAMES` matches on basename at any depth, which is
50
- right for `packages/foo/package.json` in a monorepo and wrong for
51
- `src/vendor/setup.py` -- a vendored tree is where unreviewed third-party
52
- source lives, and it is the one place these five are not this project's own
53
- statement about itself.
54
-
55
- THE RESIDUAL, STATED RATHER THAN LEFT TO BE FOUND: `check_output_policy`
56
- scans every value (#47), so `sk-ant-...`, `ghp_...`, `AKIA...` and a PEM
57
- header are redacted out of a result. A plaintext `<password>` element, a
58
- Gradle `password "..."` and a `user:token@host` URL are NOT, and those are
59
- the credential shapes that occur in exactly these five files. Filed against
60
- the redactor rather than fixed here, because a pattern added there redacts
61
- content out of every tool result in the harness, not only this one.
62
- """
63
-
64
- from __future__ import annotations
65
-
66
- import logging
67
- import os
68
- from typing import Optional
69
-
70
- import config
71
- from core import config_loader, workspace_trust
72
- from security import protected_paths
73
-
74
- logger = logging.getLogger(__name__)
75
-
76
- # Documentation and manifests. Deliberately NOT a general text-file list --
77
- # see the module docstring's consequence note.
78
- _DOC_EXTENSIONS = frozenset({".md", ".markdown", ".rst", ".txt"})
79
- _DOC_FILENAMES = frozenset({
80
- "pyproject.toml", "package.json", "cargo.toml", "go.mod",
81
- "makefile", "dockerfile", "license", "licence", "changelog", "notice",
82
- })
83
-
84
- # Build manifests, readable at the PROJECT ROOT ONLY -- see the docstring.
85
- # A nested copy is somebody else's source; the root copy is this project's
86
- # own statement about what it is.
87
- _ROOT_ONLY_FILENAMES = frozenset({
88
- "setup.py", "setup.cfg", "gemfile", "pom.xml", "build.gradle",
89
- })
90
-
91
- # Denied whatever the extension says. `.venastine/` can hold mcp.json and
92
- # settings.json; providers.json is where API keys live. check_output_policy
93
- # would redact a leaked key from the result, but a backstop is not a reason
94
- # to hand it the chance.
95
- #
96
- # `.venastine` is spelled ONCE, in security.protected_paths.PROTECTED_SEGMENTS
97
- # -- the same segment the file tools hard-refuse and the shell's approval
98
- # check always asks about -- and unioned in here rather than re-spelled, so
99
- # the one fact cannot drift between its three consumers.
100
- _DENIED_SEGMENTS = (protected_paths.PROTECTED_SEGMENTS
101
- | {".git", "node_modules", ".venv", "venv",
102
- "__pycache__", ".pytest_cache"})
103
- _DENIED_FILENAMES = frozenset({"providers.json"})
104
-
105
- #: Re-exported so callers name one constant. The name lives in
106
- #: core/workspace_trust because the load-bearing fact about it is that a
107
- #: grant covers it (§44).
108
- HUB_FILENAME = workspace_trust.PROJECT_CONTEXT_FILENAME
109
-
110
-
111
- def _project_root() -> Optional[str]:
112
- """The resolved project path, or None when no session has been
113
- initialized. None is "there is no project", not "guess one" -- the same
114
- convention get_agents() and memories/manager.py follow."""
115
- return config_loader.get_project_path()
116
-
117
-
118
- def doc_path(project_path: str, name: str) -> str:
119
- """Where a document in the set lives. DERIVED FROM ITS NAME, never taken
120
- from a path parameter (I1).
121
-
122
- ONE JOIN SINCE §44, where this used to branch. I9 put the hub inside
123
- `.venastine/` so that the one file every agent reads sat inside the
124
- trust boundary. §44 keeps the boundary and moves the file: AGENTS.md is
125
- an ordinary committed root document, and workspace_trust.content_files()
126
- covers it explicitly. What that buys is a project you can share without
127
- your configuration and still have it make sense to whoever cloned it --
128
- where a hub in `.venastine/` meant sharing the repo without that
129
- directory shipped a set of documents pointing at a file that was not
130
- there.
131
-
132
- The function survives the simplification because the confinement is
133
- what it is FOR: a name from a fixed allowlist, resolved under the
134
- project, with no path parameter anywhere in the tool that calls it.
135
- """
136
- return os.path.join(project_path, name)
137
-
138
-
139
- def _resolve_in_project(root: str, user_path: str) -> Optional[str]:
140
- """Resolve *user_path* under *root* and return it only if it really
141
- lands inside.
142
-
143
- realpath BEFORE the containment test, so '..' segments and a symlink
144
- pointing outside the project are both caught -- file_ops' rule, and the
145
- reason it is a rule: a path that merely looks contained is not.
146
- """
147
- resolved = os.path.realpath(os.path.join(root, user_path))
148
- if resolved != root and not resolved.startswith(root + os.sep):
149
- return None
150
- return resolved
151
-
152
-
153
- def _is_readable_doc(root: str, resolved: str) -> bool:
154
- rel = os.path.relpath(resolved, root)
155
- parts = rel.split(os.sep)
156
- if any(segment in _DENIED_SEGMENTS for segment in parts):
157
- return False
158
- name = os.path.basename(resolved).lower()
159
- if name in _DENIED_FILENAMES or name.startswith(".env"):
160
- return False
161
- if name in _DOC_FILENAMES:
162
- return True
163
- if name in _ROOT_ONLY_FILENAMES:
164
- # `parts` is the path relative to the project root, so a length of
165
- # one IS "at the root". Checked against the split rather than the
166
- # string, because os.altsep exists.
167
- return len(parts) == 1
168
- return os.path.splitext(name)[1] in _DOC_EXTENSIONS
169
-
170
-
171
- def is_readable_doc(project_path: str, user_path: str) -> bool:
172
- """This tool's own test, in public, for /init's manifest (#94).
173
-
174
- The manifest prints "Paths below are exactly what read_project_doc
175
- expects" over its listing, and used to decide what to list with a
176
- parallel test of its own. Nothing kept the two in step and they
177
- disagreed in both directions: six advertised paths the tool refused,
178
- and four it accepted that never appeared -- including every `.txt`
179
- document in a project, invisible because the manifest tested extensions
180
- and this module tests these.
181
-
182
- Exported rather than reimplemented, so the sentence is true by
183
- construction. The read path is unchanged: `read_run` still resolves and
184
- re-tests for itself, because a listing is not an authorization.
185
- """
186
- root = os.path.realpath(project_path)
187
- resolved = _resolve_in_project(root, user_path)
188
- return resolved is not None and _is_readable_doc(root, resolved)
189
-
190
-
191
- # ===========================================================================
192
- # ---- READ -----------------------------------------------------------------
193
- # ===========================================================================
194
-
195
- READ_TOOL_SCHEMA = {
196
- "name": "read_project_doc",
197
- "description": (
198
- "Read one of this project's documentation or manifest files, by the "
199
- "relative path given in the file listing you were shown. Markdown, "
200
- "text and manifest files only, and only within the project "
201
- f"directory. Returns at most {config.INIT_READ_CHARS} characters per "
202
- "call; use offset to continue through a longer file."
203
- ),
204
- "input_schema": {
205
- "type": "object",
206
- "properties": {
207
- "path": {
208
- "type": "string",
209
- "description": "Path relative to the project root, exactly "
210
- "as it appears in the file listing.",
211
- },
212
- "offset": {
213
- "type": "integer",
214
- "description": "Characters to skip before reading. Use the "
215
- "value suggested by a truncated response to "
216
- "read the next part of a long file.",
217
- },
218
- },
219
- "required": ["path"],
220
- },
221
- }
222
-
223
-
224
- def _skip(handle, offset: int) -> None:
225
- """Advance `offset` characters without holding them.
226
-
227
- f.seek() on a text stream takes an opaque cookie, not a character
228
- count, so an offset cannot simply be jumped to. Reading forward in
229
- bounded pieces keeps the memory ceiling at one piece instead of the
230
- whole prefix, which is the property #55 is about -- the cost is
231
- proportional to the offset, but the MEMORY is not.
232
- """
233
- remaining = offset
234
- while remaining > 0:
235
- piece = handle.read(min(remaining, config.INIT_READ_CHARS))
236
- if not piece:
237
- return
238
- remaining -= len(piece)
239
-
240
-
241
- def read_run(params: dict) -> dict:
242
- # params.get throughout, not params[]: no provider validates tool inputs
243
- # against the schema, and a bare KeyError escapes the loop's
244
- # ToolCallDenied handler and aborts the whole turn (remember.py's note).
245
- root = _project_root()
246
- if root is None:
247
- return {"error": "read_project_doc: no project directory has been "
248
- "resolved, so there is nothing to read."}
249
-
250
- user_path = (params.get("path") or "").strip()
251
- if not user_path:
252
- return {"error": "read_project_doc requires 'path'."}
253
-
254
- resolved = _resolve_in_project(root, user_path)
255
- if resolved is None:
256
- return {"error": f"read_project_doc: {user_path!r} resolves outside "
257
- f"the project directory."}
258
- if not _is_readable_doc(root, resolved):
259
- return {"error": f"read_project_doc: {user_path!r} is not a readable "
260
- f"project document. Documentation and manifest "
261
- f"files only."}
262
- if not os.path.isfile(resolved):
263
- return {"error": f"read_project_doc: no such file: {user_path}"}
264
-
265
- offset = params.get("offset") or 0
266
- if not isinstance(offset, int) or offset < 0:
267
- offset = 0
268
-
269
- # ROADMAP_v2 §31 (H7), #55. This used to be f.read() followed by
270
- # text[offset:offset + INIT_READ_CHARS], so returning 20,000
271
- # characters of a 30 MB document cost 60 MB of peak traced memory --
272
- # and cost it AGAIN on every page, because each call re-read the
273
- # whole file to slice a different part of it.
274
- #
275
- # A getsize guard like read_run's would be the obvious copy, and it
276
- # is the wrong one here: refusing a large document is not what this
277
- # tool is for -- I7 chose INIT_READ_CHARS deliberately so /init could
278
- # page through exactly such a document. Seeking to the offset bounds
279
- # the read AND removes the re-read, which a size check would not.
280
- #
281
- # One extra character is read to answer `truncated` without a second
282
- # pass. seek() counts characters in text mode only for utf-8-sig-free
283
- # streams, so the offset is walked rather than jumped: correctness
284
- # over cleverness, and it still holds one chunk rather than the file.
285
- try:
286
- with open(resolved, "r", encoding="utf-8", errors="replace") as f:
287
- _skip(f, offset)
288
- chunk = f.read(config.INIT_READ_CHARS)
289
- more = f.read(1) != ""
290
- except OSError as e:
291
- logger.warning("read_project_doc failed for %s: %s", user_path, e)
292
- return {"error": f"Could not read {user_path}: {e}"}
293
-
294
- result = {"path": user_path, "content": chunk, "truncated": more}
295
- if result["truncated"]:
296
- # The continuation offset is IN the message, not merely implied by
297
- # the numbers. A model that has to compute where to resume usually
298
- # re-reads from zero and spends the budget twice.
299
- #
300
- # §31 (H7) dropped the total. It used to read `of {len(text)}`,
301
- # and len(text) was the whole file -- the very read this section
302
- # removed. A total could be faked from os.path.getsize, but that
303
- # is BYTES and this count is CHARACTERS, so on any document with
304
- # a non-ASCII character it would be a number that looks exact and
305
- # is not. Saying less is the honest option; the part that was
306
- # load-bearing -- where to resume -- is untouched.
307
- end = offset + len(chunk)
308
- result["message"] = (
309
- f"Read characters {offset}-{end}. "
310
- f"Call again with offset={end} to continue.")
311
- return result
312
-
313
-
314
- # ===========================================================================
315
- # ---- WRITE ----------------------------------------------------------------
316
- # ===========================================================================
317
-
318
- WRITE_TOOL_SCHEMA = {
319
- "name": "write_project_doc",
320
- "description": (
321
- "Write one of this project's standard documentation files. Takes the "
322
- "document's NAME, not a path -- the location is derived, so this "
323
- "cannot write anywhere else. Overwrites the named file, so the caller "
324
- "is expected to have shown the user what changes."
325
- ),
326
- "input_schema": {
327
- "type": "object",
328
- "properties": {
329
- "name": {
330
- "type": "string",
331
- "description": "One of the project's standard document names, "
332
- "e.g. AGENTS.md or ARCHITECTURE.md.",
333
- },
334
- "content": {
335
- "type": "string",
336
- "description": "Full markdown body of the document.",
337
- },
338
- },
339
- "required": ["name", "content"],
340
- },
341
- }
342
-
343
-
344
- def _known_doc_names() -> frozenset:
345
- """The allowlist IS the confinement (I1), so it is read from the one
346
- place that defines the sets rather than restated here. Imported lazily:
347
- tools/registry.py imports this module at import time, and project_init
348
- imports config, which would close a cycle."""
349
- from project_init.doc_sets import all_document_names
350
- return all_document_names()
351
-
352
-
353
- def approval_notice(params: dict, context) -> str:
354
- """What the approval prompt shows.
355
-
356
- The gate is only worth having if the prompt says what it is gating
357
- (remember.py's rule). Here that is the destination and the size --
358
- the content itself has already been shown as a diff by the caller,
359
- and repeating several kilobytes of markdown inside a modal would bury
360
- the one line that says which file is about to change.
361
- """
362
- root = _project_root()
363
- name = params.get("name") or HUB_FILENAME
364
- where = doc_path(root, name) if root else name
365
- size = len(params.get("content") or "")
366
- verb = "Overwrite" if root and os.path.exists(where) else "Create"
367
- return f"{verb} {where} ({size} characters)."
368
-
369
-
370
- def write_run(params: dict) -> dict:
371
- root = _project_root()
372
- if root is None:
373
- return {"error": "write_project_doc: no project directory has been "
374
- "resolved, so there is nowhere to write."}
375
-
376
- name = (params.get("name") or "").strip()
377
- known = _known_doc_names()
378
- if name not in known:
379
- # Not coerced to the hub, and not accepted as a path. An
380
- # unrecognised name is the one case where this tool could become a
381
- # general writer, so it fails loudly and lists what it accepts.
382
- return {"error": f"write_project_doc: {name!r} is not one of this "
383
- f"project's standard documents. Expected one of: "
384
- f"{', '.join(sorted(known))}."}
385
-
386
- content = params.get("content")
387
- if not isinstance(content, str) or not content.strip():
388
- return {"error": "write_project_doc requires non-empty 'content'."}
389
-
390
- encoded = content.encode("utf-8")
391
- if len(encoded) > config.MAX_FILE_SIZE_BYTES:
392
- return {"error": f"Content size ({len(encoded)} bytes) exceeds the "
393
- f"maximum writable size "
394
- f"({config.MAX_FILE_SIZE_BYTES} bytes)."}
395
-
396
- destination = doc_path(root, name)
397
- try:
398
- os.makedirs(os.path.dirname(destination), exist_ok=True)
399
- with open(destination, "w", encoding="utf-8") as f:
400
- f.write(content)
401
- except OSError as e:
402
- logger.warning("write_project_doc failed for %s: %s", destination, e)
403
- return {"error": f"Could not write {destination}: {e}"}
404
-
405
- return {"result": f"Wrote {len(content)} characters to {destination}"}
1
+ """
2
+ tools/builtin/project_docs.py
3
+
4
+ ROADMAP_v2 §24: the two narrowly-scoped file tools `/init` runs on --
5
+ `read_project_doc` (I2) and `write_project_doc` (I1).
6
+
7
+ WHY NOT `read` AND `write`. Both are `False` in config.ToolPermissions, and
8
+ that is not a default anyone can change: is_tool_allowed() reads the
9
+ dataclass directly, settings.json has no `permissions` section (and
10
+ _KNOWN_SETTINGS *raises* on an unknown key), and D14 forbids a ToolContext
11
+ widening anything -- the global check runs first and unconditionally. So
12
+ registry.dispatch("write", ...) raises ToolCallDenied BEFORE the
13
+ approval_callback is ever consulted, for every user, out of the box.
14
+
15
+ The two ways out were flipping those globals or scoping new tools. Flipping
16
+ `write` hands the model unprompted write access anywhere inside
17
+ WORKSPACE_DIR permanently, and flipping `read` hands every agent and all ten
18
+ research passes file-read access by default -- a standing posture change to
19
+ serve one command. These tools instead do exactly what /init needs and
20
+ nothing else, so §24 adds no capability that outlives it.
21
+
22
+ BOTH TOOLS LIVE IN ONE MODULE because they resolve paths against the same
23
+ root. A second copy of that resolver is precisely how the two would drift
24
+ apart -- the project's "fix at the producer" rule, applied before the bug.
25
+
26
+ CONSEQUENCE, NAMED RATHER THAN DISCOVERED: a registered tool with permission
27
+ True is advertised to EVERY run, not only to /init's. The initializer agent's
28
+ `allowed_tools` narrows that agent; it does not stop plain chat or a research
29
+ pass from calling `read_project_doc`. That is why the readable set here is
30
+ DOCUMENTATION, not "text files": a doc/manifest allowlist plus a hard deny of
31
+ `.venastine/`, `.git/`, `.env*` and `providers.json` means the most a
32
+ prompt-injected research pass gains is the project's own README. Widening
33
+ this to source files would quietly turn it into `read` with no approval gate.
34
+
35
+ THE FIVE BUILD MANIFESTS, AND WHY THEY ARE ROOT-ONLY (#94). `setup.py`,
36
+ `setup.cfg`, `Gemfile`, `pom.xml` and `build.gradle` were on neither list
37
+ while `pyproject.toml`, `package.json`, `Cargo.toml`, `go.mod`, `Makefile`
38
+ and `Dockerfile` were on the first -- an incomplete enumeration rather than
39
+ a judgement, and `requirements.txt` got in by accident through `.txt`. The
40
+ manifest /init shows its agent advertised all of them as readable, so the
41
+ agent spent steps out of a budget of twelve discovering that six were not.
42
+
43
+ They are added BY EXACT NAME. That is what keeps the paragraph above true:
44
+ `.py` never enters `_DOC_EXTENSIONS`, so `main.py`, `config.py` and
45
+ `credentials.py` stay refused, and this is five filenames rather than a
46
+ class of file. Driven, not assumed, before the decision was taken.
47
+
48
+ They are also the first entries that match at the project ROOT only.
49
+ Everything in `_DOC_FILENAMES` matches on basename at any depth, which is
50
+ right for `packages/foo/package.json` in a monorepo and wrong for
51
+ `src/vendor/setup.py` -- a vendored tree is where unreviewed third-party
52
+ source lives, and it is the one place these five are not this project's own
53
+ statement about itself.
54
+
55
+ THE RESIDUAL THAT WAS STATED HERE IS CLOSED, and what is left of the
56
+ paragraph is the part that was always the point. `check_output_policy` scans
57
+ every value (#47), so `sk-ant-...`, `ghp_...`, `AKIA...` and a PEM header
58
+ are redacted out of a result. A plaintext `<password>` element, a Gradle
59
+ `password "..."` and a `user:token@host` URL were NOT, and those are the
60
+ credential shapes that occur in exactly these five files -- so they were
61
+ filed against the REDACTOR rather than fixed here, because a pattern added
62
+ there redacts content out of every tool result in the harness and one added
63
+ here would serve one tool.
64
+
65
+ That filing is #167, closed 2026-08-23: `safety/policy_enforcement.py` now
66
+ carries `_URL_USERINFO_RE`, `_XML_PASSWORD_RE` and `_ASSIGNMENT_RE`, whose
67
+ `[ \t]` alternative is there for Gradle's space form specifically. All
68
+ three shapes are redacted out of a `read_project_doc` result today, driven
69
+ on all four file types, with a credential-free document passing through
70
+ byte-identical as the control. This paragraph went on claiming the leak for
71
+ seven weeks after the leak was fixed, which is why it now names the issue
72
+ and the patterns: a security residual that reads as OPEN costs every later
73
+ reader what it cost the reader who re-measured it (batch 146).
74
+ """
75
+
76
+ from __future__ import annotations
77
+
78
+ import logging
79
+ import os
80
+ from typing import Optional
81
+
82
+ import config
83
+ from core import config_loader, workspace_trust
84
+ from json_store import write_text_atomic
85
+ from security import protected_paths
86
+
87
+ logger = logging.getLogger(__name__)
88
+
89
+ # Documentation and manifests. Deliberately NOT a general text-file list --
90
+ # see the module docstring's consequence note.
91
+ _DOC_EXTENSIONS = frozenset({".md", ".markdown", ".rst", ".txt"})
92
+ _DOC_FILENAMES = frozenset({
93
+ "pyproject.toml", "package.json", "cargo.toml", "go.mod",
94
+ "makefile", "dockerfile", "license", "licence", "changelog", "notice",
95
+ })
96
+
97
+ # Build manifests, readable at the PROJECT ROOT ONLY -- see the docstring.
98
+ # A nested copy is somebody else's source; the root copy is this project's
99
+ # own statement about what it is.
100
+ _ROOT_ONLY_FILENAMES = frozenset({
101
+ "setup.py", "setup.cfg", "gemfile", "pom.xml", "build.gradle",
102
+ })
103
+
104
+ # Denied whatever the extension says. `.venastine/` can hold mcp.json and
105
+ # settings.json; providers.json is where API keys live. check_output_policy
106
+ # would redact a leaked key from the result, but a backstop is not a reason
107
+ # to hand it the chance.
108
+ #
109
+ # `.venastine` is spelled ONCE, in security.protected_paths.PROTECTED_SEGMENTS
110
+ # -- the same segment the file tools hard-refuse and the shell's approval
111
+ # check always asks about -- and unioned in here rather than re-spelled, so
112
+ # the one fact cannot drift between its three consumers.
113
+ _DENIED_SEGMENTS = (protected_paths.PROTECTED_SEGMENTS
114
+ | {".git", "node_modules", ".venv", "venv",
115
+ "__pycache__", ".pytest_cache"})
116
+
117
+ #: And compared the way the FILESYSTEM will compare them (batch 146),
118
+ #: through the one spelling of the fold that `protected_segment` uses. This
119
+ #: set unioned the segment list in and then compared it case-sensitively,
120
+ #: so the two consumers of one fact disagreed about the only thing left to
121
+ #: disagree about. `.VENASTINE/agents/foo.md` was a readable `.md`.
122
+ _DENIED_FOLDED = protected_paths.folded_segments(_DENIED_SEGMENTS)
123
+ _DENIED_FILENAMES = frozenset({"providers.json"})
124
+
125
+ #: Re-exported so callers name one constant. The name lives in
126
+ #: core/workspace_trust because the load-bearing fact about it is that a
127
+ #: grant covers it (§44).
128
+ HUB_FILENAME = workspace_trust.PROJECT_CONTEXT_FILENAME
129
+
130
+
131
+ def _project_root() -> Optional[str]:
132
+ """The resolved project path, or None when no session has been
133
+ initialized. None is "there is no project", not "guess one" -- the same
134
+ convention get_agents() and memories/manager.py follow."""
135
+ return config_loader.get_project_path()
136
+
137
+
138
+ def doc_path(project_path: str, name: str) -> str:
139
+ """Where a document in the set lives. DERIVED FROM ITS NAME, never taken
140
+ from a path parameter (I1).
141
+
142
+ ONE JOIN SINCE §44, where this used to branch. I9 put the hub inside
143
+ `.venastine/` so that the one file every agent reads sat inside the
144
+ trust boundary. §44 keeps the boundary and moves the file: AGENTS.md is
145
+ an ordinary committed root document, and workspace_trust.content_files()
146
+ covers it explicitly. What that buys is a project you can share without
147
+ your configuration and still have it make sense to whoever cloned it --
148
+ where a hub in `.venastine/` meant sharing the repo without that
149
+ directory shipped a set of documents pointing at a file that was not
150
+ there.
151
+
152
+ The function survives the simplification because the confinement is
153
+ what it is FOR: a name from a fixed allowlist, resolved under the
154
+ project, with no path parameter anywhere in the tool that calls it.
155
+ """
156
+ return os.path.join(project_path, name)
157
+
158
+
159
+ def _resolve_in_project(root: str, user_path: str) -> Optional[str]:
160
+ """Resolve *user_path* under *root* and return it only if it really
161
+ lands inside.
162
+
163
+ realpath BEFORE the containment test, so '..' segments and a symlink
164
+ pointing outside the project are both caught -- file_ops' rule, and the
165
+ reason it is a rule: a path that merely looks contained is not.
166
+ """
167
+ resolved = os.path.realpath(os.path.join(root, user_path))
168
+ if resolved != root and not resolved.startswith(root + os.sep):
169
+ return None
170
+ return resolved
171
+
172
+
173
+ def _is_readable_doc(root: str, resolved: str) -> bool:
174
+ rel = os.path.relpath(resolved, root)
175
+ parts = rel.split(os.sep)
176
+ if any(segment.casefold() in _DENIED_FOLDED for segment in parts):
177
+ return False
178
+ name = os.path.basename(resolved).lower()
179
+ if name in _DENIED_FILENAMES or name.startswith(".env"):
180
+ return False
181
+ if name in _DOC_FILENAMES:
182
+ return True
183
+ if name in _ROOT_ONLY_FILENAMES:
184
+ # `parts` is the path relative to the project root, so a length of
185
+ # one IS "at the root". Checked against the split rather than the
186
+ # string, because os.altsep exists.
187
+ return len(parts) == 1
188
+ return os.path.splitext(name)[1] in _DOC_EXTENSIONS
189
+
190
+
191
+ def is_readable_doc(project_path: str, user_path: str) -> bool:
192
+ """This tool's own test, in public, for /init's manifest (#94).
193
+
194
+ The manifest prints "Paths below are exactly what read_project_doc
195
+ expects" over its listing, and used to decide what to list with a
196
+ parallel test of its own. Nothing kept the two in step and they
197
+ disagreed in both directions: six advertised paths the tool refused,
198
+ and four it accepted that never appeared -- including every `.txt`
199
+ document in a project, invisible because the manifest tested extensions
200
+ and this module tests these.
201
+
202
+ Exported rather than reimplemented, so the sentence is true by
203
+ construction. The read path is unchanged: `read_run` still resolves and
204
+ re-tests for itself, because a listing is not an authorization.
205
+ """
206
+ root = os.path.realpath(project_path)
207
+ resolved = _resolve_in_project(root, user_path)
208
+ return resolved is not None and _is_readable_doc(root, resolved)
209
+
210
+
211
+ # ===========================================================================
212
+ # ---- READ -----------------------------------------------------------------
213
+ # ===========================================================================
214
+
215
+ READ_TOOL_SCHEMA = {
216
+ "name": "read_project_doc",
217
+ "description": (
218
+ "Read one of this project's documentation or manifest files, by the "
219
+ "relative path given in the file listing you were shown. Markdown, "
220
+ "text and manifest files only, and only within the project "
221
+ f"directory. Returns at most {config.INIT_READ_CHARS} characters per "
222
+ "call; use offset to continue through a longer file."
223
+ ),
224
+ "input_schema": {
225
+ "type": "object",
226
+ "properties": {
227
+ "path": {
228
+ "type": "string",
229
+ "description": "Path relative to the project root, exactly "
230
+ "as it appears in the file listing.",
231
+ },
232
+ "offset": {
233
+ "type": "integer",
234
+ "description": "Characters to skip before reading. Use the "
235
+ "value suggested by a truncated response to "
236
+ "read the next part of a long file.",
237
+ },
238
+ },
239
+ "required": ["path"],
240
+ },
241
+ }
242
+
243
+
244
+ def _skip(handle, offset: int) -> None:
245
+ """Advance `offset` characters without holding them.
246
+
247
+ f.seek() on a text stream takes an opaque cookie, not a character
248
+ count, so an offset cannot simply be jumped to. Reading forward in
249
+ bounded pieces keeps the memory ceiling at one piece instead of the
250
+ whole prefix, which is the property #55 is about -- the cost is
251
+ proportional to the offset, but the MEMORY is not.
252
+ """
253
+ remaining = offset
254
+ while remaining > 0:
255
+ piece = handle.read(min(remaining, config.INIT_READ_CHARS))
256
+ if not piece:
257
+ return
258
+ remaining -= len(piece)
259
+
260
+
261
+ def read_run(params: dict) -> dict:
262
+ # params.get throughout, not params[]. tools/base.py carries the one
263
+ # copy of why, under "WHAT A CALLABLE REGISTERED BELOW MAY RAISE": a
264
+ # handler's exception IS contained, so the reason this is right is that
265
+ # an error dict the model can read beats the generic wrapper it would
266
+ # get -- not the turn-ending raise six comments in this directory used
267
+ # to claim (batch 146).
268
+ root = _project_root()
269
+ if root is None:
270
+ return {"error": "read_project_doc: no project directory has been "
271
+ "resolved, so there is nothing to read."}
272
+
273
+ user_path = (params.get("path") or "").strip()
274
+ if not user_path:
275
+ return {"error": "read_project_doc requires 'path'."}
276
+
277
+ resolved = _resolve_in_project(root, user_path)
278
+ if resolved is None:
279
+ return {"error": f"read_project_doc: {user_path!r} resolves outside "
280
+ f"the project directory."}
281
+ if not _is_readable_doc(root, resolved):
282
+ return {"error": f"read_project_doc: {user_path!r} is not a readable "
283
+ f"project document. Documentation and manifest "
284
+ f"files only."}
285
+ if not os.path.isfile(resolved):
286
+ return {"error": f"read_project_doc: no such file: {user_path}"}
287
+
288
+ offset = params.get("offset") or 0
289
+ if not isinstance(offset, int) or offset < 0:
290
+ offset = 0
291
+
292
+ # ROADMAP_v2 §31 (H7), #55. This used to be f.read() followed by
293
+ # text[offset:offset + INIT_READ_CHARS], so returning 20,000
294
+ # characters of a 30 MB document cost 60 MB of peak traced memory --
295
+ # and cost it AGAIN on every page, because each call re-read the
296
+ # whole file to slice a different part of it.
297
+ #
298
+ # A getsize guard like read_run's would be the obvious copy, and it
299
+ # is the wrong one here: refusing a large document is not what this
300
+ # tool is for -- I7 chose INIT_READ_CHARS deliberately so /init could
301
+ # page through exactly such a document. Seeking to the offset bounds
302
+ # the read AND removes the re-read, which a size check would not.
303
+ #
304
+ # One extra character is read to answer `truncated` without a second
305
+ # pass. seek() counts characters in text mode only for utf-8-sig-free
306
+ # streams, so the offset is walked rather than jumped: correctness
307
+ # over cleverness, and it still holds one chunk rather than the file.
308
+ try:
309
+ with open(resolved, encoding="utf-8", errors="replace") as f:
310
+ _skip(f, offset)
311
+ chunk = f.read(config.INIT_READ_CHARS)
312
+ more = f.read(1) != ""
313
+ except OSError as e:
314
+ logger.warning("read_project_doc failed for %s: %s", user_path, e)
315
+ return {"error": f"Could not read {user_path}: {e}"}
316
+
317
+ result = {"path": user_path, "content": chunk, "truncated": more}
318
+ if result["truncated"]:
319
+ # The continuation offset is IN the message, not merely implied by
320
+ # the numbers. A model that has to compute where to resume usually
321
+ # re-reads from zero and spends the budget twice.
322
+ #
323
+ # §31 (H7) dropped the total. It used to read `of {len(text)}`,
324
+ # and len(text) was the whole file -- the very read this section
325
+ # removed. A total could be faked from os.path.getsize, but that
326
+ # is BYTES and this count is CHARACTERS, so on any document with
327
+ # a non-ASCII character it would be a number that looks exact and
328
+ # is not. Saying less is the honest option; the part that was
329
+ # load-bearing -- where to resume -- is untouched.
330
+ end = offset + len(chunk)
331
+ result["message"] = (
332
+ f"Read characters {offset}-{end}. "
333
+ f"Call again with offset={end} to continue.")
334
+ return result
335
+
336
+
337
+ # ===========================================================================
338
+ # ---- WRITE ----------------------------------------------------------------
339
+ # ===========================================================================
340
+
341
+ WRITE_TOOL_SCHEMA = {
342
+ "name": "write_project_doc",
343
+ "description": (
344
+ "Write one of this project's standard documentation files. Takes the "
345
+ "document's NAME, not a path -- the location is derived, so this "
346
+ "cannot write anywhere else. Overwrites the named file, so the caller "
347
+ "is expected to have shown the user what changes."
348
+ ),
349
+ "input_schema": {
350
+ "type": "object",
351
+ "properties": {
352
+ "name": {
353
+ "type": "string",
354
+ "description": "One of the project's standard document names, "
355
+ "e.g. AGENTS.md or ARCHITECTURE.md.",
356
+ },
357
+ "content": {
358
+ "type": "string",
359
+ "description": "Full markdown body of the document.",
360
+ },
361
+ },
362
+ "required": ["name", "content"],
363
+ },
364
+ }
365
+
366
+
367
+ def _known_doc_names() -> frozenset:
368
+ """The allowlist IS the confinement (I1), so it is read from the one
369
+ place that defines the sets rather than restated here. Imported lazily:
370
+ tools/registry.py imports this module at import time, and project_init
371
+ imports config, which would close a cycle."""
372
+ from project_init.doc_sets import all_document_names
373
+ return all_document_names()
374
+
375
+
376
+ def approval_notice(params: dict, context) -> str:
377
+ """What the approval prompt shows.
378
+
379
+ The gate is only worth having if the prompt says what it is gating
380
+ (remember.py's rule). Here that is the destination and the size --
381
+ the content itself has already been shown as a diff by the caller,
382
+ and repeating several kilobytes of markdown inside a modal would bury
383
+ the one line that says which file is about to change.
384
+ """
385
+ root = _project_root()
386
+ name = params.get("name") or HUB_FILENAME
387
+ size = len(params.get("content") or "")
388
+ if not root:
389
+ return f"Create {name} ({size} characters)."
390
+
391
+ # RESOLVED, so the consent can never name a file the bytes will not
392
+ # land on (batch 146). `_project_root()` is already a realpath, so for
393
+ # an ordinary document this is the same string the join produced and
394
+ # the prompt is unchanged; where it differs, the difference IS the
395
+ # thing the person needs to see.
396
+ resolved = _resolve_in_project(root, name)
397
+ if resolved is None:
398
+ return (f"REFUSE {doc_path(root, name)} ({size} characters): that "
399
+ f"name resolves outside the project, so write_project_doc "
400
+ f"will not write it.")
401
+ verb = "Overwrite" if os.path.exists(resolved) else "Create"
402
+ return f"{verb} {resolved} ({size} characters)."
403
+
404
+
405
+ def write_run(params: dict) -> dict:
406
+ root = _project_root()
407
+ if root is None:
408
+ return {"error": "write_project_doc: no project directory has been "
409
+ "resolved, so there is nowhere to write."}
410
+
411
+ name = (params.get("name") or "").strip()
412
+ known = _known_doc_names()
413
+ if name not in known:
414
+ # Not coerced to the hub, and not accepted as a path. An
415
+ # unrecognised name is the one case where this tool could become a
416
+ # general writer, so it fails loudly and lists what it accepts.
417
+ return {"error": f"write_project_doc: {name!r} is not one of this "
418
+ f"project's standard documents. Expected one of: "
419
+ f"{', '.join(sorted(known))}."}
420
+
421
+ content = params.get("content")
422
+ if not isinstance(content, str) or not content.strip():
423
+ return {"error": "write_project_doc requires non-empty 'content'."}
424
+
425
+ encoded = content.encode("utf-8")
426
+ if len(encoded) > config.MAX_FILE_SIZE_BYTES:
427
+ return {"error": f"Content size ({len(encoded)} bytes) exceeds the "
428
+ f"maximum writable size "
429
+ f"({config.MAX_FILE_SIZE_BYTES} bytes)."}
430
+
431
+ # RESOLVED BEFORE WRITING, which the read path has always done and this
432
+ # one did not (batch 146). The module's invariant is that the
433
+ # destination is derived from a name "so it cannot be aimed elsewhere",
434
+ # and a document name that is a LINK aims it elsewhere: a cloned project
435
+ # carrying `ARCHITECTURE.md -> ~/.bashrc` took the bytes to the link
436
+ # target, under a consent that named the in-project path. git stores
437
+ # symlinks natively, so the layout needs no privilege to arrive.
438
+ #
439
+ # An error rather than a coercion, in the sense the unknown-name branch
440
+ # above means: a name that leaves the project is not one of this
441
+ # project's documents.
442
+ destination = doc_path(root, name)
443
+ resolved = _resolve_in_project(root, name)
444
+ if resolved is None:
445
+ logger.warning("write_project_doc refused %s: resolves outside the "
446
+ "project", destination)
447
+ return {"error": f"write_project_doc: {name!r} resolves outside the "
448
+ f"project directory, so it is not one of this "
449
+ f"project's documents."}
450
+
451
+ try:
452
+ # REPLACES THE NAME RATHER THAN WRITING THROUGH IT, which closes the
453
+ # half `realpath` cannot see: a hardlink is not a link to anything,
454
+ # so the resolution above admits one. And `newline=""`, so the bytes
455
+ # the model supplied are the bytes that land -- this tool is the one
456
+ # write path in the harness reachable with no config edit, and its
457
+ # whole purpose is to overwrite a document in place, under an
458
+ # approval that was shown a diff of the lines that changed.
459
+ write_text_atomic(resolved, content)
460
+ except OSError as e:
461
+ logger.warning("write_project_doc failed for %s: %s", resolved, e)
462
+ return {"error": f"Could not write {resolved}: {e}"}
463
+
464
+ return {"result": f"Wrote {len(content)} characters to {resolved}"}