@yahyahammad/venastine 0.2.0 → 0.3.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (152) hide show
  1. package/.env.example +9 -4
  2. package/CONFIG_ARCHITECTURE.md +2030 -0
  3. package/LICENSE +201 -201
  4. package/NOTICE +1 -1
  5. package/README.md +1034 -895
  6. package/agents/builtin/build.md +73 -0
  7. package/agents/builtin/compactor.md +75 -75
  8. package/agents/builtin/explore.md +77 -77
  9. package/agents/builtin/general.md +80 -0
  10. package/agents/builtin/pipeline-reviewer.md +100 -100
  11. package/agents/builtin/plan.md +106 -88
  12. package/agents/builtin/review.md +74 -74
  13. package/agents/builtin/test.md +65 -0
  14. package/agents/builtin/writer.md +67 -0
  15. package/agents/manager.py +68 -2
  16. package/agents/subagent_tool.py +472 -238
  17. package/agents/tui_commands.py +238 -151
  18. package/bin/venastine.mjs +150 -4
  19. package/bin/venastine.py +71 -0
  20. package/cli_commands.py +838 -0
  21. package/config.py +95 -1198
  22. package/config.yaml +1103 -0
  23. package/config_edit.py +1301 -0
  24. package/config_schema.py +971 -0
  25. package/config_update.py +749 -0
  26. package/core/agent_activity.py +256 -118
  27. package/core/ansi.py +452 -0
  28. package/core/approval.py +137 -115
  29. package/core/call_view.py +364 -0
  30. package/core/cancel.py +121 -0
  31. package/core/chatgpt_auth.py +747 -0
  32. package/core/claims_view.py +107 -0
  33. package/core/client.py +2715 -1559
  34. package/core/commands.py +460 -0
  35. package/core/compaction.py +1735 -971
  36. package/core/config_loader.py +1982 -1563
  37. package/core/connect.py +686 -0
  38. package/core/events.py +123 -61
  39. package/core/file_mentions.py +280 -0
  40. package/core/interaction.py +411 -328
  41. package/core/line_pattern.py +128 -0
  42. package/core/loop.py +2566 -1490
  43. package/core/memory.py +482 -370
  44. package/core/pipeline_models.py +190 -176
  45. package/core/provider_errors.py +234 -0
  46. package/core/reasoning/authorization.py +130 -130
  47. package/core/reasoning/base.py +219 -219
  48. package/core/reasoning/confidence_scoring.py +484 -468
  49. package/core/reasoning/events.py +149 -149
  50. package/core/reasoning/json_retry.py +19 -1
  51. package/core/reasoning/orchestrator.py +1561 -1382
  52. package/core/reasoning/output_writer.py +345 -286
  53. package/core/reasoning/payload_validation.py +524 -398
  54. package/core/reasoning/pipeline_storage.py +88 -22
  55. package/core/reasoning/review.py +659 -615
  56. package/core/reasoning/scholar.py +458 -434
  57. package/core/reasoning/source_corpus.py +433 -327
  58. package/core/reasoning/source_scoring.py +855 -855
  59. package/core/replay.py +315 -183
  60. package/core/session.py +36 -12
  61. package/core/session_view.py +259 -0
  62. package/core/session_wake.py +259 -0
  63. package/core/shell_sessions.py +1553 -0
  64. package/core/workspace_trust.py +1 -1
  65. package/credentials.py +148 -20
  66. package/database.py +333 -252
  67. package/{PRIVACY.md → docs/PRIVACY.md} +78 -66
  68. package/docs/SECURITY.md +108 -0
  69. package/docs/THIRD_PARTY_NOTICES.md +148 -0
  70. package/env_secrets.py +50 -9
  71. package/json_store.py +343 -123
  72. package/logging_setup.py +295 -185
  73. package/main.py +3433 -1961
  74. package/mcp_client/client.py +733 -499
  75. package/mcp_client/config.py +126 -21
  76. package/mcp_client/registration.py +343 -182
  77. package/memories/manager.py +147 -132
  78. package/memories/tui_commands.py +319 -244
  79. package/package.json +303 -73
  80. package/project_init/config_files.py +282 -278
  81. package/project_init/generator.py +728 -564
  82. package/project_init/manifest.py +18 -6
  83. package/project_init/tui_commands.py +147 -144
  84. package/prompts/critic_pass.md +24 -24
  85. package/prompts/revalidate.md +25 -25
  86. package/prompts/revise.md +2 -0
  87. package/prompts/source_grounding.md +66 -66
  88. package/prompts/system_prompts.py +316 -262
  89. package/providers.json.example +4 -2
  90. package/pyproject.toml +149 -100
  91. package/requirements.txt +295 -72
  92. package/safety/policy_enforcement.py +1082 -746
  93. package/security/askpass.py +419 -0
  94. package/security/capability.py +207 -177
  95. package/security/confine.py +484 -0
  96. package/security/hosted.py +182 -0
  97. package/security/permissions.py +237 -190
  98. package/security/posture.py +124 -12
  99. package/security/protected_paths.py +501 -309
  100. package/security/sandbox.py +4108 -985
  101. package/security/secrets.py +855 -0
  102. package/skills/builtin/math/formal-specification.md +67 -67
  103. package/skills/builtin/math/numerical-methods.md +66 -66
  104. package/skills/builtin/research/experiment-design.md +62 -62
  105. package/skills/builtin/research/reproducibility.md +55 -55
  106. package/skills/builtin/research/source-evaluation.md +70 -70
  107. package/skills/builtin/research/statistical-inference.md +63 -63
  108. package/skills/builtin/research/technical-writing.md +59 -59
  109. package/skills/builtin/software/code-review.md +61 -61
  110. package/skills/builtin/software/debugging.md +61 -61
  111. package/skills/builtin/software/test-design.md +67 -67
  112. package/skills/tui_commands.py +110 -111
  113. package/storage.py +1338 -1005
  114. package/tools/base.py +161 -1
  115. package/tools/builtin/_math_common.py +667 -377
  116. package/tools/builtin/_net_common.py +225 -19
  117. package/tools/builtin/arxiv.py +497 -39
  118. package/tools/builtin/ask_user.py +231 -213
  119. package/tools/builtin/discrete_math.py +35 -4
  120. package/tools/builtin/fetch_url.py +371 -153
  121. package/tools/builtin/file_ops.py +720 -412
  122. package/tools/builtin/geometry.py +48 -12
  123. package/tools/builtin/get_time.py +2 -2
  124. package/tools/builtin/linear_algebra.py +66 -23
  125. package/tools/builtin/load_skill.py +76 -66
  126. package/tools/builtin/logic.py +171 -12
  127. package/tools/builtin/pin.py +227 -193
  128. package/tools/builtin/probability_stats.py +12 -16
  129. package/tools/builtin/project_docs.py +464 -405
  130. package/tools/builtin/remember.py +175 -158
  131. package/tools/builtin/shell.py +980 -461
  132. package/tools/builtin/shell_sessions.py +613 -0
  133. package/tools/builtin/symbolic_math.py +80 -10
  134. package/tools/builtin/todo.py +149 -147
  135. package/tools/builtin/web_search.py +191 -13
  136. package/tools/context.py +159 -136
  137. package/tools/isolation.py +107 -34
  138. package/tools/registry.py +1242 -925
  139. package/tui/app.py +8318 -4100
  140. package/tui/app.tcss +747 -556
  141. package/tui/commands.py +26 -170
  142. package/tui/diffs.py +34 -13
  143. package/tui/history.py +128 -128
  144. package/tui/hosted_driver.py +102 -0
  145. package/tui/markdown.py +1329 -1279
  146. package/tui/meters.py +364 -268
  147. package/tui/ravens.py +146 -146
  148. package/tui/screens.py +1255 -943
  149. package/tui/themes.py +599 -559
  150. package/tui/widgets.py +3813 -2332
  151. package/SECURITY.md +0 -88
  152. package/THIRD_PARTY_NOTICES.md +0 -100
