@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.
- package/.env.example +14 -0
- package/LICENSE +201 -0
- package/NOTICE +14 -0
- package/PRIVACY.md +66 -0
- package/README.md +878 -0
- package/SECURITY.md +88 -0
- package/THIRD_PARTY_NOTICES.md +100 -0
- package/agents/builtin/compactor.md +75 -0
- package/agents/builtin/explore.md +77 -0
- package/agents/builtin/grill-me.md +27 -0
- package/agents/builtin/initializer.md +94 -0
- package/agents/builtin/pipeline-reviewer.md +100 -0
- package/agents/builtin/plan.md +88 -0
- package/agents/builtin/review.md +74 -0
- package/agents/manager.py +195 -0
- package/agents/subagent_tool.py +215 -0
- package/agents/tui_commands.py +136 -0
- package/bin/venastine.mjs +382 -0
- package/config.py +1198 -0
- package/core/__init__.py +0 -0
- package/core/approval.py +115 -0
- package/core/client.py +1548 -0
- package/core/compaction.py +959 -0
- package/core/config_loader.py +1563 -0
- package/core/events.py +61 -0
- package/core/interaction.py +328 -0
- package/core/loop.py +1353 -0
- package/core/memory.py +370 -0
- package/core/model_windows.py +175 -0
- package/core/pipeline_models.py +176 -0
- package/core/reasoning/__init__.py +0 -0
- package/core/reasoning/authorization.py +130 -0
- package/core/reasoning/base.py +219 -0
- package/core/reasoning/confidence_scoring.py +468 -0
- package/core/reasoning/events.py +149 -0
- package/core/reasoning/json_retry.py +219 -0
- package/core/reasoning/orchestrator.py +1382 -0
- package/core/reasoning/output_writer.py +286 -0
- package/core/reasoning/payload_validation.py +398 -0
- package/core/reasoning/pipeline_storage.py +361 -0
- package/core/reasoning/review.py +615 -0
- package/core/reasoning/scholar.py +434 -0
- package/core/reasoning/source_corpus.py +327 -0
- package/core/reasoning/source_scoring.py +855 -0
- package/core/replay.py +167 -0
- package/core/session.py +153 -0
- package/core/workspace_trust.py +207 -0
- package/credentials.py +180 -0
- package/database.py +252 -0
- package/env_secrets.py +77 -0
- package/json_store.py +123 -0
- package/logging_setup.py +185 -0
- package/main.py +1959 -0
- package/mcp_client/__init__.py +15 -0
- package/mcp_client/client.py +499 -0
- package/mcp_client/config.py +379 -0
- package/mcp_client/registration.py +182 -0
- package/memories/manager.py +132 -0
- package/memories/tui_commands.py +232 -0
- package/package.json +73 -0
- package/project_init/config_files.py +278 -0
- package/project_init/doc_sets.py +330 -0
- package/project_init/generator.py +564 -0
- package/project_init/manifest.py +406 -0
- package/project_init/tui_commands.py +144 -0
- package/prompts/__init__.py +0 -0
- package/prompts/annotate.md +14 -0
- package/prompts/assumption_audit.md +27 -0
- package/prompts/claim_extraction.md +34 -0
- package/prompts/completeness.md +18 -0
- package/prompts/confidence_tiers.md +23 -0
- package/prompts/critic_pass.md +24 -0
- package/prompts/final_synthesis.md +13 -0
- package/prompts/initial_generation.md +14 -0
- package/prompts/preliminary_plan.md +23 -0
- package/prompts/revalidate.md +25 -0
- package/prompts/revise.md +15 -0
- package/prompts/source_grounding.md +66 -0
- package/prompts/system_prompts.py +262 -0
- package/prompts/universal_system_prompt +7 -0
- package/prompts/untrusted_content +1 -0
- package/providers.json.example +92 -0
- package/pyproject.toml +100 -0
- package/requirements.txt +72 -0
- package/safety/__init__.py +0 -0
- package/safety/policy_enforcement.py +682 -0
- package/security/__init__.py +0 -0
- package/security/capability.py +177 -0
- package/security/permissions.py +190 -0
- package/security/posture.py +302 -0
- package/security/protected_paths.py +309 -0
- package/security/sandbox.py +985 -0
- package/skills/builtin/crypto/cryptography-verification.md +66 -0
- package/skills/builtin/math/formal-specification.md +67 -0
- package/skills/builtin/math/numerical-methods.md +66 -0
- package/skills/builtin/math/proof-writing.md +61 -0
- package/skills/builtin/research/experiment-design.md +62 -0
- package/skills/builtin/research/literature-review.md +65 -0
- package/skills/builtin/research/reproducibility.md +55 -0
- package/skills/builtin/research/source-evaluation.md +70 -0
- package/skills/builtin/research/statistical-inference.md +63 -0
- package/skills/builtin/research/technical-writing.md +59 -0
- package/skills/builtin/security/cybersecurity-research.md +63 -0
- package/skills/builtin/software/code-review.md +61 -0
- package/skills/builtin/software/debugging.md +61 -0
- package/skills/builtin/software/test-design.md +67 -0
- package/skills/manager.py +138 -0
- package/skills/tui_commands.py +111 -0
- package/storage.py +1005 -0
- package/tools/base.py +305 -0
- package/tools/builtin/__init__.py +0 -0
- package/tools/builtin/_math_common.py +377 -0
- package/tools/builtin/_net_common.py +61 -0
- package/tools/builtin/arxiv.py +223 -0
- package/tools/builtin/ask_user.py +213 -0
- package/tools/builtin/discrete_math.py +134 -0
- package/tools/builtin/fetch_url.py +153 -0
- package/tools/builtin/file_ops.py +412 -0
- package/tools/builtin/geometry.py +148 -0
- package/tools/builtin/get_time.py +20 -0
- package/tools/builtin/linear_algebra.py +155 -0
- package/tools/builtin/load_skill.py +66 -0
- package/tools/builtin/logic.py +96 -0
- package/tools/builtin/pin.py +193 -0
- package/tools/builtin/probability_stats.py +228 -0
- package/tools/builtin/project_docs.py +405 -0
- package/tools/builtin/remember.py +158 -0
- package/tools/builtin/shell.py +461 -0
- package/tools/builtin/symbolic_math.py +119 -0
- package/tools/builtin/todo.py +147 -0
- package/tools/builtin/web_search.py +151 -0
- package/tools/context.py +136 -0
- package/tools/isolation.py +314 -0
- package/tools/registry.py +897 -0
- package/tui/app.py +3423 -0
- package/tui/app.tcss +458 -0
- package/tui/commands.py +61 -0
- package/tui/diffs.py +265 -0
- package/tui/preferences.py +182 -0
- package/tui/ravens.py +146 -0
- package/tui/screens.py +943 -0
- package/tui/themes.py +366 -0
- 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
|