1use std::collections::HashMap;
2use std::fs;
3use std::path::Path;
4
5use crate::extract_args;
6use crate::image::SUPPORTED_MIME_TYPES;
7use crate::path_guard::PathGuard;
8use crate::tools::tool::{BoxFuture, ToolCategory, build_string_params_schema, make_tool};
9use serde_json::Value;
10
11const MAX_NOTEBOOK_VALUE_CHARS: usize = 4_000;
14
15const MAX_SCRUBBED_LINE_CHARS: usize = 2_000;
19
20pub fn read_tool_entry(guard: Option<PathGuard>) -> crate::tools::tool::Tool {
21 make_tool(
22 "read",
23 "Read file content. Returns the entire file or a specific line range if from/to are provided. For image files (png, jpg, webp, gif, bmp), returns a description and the image data is automatically loaded for the model to view. For Jupyter notebooks (.ipynb), renders the JSON with base64 image outputs stripped and oversized text truncated — pass from/to to page through the rendered result.",
24 ToolCategory::ReadOnly,
25 build_string_params_schema(
26 &[("path", "The absolute path to the file to read")],
27 &[
28 ("from", "Starting line number (0-based, inclusive)", "0"),
29 (
30 "to",
31 "Number of lines to read (if from is set, reads this many lines)",
32 "",
33 ),
34 ],
35 ),
36 move |args| {
37 let guard = guard.clone();
38 Box::pin(read_tool_inner(args, guard))
39 },
40 )
41}
42
43pub fn read_tool(args: HashMap<String, String>) -> BoxFuture<'static, String> {
44 Box::pin(read_tool_inner(args, None))
45}
46
47pub(crate) fn read_bytes_guarded(path: &str, guard: Option<&PathGuard>) -> Result<Vec<u8>, String> {
51 match guard {
52 Some(g) => {
53 use std::io::Read;
54 let mut file = g.open_read_contained(Path::new(path))?;
55 let mut buf = Vec::new();
56 file.read_to_end(&mut buf)
57 .map_err(|e| format!("Error reading '{}': {}", path, e))?;
58 Ok(buf)
59 }
60 None => fs::read(path).map_err(|e| e.to_string()),
61 }
62}
63
64pub(crate) fn read_string_guarded(path: &str, guard: Option<&PathGuard>) -> Result<String, String> {
66 match guard {
67 Some(g) => g.read_contained(Path::new(path)),
68 None => fs::read_to_string(path).map_err(|e| e.to_string()),
69 }
70}
71
72async fn read_tool_inner(args: HashMap<String, String>, guard: Option<PathGuard>) -> String {
73 extract_args!(args, path);
74
75 if is_image_file(&path) {
78 let data = match read_bytes_guarded(&path, guard.as_ref()) {
82 Ok(d) => d,
83 Err(e) => return format!("Error reading file: {}", e),
84 };
85 let dims = image_dimensions(&data);
86 let dims_str = dims
87 .map(|(w, h)| format!("{}x{}px, ", w, h))
88 .unwrap_or_default();
89 let size = std::fs::metadata(&path).map(|m| m.len()).unwrap_or(0);
90 let size_str = format_image_size(size);
91 let mime = guess_image_mime(&path).unwrap_or("unknown");
92 return format!(
93 "[IMAGE] {0}\nImage file: '{0}' ({1}{2} {3})\n\
94 This is an image — its content has been automatically loaded so you can view it.",
95 path, dims_str, size_str, mime,
96 );
97 }
98
99 let from = args.get("from").and_then(|f| f.parse::<usize>().ok());
101 let to = args.get("to").and_then(|t| t.parse::<usize>().ok());
102
103 if is_notebook_file(&path) {
108 return read_notebook(&path, from, to, guard.as_ref());
109 }
110
111 match (from, to) {
112 (Some(from), Some(to)) => read_partial(&path, from, to, guard.as_ref()),
113 _ => match read_string_guarded(&path, guard.as_ref()) {
114 Ok(content) => {
115 let line_count = content.lines().count();
116 format!("({} lines)\n{}", line_count, content)
117 }
118 Err(e) => format!("Error reading file: {}", e),
119 },
120 }
121}
122
123pub fn is_notebook_file(path: &str) -> bool {
125 path.to_lowercase().ends_with(".ipynb")
126}
127
128fn read_notebook(
151 path: &str,
152 from: Option<usize>,
153 to: Option<usize>,
154 guard: Option<&PathGuard>,
155) -> String {
156 let raw = match read_string_guarded(path, guard) {
157 Ok(content) => content,
158 Err(e) => return format!("Error reading file: {e}"),
159 };
160
161 let (rendered, mut notes) = match serde_json::from_str::<Value>(&raw) {
162 Ok(mut value) => {
163 let stripped = strip_binary_payloads(&mut value);
164 let truncated = truncate_oversized_strings(&mut value);
165 let text = serde_json::to_string_pretty(&value).unwrap_or_else(|_| raw.clone());
166 let mut notes = Vec::new();
167 if stripped > 0 {
168 notes.push(format!("{stripped} image outputs stripped"));
169 }
170 if truncated > 0 {
171 notes.push(format!("{truncated} oversized outputs truncated"));
172 }
173 (text, notes)
174 }
175 Err(_) => (scrub_huge_lines(&raw), vec!["long lines truncated".into()]),
176 };
177
178 let rendered = rendered.trim_end_matches('\n');
179 match (from, to) {
180 (Some(from), Some(to)) => {
181 let selected: Vec<&str> = rendered.lines().skip(from).take(to).collect();
182 if selected.is_empty() {
183 format!("Error: No lines to read in '{path}' at offset {from}")
184 } else {
185 format!(
186 "({} lines from line {from})\n{}",
187 selected.len(),
188 selected.join("\n")
189 )
190 }
191 }
192 _ => {
193 let count = rendered.lines().count();
194 if !notes.is_empty() {
195 notes.insert(0, format!("{count} lines"));
196 }
197 let meta = format!("({})", notes.join(", "));
198 format!("{meta}\n{rendered}")
199 }
200 }
201}
202
203fn strip_binary_payloads(value: &mut Value) -> usize {
206 fn is_binary_key(key: &str) -> bool {
207 key.starts_with("image/") || key == "application/pdf"
208 }
209
210 fn payload_len(value: &Value) -> usize {
213 match value {
214 Value::String(s) => s.chars().count(),
215 Value::Array(items) => items
216 .iter()
217 .map(|i| i.as_str().map(str::chars).map_or(0, Iterator::count))
218 .sum(),
219 _ => 0,
220 }
221 }
222
223 match value {
224 Value::Object(map) => {
225 let mut stripped = 0;
226 for (key, entry) in map.iter_mut() {
227 if is_binary_key(key) {
228 let size = payload_len(entry);
229 if size > 0 {
230 *entry =
231 Value::String(format!("[stripped {key} output — {size} base64 chars]"));
232 stripped += 1;
233 continue;
234 }
235 }
236 stripped += strip_binary_payloads(entry);
237 }
238 stripped
239 }
240 Value::Array(items) => items.iter_mut().map(strip_binary_payloads).sum(),
241 Value::Null | Value::Bool(_) | Value::Number(_) | Value::String(_) => 0,
242 }
243}
244
245fn truncate_oversized_strings(value: &mut Value) -> usize {
248 fn cap(s: &str) -> Option<String> {
249 let total = s.chars().count();
250 if total <= MAX_NOTEBOOK_VALUE_CHARS {
251 return None;
252 }
253 let head = s.floor_char_boundary(MAX_NOTEBOOK_VALUE_CHARS);
254 Some(format!("{}…[truncated, {total} chars total]", &s[..head]))
255 }
256
257 match value {
258 Value::Object(map) => map.values_mut().map(truncate_oversized_strings).sum(),
259 Value::Array(items) => items.iter_mut().map(truncate_oversized_strings).sum(),
260 Value::String(s) => match cap(s) {
261 Some(replacement) => {
262 *s = replacement;
263 1
264 }
265 None => 0,
266 },
267 Value::Null | Value::Bool(_) | Value::Number(_) => 0,
268 }
269}
270
271fn scrub_huge_lines(content: &str) -> String {
275 content
276 .lines()
277 .map(|line| {
278 if line.chars().count() > MAX_SCRUBBED_LINE_CHARS {
279 let head = line.floor_char_boundary(MAX_SCRUBBED_LINE_CHARS);
280 format!("{}…[line truncated]", &line[..head])
281 } else {
282 line.to_string()
283 }
284 })
285 .collect::<Vec<_>>()
286 .join("\n")
287}
288
289pub fn is_image_file(path: &str) -> bool {
291 let lowercase = path.to_lowercase();
292 SUPPORTED_MIME_TYPES.iter().any(|mime| {
293 let ext = mime.strip_prefix("image/").unwrap_or(mime);
294 lowercase.ends_with(&format!(".{}", ext)) || (ext == "jpeg" && lowercase.ends_with(".jpg"))
295 })
296}
297
298pub fn guess_image_mime(path: &str) -> Option<&'static str> {
300 let lowercase = path.to_lowercase();
301 for &mime in SUPPORTED_MIME_TYPES {
302 let ext = mime.strip_prefix("image/").unwrap_or(mime);
303 if lowercase.ends_with(&format!(".{}", ext))
304 || (ext == "jpeg" && lowercase.ends_with(".jpg"))
305 {
306 return Some(mime);
307 }
308 }
309 None
310}
311
312pub fn detect_image_dimensions(path: &str) -> Option<(u32, u32)> {
315 let data = std::fs::read(path).ok()?;
316 image_dimensions(&data)
317}
318
319fn image_dimensions(data: &[u8]) -> Option<(u32, u32)> {
321 if data.len() < 24 {
322 return None;
323 }
324
325 if data[0..8] == [0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A] {
327 let w = u32::from_be_bytes([data[16], data[17], data[18], data[19]]);
328 let h = u32::from_be_bytes([data[20], data[21], data[22], data[23]]);
329 return Some((w, h));
330 }
331
332 if data[0..2] == [0xFF, 0xD8] {
334 let mut i = 2;
335 while i + 10 < data.len() {
336 if data[i] != 0xFF {
337 break;
338 }
339 let marker = data[i + 1];
340 if marker == 0xC0 || marker == 0xC1 || marker == 0xC2 {
341 let h = u16::from_be_bytes([data[i + 5], data[i + 6]]) as u32;
342 let w = u16::from_be_bytes([data[i + 7], data[i + 8]]) as u32;
343 return Some((w, h));
344 }
345 let seg_len = u16::from_be_bytes([data[i + 2], data[i + 3]]) as usize;
347 i += 2 + seg_len;
348 }
349 }
350
351 None
352}
353
354fn format_image_size(bytes: u64) -> String {
356 if bytes < 1024 {
357 format!("{} B", bytes)
358 } else if bytes < 1024 * 1024 {
359 format!("{:.1} KB", bytes as f64 / 1024.0)
360 } else {
361 format!("{:.1} MB", bytes as f64 / (1024.0 * 1024.0))
362 }
363}
364
365fn read_partial(path: &str, from: usize, to: usize, guard: Option<&PathGuard>) -> String {
366 let raw = match read_string_guarded(path, guard) {
367 Ok(c) => c,
368 Err(e) => return format!("Error: {}", e),
369 };
370
371 let mut content = String::new();
372 let mut lines_read = 0usize;
373
374 for line in raw.lines().skip(from).take(to) {
375 content.push_str(line);
376 content.push('\n');
377 lines_read += 1;
378 }
379
380 if content.is_empty() {
381 format!("Error: No lines to read in '{}' at offset {}", path, from)
382 } else {
383 format!("({} lines from line {})\n{}", lines_read, from, content)
384 }
385}
386
387#[cfg(test)]
388mod tests {
389 use super::*;
390 use std::io::Write;
391
392 #[test]
393 fn test_is_image_file_png() {
394 assert!(is_image_file("screenshot.png"));
395 assert!(is_image_file("/tmp/photo.PNG"));
396 }
397
398 #[test]
399 fn test_is_image_file_jpg() {
400 assert!(is_image_file("photo.jpg"));
401 assert!(is_image_file("photo.jpeg"));
402 assert!(is_image_file("photo.JPG"));
403 }
404
405 #[test]
406 fn test_is_image_file_not_image() {
407 assert!(!is_image_file("main.rs"));
408 assert!(!is_image_file("Cargo.toml"));
409 assert!(!is_image_file("data.jsonl"));
410 }
411
412 #[test]
413 fn test_detect_png_dimensions() {
414 let dir = tempfile::tempdir().unwrap();
415 let path = dir.path().join("test.png");
416 let png = vec![
418 0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, 0x00, 0x00, 0x00, 0x0D, 0x49, 0x48, 0x44, 0x52, 0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00, 0x03, 0x08, 0x02, 0x00, 0x00, 0x00, 0x90, 0x77, 0x53, 0xDE, 0x00, 0x00, 0x00, 0x00, 0x49, 0x45, 0x4E, 0x44, 0xAE, 0x42, 0x60, 0x82,
426 ];
427 let mut f = std::fs::File::create(&path).unwrap();
428 f.write_all(&png).unwrap();
429
430 let dims = detect_image_dimensions(&path.to_string_lossy());
431 assert_eq!(dims, Some((2, 3)));
432 }
433
434 #[test]
435 fn test_guess_image_mime() {
436 assert_eq!(guess_image_mime("photo.png"), Some("image/png"));
437 assert_eq!(guess_image_mime("photo.jpg"), Some("image/jpeg"));
438 assert_eq!(guess_image_mime("photo.jpeg"), Some("image/jpeg"));
439 assert_eq!(guess_image_mime("main.rs"), None);
440 }
441
442 fn fake_b64(len: usize) -> String {
446 "A".repeat(len)
447 }
448
449 fn write_notebook(dir: &std::path::Path, name: &str, body: &str) -> std::path::PathBuf {
450 let path = dir.join(name);
451 std::fs::write(&path, body).unwrap();
452 path
453 }
454
455 fn read_nb(path: &std::path::Path) -> String {
456 read_notebook(&path.to_string_lossy(), None, None, None)
457 }
458
459 #[test]
460 fn is_notebook_file_matches_extension() {
461 assert!(is_notebook_file("lab/main.ipynb"));
462 assert!(is_notebook_file("MAIN.IPYNB"));
463 assert!(!is_notebook_file("main.py"));
464 assert!(!is_notebook_file("nb.ipynb.bak"));
465 }
466
467 #[test]
468 fn notebook_image_outputs_are_stripped_but_source_kept() {
469 let dir = tempfile::tempdir().unwrap();
470 let big = fake_b64(100_000);
471 let nb = format!(
472 r#"{{
473 "cells": [
474 {{"cell_type": "code", "execution_count": 12, "metadata": {{}},
475 "outputs": [
476 {{"name": "stdout", "output_type": "stream", "text": ["loading done\n"]}},
477 {{"output_type": "display_data", "metadata": {{}},
478 "data": {{"image/png": "{big}", "text/plain": ["<Figure size 640x480>"]}}}}
479 ],
480 "source": ["import cv2\n", "cv2.imshow('x', img)\n"]}}
481 ],
482 "metadata": {{}}, "nbformat": 4, "nbformat_minor": 5
483}}"#
484 );
485 let path = write_notebook(dir.path(), "main.ipynb", &nb);
486 let out = read_nb(&path);
487
488 assert!(!out.contains(&fake_b64(1000)), "base64 payload survived");
490 assert!(out.contains("[stripped image/png output — 100000 base64 chars]"));
491
492 assert!(out.contains("import cv2"));
494 assert!(out.contains("cv2.imshow"));
495 assert!(out.contains("loading done"));
496 assert!(out.contains("<Figure size 640x480>"));
497 assert!(out.contains("\"execution_count\": 12"));
498
499 let meta = out.lines().next().unwrap();
501 assert!(
502 meta.starts_with('(') && meta.ends_with(')'),
503 "meta was: {meta}"
504 );
505 assert!(meta.contains(" lines"), "meta was: {meta}");
506 assert!(
507 meta.contains("1 image outputs stripped"),
508 "meta was: {meta}"
509 );
510 }
511
512 #[test]
513 fn notebook_image_payload_stored_as_string_list_is_stripped() {
514 let dir = tempfile::tempdir().unwrap();
515 let nb = format!(
516 r#"{{"cells": [{{"cell_type": "code", "outputs": [{{"output_type": "display_data",
517 "data": {{"image/png": ["{}", "{}"]}}}}], "source": ["x=1"]}}],
518 "nbformat": 4, "nbformat_minor": 5}}"#,
519 fake_b64(600),
520 fake_b64(600)
521 );
522 let path = write_notebook(dir.path(), "listed.ipynb", &nb);
523 let out = read_nb(&path);
524 assert!(out.contains("[stripped image/png output — 1200 base64 chars]"));
525 assert!(!out.contains(&fake_b64(600)));
526 }
527
528 #[test]
529 fn notebook_markdown_attachments_are_stripped() {
530 let dir = tempfile::tempdir().unwrap();
531 let nb = format!(
532 r#"{{"cells": [{{"cell_type": "markdown", "attachments": {{"image/jpeg": "{b}"}},
533 "source": ["see figure"]}}], "nbformat": 4, "nbformat_minor": 5}}"#,
534 b = fake_b64(5000)
535 );
536 let path = write_notebook(dir.path(), "attach.ipynb", &nb);
537 let out = read_nb(&path);
538 assert!(out.contains("[stripped image/jpeg output"));
539 assert!(out.contains("see figure"));
540 assert!(!out.contains(&fake_b64(5000)));
541 }
542
543 #[test]
544 fn notebook_oversized_text_output_is_truncated() {
545 let dir = tempfile::tempdir().unwrap();
546 let big = fake_b64(MAX_NOTEBOOK_VALUE_CHARS * 3);
547 let nb = format!(
548 r#"{{"cells": [{{"cell_type": "code", "outputs": [{{"output_type": "execute_result",
549 "data": {{"text/plain": "{big}"}}}}], "source": ["df"]}}],
550 "nbformat": 4, "nbformat_minor": 5}}"#
551 );
552 let path = write_notebook(dir.path(), "text.ipynb", &nb);
553 let out = read_nb(&path);
554 assert!(out.contains(&format!(
555 "…[truncated, {} chars total]",
556 MAX_NOTEBOOK_VALUE_CHARS * 3
557 )));
558 assert!(out.contains("1 oversized outputs truncated"));
559 assert!(!out.contains(&big));
560 assert!(out.len() < MAX_NOTEBOOK_VALUE_CHARS * 2);
561 }
562
563 #[test]
564 fn notebook_without_big_outputs_is_left_alone() {
565 let dir = tempfile::tempdir().unwrap();
566 let nb = r#"{"cells": [{"cell_type": "code", "execution_count": 1,
567 "outputs": [{"output_type": "stream", "name": "stdout", "text": ["hi\n"]}],
568 "source": ["print('hi')"]}], "metadata": {}, "nbformat": 4, "nbformat_minor": 5}"#;
569 let path = write_notebook(dir.path(), "clean.ipynb", nb);
570 let out = read_nb(&path);
571 assert!(out.contains("print('hi')"));
572 assert!(out.contains("hi\\n"));
573 let meta = out.lines().next().unwrap();
575 assert!(!meta.contains("stripped"), "meta was: {meta}");
576 assert!(!meta.contains("truncated"), "meta was: {meta}");
577 }
578
579 #[test]
580 fn malformed_notebook_falls_back_to_line_scrubbing() {
581 let dir = tempfile::tempdir().unwrap();
582 let body = format!(
583 "{{{{ not json at all\nsecond line ok\nlong line: {}\nfourth\n",
584 fake_b64(MAX_SCRUBBED_LINE_CHARS * 4)
585 );
586 let path = write_notebook(dir.path(), "broken.ipynb", &body);
587 let out = read_nb(&path);
588 assert!(out.contains("second line ok"));
589 assert!(out.contains("[line truncated]"));
590 assert!(!out.contains(&fake_b64(MAX_SCRUBBED_LINE_CHARS * 2)));
591 assert!(out.lines().next().unwrap().contains("long lines truncated"));
592 }
593
594 #[test]
595 fn notebook_from_to_pages_the_rendered_text() {
596 let dir = tempfile::tempdir().unwrap();
597 let nb = format!(
598 r#"{{"cells": [{{"cell_type": "code", "outputs": [{{"output_type": "display_data",
599 "data": {{"image/png": "{b}"}}}}], "source": ["alpha\n", "beta"]}}],
600 "nbformat": 4, "nbformat_minor": 5}}"#,
601 b = fake_b64(20_000)
602 );
603 let path = write_notebook(dir.path(), "paged.ipynb", &nb);
604 let full = read_notebook(&path.to_string_lossy(), None, None, None);
605 let body: Vec<&str> = full.lines().skip(1).collect();
608 assert!(body.len() > 4, "fixture should render several lines");
609
610 let window = read_notebook(&path.to_string_lossy(), Some(0), Some(3), None);
611 assert!(window.starts_with("(3 lines from line 0)"));
612 assert_eq!(window.lines().skip(1).collect::<Vec<_>>(), &body[..3]);
613
614 let middle = read_notebook(&path.to_string_lossy(), Some(1), Some(2), None);
615 assert_eq!(middle.lines().skip(1).collect::<Vec<_>>(), &body[1..3]);
616
617 let tail = read_notebook(&path.to_string_lossy(), Some(body.len() - 2), Some(5), None);
618 assert_eq!(
619 tail.lines().skip(1).collect::<Vec<_>>(),
620 &body[body.len() - 2..]
621 );
622 assert!(tail.contains("\"nbformat_minor\": 5"));
623
624 let empty = read_notebook(
625 &path.to_string_lossy(),
626 Some(body.len() + 10),
627 Some(5),
628 None,
629 );
630 assert!(empty.starts_with("Error: No lines to read"));
631 }
632
633 #[test]
637 fn realistic_notebook_with_many_figures_stays_small() {
638 let dir = tempfile::tempdir().unwrap();
639 let cells: Vec<String> = (0..4)
640 .map(|i| {
641 format!(
642 r#"{{"cell_type": "code", "execution_count": {i}, "metadata": {{}},
643 "outputs": [{{"output_type": "display_data", "metadata": {{}},
644 "data": {{"image/png": "{b}", "text/plain": ["<Figure {i}>"]}}}}],
645 "source": ["cell_{i}\n", "imshow(x)\n"]}}"#,
646 b = fake_b64(377_440)
647 )
648 })
649 .collect();
650 let nb = format!(
651 r#"{{"cells": [{}], "metadata": {{}}, "nbformat": 4, "nbformat_minor": 5}}"#,
652 cells.join(",")
653 );
654 assert!(nb.len() > 1_400_000, "fixture should mirror the real file");
655
656 let path = write_notebook(dir.path(), "big.ipynb", &nb);
657 let out = read_nb(&path);
658 assert!(out.len() < 4_000, "notebook render was {} chars", out.len());
659 assert!(out.contains("cell_0") && out.contains("cell_3"));
660 assert!(out.contains("4 image outputs stripped"));
661 }
662
663 #[test]
664 fn read_tool_dispatches_notebooks_without_image_marker() {
665 let dir = tempfile::tempdir().unwrap();
666 let nb = format!(
667 r#"{{"cells": [{{"cell_type": "code", "outputs": [{{"data": {{"image/png": "{b}"}}}}],
668 "source": ["plot()"]}}], "nbformat": 4, "nbformat_minor": 5}}"#,
669 b = fake_b64(50_000)
670 );
671 let path = write_notebook(dir.path(), "dispatch.ipynb", &nb);
672
673 let runtime = tokio::runtime::Builder::new_current_thread()
674 .enable_all()
675 .build()
676 .unwrap();
677 let out = runtime.block_on(read_tool(HashMap::from([(
678 "path".to_string(),
679 path.to_string_lossy().to_string(),
680 )])));
681
682 assert!(!out.starts_with("[IMAGE]"));
685 assert!(out.contains("plot()"));
686 assert!(out.contains("[stripped image/png output"));
687 }
688}