@yahyahammad/venastine 0.1.0 → 0.3.8

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 (130) hide show
  1. package/.env.example +19 -14
  2. package/CONFIG_ARCHITECTURE.md +2002 -0
  3. package/NOTICE +1 -1
  4. package/README.md +249 -93
  5. package/agents/builtin/build.md +73 -0
  6. package/agents/builtin/general.md +80 -0
  7. package/agents/builtin/plan.md +23 -5
  8. package/agents/builtin/test.md +65 -0
  9. package/agents/builtin/writer.md +67 -0
  10. package/agents/manager.py +261 -195
  11. package/agents/subagent_tool.py +280 -23
  12. package/agents/tui_commands.py +31 -21
  13. package/bin/venastine.mjs +528 -382
  14. package/bin/venastine.py +71 -0
  15. package/cli_commands.py +835 -0
  16. package/config.py +95 -1198
  17. package/config.yaml +1090 -0
  18. package/config_edit.py +1301 -0
  19. package/config_schema.py +966 -0
  20. package/config_update.py +749 -0
  21. package/core/agent_activity.py +256 -0
  22. package/core/ansi.py +452 -0
  23. package/core/approval.py +27 -5
  24. package/core/call_view.py +364 -0
  25. package/core/cancel.py +121 -0
  26. package/core/chatgpt_auth.py +747 -0
  27. package/core/claims_view.py +107 -0
  28. package/core/client.py +1249 -82
  29. package/core/commands.py +454 -0
  30. package/core/compaction.py +1735 -959
  31. package/core/config_loader.py +516 -97
  32. package/core/connect.py +686 -0
  33. package/core/events.py +68 -6
  34. package/core/file_mentions.py +280 -0
  35. package/core/interaction.py +87 -4
  36. package/core/line_pattern.py +128 -0
  37. package/core/loop.py +2566 -1353
  38. package/core/memory.py +482 -370
  39. package/core/pipeline_models.py +23 -9
  40. package/core/provider_errors.py +234 -0
  41. package/core/reasoning/confidence_scoring.py +70 -54
  42. package/core/reasoning/json_retry.py +19 -1
  43. package/core/reasoning/orchestrator.py +232 -53
  44. package/core/reasoning/output_writer.py +90 -31
  45. package/core/reasoning/payload_validation.py +133 -7
  46. package/core/reasoning/pipeline_storage.py +427 -361
  47. package/core/reasoning/review.py +659 -615
  48. package/core/reasoning/scholar.py +38 -14
  49. package/core/reasoning/source_corpus.py +110 -4
  50. package/core/replay.py +315 -167
  51. package/core/session.py +36 -12
  52. package/core/session_view.py +259 -0
  53. package/core/session_wake.py +259 -0
  54. package/core/shell_sessions.py +1553 -0
  55. package/core/workspace_trust.py +1 -1
  56. package/credentials.py +308 -180
  57. package/database.py +82 -1
  58. package/{PRIVACY.md → docs/PRIVACY.md} +19 -7
  59. package/docs/SECURITY.md +108 -0
  60. package/docs/THIRD_PARTY_NOTICES.md +148 -0
  61. package/env_secrets.py +118 -77
  62. package/json_store.py +236 -16
  63. package/logging_setup.py +121 -11
  64. package/main.py +1672 -198
  65. package/mcp_client/client.py +257 -23
  66. package/mcp_client/config.py +484 -379
  67. package/mcp_client/registration.py +163 -2
  68. package/memories/manager.py +15 -0
  69. package/memories/tui_commands.py +21 -14
  70. package/package.json +303 -73
  71. package/project_init/config_files.py +4 -0
  72. package/project_init/generator.py +201 -37
  73. package/project_init/manifest.py +418 -406
  74. package/project_init/tui_commands.py +7 -4
  75. package/prompts/revalidate.md +1 -1
  76. package/prompts/revise.md +17 -15
  77. package/prompts/system_prompts.py +64 -10
  78. package/providers.json.example +94 -92
  79. package/pyproject.toml +149 -100
  80. package/requirements.txt +252 -29
  81. package/safety/policy_enforcement.py +1082 -682
  82. package/security/askpass.py +419 -0
  83. package/security/capability.py +37 -7
  84. package/security/confine.py +484 -0
  85. package/security/hosted.py +182 -0
  86. package/security/permissions.py +54 -7
  87. package/security/posture.py +124 -12
  88. package/security/protected_paths.py +198 -6
  89. package/security/sandbox.py +3262 -139
  90. package/security/secrets.py +855 -0
  91. package/skills/tui_commands.py +3 -4
  92. package/storage.py +1338 -1005
  93. package/tools/base.py +465 -305
  94. package/tools/builtin/_math_common.py +306 -16
  95. package/tools/builtin/_net_common.py +267 -61
  96. package/tools/builtin/arxiv.py +681 -223
  97. package/tools/builtin/ask_user.py +231 -213
  98. package/tools/builtin/discrete_math.py +35 -4
  99. package/tools/builtin/fetch_url.py +239 -21
  100. package/tools/builtin/file_ops.py +341 -33
  101. package/tools/builtin/geometry.py +184 -148
  102. package/tools/builtin/get_time.py +2 -2
  103. package/tools/builtin/linear_algebra.py +66 -23
  104. package/tools/builtin/load_skill.py +10 -0
  105. package/tools/builtin/logic.py +171 -12
  106. package/tools/builtin/pin.py +46 -12
  107. package/tools/builtin/probability_stats.py +224 -228
  108. package/tools/builtin/project_docs.py +80 -21
  109. package/tools/builtin/remember.py +21 -4
  110. package/tools/builtin/shell.py +586 -67
  111. package/tools/builtin/shell_sessions.py +613 -0
  112. package/tools/builtin/symbolic_math.py +80 -10
  113. package/tools/builtin/todo.py +5 -3
  114. package/tools/builtin/web_search.py +329 -151
  115. package/tools/context.py +23 -0
  116. package/tools/isolation.py +387 -314
  117. package/tools/registry.py +374 -29
  118. package/tui/app.py +5281 -397
  119. package/tui/app.tcss +290 -9
  120. package/tui/commands.py +26 -61
  121. package/tui/diffs.py +286 -265
  122. package/tui/history.py +128 -0
  123. package/tui/hosted_driver.py +102 -0
  124. package/tui/markdown.py +1329 -0
  125. package/tui/meters.py +364 -0
  126. package/tui/screens.py +346 -92
  127. package/tui/themes.py +599 -366
  128. package/tui/widgets.py +2673 -116
  129. package/SECURITY.md +0 -88
  130. package/THIRD_PARTY_NOTICES.md +0 -100
