@yahyahammad/venastine 0.3.8 → 0.3.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.env.example +19 -19
- package/CONFIG_ARCHITECTURE.md +2139 -2002
- package/LICENSE +201 -201
- package/README.md +1043 -1034
- package/agents/builtin/compactor.md +75 -75
- package/agents/builtin/explore.md +77 -77
- package/agents/builtin/pipeline-reviewer.md +100 -100
- package/agents/builtin/plan.md +106 -106
- package/agents/builtin/review.md +74 -74
- package/agents/manager.py +261 -261
- package/agents/subagent_tool.py +472 -472
- package/agents/tui_commands.py +238 -146
- package/bin/venastine.mjs +584 -528
- package/bin/venastine.py +73 -71
- package/cli_commands.py +848 -835
- package/config.yaml +64 -0
- package/config_edit.py +1301 -1301
- package/config_schema.py +987 -966
- package/config_update.py +749 -749
- package/core/agent_activity.py +256 -256
- package/core/ansi.py +452 -452
- package/core/approval.py +137 -137
- package/core/call_view.py +364 -364
- package/core/cancel.py +121 -121
- package/core/chatgpt_auth.py +747 -747
- package/core/claims_view.py +107 -107
- package/core/client.py +2756 -2715
- package/core/commands.py +464 -454
- package/core/compaction.py +1735 -1735
- package/core/config_loader.py +1982 -1982
- package/core/connect.py +686 -686
- package/core/events.py +123 -123
- package/core/file_mentions.py +280 -280
- package/core/interaction.py +411 -411
- package/core/loop.py +2566 -2566
- package/core/memory.py +482 -482
- package/core/pipeline_models.py +190 -190
- package/core/provider_errors.py +274 -234
- package/core/reasoning/authorization.py +130 -130
- package/core/reasoning/base.py +219 -219
- package/core/reasoning/confidence_scoring.py +484 -484
- package/core/reasoning/events.py +149 -149
- package/core/reasoning/orchestrator.py +1561 -1561
- package/core/reasoning/output_writer.py +345 -345
- package/core/reasoning/payload_validation.py +524 -524
- package/core/reasoning/pipeline_storage.py +427 -427
- package/core/reasoning/scholar.py +467 -458
- package/core/reasoning/source_corpus.py +433 -433
- package/core/reasoning/source_scoring.py +855 -855
- package/core/replay.py +315 -315
- package/core/shell_sessions.py +1553 -1553
- package/credentials.py +307 -307
- package/database.py +333 -333
- package/docs/PRIVACY.md +78 -78
- package/docs/SECURITY.md +114 -108
- package/docs/THIRD_PARTY_NOTICES.md +148 -148
- package/env_secrets.py +118 -118
- package/json_store.py +343 -343
- package/logging_setup.py +295 -295
- package/main.py +3433 -3433
- package/mcp_client/client.py +780 -733
- package/mcp_client/config.py +484 -484
- package/mcp_client/registration.py +343 -343
- package/memories/manager.py +147 -147
- package/memories/tui_commands.py +319 -239
- package/package.json +303 -303
- package/project_init/config_files.py +282 -282
- package/project_init/generator.py +728 -728
- package/project_init/manifest.py +418 -418
- package/project_init/tui_commands.py +147 -147
- package/prompts/critic_pass.md +24 -24
- package/prompts/revalidate.md +25 -25
- package/prompts/revise.md +17 -17
- package/prompts/source_grounding.md +66 -66
- package/prompts/system_prompts.py +316 -316
- package/providers.json.example +94 -94
- package/pyproject.toml +149 -149
- package/requirements.txt +314 -295
- package/safety/policy_enforcement.py +1082 -1082
- package/security/askpass.py +419 -419
- package/security/capability.py +207 -207
- package/security/confine.py +484 -484
- package/security/hosted.py +182 -182
- package/security/permissions.py +237 -237
- package/security/protected_paths.py +501 -501
- package/security/sandbox.py +4108 -4108
- package/skills/builtin/math/formal-specification.md +67 -67
- package/skills/builtin/math/numerical-methods.md +66 -66
- package/skills/builtin/research/experiment-design.md +62 -62
- package/skills/builtin/research/reproducibility.md +55 -55
- package/skills/builtin/research/source-evaluation.md +70 -70
- package/skills/builtin/research/statistical-inference.md +63 -63
- package/skills/builtin/research/technical-writing.md +59 -59
- package/skills/builtin/software/code-review.md +61 -61
- package/skills/builtin/software/debugging.md +61 -61
- package/skills/builtin/software/test-design.md +67 -67
- package/skills/tui_commands.py +110 -110
- package/storage.py +1338 -1338
- package/tools/base.py +465 -465
- package/tools/builtin/_math_common.py +667 -667
- package/tools/builtin/_net_common.py +1145 -267
- package/tools/builtin/_page_text.py +490 -0
- package/tools/builtin/_pdf_text.py +113 -0
- package/tools/builtin/arxiv.py +685 -681
- package/tools/builtin/fetch_url.py +639 -371
- package/tools/builtin/file_ops.py +720 -720
- package/tools/builtin/geometry.py +184 -184
- package/tools/builtin/load_skill.py +76 -76
- package/tools/builtin/pin.py +227 -227
- package/tools/builtin/probability_stats.py +224 -224
- package/tools/builtin/project_docs.py +464 -464
- package/tools/builtin/remember.py +175 -175
- package/tools/builtin/shell.py +980 -980
- package/tools/builtin/todo.py +149 -149
- package/tools/builtin/web_search.py +402 -328
- package/tools/context.py +159 -159
- package/tools/isolation.py +387 -387
- package/tools/registry.py +1252 -1242
- package/tui/app.py +8372 -8307
- package/tui/app.tcss +754 -739
- package/tui/commands.py +26 -26
- package/tui/diffs.py +286 -286
- package/tui/history.py +128 -128
- package/tui/hosted_driver.py +102 -102
- package/tui/markdown.py +1329 -1329
- package/tui/meters.py +364 -364
- package/tui/ravens.py +146 -146
- package/tui/screens.py +1255 -1197
- package/tui/themes.py +599 -599
- package/tui/widgets.py +3861 -3796
|
@@ -1,464 +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 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}"}
|
|
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}"}
|