@yahyahammad/venastine 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (143) hide show
  1. package/.env.example +14 -0
  2. package/LICENSE +201 -0
  3. package/NOTICE +14 -0
  4. package/PRIVACY.md +66 -0
  5. package/README.md +878 -0
  6. package/SECURITY.md +88 -0
  7. package/THIRD_PARTY_NOTICES.md +100 -0
  8. package/agents/builtin/compactor.md +75 -0
  9. package/agents/builtin/explore.md +77 -0
  10. package/agents/builtin/grill-me.md +27 -0
  11. package/agents/builtin/initializer.md +94 -0
  12. package/agents/builtin/pipeline-reviewer.md +100 -0
  13. package/agents/builtin/plan.md +88 -0
  14. package/agents/builtin/review.md +74 -0
  15. package/agents/manager.py +195 -0
  16. package/agents/subagent_tool.py +215 -0
  17. package/agents/tui_commands.py +136 -0
  18. package/bin/venastine.mjs +382 -0
  19. package/config.py +1198 -0
  20. package/core/__init__.py +0 -0
  21. package/core/approval.py +115 -0
  22. package/core/client.py +1548 -0
  23. package/core/compaction.py +959 -0
  24. package/core/config_loader.py +1563 -0
  25. package/core/events.py +61 -0
  26. package/core/interaction.py +328 -0
  27. package/core/loop.py +1353 -0
  28. package/core/memory.py +370 -0
  29. package/core/model_windows.py +175 -0
  30. package/core/pipeline_models.py +176 -0
  31. package/core/reasoning/__init__.py +0 -0
  32. package/core/reasoning/authorization.py +130 -0
  33. package/core/reasoning/base.py +219 -0
  34. package/core/reasoning/confidence_scoring.py +468 -0
  35. package/core/reasoning/events.py +149 -0
  36. package/core/reasoning/json_retry.py +219 -0
  37. package/core/reasoning/orchestrator.py +1382 -0
  38. package/core/reasoning/output_writer.py +286 -0
  39. package/core/reasoning/payload_validation.py +398 -0
  40. package/core/reasoning/pipeline_storage.py +361 -0
  41. package/core/reasoning/review.py +615 -0
  42. package/core/reasoning/scholar.py +434 -0
  43. package/core/reasoning/source_corpus.py +327 -0
  44. package/core/reasoning/source_scoring.py +855 -0
  45. package/core/replay.py +167 -0
  46. package/core/session.py +153 -0
  47. package/core/workspace_trust.py +207 -0
  48. package/credentials.py +180 -0
  49. package/database.py +252 -0
  50. package/env_secrets.py +77 -0
  51. package/json_store.py +123 -0
  52. package/logging_setup.py +185 -0
  53. package/main.py +1959 -0
  54. package/mcp_client/__init__.py +15 -0
  55. package/mcp_client/client.py +499 -0
  56. package/mcp_client/config.py +379 -0
  57. package/mcp_client/registration.py +182 -0
  58. package/memories/manager.py +132 -0
  59. package/memories/tui_commands.py +232 -0
  60. package/package.json +73 -0
  61. package/project_init/config_files.py +278 -0
  62. package/project_init/doc_sets.py +330 -0
  63. package/project_init/generator.py +564 -0
  64. package/project_init/manifest.py +406 -0
  65. package/project_init/tui_commands.py +144 -0
  66. package/prompts/__init__.py +0 -0
  67. package/prompts/annotate.md +14 -0
  68. package/prompts/assumption_audit.md +27 -0
  69. package/prompts/claim_extraction.md +34 -0
  70. package/prompts/completeness.md +18 -0
  71. package/prompts/confidence_tiers.md +23 -0
  72. package/prompts/critic_pass.md +24 -0
  73. package/prompts/final_synthesis.md +13 -0
  74. package/prompts/initial_generation.md +14 -0
  75. package/prompts/preliminary_plan.md +23 -0
  76. package/prompts/revalidate.md +25 -0
  77. package/prompts/revise.md +15 -0
  78. package/prompts/source_grounding.md +66 -0
  79. package/prompts/system_prompts.py +262 -0
  80. package/prompts/universal_system_prompt +7 -0
  81. package/prompts/untrusted_content +1 -0
  82. package/providers.json.example +92 -0
  83. package/pyproject.toml +100 -0
  84. package/requirements.txt +72 -0
  85. package/safety/__init__.py +0 -0
  86. package/safety/policy_enforcement.py +682 -0
  87. package/security/__init__.py +0 -0
  88. package/security/capability.py +177 -0
  89. package/security/permissions.py +190 -0
  90. package/security/posture.py +302 -0
  91. package/security/protected_paths.py +309 -0
  92. package/security/sandbox.py +985 -0
  93. package/skills/builtin/crypto/cryptography-verification.md +66 -0
  94. package/skills/builtin/math/formal-specification.md +67 -0
  95. package/skills/builtin/math/numerical-methods.md +66 -0
  96. package/skills/builtin/math/proof-writing.md +61 -0
  97. package/skills/builtin/research/experiment-design.md +62 -0
  98. package/skills/builtin/research/literature-review.md +65 -0
  99. package/skills/builtin/research/reproducibility.md +55 -0
  100. package/skills/builtin/research/source-evaluation.md +70 -0
  101. package/skills/builtin/research/statistical-inference.md +63 -0
  102. package/skills/builtin/research/technical-writing.md +59 -0
  103. package/skills/builtin/security/cybersecurity-research.md +63 -0
  104. package/skills/builtin/software/code-review.md +61 -0
  105. package/skills/builtin/software/debugging.md +61 -0
  106. package/skills/builtin/software/test-design.md +67 -0
  107. package/skills/manager.py +138 -0
  108. package/skills/tui_commands.py +111 -0
  109. package/storage.py +1005 -0
  110. package/tools/base.py +305 -0
  111. package/tools/builtin/__init__.py +0 -0
  112. package/tools/builtin/_math_common.py +377 -0
  113. package/tools/builtin/_net_common.py +61 -0
  114. package/tools/builtin/arxiv.py +223 -0
  115. package/tools/builtin/ask_user.py +213 -0
  116. package/tools/builtin/discrete_math.py +134 -0
  117. package/tools/builtin/fetch_url.py +153 -0
  118. package/tools/builtin/file_ops.py +412 -0
  119. package/tools/builtin/geometry.py +148 -0
  120. package/tools/builtin/get_time.py +20 -0
  121. package/tools/builtin/linear_algebra.py +155 -0
  122. package/tools/builtin/load_skill.py +66 -0
  123. package/tools/builtin/logic.py +96 -0
  124. package/tools/builtin/pin.py +193 -0
  125. package/tools/builtin/probability_stats.py +228 -0
  126. package/tools/builtin/project_docs.py +405 -0
  127. package/tools/builtin/remember.py +158 -0
  128. package/tools/builtin/shell.py +461 -0
  129. package/tools/builtin/symbolic_math.py +119 -0
  130. package/tools/builtin/todo.py +147 -0
  131. package/tools/builtin/web_search.py +151 -0
  132. package/tools/context.py +136 -0
  133. package/tools/isolation.py +314 -0
  134. package/tools/registry.py +897 -0
  135. package/tui/app.py +3423 -0
  136. package/tui/app.tcss +458 -0
  137. package/tui/commands.py +61 -0
  138. package/tui/diffs.py +265 -0
  139. package/tui/preferences.py +182 -0
  140. package/tui/ravens.py +146 -0
  141. package/tui/screens.py +943 -0
  142. package/tui/themes.py +366 -0
  143. package/tui/widgets.py +1239 -0