@@ -7,6 +7,11 @@ to match config.ToolPermissions' three separate boolean fields (read /
7
7
  write / edit), so review/audit agents can be given read access without
8
8
  write or edit.
9
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
+
10
15
  SECURITY MODEL (ROADMAP §6, deviated per user decision):
11
16
  Paths within WORKSPACE_DIR are auto-approved (unless the matching
12
17
  ToolApprovals boolean is True, which forces approval even inside the
@@ -20,7 +25,37 @@ SECURITY MODEL (ROADMAP §6, deviated per user decision):
20
25
  deny, and the exception to both rules above: any path -- inside or
21
26
  outside the workspace -- that resolves into `.venastine/` is refused
22
27
  by the refusal_check before approval and re-tested in all three
23
- handlers, whatever the ToolApprovals booleans say.
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.
24
59
 
25
60
  READ TOOL PAGINATION (deviated from ROADMAP §6):
26
61
  The read tool accepts offset (lines to skip) and count (lines to
@@ -39,6 +74,7 @@ RICH FORMAT SUPPORT (deviated from ROADMAP §6):
39
74
 
40
75
  from __future__ import annotations
41
76
 
77
+ import base64
42
78
  import logging
43
79
  import os
44
80
  from typing import Optional
@@ -46,8 +82,9 @@ from typing import Optional
46
82
  from pydantic import BaseModel, Field
47
83
 
48
84
  import config
49
-
50
- from security.protected_paths import protected_segment
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
51
88
 
52
89
  logger = logging.getLogger(__name__)
53
90
 
@@ -91,8 +128,25 @@ def _file_approval_check(tool_name: str, params: dict) -> bool:
91
128
  Outside workspace → always True (ask user).
92
129
  Within workspace → defer to the matching ToolApprovals boolean
93
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.
94
144
  """
145
+ if not isinstance(params, dict):
146
+ return True
95
147
  path = params.get("path", "")
148
+ if not isinstance(path, str):
149
+ return True
96
150
  if not _is_within_workspace(path):
97
151
  return True
98
152
  approvals = config.ToolApprovals()
@@ -119,19 +173,44 @@ def _protected_path_error(user_path: str) -> Optional[str]:
119
173
  question here: with AGENT_WORKSPACE pointed at the project the
120
174
  directory is INSIDE the workspace and _file_approval_check would
121
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.
122
182
  """
123
- segment = protected_segment(resolve_path(user_path))
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"
124
189
  if segment is None:
125
190
  return None
126
191
  return (
127
- f"Refused: the path resolves into '{segment}/', which holds this "
192
+ f"Refused: {via} '{segment}/', which holds this "
128
193
  "harness's own configuration and trust-gated content (settings.json, "
129
194
  "mcp.json, skills, agents). It is denied however the file tools are "
130
195
  "called."
131
196
  )
132
197
 
133
198
 
134
- def _protected_refusal(params: dict, _context=None) -> Optional[str]:
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):
135
214
  """ToolSpec.refusal_check for read / write / edit (§32 A7's shape).
136
215
 
137
216
  dispatch() consults this BEFORE the approval gate and returns the
@@ -140,8 +219,32 @@ def _protected_refusal(params: dict, _context=None) -> Optional[str]:
140
219
  change the outcome. NOT the enforcement (base.py's own words): the
141
220
  three handlers re-test below, so a caller that reaches them
142
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.
143
239
  """
144
- return _protected_path_error(params.get("path", ""))
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
145
248
 
146
249
 
147
250
  # ===========================================================================
@@ -200,32 +303,80 @@ def _truncate_lines(
200
303
  offset: int,
201
304
  count: int,
202
305
  ) -> tuple[str, int, bool, Optional[str]]:
203
- """Apply offset, clamp count, join, then char-truncate.
204
-
205
- Returns (content, lines_returned, truncated, message).
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.
206
329
  """
207
330
  clamped = count > config.MAX_READ_LINES
208
331
  effective_count = min(count, config.MAX_READ_LINES)
209
332
 
210
333
  selected = lines[offset:offset + effective_count]
211
- lines_returned = len(selected)
212
- content = "\n".join(selected)
213
334
 
214
- truncated = False
215
- message_parts: list[str] = []
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
216
359
 
360
+ message_parts: list[str] = []
217
361
  if clamped:
218
- truncated = True
219
362
  message_parts.append(
220
- f"Requested {count} lines, returned {effective_count} (maximum). "
221
- f"Use offset={offset + effective_count} to read further."
363
+ f"Requested {count} lines, returned at most {effective_count} "
364
+ f"(maximum)."
222
365
  )
223
-
224
- if len(content) > config.MAX_READ_CHARS:
225
- truncated = True
226
- content = content[:config.MAX_READ_CHARS]
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:
227
372
  message_parts.append(
228
- f"Content truncated at {config.MAX_READ_CHARS} characters."
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."
229
380
  )
230
381
 
231
382
  message = " ".join(message_parts) if message_parts else None
@@ -260,7 +411,7 @@ def read_run(params: dict) -> dict:
260
411
  raw_text = _read_rich(resolved)
261
412
  all_lines = raw_text.splitlines()
262
413
  else:
263
- with open(resolved, "r", encoding="utf-8", errors="replace") as f:
414
+ with open(resolved, encoding="utf-8", errors="replace") as f:
264
415
  all_lines = f.read().splitlines()
265
416
  except Exception as e:
266
417
  logger.exception("read tool failed on %s", parsed.path)
@@ -304,8 +455,11 @@ WRITE_TOOL_SCHEMA = {
304
455
  def write_run(params: dict) -> dict:
305
456
  parsed = WriteFileParams(**params)
306
457
 
307
- # BEFORE the makedirs below: a refused write must not conjure the
308
- # protected directory into existence on its way to being refused.
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.
309
463
  refused = _protected_path_error(parsed.path)
310
464
  if refused is not None:
311
465
  return {"error": refused}
@@ -320,15 +474,21 @@ def write_run(params: dict) -> dict:
320
474
  }
321
475
 
322
476
  resolved = resolve_path(parsed.path)
323
- os.makedirs(os.path.dirname(resolved), exist_ok=True)
324
477
 
325
478
  try:
326
- with open(resolved, "w", encoding="utf-8") as f:
327
- f.write(parsed.content)
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)
328
484
  except Exception as e:
