@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,720 +1,720 @@
|
|
|
1
|
-
"""
|
|
2
|
-
tools/builtin/file_ops.py
|
|
3
|
-
|
|
4
|
-
Three file-operation tools — read, write, edit — confined to a
|
|
5
|
-
configurable workspace directory. Registered as three separate tools
|
|
6
|
-
to match config.ToolPermissions' three separate boolean fields (read /
|
|
7
|
-
write / edit), so review/audit agents can be given read access without
|
|
8
|
-
write or edit.
|
|
9
|
-
|
|
10
|
-
A fourth, view_image (ROADMAP_v3 §81), reads an image and attaches it
|
|
11
|
-
to its own result rather than returning text. It follows read's path
|
|
12
|
-
rules exactly, with its own permission row so it can be enabled apart
|
|
13
|
-
from read. See view_image_run for where the bytes go.
|
|
14
|
-
|
|
15
|
-
SECURITY MODEL (ROADMAP §6, deviated per user decision):
|
|
16
|
-
Paths within WORKSPACE_DIR are auto-approved (unless the matching
|
|
17
|
-
ToolApprovals boolean is True, which forces approval even inside the
|
|
18
|
-
workspace). Paths outside WORKSPACE_DIR always require user approval
|
|
19
|
-
— they are NOT hard-rejected, so an operator can grant one-off access
|
|
20
|
-
to files outside the workspace. Symlinks and '..' segments are always
|
|
21
|
-
resolved via os.path.realpath before any check, so a path that looks
|
|
22
|
-
inside the workspace but resolves outside it is treated as outside.
|
|
23
|
-
|
|
24
|
-
PROTECTED SEGMENTS (security/protected_paths.py) are the one hard
|
|
25
|
-
deny, and the exception to both rules above: any path -- inside or
|
|
26
|
-
outside the workspace -- that resolves into `.venastine/` is refused
|
|
27
|
-
by the refusal_check before approval and re-tested in all three
|
|
28
|
-
handlers, whatever the ToolApprovals booleans say. Case-folded since
|
|
29
|
-
batch 146, because `realpath` only canonicalises a spelling for a
|
|
30
|
-
path that already EXISTS -- which is not the state a `write` is in.
|
|
31
|
-
|
|
32
|
-
WHAT THE DENY RESTS ON, AND THE ONE SHAPE IT CANNOT SEE. It rests on
|
|
33
|
-
`realpath`, so a symlink and a junction into `.venastine/` both arrive
|
|
34
|
-
as the real thing. A HARDLINK does not: it is not a link to anything,
|
|
35
|
-
it is the file, and `realpath` returns the path it was given. Batch 146
|
|
36
|
-
measured a `write` through a hardlinked name putting an mcpServers
|
|
37
|
-
object into a protected `settings.json` whose direct spelling is
|
|
38
|
-
refused. The write half is closed -- `json_store.write_text_atomic`
|
|
39
|
-
replaces the name rather than writing through it, so the link breaks
|
|
40
|
-
and the other name keeps its bytes -- and the READ half is not. A
|
|
41
|
-
`read` through a hardlink into `.venastine/` still serves the file,
|
|
42
|
-
and nothing available here can tell: enumerating a file's other names
|
|
43
|
-
is per-platform, and refusing every multiply-linked file would deny
|
|
44
|
-
ordinary ones. Filed in docs/TECHNICAL_DEBT.md rather than left to be
|
|
45
|
-
found, with the same answer the sandbox reached for a link it cannot
|
|
46
|
-
resolve.
|
|
47
|
-
|
|
48
|
-
BYTES, NOT TEXT, ON THE WRITE PATHS (batch 146):
|
|
49
|
-
All three used to open with mode "w" and no `newline=`, so Python
|
|
50
|
-
translated every "\n" to os.linesep. On Windows `write` could not
|
|
51
|
-
reproduce a file it had just read, and `edit` replacing one span of an
|
|
52
|
-
LF file rewrote every line ending in it -- 2,910 of them in this
|
|
53
|
-
repository's own AGENTS.md. `edit` now reads with `newline=""` as well,
|
|
54
|
-
so the match runs against the file's real bytes, and retries an
|
|
55
|
-
LF-spelled `old_text` translated when the file is CRLF: the model
|
|
56
|
-
cannot see a file's endings through `read` (which joins with "\n"
|
|
57
|
-
whatever it found), so a span it spells from what it was shown has to
|
|
58
|
-
be able to match.
|
|
59
|
-
|
|
60
|
-
READ TOOL PAGINATION (deviated from ROADMAP §6):
|
|
61
|
-
The read tool accepts offset (lines to skip) and count (lines to
|
|
62
|
-
read). count is clamped to config.MAX_READ_LINES with a note in the
|
|
63
|
-
response (not a hard error). Output is also truncated at
|
|
64
|
-
config.MAX_READ_CHARS with a note. Files larger than
|
|
65
|
-
config.MAX_FILE_SIZE_BYTES are rejected before opening to prevent
|
|
66
|
-
memory exhaustion (especially on the markitdown path, which loads
|
|
67
|
-
the whole file).
|
|
68
|
-
|
|
69
|
-
RICH FORMAT SUPPORT (deviated from ROADMAP §6):
|
|
70
|
-
For binary/rich extensions (.pdf, .docx, .pptx, etc.) the read tool
|
|
71
|
-
uses markitdown to convert to markdown before applying line/char
|
|
72
|
-
truncation. Plain-text extensions use open() directly.
|
|
73
|
-
"""
|
|
74
|
-
|
|
75
|
-
from __future__ import annotations
|
|
76
|
-
|
|
77
|
-
import base64
|
|
78
|
-
import logging
|
|
79
|
-
import os
|
|
80
|
-
from typing import Optional
|
|
81
|
-
|
|
82
|
-
from pydantic import BaseModel, Field
|
|
83
|
-
|
|
84
|
-
import config
|
|
85
|
-
from json_store import write_text_atomic
|
|
86
|
-
from security.protected_paths import hardlinked_segment, protected_segment
|
|
87
|
-
from tools.base import invalid_params
|
|
88
|
-
|
|
89
|
-
logger = logging.getLogger(__name__)
|
|
90
|
-
|
|
91
|
-
# ---------------------------------------------------------------------------
|
|
92
|
-
# ---- Path helpers ---------------------------------------------------------
|
|
93
|
-
# ---------------------------------------------------------------------------
|
|
94
|
-
|
|
95
|
-
WORKSPACE_ROOT = os.path.realpath(config.WORKSPACE_DIR)
|
|
96
|
-
|
|
97
|
-
_RICH_EXTENSIONS = frozenset({
|
|
98
|
-
".pdf", ".docx", ".pptx", ".xlsx", ".xls",
|
|
99
|
-
".html", ".htm", ".epub", ".ipynb",
|
|
100
|
-
})
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
def resolve_path(user_path: str) -> str:
|
|
104
|
-
"""Resolve *user_path* relative to WORKSPACE_ROOT via realpath.
|
|
105
|
-
|
|
106
|
-
Handles ``..`` segments and symlinks. Does NOT reject paths that
|
|
107
|
-
land outside the workspace — that decision belongs to the approval
|
|
108
|
-
layer (``_file_approval_check``), not to path resolution.
|
|
109
|
-
|
|
110
|
-
PUBLIC since batch 41 (X4). The TUI has to read the file a `write`
|
|
111
|
-
or an `edit` is about to change in order to show the diff, and it
|
|
112
|
-
must land on the same file the tool will — a second
|
|
113
|
-
``os.path.join(WORKSPACE_ROOT, ...)`` at the call site is this
|
|
114
|
-
project's canonical producer/consumer bug, and here it would mean a
|
|
115
|
-
diff of one file beside an edit to another.
|
|
116
|
-
"""
|
|
117
|
-
return os.path.realpath(os.path.join(WORKSPACE_ROOT, user_path))
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
def _is_within_workspace(user_path: str) -> bool:
|
|
121
|
-
resolved = resolve_path(user_path)
|
|
122
|
-
return resolved == WORKSPACE_ROOT or resolved.startswith(WORKSPACE_ROOT + os.sep)
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
def _file_approval_check(tool_name: str, params: dict) -> bool:
|
|
126
|
-
"""Path-dependent approval policy for read / write / edit.
|
|
127
|
-
|
|
128
|
-
Outside workspace → always True (ask user).
|
|
129
|
-
Within workspace → defer to the matching ToolApprovals boolean
|
|
130
|
-
(False = auto-approved, True = still ask).
|
|
131
|
-
|
|
132
|
-
TOTAL over any JSON object, which it was not until batch 146: a
|
|
133
|
-
`{"path": null}` is well-formed, so `params.get("path", "")` returns
|
|
134
|
-
None rather than the default -- the key IS present -- and
|
|
135
|
-
`os.path.join(WORKSPACE_ROOT, None)` raised a TypeError out of a gate
|
|
136
|
-
that runs ABOVE dispatch()'s containment. tools/base.py carries the one
|
|
137
|
-
copy of what that costs; shell.py's gate has said "total, like
|
|
138
|
-
everything else the gate calls" for a long time, and these two were the
|
|
139
|
-
exception.
|
|
140
|
-
|
|
141
|
-
True for a path it cannot read, because ASKING is the fail-closed
|
|
142
|
-
direction for a predicate that can only tighten. In practice the
|
|
143
|
-
refusal_check answers first and the call never arrives here.
|
|
144
|
-
"""
|
|
145
|
-
if not isinstance(params, dict):
|
|
146
|
-
return True
|
|
147
|
-
path = params.get("path", "")
|
|
148
|
-
if not isinstance(path, str):
|
|
149
|
-
return True
|
|
150
|
-
if not _is_within_workspace(path):
|
|
151
|
-
return True
|
|
152
|
-
approvals = config.ToolApprovals()
|
|
153
|
-
return getattr(approvals, tool_name, False)
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
# ===========================================================================
|
|
157
|
-
# ---- Protected segments (.venastine/) -------------------------------------
|
|
158
|
-
# ===========================================================================
|
|
159
|
-
|
|
160
|
-
def _protected_path_error(user_path: str) -> Optional[str]:
|
|
161
|
-
"""Why *user_path* must be refused outright, or None.
|
|
162
|
-
|
|
163
|
-
Shared by the refusal_check and all three handlers so the decision
|
|
164
|
-
and its wording cannot drift between the pre-approval answer and the
|
|
165
|
-
backstop. resolve_path BEFORE the segment test, so `..` travel and a
|
|
166
|
-
symlink are caught the same way _is_within_workspace catches them.
|
|
167
|
-
|
|
168
|
-
Unconditional on workspace membership, like project_docs'
|
|
169
|
-
`_is_readable_doc`: the segment is denied wherever the path lands,
|
|
170
|
-
because `.venastine/` holds mcp.json -- which names commands the
|
|
171
|
-
harness spawns at startup -- and skills/ and agents/ content that is
|
|
172
|
-
injected into system prompts. Workspace membership is the wrong
|
|
173
|
-
question here: with AGENT_WORKSPACE pointed at the project the
|
|
174
|
-
directory is INSIDE the workspace and _file_approval_check would
|
|
175
|
-
auto-approve every call against it.
|
|
176
|
-
|
|
177
|
-
A HARDLINK IS A SECOND NAME, NOT A PATH, so resolving cannot reach it
|
|
178
|
-
(TECHNICAL_DEBT 90, batch 160): `hardlinked_segment` asks whether a
|
|
179
|
-
multiply-linked file is the same file as one under the project's or the
|
|
180
|
-
workspace's protected directory, and the answer is refused in the same
|
|
181
|
-
words. Until then a `read` through one served the protected file.
|
|
182
|
-
"""
|
|
183
|
-
resolved = resolve_path(user_path)
|
|
184
|
-
segment = protected_segment(resolved)
|
|
185
|
-
via = "the path resolves into"
|
|
186
|
-
if segment is None:
|
|
187
|
-
segment = hardlinked_segment(resolved, _protected_roots())
|
|
188
|
-
via = "the path is a hard link to a file in"
|
|
189
|
-
if segment is None:
|
|
190
|
-
return None
|
|
191
|
-
return (
|
|
192
|
-
f"Refused: {via} '{segment}/', which holds this "
|
|
193
|
-
"harness's own configuration and trust-gated content (settings.json, "
|
|
194
|
-
"mcp.json, skills, agents). It is denied however the file tools are "
|
|
195
|
-
"called."
|
|
196
|
-
)
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
def _protected_roots() -> list[str]:
|
|
200
|
-
"""The directories whose `.venastine/` the file tools could otherwise
|
|
201
|
-
reach under another name: the workspace, and the project when one has
|
|
202
|
-
been initialised (they are the same directory when the workspace was
|
|
203
|
-
named as the project)."""
|
|
204
|
-
from core import config_loader
|
|
205
|
-
|
|
206
|
-
roots = [WORKSPACE_ROOT]
|
|
207
|
-
project = config_loader.get_project_path()
|
|
208
|
-
if project and os.path.realpath(project) != WORKSPACE_ROOT:
|
|
209
|
-
roots.append(project)
|
|
210
|
-
return roots
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
def _refusal_for(tool_name: str):
|
|
214
|
-
"""ToolSpec.refusal_check for read / write / edit (§32 A7's shape).
|
|
215
|
-
|
|
216
|
-
dispatch() consults this BEFORE the approval gate and returns the
|
|
217
|
-
reason as the result, and core/loop.py suppresses the prompt for a
|
|
218
|
-
refused call -- nobody is asked a question whose answer cannot
|
|
219
|
-
change the outcome. NOT the enforcement (base.py's own words): the
|
|
220
|
-
three handlers re-test below, so a caller that reaches them
|
|
221
|
-
directly is refused too.
|
|
222
|
-
|
|
223
|
-
ONE PER TOOL since batch 146, which is what makes it able to answer the
|
|
224
|
-
arguments as well as the path. The module already declared the three
|
|
225
|
-
pydantic models that say what each tool takes; they just ran inside the
|
|
226
|
-
handlers, after this check had been handed the raw dict and had already
|
|
227
|
-
raised. Validating here turns a mistyped parameter into a refusal the
|
|
228
|
-
model can read, which is what the sibling four session tools have always
|
|
229
|
-
done -- `shell_sessions._start_refusal` is this shape, one question over.
|
|
230
|
-
|
|
231
|
-
THE ORDER IS THE DENY FIRST, and two existing tests are what settled
|
|
232
|
-
it. Validating the whole model first made `write` with a protected path
|
|
233
|
-
and no `content` answer "content: Field required" -- which is the same
|
|
234
|
-
mistake §32 A7 exists to prevent, one layer over: supplying the content
|
|
235
|
-
would only earn the refusal on the next turn, so a correction that
|
|
236
|
-
cannot change the outcome is not the answer to give. The path's own type
|
|
237
|
-
has to be settled before that, because `_protected_path_error` resolves
|
|
238
|
-
it; everything else the model got wrong is answered after.
|
|
239
|
-
"""
|
|
240
|
-
def refusal(params: dict, _context=None) -> Optional[str]:
|
|
241
|
-
model = _PARAM_MODELS[tool_name]
|
|
242
|
-
if isinstance(params, dict) and isinstance(params.get("path"), str):
|
|
243
|
-
refused = _protected_path_error(params["path"])
|
|
244
|
-
if refused is not None:
|
|
245
|
-
return refused
|
|
246
|
-
return invalid_params(tool_name, model, params)
|
|
247
|
-
return refusal
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
# ===========================================================================
|
|
251
|
-
# ---- READ -----------------------------------------------------------------
|
|
252
|
-
# ===========================================================================
|
|
253
|
-
|
|
254
|
-
class ReadFileParams(BaseModel):
|
|
255
|
-
path: str = Field(..., description="Path relative to the agent's workspace directory, or an absolute path.")
|
|
256
|
-
offset: int = Field(0, ge=0, description="Number of lines to skip before reading (0-based).")
|
|
257
|
-
count: int = Field(
|
|
258
|
-
config.MAX_READ_LINES,
|
|
259
|
-
ge=1,
|
|
260
|
-
description=f"Number of lines to read. Clamped to {config.MAX_READ_LINES} if higher.",
|
|
261
|
-
)
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
READ_TOOL_SCHEMA = {
|
|
265
|
-
"name": "read",
|
|
266
|
-
"description": (
|
|
267
|
-
"Read the contents of a file. For rich formats (PDF, DOCX, PPTX, "
|
|
268
|
-
"XLSX, HTML, etc.) the content is converted to markdown first. "
|
|
269
|
-
"Use offset and count to page through large files. Output is "
|
|
270
|
-
f"limited to {config.MAX_READ_LINES} lines or {config.MAX_READ_CHARS} "
|
|
271
|
-
"characters, whichever comes first."
|
|
272
|
-
),
|
|
273
|
-
"input_schema": ReadFileParams.model_json_schema(),
|
|
274
|
-
}
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
def _read_rich(resolved_path: str) -> str:
|
|
278
|
-
"""Convert a rich-format file to markdown via markitdown.
|
|
279
|
-
|
|
280
|
-
markitdown is an OPTIONAL extra since #144: this function is its only
|
|
281
|
-
consumer, it sits behind `read`, and `read` is globally denied and
|
|
282
|
-
cannot be re-enabled at runtime -- so a default install carries neither
|
|
283
|
-
it nor its eleven transitive distributions. Anyone who reaches here has
|
|
284
|
-
enabled `read` in config.py, and the bare ModuleNotFoundError would name
|
|
285
|
-
a package they never asked for and cannot place.
|
|
286
|
-
"""
|
|
287
|
-
try:
|
|
288
|
-
from markitdown import MarkItDown
|
|
289
|
-
except ImportError as e:
|
|
290
|
-
raise RuntimeError(
|
|
291
|
-
f"Reading {os.path.basename(resolved_path)} needs the optional "
|
|
292
|
-
f"`markitdown` dependency, which a default install does not "
|
|
293
|
-
f"carry (it serves only this path, behind the globally-denied "
|
|
294
|
-
f"`read` tool). Install it with: pip install -e \".[documents]\""
|
|
295
|
-
) from e
|
|
296
|
-
md = MarkItDown()
|
|
297
|
-
result = md.convert(resolved_path)
|
|
298
|
-
return result.text_content
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
def _truncate_lines(
|
|
302
|
-
lines: list[str],
|
|
303
|
-
offset: int,
|
|
304
|
-
count: int,
|
|
305
|
-
) -> tuple[str, int, bool, Optional[str]]:
|
|
306
|
-
"""Apply offset, clamp count, then cut at a LINE BOUNDARY.
|
|
307
|
-
|
|
308
|
-
Returns (content, lines_returned, truncated, message), where
|
|
309
|
-
`lines_returned` counts the lines that are IN `content`.
|
|
310
|
-
|
|
311
|
-
THE CUT NOW HAPPENS BEFORE THE COUNT (batch 146). It used to be the
|
|
312
|
-
other way round: `lines_returned` was computed from the selection and
|
|
313
|
-
the character cut threw most of it away afterwards, so on any file
|
|
314
|
-
averaging over 100 characters a line the number the model resumes from
|
|
315
|
-
named a line far past the last one delivered. Measured on 800 lines of
|
|
316
|
-
160 characters: 500 reported, 313 delivered, and `offset=500` -- which
|
|
317
|
-
the clamp branch's own message tells the model to use -- skipped 187
|
|
318
|
-
lines and 29,920 characters that no call it could construct would ever
|
|
319
|
-
return.
|
|
320
|
-
|
|
321
|
-
Cutting at a line boundary rather than mid-line is what makes every
|
|
322
|
-
byte reachable, since `offset` and `count` are in LINES and the ceiling
|
|
323
|
-
is in characters. The sibling in this scope had already reached the
|
|
324
|
-
other half of this: "the continuation offset is IN the message, not
|
|
325
|
-
merely implied by the numbers. A model that has to compute where to
|
|
326
|
-
resume usually re-reads from zero and spends the budget twice"
|
|
327
|
-
(project_docs.read_run). One resume point, named once, for both
|
|
328
|
-
branches -- the clamp message used to carry its own and they disagreed.
|
|
329
|
-
"""
|
|
330
|
-
clamped = count > config.MAX_READ_LINES
|
|
331
|
-
effective_count = min(count, config.MAX_READ_LINES)
|
|
332
|
-
|
|
333
|
-
selected = lines[offset:offset + effective_count]
|
|
334
|
-
|
|
335
|
-
kept: list[str] = []
|
|
336
|
-
used = 0
|
|
337
|
-
cut_inside_a_line = False
|
|
338
|
-
for line in selected:
|
|
339
|
-
extra = len(line) + (1 if kept else 0) # the joining newline
|
|
340
|
-
if used + extra > config.MAX_READ_CHARS:
|
|
341
|
-
if not kept:
|
|
342
|
-
# A SINGLE LINE LONGER THAN THE WHOLE CEILING -- minified
|
|
343
|
-
# JavaScript, a one-line JSON document, a packed asset.
|
|
344
|
-
# Keeping whole lines only would deliver NOTHING here and
|
|
345
|
-
# the model would have nowhere to go, so this one line is
|
|
346
|
-
# cut and the message says so: `offset + 1` resumes at the
|
|
347
|
-
# next line, and the rest of this one is not reachable
|
|
348
|
-
# through a tool whose paging unit is a line.
|
|
349
|
-
kept.append(line[:config.MAX_READ_CHARS])
|
|
350
|
-
cut_inside_a_line = True
|
|
351
|
-
break
|
|
352
|
-
kept.append(line)
|
|
353
|
-
used += extra
|
|
354
|
-
|
|
355
|
-
content = "\n".join(kept)
|
|
356
|
-
lines_returned = len(kept)
|
|
357
|
-
char_cut = cut_inside_a_line or len(kept) < len(selected)
|
|
358
|
-
truncated = clamped or char_cut
|
|
359
|
-
|
|
360
|
-
message_parts: list[str] = []
|
|
361
|
-
if clamped:
|
|
362
|
-
message_parts.append(
|
|
363
|
-
f"Requested {count} lines, returned at most {effective_count} "
|
|
364
|
-
f"(maximum)."
|
|
365
|
-
)
|
|
366
|
-
if char_cut:
|
|
367
|
-
message_parts.append(
|
|
368
|
-
f"Content truncated at {config.MAX_READ_CHARS} characters, on a "
|
|
369
|
-
f"line boundary."
|
|
370
|
-
)
|
|
371
|
-
if cut_inside_a_line:
|
|
372
|
-
message_parts.append(
|
|
373
|
-
f"Line {offset} is itself longer than "
|
|
374
|
-
f"{config.MAX_READ_CHARS} characters and was cut, so the rest of "
|
|
375
|
-
f"it is not reachable by offset."
|
|
376
|
-
)
|
|
377
|
-
if truncated:
|
|
378
|
-
message_parts.append(
|
|
379
|
-
f"Use offset={offset + lines_returned} to read further."
|
|
380
|
-
)
|
|
381
|
-
|
|
382
|
-
message = " ".join(message_parts) if message_parts else None
|
|
383
|
-
return content, lines_returned, truncated, message
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
def read_run(params: dict) -> dict:
|
|
387
|
-
parsed = ReadFileParams(**params)
|
|
388
|
-
refused = _protected_path_error(parsed.path)
|
|
389
|
-
if refused is not None:
|
|
390
|
-
return {"error": refused}
|
|
391
|
-
resolved = resolve_path(parsed.path)
|
|
392
|
-
|
|
393
|
-
if not os.path.exists(resolved):
|
|
394
|
-
return {"error": f"No such file or directory: {parsed.path}"}
|
|
395
|
-
if not os.path.isfile(resolved):
|
|
396
|
-
return {"error": f"Not a regular file: {parsed.path}"}
|
|
397
|
-
|
|
398
|
-
file_size = os.path.getsize(resolved)
|
|
399
|
-
if file_size > config.MAX_FILE_SIZE_BYTES:
|
|
400
|
-
return {
|
|
401
|
-
"error": (
|
|
402
|
-
f"File size ({file_size} bytes) exceeds the maximum "
|
|
403
|
-
f"readable size ({config.MAX_FILE_SIZE_BYTES} bytes)."
|
|
404
|
-
),
|
|
405
|
-
}
|
|
406
|
-
|
|
407
|
-
ext = os.path.splitext(resolved)[1].lower()
|
|
408
|
-
|
|
409
|
-
try:
|
|
410
|
-
if ext in _RICH_EXTENSIONS:
|
|
411
|
-
raw_text = _read_rich(resolved)
|
|
412
|
-
all_lines = raw_text.splitlines()
|
|
413
|
-
else:
|
|
414
|
-
with open(resolved, encoding="utf-8", errors="replace") as f:
|
|
415
|
-
all_lines = f.read().splitlines()
|
|
416
|
-
except Exception as e:
|
|
417
|
-
logger.exception("read tool failed on %s", parsed.path)
|
|
418
|
-
return {"error": f"Could not read file: {e}"}
|
|
419
|
-
|
|
420
|
-
content, lines_returned, truncated, message = _truncate_lines(
|
|
421
|
-
all_lines, parsed.offset, parsed.count,
|
|
422
|
-
)
|
|
423
|
-
|
|
424
|
-
result: dict = {
|
|
425
|
-
"content": content,
|
|
426
|
-
"lines_returned": lines_returned,
|
|
427
|
-
"offset": parsed.offset,
|
|
428
|
-
"truncated": truncated,
|
|
429
|
-
}
|
|
430
|
-
if message:
|
|
431
|
-
result["message"] = message
|
|
432
|
-
return result
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
# ===========================================================================
|
|
436
|
-
# ---- WRITE ----------------------------------------------------------------
|
|
437
|
-
# ===========================================================================
|
|
438
|
-
|
|
439
|
-
class WriteFileParams(BaseModel):
|
|
440
|
-
path: str = Field(..., description="Path relative to the agent's workspace directory, or an absolute path.")
|
|
441
|
-
content: str = Field(..., description="Full content to write — overwrites any existing file.")
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
WRITE_TOOL_SCHEMA = {
|
|
445
|
-
"name": "write",
|
|
446
|
-
"description": (
|
|
447
|
-
"Create or overwrite a file. Parent directories are created "
|
|
448
|
-
"automatically. Content size is limited to "
|
|
449
|
-
f"{config.MAX_FILE_SIZE_BYTES} bytes."
|
|
450
|
-
),
|
|
451
|
-
"input_schema": WriteFileParams.model_json_schema(),
|
|
452
|
-
}
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
def write_run(params: dict) -> dict:
|
|
456
|
-
parsed = WriteFileParams(**params)
|
|
457
|
-
|
|
458
|
-
# BEFORE anything creates a directory: a refused write must not
|
|
459
|
-
# conjure the protected directory into existence on its way to being
|
|
460
|
-
# refused. The makedirs moved into `write_text_atomic` in batch 146 and
|
|
461
|
-
# the ordering it needs did not move with it, which is why this says
|
|
462
|
-
# what it protects rather than naming a line below.
|
|
463
|
-
refused = _protected_path_error(parsed.path)
|
|
464
|
-
if refused is not None:
|
|
465
|
-
return {"error": refused}
|
|
466
|
-
|
|
467
|
-
content_bytes = parsed.content.encode("utf-8")
|
|
468
|
-
if len(content_bytes) > config.MAX_FILE_SIZE_BYTES:
|
|
469
|
-
return {
|
|
470
|
-
"error": (
|
|
471
|
-
f"Content size ({len(content_bytes)} bytes) exceeds the "
|
|
472
|
-
f"maximum writable size ({config.MAX_FILE_SIZE_BYTES} bytes)."
|
|
473
|
-
),
|
|
474
|
-
}
|
|
475
|
-
|
|
476
|
-
resolved = resolve_path(parsed.path)
|
|
477
|
-
|
|
478
|
-
try:
|
|
479
|
-
# newline="" and a replace rather than a truncating write -- the
|
|
480
|
-
# module docstring's BYTES section says what each buys, and
|
|
481
|
-
# `write_text_atomic` says why it owns both.
|
|
482
|
-
created = not os.path.exists(resolved)
|
|
483
|
-
write_text_atomic(resolved, parsed.content)
|
|
484
|
-
except Exception as e:
|
|
485
|
-
logger.exception("write tool failed on %s", parsed.path)
|
|
486
|
-
return {"error": f"Could not write file: {e}"}
|
|
487
|
-
|
|
488
|
-
if created:
|
|
489
|
-
from core.file_mentions import note_file_created
|
|
490
|
-
|
|
491
|
-
note_file_created(resolved)
|
|
492
|
-
return {"result": f"Wrote {len(parsed.content)} characters to {parsed.path}"}
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
# ===========================================================================
|
|
496
|
-
# ---- EDIT -----------------------------------------------------------------
|
|
497
|
-
# ===========================================================================
|
|
498
|
-
|
|
499
|
-
class EditFileParams(BaseModel):
|
|
500
|
-
path: str = Field(..., description="Path relative to the agent's workspace directory, or an absolute path.")
|
|
501
|
-
old_text: str = Field(..., description="Exact text to replace — must appear EXACTLY ONCE in the file.")
|
|
502
|
-
new_text: str = Field(..., description="Replacement text.")
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
EDIT_TOOL_SCHEMA = {
|
|
506
|
-
"name": "edit",
|
|
507
|
-
"description": (
|
|
508
|
-
"Replace an exact, uniquely-matching span of text within an "
|
|
509
|
-
"existing file. old_text must appear exactly once; if it appears "
|
|
510
|
-
"zero or more than one time the edit is rejected with an error."
|
|
511
|
-
),
|
|
512
|
-
"input_schema": EditFileParams.model_json_schema(),
|
|
513
|
-
}
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
def edit_run(params: dict) -> dict:
|
|
517
|
-
parsed = EditFileParams(**params)
|
|
518
|
-
refused = _protected_path_error(parsed.path)
|
|
519
|
-
if refused is not None:
|
|
520
|
-
return {"error": refused}
|
|
521
|
-
resolved = resolve_path(parsed.path)
|
|
522
|
-
|
|
523
|
-
if not os.path.isfile(resolved):
|
|
524
|
-
return {"error": f"No such file: {parsed.path}"}
|
|
525
|
-
|
|
526
|
-
# ROADMAP_v2 §31 (H7), #55. read_run has had this check since the
|
|
527
|
-
# beginning and this module's own docstring gives the reason --
|
|
528
|
-
# "rejected before opening to prevent memory exhaustion" -- while
|
|
529
|
-
# the sibling twenty lines down read whatever it was pointed at.
|
|
530
|
-
# Measured on a 30 MB file: 60 MB of peak traced memory to answer
|
|
531
|
-
# "old_text not found in file."
|
|
532
|
-
#
|
|
533
|
-
# Copied rather than reinvented, down to the wording, so the two
|
|
534
|
-
# paths refuse identically. A caller that learns what `read` rejects
|
|
535
|
-
# now knows what `edit` rejects.
|
|
536
|
-
file_size = os.path.getsize(resolved)
|
|
537
|
-
if file_size > config.MAX_FILE_SIZE_BYTES:
|
|
538
|
-
return {
|
|
539
|
-
"error": (
|
|
540
|
-
f"File size ({file_size} bytes) exceeds the maximum "
|
|
541
|
-
f"editable size ({config.MAX_FILE_SIZE_BYTES} bytes)."
|
|
542
|
-
),
|
|
543
|
-
}
|
|
544
|
-
|
|
545
|
-
try:
|
|
546
|
-
# newline="" so `content` holds the file's REAL line endings and the
|
|
547
|
-
# uniqueness contract is checked against the bytes on disk. With
|
|
548
|
-
# universal newlines a CRLF file arrived as LF, and writing that
|
|
549
|
-
# back converted the whole file -- which is the defect this fixes,
|
|
550
|
-
# pointing the other way.
|
|
551
|
-
with open(resolved, encoding="utf-8", newline="") as f:
|
|
552
|
-
content = f.read()
|
|
553
|
-
except Exception as e:
|
|
554
|
-
logger.exception("edit tool read failed on %s", parsed.path)
|
|
555
|
-
return {"error": f"Could not read file: {e}"}
|
|
556
|
-
|
|
557
|
-
old_text, new_text = parsed.old_text, parsed.new_text
|
|
558
|
-
match_count = content.count(old_text)
|
|
559
|
-
if match_count == 0 and "\n" in old_text:
|
|
560
|
-
# TRANSLATED AND RETRIED, because the model cannot see what it
|
|
561
|
-
# would have to spell. `read` joins the lines it delivers with
|
|
562
|
-
# "\n" whatever the file held, so a span copied from what the
|
|
563
|
-
# model was shown is LF-spelled even for a CRLF file -- and a
|
|
564
|
-
# strict matcher would refuse every multi-line edit of one, with a
|
|
565
|
-
# message naming text the model has no way to produce. Both sides
|
|
566
|
-
# move together so the replacement carries the file's endings too.
|
|
567
|
-
crlf_old = old_text.replace("\n", "\r\n")
|
|
568
|
-
crlf_count = content.count(crlf_old)
|
|
569
|
-
if crlf_count:
|
|
570
|
-
old_text = crlf_old
|
|
571
|
-
new_text = new_text.replace("\n", "\r\n")
|
|
572
|
-
match_count = crlf_count
|
|
573
|
-
|
|
574
|
-
if match_count == 0:
|
|
575
|
-
return {"error": "old_text not found in file."}
|
|
576
|
-
if match_count > 1:
|
|
577
|
-
return {
|
|
578
|
-
"error": (
|
|
579
|
-
f"old_text appears {match_count} times — must be unique. "
|
|
580
|
-
"Include more surrounding context to narrow the match."
|
|
581
|
-
),
|
|
582
|
-
}
|
|
583
|
-
|
|
584
|
-
content = content.replace(old_text, new_text)
|
|
585
|
-
|
|
586
|
-
try:
|
|
587
|
-
write_text_atomic(resolved, content)
|
|
588
|
-
except Exception as e:
|
|
589
|
-
logger.exception("edit tool write failed on %s", parsed.path)
|
|
590
|
-
return {"error": f"Could not write file: {e}"}
|
|
591
|
-
|
|
592
|
-
return {"result": f"Replaced 1 occurrence in {parsed.path}"}
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
# ===========================================================================
|
|
596
|
-
# ---- VIEW_IMAGE (ROADMAP_v3 §81) ------------------------------------------
|
|
597
|
-
# ===========================================================================
|
|
598
|
-
|
|
599
|
-
#: What both wires §81 delivers to accept as a base64 image: Anthropic's
|
|
600
|
-
#: image block and the OpenAI-compatible `image_url` part (IM7). Google, a wire
|
|
601
|
-
#: since batch 173, is sent three of them and gets a note for GIF (IM10). Judged from
|
|
602
|
-
#: the file's own leading bytes, never its extension -- a PNG renamed `.jpg`
|
|
603
|
-
#: is a PNG, and declaring the wrong media type is a request the provider
|
|
604
|
-
#: rejects.
|
|
605
|
-
_IMAGE_SIGNATURES = (
|
|
606
|
-
(b"\x89PNG\r\n\x1a\n", "image/png"),
|
|
607
|
-
(b"\xff\xd8\xff", "image/jpeg"),
|
|
608
|
-
(b"GIF87a", "image/gif"),
|
|
609
|
-
(b"GIF89a", "image/gif"),
|
|
610
|
-
)
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
def _image_media_type(head: bytes) -> Optional[str]:
|
|
614
|
-
"""The media type *head* (a file's first bytes) declares, or None."""
|
|
615
|
-
for signature, media_type in _IMAGE_SIGNATURES:
|
|
616
|
-
if head.startswith(signature):
|
|
617
|
-
return media_type
|
|
618
|
-
# WEBP is a RIFF container: "RIFF", a four-byte length, then "WEBP".
|
|
619
|
-
if head[:4] == b"RIFF" and head[8:12] == b"WEBP":
|
|
620
|
-
return "image/webp"
|
|
621
|
-
return None
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
class ViewImageParams(BaseModel):
|
|
625
|
-
path: str = Field(..., description="Path to a PNG, JPEG, GIF or WEBP file, relative to the agent's workspace directory, or an absolute path.")
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
VIEW_IMAGE_TOOL_SCHEMA = {
|
|
629
|
-
"name": "view_image",
|
|
630
|
-
"description": (
|
|
631
|
-
"Look at an image file. The image itself is attached to the result, "
|
|
632
|
-
"so you see the picture rather than a description of it. PNG, JPEG, "
|
|
633
|
-
f"GIF and WEBP, up to {config.MAX_IMAGE_BYTES} bytes. For text and "
|
|
634
|
-
"documents use read."
|
|
635
|
-
),
|
|
636
|
-
"input_schema": ViewImageParams.model_json_schema(),
|
|
637
|
-
}
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
def view_image_run(params: dict, memory=None, call_id=None,
|
|
641
|
-
parent_run=None) -> dict:
|
|
642
|
-
"""Read an image off disk and attach it to this call's result (IM1).
|
|
643
|
-
|
|
644
|
-
The RESULT is text -- it names what was attached -- and the bytes go to
|
|
645
|
-
`memory.attach_image`, which writes them into the same row as that
|
|
646
|
-
result (IM3). They never ride in the returned dict, so the output
|
|
647
|
-
redactor, the tool_result event and both shells' transcripts see only
|
|
648
|
-
the sentence.
|
|
649
|
-
|
|
650
|
-
The path rules are `read`'s exactly: the same `_refusal_for` and
|
|
651
|
-
`_file_approval_check`, and the protected segment re-tested here as all
|
|
652
|
-
three file tools re-test it.
|
|
653
|
-
"""
|
|
654
|
-
parsed = ViewImageParams(**params)
|
|
655
|
-
refused = _protected_path_error(parsed.path)
|
|
656
|
-
if refused is not None:
|
|
657
|
-
return {"error": refused}
|
|
658
|
-
# THE RUN'S OWN ANSWER (IM6), computed once by the loop and read by the
|
|
659
|
-
# schema list too, so the two cannot disagree. The schema list already
|
|
660
|
-
# left this tool out when it is False; this is the backstop for a call
|
|
661
|
-
# made anyway, by a model naming a tool it was not offered.
|
|
662
|
-
if parent_run is None or not getattr(parent_run, "images", False):
|
|
663
|
-
return {"error": (
|
|
664
|
-
"view_image is not available in this run: either the provider "
|
|
665
|
-
"is not marked `accepts_images` in providers.json, or this is a "
|
|
666
|
-
"research pass, which does not take images."
|
|
667
|
-
)}
|
|
668
|
-
if memory is None or call_id is None:
|
|
669
|
-
return {"error": "view_image has no conversation to attach the image to."}
|
|
670
|
-
|
|
671
|
-
resolved = resolve_path(parsed.path)
|
|
672
|
-
if not os.path.exists(resolved):
|
|
673
|
-
return {"error": f"No such file or directory: {parsed.path}"}
|
|
674
|
-
if not os.path.isfile(resolved):
|
|
675
|
-
return {"error": f"Not a regular file: {parsed.path}"}
|
|
676
|
-
file_size = os.path.getsize(resolved)
|
|
677
|
-
if file_size > config.MAX_IMAGE_BYTES:
|
|
678
|
-
return {"error": (
|
|
679
|
-
f"Image size ({file_size} bytes) exceeds the maximum attachable "
|
|
680
|
-
f"size ({config.MAX_IMAGE_BYTES} bytes)."
|
|
681
|
-
)}
|
|
682
|
-
try:
|
|
683
|
-
# One byte past the cap, so a file that grew after the size check
|
|
684
|
-
# is refused rather than read without a bound.
|
|
685
|
-
with open(resolved, "rb") as f:
|
|
686
|
-
raw = f.read(config.MAX_IMAGE_BYTES + 1)
|
|
687
|
-
except OSError as e:
|
|
688
|
-
logger.exception("view_image failed on %s", parsed.path)
|
|
689
|
-
return {"error": f"Could not read file: {e}"}
|
|
690
|
-
if len(raw) > config.MAX_IMAGE_BYTES:
|
|
691
|
-
return {"error": (
|
|
692
|
-
f"Image exceeds the maximum attachable size "
|
|
693
|
-
f"({config.MAX_IMAGE_BYTES} bytes)."
|
|
694
|
-
)}
|
|
695
|
-
|
|
696
|
-
media_type = _image_media_type(raw[:12])
|
|
697
|
-
if media_type is None:
|
|
698
|
-
return {"error": (
|
|
699
|
-
f"{parsed.path} is not a PNG, JPEG, GIF or WEBP image (judged by "
|
|
700
|
-
f"its contents, not its name)."
|
|
701
|
-
)}
|
|
702
|
-
memory.attach_image(call_id, media_type,
|
|
703
|
-
base64.b64encode(raw).decode("ascii"))
|
|
704
|
-
return {"content": f"Attached {parsed.path} ({media_type}, {len(raw)} bytes)."}
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
# ===========================================================================
|
|
708
|
-
# ---- What each tool takes -------------------------------------------------
|
|
709
|
-
# ===========================================================================
|
|
710
|
-
|
|
711
|
-
#: Read by `_refusal_for`, so the pre-approval check validates against the
|
|
712
|
-
#: same model the handler does. At the BOTTOM because all three classes have
|
|
713
|
-
#: to exist first, and looked up inside the closure rather than captured, so
|
|
714
|
-
#: there is no import-order question to get wrong.
|
|
715
|
-
_PARAM_MODELS = {
|
|
716
|
-
"read": ReadFileParams,
|
|
717
|
-
"write": WriteFileParams,
|
|
718
|
-
"edit": EditFileParams,
|
|
719
|
-
"view_image": ViewImageParams,
|
|
720
|
-
}
|
|
1
|
+
"""
|
|
2
|
+
tools/builtin/file_ops.py
|
|
3
|
+
|
|
4
|
+
Three file-operation tools — read, write, edit — confined to a
|
|
5
|
+
configurable workspace directory. Registered as three separate tools
|
|
6
|
+
to match config.ToolPermissions' three separate boolean fields (read /
|
|
7
|
+
write / edit), so review/audit agents can be given read access without
|
|
8
|
+
write or edit.
|
|
9
|
+
|
|
10
|
+
A fourth, view_image (ROADMAP_v3 §81), reads an image and attaches it
|
|
11
|
+
to its own result rather than returning text. It follows read's path
|
|
12
|
+
rules exactly, with its own permission row so it can be enabled apart
|
|
13
|
+
from read. See view_image_run for where the bytes go.
|
|
14
|
+
|
|
15
|
+
SECURITY MODEL (ROADMAP §6, deviated per user decision):
|
|
16
|
+
Paths within WORKSPACE_DIR are auto-approved (unless the matching
|
|
17
|
+
ToolApprovals boolean is True, which forces approval even inside the
|
|
18
|
+
workspace). Paths outside WORKSPACE_DIR always require user approval
|
|
19
|
+
— they are NOT hard-rejected, so an operator can grant one-off access
|
|
20
|
+
to files outside the workspace. Symlinks and '..' segments are always
|
|
21
|
+
resolved via os.path.realpath before any check, so a path that looks
|
|
22
|
+
inside the workspace but resolves outside it is treated as outside.
|
|
23
|
+
|
|
24
|
+
PROTECTED SEGMENTS (security/protected_paths.py) are the one hard
|
|
25
|
+
deny, and the exception to both rules above: any path -- inside or
|
|
26
|
+
outside the workspace -- that resolves into `.venastine/` is refused
|
|
27
|
+
by the refusal_check before approval and re-tested in all three
|
|
28
|
+
handlers, whatever the ToolApprovals booleans say. Case-folded since
|
|
29
|
+
batch 146, because `realpath` only canonicalises a spelling for a
|
|
30
|
+
path that already EXISTS -- which is not the state a `write` is in.
|
|
31
|
+
|
|
32
|
+
WHAT THE DENY RESTS ON, AND THE ONE SHAPE IT CANNOT SEE. It rests on
|
|
33
|
+
`realpath`, so a symlink and a junction into `.venastine/` both arrive
|
|
34
|
+
as the real thing. A HARDLINK does not: it is not a link to anything,
|
|
35
|
+
it is the file, and `realpath` returns the path it was given. Batch 146
|
|
36
|
+
measured a `write` through a hardlinked name putting an mcpServers
|
|
37
|
+
object into a protected `settings.json` whose direct spelling is
|
|
38
|
+
refused. The write half is closed -- `json_store.write_text_atomic`
|
|
39
|
+
replaces the name rather than writing through it, so the link breaks
|
|
40
|
+
and the other name keeps its bytes -- and the READ half is not. A
|
|
41
|
+
`read` through a hardlink into `.venastine/` still serves the file,
|
|
42
|
+
and nothing available here can tell: enumerating a file's other names
|
|
43
|
+
is per-platform, and refusing every multiply-linked file would deny
|
|
44
|
+
ordinary ones. Filed in docs/TECHNICAL_DEBT.md rather than left to be
|
|
45
|
+
found, with the same answer the sandbox reached for a link it cannot
|
|
46
|
+
resolve.
|
|
47
|
+
|
|
48
|
+
BYTES, NOT TEXT, ON THE WRITE PATHS (batch 146):
|
|
49
|
+
All three used to open with mode "w" and no `newline=`, so Python
|
|
50
|
+
translated every "\n" to os.linesep. On Windows `write` could not
|
|
51
|
+
reproduce a file it had just read, and `edit` replacing one span of an
|
|
52
|
+
LF file rewrote every line ending in it -- 2,910 of them in this
|
|
53
|
+
repository's own AGENTS.md. `edit` now reads with `newline=""` as well,
|
|
54
|
+
so the match runs against the file's real bytes, and retries an
|
|
55
|
+
LF-spelled `old_text` translated when the file is CRLF: the model
|
|
56
|
+
cannot see a file's endings through `read` (which joins with "\n"
|
|
57
|
+
whatever it found), so a span it spells from what it was shown has to
|
|
58
|
+
be able to match.
|
|
59
|
+
|
|
60
|
+
READ TOOL PAGINATION (deviated from ROADMAP §6):
|
|
61
|
+
The read tool accepts offset (lines to skip) and count (lines to
|
|
62
|
+
read). count is clamped to config.MAX_READ_LINES with a note in the
|
|
63
|
+
response (not a hard error). Output is also truncated at
|
|
64
|
+
config.MAX_READ_CHARS with a note. Files larger than
|
|
65
|
+
config.MAX_FILE_SIZE_BYTES are rejected before opening to prevent
|
|
66
|
+
memory exhaustion (especially on the markitdown path, which loads
|
|
67
|
+
the whole file).
|
|
68
|
+
|
|
69
|
+
RICH FORMAT SUPPORT (deviated from ROADMAP §6):
|
|
70
|
+
For binary/rich extensions (.pdf, .docx, .pptx, etc.) the read tool
|
|
71
|
+
uses markitdown to convert to markdown before applying line/char
|
|
72
|
+
truncation. Plain-text extensions use open() directly.
|
|
73
|
+
"""
|
|
74
|
+
|
|
75
|
+
from __future__ import annotations
|
|
76
|
+
|
|
77
|
+
import base64
|
|
78
|
+
import logging
|
|
79
|
+
import os
|
|
80
|
+
from typing import Optional
|
|
81
|
+
|
|
82
|
+
from pydantic import BaseModel, Field
|
|
83
|
+
|
|
84
|
+
import config
|
|
85
|
+
from json_store import write_text_atomic
|
|
86
|
+
from security.protected_paths import hardlinked_segment, protected_segment
|
|
87
|
+
from tools.base import invalid_params
|
|
88
|
+
|
|
89
|
+
logger = logging.getLogger(__name__)
|
|
90
|
+
|
|
91
|
+
# ---------------------------------------------------------------------------
|
|
92
|
+
# ---- Path helpers ---------------------------------------------------------
|
|
93
|
+
# ---------------------------------------------------------------------------
|
|
94
|
+
|
|
95
|
+
WORKSPACE_ROOT = os.path.realpath(config.WORKSPACE_DIR)
|
|
96
|
+
|
|
97
|
+
_RICH_EXTENSIONS = frozenset({
|
|
98
|
+
".pdf", ".docx", ".pptx", ".xlsx", ".xls",
|
|
99
|
+
".html", ".htm", ".epub", ".ipynb",
|
|
100
|
+
})
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def resolve_path(user_path: str) -> str:
|
|
104
|
+
"""Resolve *user_path* relative to WORKSPACE_ROOT via realpath.
|
|
105
|
+
|
|
106
|
+
Handles ``..`` segments and symlinks. Does NOT reject paths that
|
|
107
|
+
land outside the workspace — that decision belongs to the approval
|
|
108
|
+
layer (``_file_approval_check``), not to path resolution.
|
|
109
|
+
|
|
110
|
+
PUBLIC since batch 41 (X4). The TUI has to read the file a `write`
|
|
111
|
+
or an `edit` is about to change in order to show the diff, and it
|
|
112
|
+
must land on the same file the tool will — a second
|
|
113
|
+
``os.path.join(WORKSPACE_ROOT, ...)`` at the call site is this
|
|
114
|
+
project's canonical producer/consumer bug, and here it would mean a
|
|
115
|
+
diff of one file beside an edit to another.
|
|
116
|
+
"""
|
|
117
|
+
return os.path.realpath(os.path.join(WORKSPACE_ROOT, user_path))
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
def _is_within_workspace(user_path: str) -> bool:
|
|
121
|
+
resolved = resolve_path(user_path)
|
|
122
|
+
return resolved == WORKSPACE_ROOT or resolved.startswith(WORKSPACE_ROOT + os.sep)
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
def _file_approval_check(tool_name: str, params: dict) -> bool:
|
|
126
|
+
"""Path-dependent approval policy for read / write / edit.
|
|
127
|
+
|
|
128
|
+
Outside workspace → always True (ask user).
|
|
129
|
+
Within workspace → defer to the matching ToolApprovals boolean
|
|
130
|
+
(False = auto-approved, True = still ask).
|
|
131
|
+
|
|
132
|
+
TOTAL over any JSON object, which it was not until batch 146: a
|
|
133
|
+
`{"path": null}` is well-formed, so `params.get("path", "")` returns
|
|
134
|
+
None rather than the default -- the key IS present -- and
|
|
135
|
+
`os.path.join(WORKSPACE_ROOT, None)` raised a TypeError out of a gate
|
|
136
|
+
that runs ABOVE dispatch()'s containment. tools/base.py carries the one
|
|
137
|
+
copy of what that costs; shell.py's gate has said "total, like
|
|
138
|
+
everything else the gate calls" for a long time, and these two were the
|
|
139
|
+
exception.
|
|
140
|
+
|
|
141
|
+
True for a path it cannot read, because ASKING is the fail-closed
|
|
142
|
+
direction for a predicate that can only tighten. In practice the
|
|
143
|
+
refusal_check answers first and the call never arrives here.
|
|
144
|
+
"""
|
|
145
|
+
if not isinstance(params, dict):
|
|
146
|
+
return True
|
|
147
|
+
path = params.get("path", "")
|
|
148
|
+
if not isinstance(path, str):
|
|
149
|
+
return True
|
|
150
|
+
if not _is_within_workspace(path):
|
|
151
|
+
return True
|
|
152
|
+
approvals = config.ToolApprovals()
|
|
153
|
+
return getattr(approvals, tool_name, False)
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
# ===========================================================================
|
|
157
|
+
# ---- Protected segments (.venastine/) -------------------------------------
|
|
158
|
+
# ===========================================================================
|
|
159
|
+
|
|
160
|
+
def _protected_path_error(user_path: str) -> Optional[str]:
|
|
161
|
+
"""Why *user_path* must be refused outright, or None.
|
|
162
|
+
|
|
163
|
+
Shared by the refusal_check and all three handlers so the decision
|
|
164
|
+
and its wording cannot drift between the pre-approval answer and the
|
|
165
|
+
backstop. resolve_path BEFORE the segment test, so `..` travel and a
|
|
166
|
+
symlink are caught the same way _is_within_workspace catches them.
|
|
167
|
+
|
|
168
|
+
Unconditional on workspace membership, like project_docs'
|
|
169
|
+
`_is_readable_doc`: the segment is denied wherever the path lands,
|
|
170
|
+
because `.venastine/` holds mcp.json -- which names commands the
|
|
171
|
+
harness spawns at startup -- and skills/ and agents/ content that is
|
|
172
|
+
injected into system prompts. Workspace membership is the wrong
|
|
173
|
+
question here: with AGENT_WORKSPACE pointed at the project the
|
|
174
|
+
directory is INSIDE the workspace and _file_approval_check would
|
|
175
|
+
auto-approve every call against it.
|
|
176
|
+
|
|
177
|
+
A HARDLINK IS A SECOND NAME, NOT A PATH, so resolving cannot reach it
|
|
178
|
+
(TECHNICAL_DEBT 90, batch 160): `hardlinked_segment` asks whether a
|
|
179
|
+
multiply-linked file is the same file as one under the project's or the
|
|
180
|
+
workspace's protected directory, and the answer is refused in the same
|
|
181
|
+
words. Until then a `read` through one served the protected file.
|
|
182
|
+
"""
|
|
183
|
+
resolved = resolve_path(user_path)
|
|
184
|
+
segment = protected_segment(resolved)
|
|
185
|
+
via = "the path resolves into"
|
|
186
|
+
if segment is None:
|
|
187
|
+
segment = hardlinked_segment(resolved, _protected_roots())
|
|
188
|
+
via = "the path is a hard link to a file in"
|
|
189
|
+
if segment is None:
|
|
190
|
+
return None
|
|
191
|
+
return (
|
|
192
|
+
f"Refused: {via} '{segment}/', which holds this "
|
|
193
|
+
"harness's own configuration and trust-gated content (settings.json, "
|
|
194
|
+
"mcp.json, skills, agents). It is denied however the file tools are "
|
|
195
|
+
"called."
|
|
196
|
+
)
|
|
197
|
+
|
|
198
|
+
|
|
199
|
+
def _protected_roots() -> list[str]:
|
|
200
|
+
"""The directories whose `.venastine/` the file tools could otherwise
|
|
201
|
+
reach under another name: the workspace, and the project when one has
|
|
202
|
+
been initialised (they are the same directory when the workspace was
|
|
203
|
+
named as the project)."""
|
|
204
|
+
from core import config_loader
|
|
205
|
+
|
|
206
|
+
roots = [WORKSPACE_ROOT]
|
|
207
|
+
project = config_loader.get_project_path()
|
|
208
|
+
if project and os.path.realpath(project) != WORKSPACE_ROOT:
|
|
209
|
+
roots.append(project)
|
|
210
|
+
return roots
|
|
211
|
+
|
|
212
|
+
|
|
213
|
+
def _refusal_for(tool_name: str):
|
|
214
|
+
"""ToolSpec.refusal_check for read / write / edit (§32 A7's shape).
|
|
215
|
+
|
|
216
|
+
dispatch() consults this BEFORE the approval gate and returns the
|
|
217
|
+
reason as the result, and core/loop.py suppresses the prompt for a
|
|
218
|
+
refused call -- nobody is asked a question whose answer cannot
|
|
219
|
+
change the outcome. NOT the enforcement (base.py's own words): the
|
|
220
|
+
three handlers re-test below, so a caller that reaches them
|
|
221
|
+
directly is refused too.
|
|
222
|
+
|
|
223
|
+
ONE PER TOOL since batch 146, which is what makes it able to answer the
|
|
224
|
+
arguments as well as the path. The module already declared the three
|
|
225
|
+
pydantic models that say what each tool takes; they just ran inside the
|
|
226
|
+
handlers, after this check had been handed the raw dict and had already
|
|
227
|
+
raised. Validating here turns a mistyped parameter into a refusal the
|
|
228
|
+
model can read, which is what the sibling four session tools have always
|
|
229
|
+
done -- `shell_sessions._start_refusal` is this shape, one question over.
|
|
230
|
+
|
|
231
|
+
THE ORDER IS THE DENY FIRST, and two existing tests are what settled
|
|
232
|
+
it. Validating the whole model first made `write` with a protected path
|
|
233
|
+
and no `content` answer "content: Field required" -- which is the same
|
|
234
|
+
mistake §32 A7 exists to prevent, one layer over: supplying the content
|
|
235
|
+
would only earn the refusal on the next turn, so a correction that
|
|
236
|
+
cannot change the outcome is not the answer to give. The path's own type
|
|
237
|
+
has to be settled before that, because `_protected_path_error` resolves
|
|
238
|
+
it; everything else the model got wrong is answered after.
|
|
239
|
+
"""
|
|
240
|
+
def refusal(params: dict, _context=None) -> Optional[str]:
|
|
241
|
+
model = _PARAM_MODELS[tool_name]
|
|
242
|
+
if isinstance(params, dict) and isinstance(params.get("path"), str):
|
|
243
|
+
refused = _protected_path_error(params["path"])
|
|
244
|
+
if refused is not None:
|
|
245
|
+
return refused
|
|
246
|
+
return invalid_params(tool_name, model, params)
|
|
247
|
+
return refusal
|
|
248
|
+
|
|
249
|
+
|
|
250
|
+
# ===========================================================================
|
|
251
|
+
# ---- READ -----------------------------------------------------------------
|
|
252
|
+
# ===========================================================================
|
|
253
|
+
|
|
254
|
+
class ReadFileParams(BaseModel):
|
|
255
|
+
path: str = Field(..., description="Path relative to the agent's workspace directory, or an absolute path.")
|
|
256
|
+
offset: int = Field(0, ge=0, description="Number of lines to skip before reading (0-based).")
|
|
257
|
+
count: int = Field(
|
|
258
|
+
config.MAX_READ_LINES,
|
|
259
|
+
ge=1,
|
|
260
|
+
description=f"Number of lines to read. Clamped to {config.MAX_READ_LINES} if higher.",
|
|
261
|
+
)
|
|
262
|
+
|
|
263
|
+
|
|
264
|
+
READ_TOOL_SCHEMA = {
|
|
265
|
+
"name": "read",
|
|
266
|
+
"description": (
|
|
267
|
+
"Read the contents of a file. For rich formats (PDF, DOCX, PPTX, "
|
|
268
|
+
"XLSX, HTML, etc.) the content is converted to markdown first. "
|
|
269
|
+
"Use offset and count to page through large files. Output is "
|
|
270
|
+
f"limited to {config.MAX_READ_LINES} lines or {config.MAX_READ_CHARS} "
|
|
271
|
+
"characters, whichever comes first."
|
|
272
|
+
),
|
|
273
|
+
"input_schema": ReadFileParams.model_json_schema(),
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
|
|
277
|
+
def _read_rich(resolved_path: str) -> str:
|
|
278
|
+
"""Convert a rich-format file to markdown via markitdown.
|
|
279
|
+
|
|
280
|
+
markitdown is an OPTIONAL extra since #144: this function is its only
|
|
281
|
+
consumer, it sits behind `read`, and `read` is globally denied and
|
|
282
|
+
cannot be re-enabled at runtime -- so a default install carries neither
|
|
283
|
+
it nor its eleven transitive distributions. Anyone who reaches here has
|
|
284
|
+
enabled `read` in config.py, and the bare ModuleNotFoundError would name
|
|
285
|
+
a package they never asked for and cannot place.
|
|
286
|
+
"""
|
|
287
|
+
try:
|
|
288
|
+
from markitdown import MarkItDown
|
|
289
|
+
except ImportError as e:
|
|
290
|
+
raise RuntimeError(
|
|
291
|
+
f"Reading {os.path.basename(resolved_path)} needs the optional "
|
|
292
|
+
f"`markitdown` dependency, which a default install does not "
|
|
293
|
+
f"carry (it serves only this path, behind the globally-denied "
|
|
294
|
+
f"`read` tool). Install it with: pip install -e \".[documents]\""
|
|
295
|
+
) from e
|
|
296
|
+
md = MarkItDown()
|
|
297
|
+
result = md.convert(resolved_path)
|
|
298
|
+
return result.text_content
|
|
299
|
+
|
|
300
|
+
|
|
301
|
+
def _truncate_lines(
|
|
302
|
+
lines: list[str],
|
|
303
|
+
offset: int,
|
|
304
|
+
count: int,
|
|
305
|
+
) -> tuple[str, int, bool, Optional[str]]:
|
|
306
|
+
"""Apply offset, clamp count, then cut at a LINE BOUNDARY.
|
|
307
|
+
|
|
308
|
+
Returns (content, lines_returned, truncated, message), where
|
|
309
|
+
`lines_returned` counts the lines that are IN `content`.
|
|
310
|
+
|
|
311
|
+
THE CUT NOW HAPPENS BEFORE THE COUNT (batch 146). It used to be the
|
|
312
|
+
other way round: `lines_returned` was computed from the selection and
|
|
313
|
+
the character cut threw most of it away afterwards, so on any file
|
|
314
|
+
averaging over 100 characters a line the number the model resumes from
|
|
315
|
+
named a line far past the last one delivered. Measured on 800 lines of
|
|
316
|
+
160 characters: 500 reported, 313 delivered, and `offset=500` -- which
|
|
317
|
+
the clamp branch's own message tells the model to use -- skipped 187
|
|
318
|
+
lines and 29,920 characters that no call it could construct would ever
|
|
319
|
+
return.
|
|
320
|
+
|
|
321
|
+
Cutting at a line boundary rather than mid-line is what makes every
|
|
322
|
+
byte reachable, since `offset` and `count` are in LINES and the ceiling
|
|
323
|
+
is in characters. The sibling in this scope had already reached the
|
|
324
|
+
other half of this: "the continuation offset is IN the message, not
|
|
325
|
+
merely implied by the numbers. A model that has to compute where to
|
|
326
|
+
resume usually re-reads from zero and spends the budget twice"
|
|
327
|
+
(project_docs.read_run). One resume point, named once, for both
|
|
328
|
+
branches -- the clamp message used to carry its own and they disagreed.
|
|
329
|
+
"""
|
|
330
|
+
clamped = count > config.MAX_READ_LINES
|
|
331
|
+
effective_count = min(count, config.MAX_READ_LINES)
|
|
332
|
+
|
|
333
|
+
selected = lines[offset:offset + effective_count]
|
|
334
|
+
|
|
335
|
+
kept: list[str] = []
|
|
336
|
+
used = 0
|
|
337
|
+
cut_inside_a_line = False
|
|
338
|
+
for line in selected:
|
|
339
|
+
extra = len(line) + (1 if kept else 0) # the joining newline
|
|
340
|
+
if used + extra > config.MAX_READ_CHARS:
|
|
341
|
+
if not kept:
|
|
342
|
+
# A SINGLE LINE LONGER THAN THE WHOLE CEILING -- minified
|
|
343
|
+
# JavaScript, a one-line JSON document, a packed asset.
|
|
344
|
+
# Keeping whole lines only would deliver NOTHING here and
|
|
345
|
+
# the model would have nowhere to go, so this one line is
|
|
346
|
+
# cut and the message says so: `offset + 1` resumes at the
|
|
347
|
+
# next line, and the rest of this one is not reachable
|
|
348
|
+
# through a tool whose paging unit is a line.
|
|
349
|
+
kept.append(line[:config.MAX_READ_CHARS])
|
|
350
|
+
cut_inside_a_line = True
|
|
351
|
+
break
|
|
352
|
+
kept.append(line)
|
|
353
|
+
used += extra
|
|
354
|
+
|
|
355
|
+
content = "\n".join(kept)
|
|
356
|
+
lines_returned = len(kept)
|
|
357
|
+
char_cut = cut_inside_a_line or len(kept) < len(selected)
|
|
358
|
+
truncated = clamped or char_cut
|
|
359
|
+
|
|
360
|
+
message_parts: list[str] = []
|
|
361
|
+
if clamped:
|
|
362
|
+
message_parts.append(
|
|
363
|
+
f"Requested {count} lines, returned at most {effective_count} "
|
|
364
|
+
f"(maximum)."
|
|
365
|
+
)
|
|
366
|
+
if char_cut:
|
|
367
|
+
message_parts.append(
|
|
368
|
+
f"Content truncated at {config.MAX_READ_CHARS} characters, on a "
|
|
369
|
+
f"line boundary."
|
|
370
|
+
)
|
|
371
|
+
if cut_inside_a_line:
|
|
372
|
+
message_parts.append(
|
|
373
|
+
f"Line {offset} is itself longer than "
|
|
374
|
+
f"{config.MAX_READ_CHARS} characters and was cut, so the rest of "
|
|
375
|
+
f"it is not reachable by offset."
|
|
376
|
+
)
|
|
377
|
+
if truncated:
|
|
378
|
+
message_parts.append(
|
|
379
|
+
f"Use offset={offset + lines_returned} to read further."
|
|
380
|
+
)
|
|
381
|
+
|
|
382
|
+
message = " ".join(message_parts) if message_parts else None
|
|
383
|
+
return content, lines_returned, truncated, message
|
|
384
|
+
|
|
385
|
+
|
|
386
|
+
def read_run(params: dict) -> dict:
|
|
387
|
+
parsed = ReadFileParams(**params)
|
|
388
|
+
refused = _protected_path_error(parsed.path)
|
|
389
|
+
if refused is not None:
|
|
390
|
+
return {"error": refused}
|
|
391
|
+
resolved = resolve_path(parsed.path)
|
|
392
|
+
|
|
393
|
+
if not os.path.exists(resolved):
|
|
394
|
+
return {"error": f"No such file or directory: {parsed.path}"}
|
|
395
|
+
if not os.path.isfile(resolved):
|
|
396
|
+
return {"error": f"Not a regular file: {parsed.path}"}
|
|
397
|
+
|
|
398
|
+
file_size = os.path.getsize(resolved)
|
|
399
|
+
if file_size > config.MAX_FILE_SIZE_BYTES:
|
|
400
|
+
return {
|
|
401
|
+
"error": (
|
|
402
|
+
f"File size ({file_size} bytes) exceeds the maximum "
|
|
403
|
+
f"readable size ({config.MAX_FILE_SIZE_BYTES} bytes)."
|
|
404
|
+
),
|
|
405
|
+
}
|
|
406
|
+
|
|
407
|
+
ext = os.path.splitext(resolved)[1].lower()
|
|
408
|
+
|
|
409
|
+
try:
|
|
410
|
+
if ext in _RICH_EXTENSIONS:
|
|
411
|
+
raw_text = _read_rich(resolved)
|
|
412
|
+
all_lines = raw_text.splitlines()
|
|
413
|
+
else:
|
|
414
|
+
with open(resolved, encoding="utf-8", errors="replace") as f:
|
|
415
|
+
all_lines = f.read().splitlines()
|
|
416
|
+
except Exception as e:
|
|
417
|
+
logger.exception("read tool failed on %s", parsed.path)
|
|
418
|
+
return {"error": f"Could not read file: {e}"}
|
|
419
|
+
|
|
420
|
+
content, lines_returned, truncated, message = _truncate_lines(
|
|
421
|
+
all_lines, parsed.offset, parsed.count,
|
|
422
|
+
)
|
|
423
|
+
|
|
424
|
+
result: dict = {
|
|
425
|
+
"content": content,
|
|
426
|
+
"lines_returned": lines_returned,
|
|
427
|
+
"offset": parsed.offset,
|
|
428
|
+
"truncated": truncated,
|
|
429
|
+
}
|
|
430
|
+
if message:
|
|
431
|
+
result["message"] = message
|
|
432
|
+
return result
|
|
433
|
+
|
|
434
|
+
|
|
435
|
+
# ===========================================================================
|
|
436
|
+
# ---- WRITE ----------------------------------------------------------------
|
|
437
|
+
# ===========================================================================
|
|
438
|
+
|
|
439
|
+
class WriteFileParams(BaseModel):
|
|
440
|
+
path: str = Field(..., description="Path relative to the agent's workspace directory, or an absolute path.")
|
|
441
|
+
content: str = Field(..., description="Full content to write — overwrites any existing file.")
|
|
442
|
+
|
|
443
|
+
|
|
444
|
+
WRITE_TOOL_SCHEMA = {
|
|
445
|
+
"name": "write",
|
|
446
|
+
"description": (
|
|
447
|
+
"Create or overwrite a file. Parent directories are created "
|
|
448
|
+
"automatically. Content size is limited to "
|
|
449
|
+
f"{config.MAX_FILE_SIZE_BYTES} bytes."
|
|
450
|
+
),
|
|
451
|
+
"input_schema": WriteFileParams.model_json_schema(),
|
|
452
|
+
}
|
|
453
|
+
|
|
454
|
+
|
|
455
|
+
def write_run(params: dict) -> dict:
|
|
456
|
+
parsed = WriteFileParams(**params)
|
|
457
|
+
|
|
458
|
+
# BEFORE anything creates a directory: a refused write must not
|
|
459
|
+
# conjure the protected directory into existence on its way to being
|
|
460
|
+
# refused. The makedirs moved into `write_text_atomic` in batch 146 and
|
|
461
|
+
# the ordering it needs did not move with it, which is why this says
|
|
462
|
+
# what it protects rather than naming a line below.
|
|
463
|
+
refused = _protected_path_error(parsed.path)
|
|
464
|
+
if refused is not None:
|
|
465
|
+
return {"error": refused}
|
|
466
|
+
|
|
467
|
+
content_bytes = parsed.content.encode("utf-8")
|
|
468
|
+
if len(content_bytes) > config.MAX_FILE_SIZE_BYTES:
|
|
469
|
+
return {
|
|
470
|
+
"error": (
|
|
471
|
+
f"Content size ({len(content_bytes)} bytes) exceeds the "
|
|
472
|
+
f"maximum writable size ({config.MAX_FILE_SIZE_BYTES} bytes)."
|
|
473
|
+
),
|
|
474
|
+
}
|
|
475
|
+
|
|
476
|
+
resolved = resolve_path(parsed.path)
|
|
477
|
+
|
|
478
|
+
try:
|
|
479
|
+
# newline="" and a replace rather than a truncating write -- the
|
|
480
|
+
# module docstring's BYTES section says what each buys, and
|
|
481
|
+
# `write_text_atomic` says why it owns both.
|
|
482
|
+
created = not os.path.exists(resolved)
|
|
483
|
+
write_text_atomic(resolved, parsed.content)
|
|
484
|
+
except Exception as e:
|
|
485
|
+
logger.exception("write tool failed on %s", parsed.path)
|
|
486
|
+
return {"error": f"Could not write file: {e}"}
|
|
487
|
+
|
|
488
|
+
if created:
|
|
489
|
+
from core.file_mentions import note_file_created
|
|
490
|
+
|
|
491
|
+
note_file_created(resolved)
|
|
492
|
+
return {"result": f"Wrote {len(parsed.content)} characters to {parsed.path}"}
|
|
493
|
+
|
|
494
|
+
|
|
495
|
+
# ===========================================================================
|
|
496
|
+
# ---- EDIT -----------------------------------------------------------------
|
|
497
|
+
# ===========================================================================
|
|
498
|
+
|
|
499
|
+
class EditFileParams(BaseModel):
|
|
500
|
+
path: str = Field(..., description="Path relative to the agent's workspace directory, or an absolute path.")
|
|
501
|
+
old_text: str = Field(..., description="Exact text to replace — must appear EXACTLY ONCE in the file.")
|
|
502
|
+
new_text: str = Field(..., description="Replacement text.")
|
|
503
|
+
|
|
504
|
+
|
|
505
|
+
EDIT_TOOL_SCHEMA = {
|
|
506
|
+
"name": "edit",
|
|
507
|
+
"description": (
|
|
508
|
+
"Replace an exact, uniquely-matching span of text within an "
|
|
509
|
+
"existing file. old_text must appear exactly once; if it appears "
|
|
510
|
+
"zero or more than one time the edit is rejected with an error."
|
|
511
|
+
),
|
|
512
|
+
"input_schema": EditFileParams.model_json_schema(),
|
|
513
|
+
}
|
|
514
|
+
|
|
515
|
+
|
|
516
|
+
def edit_run(params: dict) -> dict:
|
|
517
|
+
parsed = EditFileParams(**params)
|
|
518
|
+
refused = _protected_path_error(parsed.path)
|
|
519
|
+
if refused is not None:
|
|
520
|
+
return {"error": refused}
|
|
521
|
+
resolved = resolve_path(parsed.path)
|
|
522
|
+
|
|
523
|
+
if not os.path.isfile(resolved):
|
|
524
|
+
return {"error": f"No such file: {parsed.path}"}
|
|
525
|
+
|
|
526
|
+
# ROADMAP_v2 §31 (H7), #55. read_run has had this check since the
|
|
527
|
+
# beginning and this module's own docstring gives the reason --
|
|
528
|
+
# "rejected before opening to prevent memory exhaustion" -- while
|
|
529
|
+
# the sibling twenty lines down read whatever it was pointed at.
|
|
530
|
+
# Measured on a 30 MB file: 60 MB of peak traced memory to answer
|
|
531
|
+
# "old_text not found in file."
|
|
532
|
+
#
|
|
533
|
+
# Copied rather than reinvented, down to the wording, so the two
|
|
534
|
+
# paths refuse identically. A caller that learns what `read` rejects
|
|
535
|
+
# now knows what `edit` rejects.
|
|
536
|
+
file_size = os.path.getsize(resolved)
|
|
537
|
+
if file_size > config.MAX_FILE_SIZE_BYTES:
|
|
538
|
+
return {
|
|
539
|
+
"error": (
|
|
540
|
+
f"File size ({file_size} bytes) exceeds the maximum "
|
|
541
|
+
f"editable size ({config.MAX_FILE_SIZE_BYTES} bytes)."
|
|
542
|
+
),
|
|
543
|
+
}
|
|
544
|
+
|
|
545
|
+
try:
|
|
546
|
+
# newline="" so `content` holds the file's REAL line endings and the
|
|
547
|
+
# uniqueness contract is checked against the bytes on disk. With
|
|
548
|
+
# universal newlines a CRLF file arrived as LF, and writing that
|
|
549
|
+
# back converted the whole file -- which is the defect this fixes,
|
|
550
|
+
# pointing the other way.
|
|
551
|
+
with open(resolved, encoding="utf-8", newline="") as f:
|
|
552
|
+
content = f.read()
|
|
553
|
+
except Exception as e:
|
|
554
|
+
logger.exception("edit tool read failed on %s", parsed.path)
|
|
555
|
+
return {"error": f"Could not read file: {e}"}
|
|
556
|
+
|
|
557
|
+
old_text, new_text = parsed.old_text, parsed.new_text
|
|
558
|
+
match_count = content.count(old_text)
|
|
559
|
+
if match_count == 0 and "\n" in old_text:
|
|
560
|
+
# TRANSLATED AND RETRIED, because the model cannot see what it
|
|
561
|
+
# would have to spell. `read` joins the lines it delivers with
|
|
562
|
+
# "\n" whatever the file held, so a span copied from what the
|
|
563
|
+
# model was shown is LF-spelled even for a CRLF file -- and a
|
|
564
|
+
# strict matcher would refuse every multi-line edit of one, with a
|
|
565
|
+
# message naming text the model has no way to produce. Both sides
|
|
566
|
+
# move together so the replacement carries the file's endings too.
|
|
567
|
+
crlf_old = old_text.replace("\n", "\r\n")
|
|
568
|
+
crlf_count = content.count(crlf_old)
|
|
569
|
+
if crlf_count:
|
|
570
|
+
old_text = crlf_old
|
|
571
|
+
new_text = new_text.replace("\n", "\r\n")
|
|
572
|
+
match_count = crlf_count
|
|
573
|
+
|
|
574
|
+
if match_count == 0:
|
|
575
|
+
return {"error": "old_text not found in file."}
|
|
576
|
+
if match_count > 1:
|
|
577
|
+
return {
|
|
578
|
+
"error": (
|
|
579
|
+
f"old_text appears {match_count} times — must be unique. "
|
|
580
|
+
"Include more surrounding context to narrow the match."
|
|
581
|
+
),
|
|
582
|
+
}
|
|
583
|
+
|
|
584
|
+
content = content.replace(old_text, new_text)
|
|
585
|
+
|
|
586
|
+
try:
|
|
587
|
+
write_text_atomic(resolved, content)
|
|
588
|
+
except Exception as e:
|
|
589
|
+
logger.exception("edit tool write failed on %s", parsed.path)
|
|
590
|
+
return {"error": f"Could not write file: {e}"}
|
|
591
|
+
|
|
592
|
+
return {"result": f"Replaced 1 occurrence in {parsed.path}"}
|
|
593
|
+
|
|
594
|
+
|
|
595
|
+
# ===========================================================================
|
|
596
|
+
# ---- VIEW_IMAGE (ROADMAP_v3 §81) ------------------------------------------
|
|
597
|
+
# ===========================================================================
|
|
598
|
+
|
|
599
|
+
#: What both wires §81 delivers to accept as a base64 image: Anthropic's
|
|
600
|
+
#: image block and the OpenAI-compatible `image_url` part (IM7). Google, a wire
|
|
601
|
+
#: since batch 173, is sent three of them and gets a note for GIF (IM10). Judged from
|
|
602
|
+
#: the file's own leading bytes, never its extension -- a PNG renamed `.jpg`
|
|
603
|
+
#: is a PNG, and declaring the wrong media type is a request the provider
|
|
604
|
+
#: rejects.
|
|
605
|
+
_IMAGE_SIGNATURES = (
|
|
606
|
+
(b"\x89PNG\r\n\x1a\n", "image/png"),
|
|
607
|
+
(b"\xff\xd8\xff", "image/jpeg"),
|
|
608
|
+
(b"GIF87a", "image/gif"),
|
|
609
|
+
(b"GIF89a", "image/gif"),
|
|
610
|
+
)
|
|
611
|
+
|
|
612
|
+
|
|
613
|
+
def _image_media_type(head: bytes) -> Optional[str]:
|
|
614
|
+
"""The media type *head* (a file's first bytes) declares, or None."""
|
|
615
|
+
for signature, media_type in _IMAGE_SIGNATURES:
|
|
616
|
+
if head.startswith(signature):
|
|
617
|
+
return media_type
|
|
618
|
+
# WEBP is a RIFF container: "RIFF", a four-byte length, then "WEBP".
|
|
619
|
+
if head[:4] == b"RIFF" and head[8:12] == b"WEBP":
|
|
620
|
+
return "image/webp"
|
|
621
|
+
return None
|
|
622
|
+
|
|
623
|
+
|
|
624
|
+
class ViewImageParams(BaseModel):
|
|
625
|
+
path: str = Field(..., description="Path to a PNG, JPEG, GIF or WEBP file, relative to the agent's workspace directory, or an absolute path.")
|
|
626
|
+
|
|
627
|
+
|
|
628
|
+
VIEW_IMAGE_TOOL_SCHEMA = {
|
|
629
|
+
"name": "view_image",
|
|
630
|
+
"description": (
|
|
631
|
+
"Look at an image file. The image itself is attached to the result, "
|
|
632
|
+
"so you see the picture rather than a description of it. PNG, JPEG, "
|
|
633
|
+
f"GIF and WEBP, up to {config.MAX_IMAGE_BYTES} bytes. For text and "
|
|
634
|
+
"documents use read."
|
|
635
|
+
),
|
|
636
|
+
"input_schema": ViewImageParams.model_json_schema(),
|
|
637
|
+
}
|
|
638
|
+
|
|
639
|
+
|
|
640
|
+
def view_image_run(params: dict, memory=None, call_id=None,
|
|
641
|
+
parent_run=None) -> dict:
|
|
642
|
+
"""Read an image off disk and attach it to this call's result (IM1).
|
|
643
|
+
|
|
644
|
+
The RESULT is text -- it names what was attached -- and the bytes go to
|
|
645
|
+
`memory.attach_image`, which writes them into the same row as that
|
|
646
|
+
result (IM3). They never ride in the returned dict, so the output
|
|
647
|
+
redactor, the tool_result event and both shells' transcripts see only
|
|
648
|
+
the sentence.
|
|
649
|
+
|
|
650
|
+
The path rules are `read`'s exactly: the same `_refusal_for` and
|
|
651
|
+
`_file_approval_check`, and the protected segment re-tested here as all
|
|
652
|
+
three file tools re-test it.
|
|
653
|
+
"""
|
|
654
|
+
parsed = ViewImageParams(**params)
|
|
655
|
+
refused = _protected_path_error(parsed.path)
|
|
656
|
+
if refused is not None:
|
|
657
|
+
return {"error": refused}
|
|
658
|
+
# THE RUN'S OWN ANSWER (IM6), computed once by the loop and read by the
|
|
659
|
+
# schema list too, so the two cannot disagree. The schema list already
|
|
660
|
+
# left this tool out when it is False; this is the backstop for a call
|
|
661
|
+
# made anyway, by a model naming a tool it was not offered.
|
|
662
|
+
if parent_run is None or not getattr(parent_run, "images", False):
|
|
663
|
+
return {"error": (
|
|
664
|
+
"view_image is not available in this run: either the provider "
|
|
665
|
+
"is not marked `accepts_images` in providers.json, or this is a "
|
|
666
|
+
"research pass, which does not take images."
|
|
667
|
+
)}
|
|
668
|
+
if memory is None or call_id is None:
|
|
669
|
+
return {"error": "view_image has no conversation to attach the image to."}
|
|
670
|
+
|
|
671
|
+
resolved = resolve_path(parsed.path)
|
|
672
|
+
if not os.path.exists(resolved):
|
|
673
|
+
return {"error": f"No such file or directory: {parsed.path}"}
|
|
674
|
+
if not os.path.isfile(resolved):
|
|
675
|
+
return {"error": f"Not a regular file: {parsed.path}"}
|
|
676
|
+
file_size = os.path.getsize(resolved)
|
|
677
|
+
if file_size > config.MAX_IMAGE_BYTES:
|
|
678
|
+
return {"error": (
|
|
679
|
+
f"Image size ({file_size} bytes) exceeds the maximum attachable "
|
|
680
|
+
f"size ({config.MAX_IMAGE_BYTES} bytes)."
|
|
681
|
+
)}
|
|
682
|
+
try:
|
|
683
|
+
# One byte past the cap, so a file that grew after the size check
|
|
684
|
+
# is refused rather than read without a bound.
|
|
685
|
+
with open(resolved, "rb") as f:
|
|
686
|
+
raw = f.read(config.MAX_IMAGE_BYTES + 1)
|
|
687
|
+
except OSError as e:
|
|
688
|
+
logger.exception("view_image failed on %s", parsed.path)
|
|
689
|
+
return {"error": f"Could not read file: {e}"}
|
|
690
|
+
if len(raw) > config.MAX_IMAGE_BYTES:
|
|
691
|
+
return {"error": (
|
|
692
|
+
f"Image exceeds the maximum attachable size "
|
|
693
|
+
f"({config.MAX_IMAGE_BYTES} bytes)."
|
|
694
|
+
)}
|
|
695
|
+
|
|
696
|
+
media_type = _image_media_type(raw[:12])
|
|
697
|
+
if media_type is None:
|
|
698
|
+
return {"error": (
|
|
699
|
+
f"{parsed.path} is not a PNG, JPEG, GIF or WEBP image (judged by "
|
|
700
|
+
f"its contents, not its name)."
|
|
701
|
+
)}
|
|
702
|
+
memory.attach_image(call_id, media_type,
|
|
703
|
+
base64.b64encode(raw).decode("ascii"))
|
|
704
|
+
return {"content": f"Attached {parsed.path} ({media_type}, {len(raw)} bytes)."}
|
|
705
|
+
|
|
706
|
+
|
|
707
|
+
# ===========================================================================
|
|
708
|
+
# ---- What each tool takes -------------------------------------------------
|
|
709
|
+
# ===========================================================================
|
|
710
|
+
|
|
711
|
+
#: Read by `_refusal_for`, so the pre-approval check validates against the
|
|
712
|
+
#: same model the handler does. At the BOTTOM because all three classes have
|
|
713
|
+
#: to exist first, and looked up inside the closure rather than captured, so
|
|
714
|
+
#: there is no import-order question to get wrong.
|
|
715
|
+
_PARAM_MODELS = {
|
|
716
|
+
"read": ReadFileParams,
|
|
717
|
+
"write": WriteFileParams,
|
|
718
|
+
"edit": EditFileParams,
|
|
719
|
+
"view_image": ViewImageParams,
|
|
720
|
+
}
|