@@ -0,0 +1,405 @@
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}"}
@@ -0,0 +1,158 @@
1
+ """
2
+ tools/builtin/remember.py
3
+
4
+ ROADMAP_v2 §21b: write a durable fact that outlives this conversation.
5
+
6
+ APPROVAL-GATED (D26), and the asymmetry with `pin` is the decision rather
7
+ than an oversight. They differ on the axis that already separates `read`
8
+ from `write`: a pin is thread-scoped, reversible, and takes effect inside a
9
+ conversation the user is watching, so a wrong one costs some context budget
10
+ and nothing else. A memory outlives the thread and silently shapes
11
+ conversations the user has not started yet -- persistent, and invisible at
12
+ the moment it actually matters.
13
+
14
+ Two consequences §21 names rather than leaves to be discovered:
15
+
16
+ * It cannot fire on a headless path. With no permission channel and no
17
+ ApprovalProvider, §13 does not merely deny an approval-gated tool -- it
18
+ stops advertising it. Every research pass is such a path, and that is
19
+ the right outcome: a ten-pass pipeline reading fetched web pages is
20
+ exactly where an injected "remember this" would be most dangerous and
21
+ least noticed. §21b's CLI provider (M16) is what makes the tool
22
+ reachable in the default shell, and nothing makes it reachable in the
23
+ pipeline -- its ToolSpec declares grant_policy=GRANT_NEVER (M17,
24
+ carried by R13), which also keeps it out of §18's subagent sign-off.
25
+ * If the prompt turns out to fire too often, the answer is to make the
26
+ write VISIBLE AND UNDOABLE, not to drop the gate. An approval prompt
27
+ dismissed reflexively launders consent. `/forget` and `/memories` ship
28
+ with this section for the separate reason that a memory can go stale.
29
+
30
+ SCOPE DEFAULTS TO "project" (D25). The two error directions are not
31
+ symmetric: a memory that should have been project-scoped but landed
32
+ globally contaminates every later conversation with a stale fact about a
33
+ codebase you may not be working in, and presents as the model simply being
34
+ confident. One that should have been global merely fails to appear
35
+ somewhere useful, and the fix is to say it again.
36
+ """
37
+
38
+ import config
39
+
40
+ TOOL_SCHEMA = {
41
+ "name": "remember",
42
+ "description": (
43
+ "Save a fact so it is still available in future conversations. Use "
44
+ "this for things that stay true and would be tedious to re-establish "
45
+ "-- a project's conventions, a decision and its reason, a constraint "
46
+ "the user stated once. Do NOT use it for anything specific to the "
47
+ "task at hand, which the current conversation already carries. "
48
+ "Scope defaults to this project. Use scope='global' only for durable "
49
+ "preferences about how the user wants to work ('prefers concise "
50
+ "answers', 'wants tests before implementation') -- facts about a "
51
+ "particular codebase are not global. The user is asked to approve "
52
+ "every memory before it is written."
53
+ ),
54
+ "input_schema": {
55
+ "type": "object",
56
+ "properties": {
57
+ "content": {
58
+ "type": "string",
59
+ "description": "The fact, stated so it still makes sense "
60
+ "months later with no surrounding "
61
+ "conversation. Prefer one sentence.",
62
+ },
63
+ "scope": {
64
+ "type": "string",
65
+ "enum": ["project", "global"],
66
+ "description": "'project' (default) for facts about this "
67
+ "codebase; 'global' for how the user likes "
68
+ "to work.",
69
+ },
70
+ "category": {
71
+ "type": "string",
72
+ "description": "Optional free-text grouping, e.g. 'tooling' "
73
+ "or 'conventions'.",
74
+ },
75
+ },
76
+ "required": ["content"],
77
+ },
78
+ }
79
+
80
+ _SCOPES = ("project", "global")
81
+
82
+
83
+ def approval_notice(params: dict, context) -> str:
84
+ """What the approval prompt shows before the write.
85
+
86
+ THE GATE IS ONLY WORTH HAVING IF THE PROMPT SHOWS WHAT IT IS GATING.
87
+ "remember wants to run" tells the user nothing they can act on; the
88
+ content, verbatim, and how far it will reach is the whole decision.
89
+ This is also why §21b adds no separate "— remembered —" marker: the
90
+ user has already seen the exact text, BEFORE it was written, which is
91
+ strictly better than a confirmation afterwards.
92
+ """
93
+ from memories.manager import manager
94
+
95
+ scope = params.get("scope", "project")
96
+ where = ("every future conversation, in any project"
97
+ if scope == "global"
98
+ else f"future conversations in {manager.scope_path() or 'this project'}")
99
+ return f"Will remember, for {where}:\n {params.get('content', '')!r}"
100
+
101
+
102
+ def run(params: dict, memory=None) -> dict:
103
+ # params.get, not params[]: no provider validates tool inputs against
104
+ # the schema, and a bare KeyError escapes the loop's ToolCallDenied
105
+ # handler and aborts the whole turn. Same reasoning as load_skill's.
106
+ from memories.manager import manager
107
+ from storage import save_memory
108
+
109
+ content = (params.get("content") or "").strip()
110
+ if not content:
111
+ return {"error": "remember requires 'content' -- the fact to save."}
112
+
113
+ scope = params.get("scope", "project")
114
+ if scope not in _SCOPES:
115
+ # Not silently coerced to the default. A model asking for "global"
116
+ # and getting a project row would believe a preference follows the
117
+ # user everywhere when it does not.
118
+ return {"error": f"remember: scope must be one of "
119
+ f"{', '.join(_SCOPES)}, got {scope!r}."}
120
+
121
+ project_path = manager.scope_path()
122
+ if scope == "project" and project_path is None:
123
+ # No project has been resolved, so a "project" memory has nothing
124
+ # to be keyed to and would be invisible to every later session
125
+ # (list_memories matches on the path). Saying so beats writing a
126
+ # row that can never be read.
127
+ return {"error": "remember: no project directory has been resolved, "
128
+ "so a project-scoped memory could never be found "
129
+ "again. Use scope='global' if this should follow "
130
+ "the user everywhere."}
131
+ if memory is None:
132
+ # Reachable only if dispatched outside a run. A memory with no
133
+ # source thread loses the one piece of provenance it has.
134
+ return {"error": "remember is only available inside a conversation."}
135
+
136
+ save_memory(
137
+ content=content,
138
+ source_thread_id=memory.thread_id,
139
+ scope=scope,
140
+ category=params.get("category"),
141
+ project_path=project_path,
142
+ )
143
+ where = "everywhere" if scope == "global" else "this project"
144
+ return {"result": f"Remembered ({where}): {content}"}
145
+
146
+
147
+ def available() -> bool:
148
+ """ToolSpec.available_check.
149
+
150
+ Hidden when nothing would ever read a memory back. Writing one the
151
+ harness will not inject is the fetch_url defect shape (D24): a schema
152
+ the model can see, choose, and never get value from.
153
+
154
+ In practice this is only False before config_loader.initialize(), which
155
+ is why it is cheap -- but it also keeps the tool honest if a future
156
+ configuration turns injection off wholesale.
157
+ """
158
+ return config.MAX_INJECTED_MEMORIES > 0