329
485
  logger.exception("write tool failed on %s", parsed.path)
330
486
  return {"error": f"Could not write file: {e}"}
331
487
 
488
+ if created:
489
+ from core.file_mentions import note_file_created
490
+
491
+ note_file_created(resolved)
332
492
  return {"result": f"Wrote {len(parsed.content)} characters to {parsed.path}"}
333
493
 
334
494
 
@@ -383,13 +543,34 @@ def edit_run(params: dict) -> dict:
383
543
  }
384
544
 
385
545
  try:
386
- with open(resolved, "r", encoding="utf-8") as f:
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:
387
552
  content = f.read()
388
553
  except Exception as e:
389
554
  logger.exception("edit tool read failed on %s", parsed.path)
390
555
  return {"error": f"Could not read file: {e}"}
391
556
 
392
- match_count = content.count(parsed.old_text)
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
+
393
574
  if match_count == 0:
394
575
  return {"error": "old_text not found in file."}
395
576
  if match_count > 1:
@@ -400,13 +581,140 @@ def edit_run(params: dict) -> dict:
400
581
  ),
401
582
  }
402
583
 
403
- content = content.replace(parsed.old_text, parsed.new_text)
584
+ content = content.replace(old_text, new_text)
404
585
 
405
586
  try:
406
- with open(resolved, "w", encoding="utf-8") as f:
407
- f.write(content)
587
+ write_text_atomic(resolved, content)
408
588
  except Exception as e:
409
589
  logger.exception("edit tool write failed on %s", parsed.path)
410
590
  return {"error": f"Could not write file: {e}"}
411
591
 
412
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
+ }