@@ -1,412 +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
- SECURITY MODEL (ROADMAP §6, deviated per user decision):
11
- Paths within WORKSPACE_DIR are auto-approved (unless the matching
12
- ToolApprovals boolean is True, which forces approval even inside the
13
- workspace). Paths outside WORKSPACE_DIR always require user approval
14
- — they are NOT hard-rejected, so an operator can grant one-off access
15
- to files outside the workspace. Symlinks and '..' segments are always
16
- resolved via os.path.realpath before any check, so a path that looks
17
- inside the workspace but resolves outside it is treated as outside.
18
-
19
- PROTECTED SEGMENTS (security/protected_paths.py) are the one hard
20
- deny, and the exception to both rules above: any path -- inside or
21
- outside the workspace -- that resolves into `.venastine/` is refused
22
- by the refusal_check before approval and re-tested in all three
23
- handlers, whatever the ToolApprovals booleans say.
24
-
25
- READ TOOL PAGINATION (deviated from ROADMAP §6):
26
- The read tool accepts offset (lines to skip) and count (lines to
27
- read). count is clamped to config.MAX_READ_LINES with a note in the
28
- response (not a hard error). Output is also truncated at
29
- config.MAX_READ_CHARS with a note. Files larger than
30
- config.MAX_FILE_SIZE_BYTES are rejected before opening to prevent
31
- memory exhaustion (especially on the markitdown path, which loads
32
- the whole file).
33
-
34
- RICH FORMAT SUPPORT (deviated from ROADMAP §6):
35
- For binary/rich extensions (.pdf, .docx, .pptx, etc.) the read tool
36
- uses markitdown to convert to markdown before applying line/char
37
- truncation. Plain-text extensions use open() directly.
38
- """
39
-
40
- from __future__ import annotations
41
-
42
- import logging
43
- import os
44
- from typing import Optional
45
-
46
- from pydantic import BaseModel, Field
47
-
48
- import config
49
-
50
- from security.protected_paths import protected_segment
51
-
52
- logger = logging.getLogger(__name__)
53
-
54
- # ---------------------------------------------------------------------------
55
- # ---- Path helpers ---------------------------------------------------------
56
- # ---------------------------------------------------------------------------
57
-
58
- WORKSPACE_ROOT = os.path.realpath(config.WORKSPACE_DIR)
59
-
60
- _RICH_EXTENSIONS = frozenset({
61
- ".pdf", ".docx", ".pptx", ".xlsx", ".xls",
62
- ".html", ".htm", ".epub", ".ipynb",
63
- })
64
-
65
-
66
- def resolve_path(user_path: str) -> str:
67
- """Resolve *user_path* relative to WORKSPACE_ROOT via realpath.
68
-
69
- Handles ``..`` segments and symlinks. Does NOT reject paths that
70
- land outside the workspace — that decision belongs to the approval
71
- layer (``_file_approval_check``), not to path resolution.
72
-
73
- PUBLIC since batch 41 (X4). The TUI has to read the file a `write`
74
- or an `edit` is about to change in order to show the diff, and it
75
- must land on the same file the tool will — a second
76
- ``os.path.join(WORKSPACE_ROOT, ...)`` at the call site is this
77
- project's canonical producer/consumer bug, and here it would mean a
78
- diff of one file beside an edit to another.
79
- """
80
- return os.path.realpath(os.path.join(WORKSPACE_ROOT, user_path))
81
-
82
-
83
- def _is_within_workspace(user_path: str) -> bool:
84
- resolved = resolve_path(user_path)
85
- return resolved == WORKSPACE_ROOT or resolved.startswith(WORKSPACE_ROOT + os.sep)
86
-
87
-
88
- def _file_approval_check(tool_name: str, params: dict) -> bool:
89
- """Path-dependent approval policy for read / write / edit.
90
-
91
- Outside workspace → always True (ask user).
92
- Within workspace → defer to the matching ToolApprovals boolean
93
- (False = auto-approved, True = still ask).
94
- """
95
- path = params.get("path", "")
96
- if not _is_within_workspace(path):
97
- return True
98
- approvals = config.ToolApprovals()
99
- return getattr(approvals, tool_name, False)
100
-
101
-
102
- # ===========================================================================
103
- # ---- Protected segments (.venastine/) -------------------------------------
104
- # ===========================================================================
105
-
106
- def _protected_path_error(user_path: str) -> Optional[str]:
107
- """Why *user_path* must be refused outright, or None.
108
-
109
- Shared by the refusal_check and all three handlers so the decision
110
- and its wording cannot drift between the pre-approval answer and the
111
- backstop. resolve_path BEFORE the segment test, so `..` travel and a
112
- symlink are caught the same way _is_within_workspace catches them.
113
-
114
- Unconditional on workspace membership, like project_docs'
115
- `_is_readable_doc`: the segment is denied wherever the path lands,
116
- because `.venastine/` holds mcp.json -- which names commands the
117
- harness spawns at startup -- and skills/ and agents/ content that is
118
- injected into system prompts. Workspace membership is the wrong
119
- question here: with AGENT_WORKSPACE pointed at the project the
120
- directory is INSIDE the workspace and _file_approval_check would
121
- auto-approve every call against it.
122
- """
123
- segment = protected_segment(resolve_path(user_path))
124
- if segment is None:
125
- return None
126
- return (
127
- f"Refused: the path resolves into '{segment}/', which holds this "
128
- "harness's own configuration and trust-gated content (settings.json, "
129
- "mcp.json, skills, agents). It is denied however the file tools are "
130
- "called."
131
- )
132
-
133
-
134
- def _protected_refusal(params: dict, _context=None) -> Optional[str]:
135
- """ToolSpec.refusal_check for read / write / edit (§32 A7's shape).
136
-
137
- dispatch() consults this BEFORE the approval gate and returns the
138
- reason as the result, and core/loop.py suppresses the prompt for a
139
- refused call -- nobody is asked a question whose answer cannot
140
- change the outcome. NOT the enforcement (base.py's own words): the
141
- three handlers re-test below, so a caller that reaches them
142
- directly is refused too.
143
- """
144
- return _protected_path_error(params.get("path", ""))
145
-
146
-
147
- # ===========================================================================
148
- # ---- READ -----------------------------------------------------------------
149
- # ===========================================================================
150
-
151
- class ReadFileParams(BaseModel):
152
- path: str = Field(..., description="Path relative to the agent's workspace directory, or an absolute path.")
153
- offset: int = Field(0, ge=0, description="Number of lines to skip before reading (0-based).")
154
- count: int = Field(
155
- config.MAX_READ_LINES,
156
- ge=1,
157
- description=f"Number of lines to read. Clamped to {config.MAX_READ_LINES} if higher.",
158
- )
159
-
160
-
161
- READ_TOOL_SCHEMA = {
162
- "name": "read",
163
- "description": (
164
- "Read the contents of a file. For rich formats (PDF, DOCX, PPTX, "
165
- "XLSX, HTML, etc.) the content is converted to markdown first. "
166
- "Use offset and count to page through large files. Output is "
167
- f"limited to {config.MAX_READ_LINES} lines or {config.MAX_READ_CHARS} "
168
- "characters, whichever comes first."
169
- ),
170
- "input_schema": ReadFileParams.model_json_schema(),
171
- }
172
-
173
-
174
- def _read_rich(resolved_path: str) -> str:
175
- """Convert a rich-format file to markdown via markitdown.
176
-
177
- markitdown is an OPTIONAL extra since #144: this function is its only
178
- consumer, it sits behind `read`, and `read` is globally denied and
179
- cannot be re-enabled at runtime -- so a default install carries neither
180
- it nor its eleven transitive distributions. Anyone who reaches here has
181
- enabled `read` in config.py, and the bare ModuleNotFoundError would name
182
- a package they never asked for and cannot place.
183
- """
184
- try:
185
- from markitdown import MarkItDown
186
- except ImportError as e:
187
- raise RuntimeError(
188
- f"Reading {os.path.basename(resolved_path)} needs the optional "
189
- f"`markitdown` dependency, which a default install does not "
190
- f"carry (it serves only this path, behind the globally-denied "
191
- f"`read` tool). Install it with: pip install -e \".[documents]\""
192
- ) from e
193
- md = MarkItDown()
194
- result = md.convert(resolved_path)
195
- return result.text_content
196
-
197
-
198
- def _truncate_lines(
199
- lines: list[str],
200
- offset: int,
201
- count: int,
202
- ) -> tuple[str, int, bool, Optional[str]]:
203
- """Apply offset, clamp count, join, then char-truncate.
204
-
205
- Returns (content, lines_returned, truncated, message).
206
- """
207
- clamped = count > config.MAX_READ_LINES
208
- effective_count = min(count, config.MAX_READ_LINES)
209
-
210
- selected = lines[offset:offset + effective_count]
211
- lines_returned = len(selected)
212
- content = "\n".join(selected)
213
-
214
- truncated = False
215
- message_parts: list[str] = []
216
-
217
- if clamped:
218
- truncated = True
219
- message_parts.append(
220
- f"Requested {count} lines, returned {effective_count} (maximum). "
221
- f"Use offset={offset + effective_count} to read further."
222
- )
223
-
224
- if len(content) > config.MAX_READ_CHARS:
225
- truncated = True
226
- content = content[:config.MAX_READ_CHARS]
227
- message_parts.append(
228
- f"Content truncated at {config.MAX_READ_CHARS} characters."
229
- )
230
-
231
- message = " ".join(message_parts) if message_parts else None
232
- return content, lines_returned, truncated, message
233
-
234
-
235
- def read_run(params: dict) -> dict:
236
- parsed = ReadFileParams(**params)
237
- refused = _protected_path_error(parsed.path)
238
- if refused is not None:
239
- return {"error": refused}
240
- resolved = resolve_path(parsed.path)
241
-
242
- if not os.path.exists(resolved):
243
- return {"error": f"No such file or directory: {parsed.path}"}
244
- if not os.path.isfile(resolved):
245
- return {"error": f"Not a regular file: {parsed.path}"}
246
-
247
- file_size = os.path.getsize(resolved)
248
- if file_size > config.MAX_FILE_SIZE_BYTES:
249
- return {
250
- "error": (
251
- f"File size ({file_size} bytes) exceeds the maximum "
252
- f"readable size ({config.MAX_FILE_SIZE_BYTES} bytes)."
253
- ),
254
- }
255
-
256
- ext = os.path.splitext(resolved)[1].lower()
257
-
258
- try:
259
- if ext in _RICH_EXTENSIONS:
260
- raw_text = _read_rich(resolved)
261
- all_lines = raw_text.splitlines()
262
- else:
263
- with open(resolved, "r", encoding="utf-8", errors="replace") as f:
264
- all_lines = f.read().splitlines()
265
- except Exception as e:
266
- logger.exception("read tool failed on %s", parsed.path)
267
- return {"error": f"Could not read file: {e}"}
268
-
269
- content, lines_returned, truncated, message = _truncate_lines(
270
- all_lines, parsed.offset, parsed.count,
271
- )
272
-
273
- result: dict = {
274
- "content": content,
275
- "lines_returned": lines_returned,
276
- "offset": parsed.offset,
277
- "truncated": truncated,
278
- }
279
- if message:
280
- result["message"] = message
281
- return result
282
-
283
-
284
- # ===========================================================================
285
- # ---- WRITE ----------------------------------------------------------------
286
- # ===========================================================================
287
-
288
- class WriteFileParams(BaseModel):
289
- path: str = Field(..., description="Path relative to the agent's workspace directory, or an absolute path.")
290
- content: str = Field(..., description="Full content to write — overwrites any existing file.")
291
-
292
-
293
- WRITE_TOOL_SCHEMA = {
294
- "name": "write",
295
- "description": (
296
- "Create or overwrite a file. Parent directories are created "
297
- "automatically. Content size is limited to "
298
- f"{config.MAX_FILE_SIZE_BYTES} bytes."
299
- ),
300
- "input_schema": WriteFileParams.model_json_schema(),
301
- }
302
-
303
-
304
- def write_run(params: dict) -> dict:
305
- parsed = WriteFileParams(**params)
306
-
307
- # BEFORE the makedirs below: a refused write must not conjure the
308
- # protected directory into existence on its way to being refused.
309
- refused = _protected_path_error(parsed.path)
310
- if refused is not None:
311
- return {"error": refused}
312
-
313
- content_bytes = parsed.content.encode("utf-8")
314
- if len(content_bytes) > config.MAX_FILE_SIZE_BYTES:
315
- return {
316
- "error": (
317
- f"Content size ({len(content_bytes)} bytes) exceeds the "
318
- f"maximum writable size ({config.MAX_FILE_SIZE_BYTES} bytes)."
319
- ),
320
- }
321
-
322
- resolved = resolve_path(parsed.path)
323
- os.makedirs(os.path.dirname(resolved), exist_ok=True)
324
-
325
- try:
326
- with open(resolved, "w", encoding="utf-8") as f:
327
- f.write(parsed.content)
328
- except Exception as e:
329
- logger.exception("write tool failed on %s", parsed.path)
330
- return {"error": f"Could not write file: {e}"}
331
-
332
- return {"result": f"Wrote {len(parsed.content)} characters to {parsed.path}"}
333
-
334
-
335
- # ===========================================================================
336
- # ---- EDIT -----------------------------------------------------------------
337
- # ===========================================================================
338
-
339
- class EditFileParams(BaseModel):
340
- path: str = Field(..., description="Path relative to the agent's workspace directory, or an absolute path.")
341
- old_text: str = Field(..., description="Exact text to replace — must appear EXACTLY ONCE in the file.")
342
- new_text: str = Field(..., description="Replacement text.")
343
-
344
-
345
- EDIT_TOOL_SCHEMA = {
346
- "name": "edit",
347
- "description": (
348
- "Replace an exact, uniquely-matching span of text within an "
349
- "existing file. old_text must appear exactly once; if it appears "
350
- "zero or more than one time the edit is rejected with an error."
351
- ),
352
- "input_schema": EditFileParams.model_json_schema(),
353
- }
354
-
355
-
356
- def edit_run(params: dict) -> dict:
357
- parsed = EditFileParams(**params)
358
- refused = _protected_path_error(parsed.path)
359
- if refused is not None:
360
- return {"error": refused}
361
- resolved = resolve_path(parsed.path)
362
-
363
- if not os.path.isfile(resolved):
364
- return {"error": f"No such file: {parsed.path}"}
365
-
366
- # ROADMAP_v2 §31 (H7), #55. read_run has had this check since the
367
- # beginning and this module's own docstring gives the reason --
368
- # "rejected before opening to prevent memory exhaustion" -- while
369
- # the sibling twenty lines down read whatever it was pointed at.
370
- # Measured on a 30 MB file: 60 MB of peak traced memory to answer
371
- # "old_text not found in file."
372
- #
373
- # Copied rather than reinvented, down to the wording, so the two
374
- # paths refuse identically. A caller that learns what `read` rejects
375
- # now knows what `edit` rejects.
376
- file_size = os.path.getsize(resolved)
377
- if file_size > config.MAX_FILE_SIZE_BYTES:
378
- return {
379
- "error": (
380
- f"File size ({file_size} bytes) exceeds the maximum "
381
- f"editable size ({config.MAX_FILE_SIZE_BYTES} bytes)."
382
- ),
383
- }
384
-
385
- try:
386
- with open(resolved, "r", encoding="utf-8") as f:
387
- content = f.read()
388
- except Exception as e:
389
- logger.exception("edit tool read failed on %s", parsed.path)
390
- return {"error": f"Could not read file: {e}"}
391
-
392
- match_count = content.count(parsed.old_text)
393
- if match_count == 0:
394
- return {"error": "old_text not found in file."}
395
- if match_count > 1:
396
- return {
397
- "error": (
398
- f"old_text appears {match_count} times — must be unique. "
399
- "Include more surrounding context to narrow the match."
400
- ),
401
- }
402
-
403
- content = content.replace(parsed.old_text, parsed.new_text)
404
-
405
- try:
406
- with open(resolved, "w", encoding="utf-8") as f:
407
- f.write(content)
408
- except Exception as e:
409
- logger.exception("edit tool write failed on %s", parsed.path)
410
- return {"error": f"Could not write file: {e}"}
411
-
412
- return {"result": f"Replaced 1 occurrence in {parsed.path}"}
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
+ }