Skip to main content

tinyharness_lib/tools/
read.rs

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
11/// Maximum characters kept from a single notebook output value (e.g. a huge
12/// `text/plain` dataframe dump). Larger values are truncated with a marker.
13const MAX_NOTEBOOK_VALUE_CHARS: usize = 4_000;
14
15/// Hard cap for a single line in the notebook fallback scrubber, used when the
16/// `.ipynb` file is not valid JSON (or is minified onto one line) and the
17/// structure-aware sanitizer cannot run.
18const 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
47/// Read a file's bytes through the guard's verified descriptor when a guard
48/// is active, so a symlink swapped in after the argument check cannot redirect
49/// the read outside an allowed root.
50pub(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
64/// Same as [`read_bytes_guarded`] for text.
65pub(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    // Check if this is an image file — skip binary read, return description only.
76    // The agent layer will load the image as an ImageAttachment separately.
77    if is_image_file(&path) {
78        // Read through the guard's verified descriptor when active, so a
79        // symlink swapped in after the argument check cannot redirect the
80        // read outside an allowed root.
81        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    // Check if partial reading is requested
100    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    // Jupyter notebooks: embedded base64 image outputs routinely reach
104    // hundreds of kilobytes per cell and blow the model's input limit, so
105    // render a structure-aware, image-free view of the notebook instead of
106    // dumping the raw JSON. `from`/`to` page through the rendered text.
107    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
123/// Check if a path refers to a Jupyter notebook by extension.
124pub fn is_notebook_file(path: &str) -> bool {
125    path.to_lowercase().ends_with(".ipynb")
126}
127
128/// Read a Jupyter notebook as compact, model-safe JSON.
129///
130/// Notebook cells routinely embed rendered figures as base64 payloads
131/// (`"image/png": "iVBOR…"` — hundreds of kilobytes *on a single line*), which
132/// can push a request past the provider's input-length limit. The JSON is
133/// therefore parsed and sanitized before it is returned:
134///
135/// * every binary payload (image/*, `application/pdf`) is replaced by a
136///   short placeholder recording the mime type and the stripped size — this
137///   covers both `outputs[].data` and markdown `attachments`;
138/// * remaining text values longer than [`MAX_NOTEBOOK_VALUE_CHARS`] are
139///   truncated with a marker, so a giant `text/plain` dump cannot recreate
140///   the same problem;
141/// * cell sources, stream text, `text/plain` results and execution counts are
142///   preserved verbatim.
143///
144/// If the file is not valid JSON (or is a notebook-shaped document the
145/// sanitizer cannot walk), the raw text is returned with over-long lines
146/// truncated instead, so the base64 blow-up is still neutralised.
147///
148/// `from`/`to` page through the *rendered* text, not the on-disk file, so the
149/// line numbers stay stable across reads.
150fn 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
203/// Replace every binary (image / PDF) payload in a parsed notebook with a
204/// placeholder. Returns the number of payloads stripped.
205fn 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    /// Base64 payloads are stored either as one string or as a list of
211    /// strings; both collapse to the same character count.
212    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
245/// Truncate text values longer than [`MAX_NOTEBOOK_VALUE_CHARS`]. Returns the
246/// number of values truncated.
247fn 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
271/// Line-oriented fallback for documents that are not valid JSON: keep the
272/// text but cut any line longer than [`MAX_SCRUBBED_LINE_CHARS`], which is
273/// where embedded base64 lives in a notebook.
274fn 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
289/// Check if a path refers to an image file by extension.
290pub 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
298/// Guess the MIME type of an image file from its extension.
299pub 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
312/// Parse image dimensions from a PNG or JPEG file header.
313/// Returns `None` for unsupported formats or on error.
314pub fn detect_image_dimensions(path: &str) -> Option<(u32, u32)> {
315    let data = std::fs::read(path).ok()?;
316    image_dimensions(&data)
317}
318
319/// [`detect_image_dimensions`] on already-read bytes.
320fn image_dimensions(data: &[u8]) -> Option<(u32, u32)> {
321    if data.len() < 24 {
322        return None;
323    }
324
325    // PNG: width at offset 16, height at offset 20 (after signature + IHDR)
326    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    // JPEG: look for SOF0/1/2 marker (0xFF 0xC0/0xC1/0xC2)
333    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            // Skip to next marker segment
346            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
354/// Format a byte size for display.
355fn 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        // Minimal valid PNG: 2x3 pixels (width=2, height=3)
417        let png = vec![
418            0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A, // signature
419            0x00, 0x00, 0x00, 0x0D, 0x49, 0x48, 0x44, 0x52, // IHDR
420            0x00, 0x00, 0x00, 0x02, // width  = 2
421            0x00, 0x00, 0x00, 0x03, // height = 3
422            0x08, 0x02, 0x00, 0x00, 0x00, // bit depth + color type + etc
423            0x90, 0x77, 0x53, 0xDE, // IHDR CRC
424            0x00, 0x00, 0x00, 0x00, 0x49, 0x45, 0x4E, 0x44, // IEND
425            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    // ── notebook handling ────────────────────────────────────────────────
443
444    /// A base64 PNG payload of the requested length, as jupyter stores it.
445    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        // The base64 blob is gone, replaced by a size-recording placeholder.
489        assert!(!out.contains(&fake_b64(1000)), "base64 payload survived");
490        assert!(out.contains("[stripped image/png output — 100000 base64 chars]"));
491
492        // Everything the model actually needs survives.
493        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        // Meta line reports the line count first so the UI card still parses it.
500        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        // Nothing was rewritten, so no action notes are appended.
574        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        // `from`/`to` index the rendered body, never the meta line — the same
606        // contract `read_partial` honours for plain files.
607        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    /// Regression for the bug that motivated this code path: a notebook whose
634    /// cells embed four ~380 KB figures must not produce a multi-megabyte tool
635    /// result (that request exceeded the provider's input limit).
636    #[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        // A notebook is not an image: no `[IMAGE]` marker, so the agent layer
683        // must not try to attach it as a multimodal payload.
684        assert!(!out.starts_with("[IMAGE]"));
685        assert!(out.contains("plot()"));
686        assert!(out.contains("[stripped image/png output"));
687    }
688}