pi-oxidized 0.1.1

package/crates/pi/src/core/tools/read.rs

@@ -0,0 +1,1413 @@
+//! Read tool: text files and supported images.
+//!
+//! Ports `.references/pi/packages/coding-agent/src/core/tools/read.ts` plus the
+//! image pipeline from `utils/{mime,image-process,image-resize-core}.ts`.
+
+use std::fmt::Write as _;
+use std::io::Cursor;
+use std::path::PathBuf;
+use std::sync::Arc;
+
+use base64::Engine as _;
+use base64::engine::general_purpose::STANDARD as BASE64;
+use futures::FutureExt as _;
+use futures::future::BoxFuture;
+use image::codecs::jpeg::JpegEncoder;
+use image::imageops::FilterType;
+use image::{DynamicImage, ImageDecoder, ImageFormat, ImageReader};
+use pi_agent::{AgentTool, AgentToolResult, ToolError, ToolUpdates};
+use pi_ai::types::{ImageContent, Model, ModelInput, TextContent, ToolResultContent};
+use schemars::JsonSchema;
+use serde::{Deserialize, Serialize};
+use serde_json::{Map, Value, json};
+use tokio::task;
+use tokio_util::sync::CancellationToken;
+
+use super::{
+    DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, PathResolveError, TruncationOptions, TruncationResult,
+    format_size, resolve_read_path_async, truncate_head,
+};
+
+/// Default max image edge (TypeScript `ImageResizeOptions.maxWidth/maxHeight`).
+const IMAGE_MAX_DIMENSION: u32 = 2000;
+/// Default max base64 payload size (4.5 MiB).
+const IMAGE_MAX_BASE64_BYTES: usize = 4_718_592;
+/// Default JPEG quality for the first encode candidate.
+const IMAGE_JPEG_QUALITY: u8 = 80;
+/// Bytes sniffed for MIME detection (TypeScript `IMAGE_TYPE_SNIFF_BYTES`).
+const IMAGE_TYPE_SNIFF_BYTES: usize = 4100;
+
+const PNG_SIGNATURE: [u8; 8] = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+
+/// TypeBox-compatible read arguments (fixture `read.json`).
+#[derive(Clone, Debug, Deserialize, JsonSchema, PartialEq, Serialize)]
+pub struct ReadToolInput {
+    /// Path to the file to read (relative or absolute).
+    #[schemars(description = "Path to the file to read (relative or absolute)")]
+    pub path: String,
+    /// Line number to start reading from (1-indexed).
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[schemars(description = "Line number to start reading from (1-indexed)")]
+    pub offset: Option<f64>,
+    /// Maximum number of lines to read.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    #[schemars(description = "Maximum number of lines to read")]
+    pub limit: Option<f64>,
+}
+
+/// Optional structured details returned by the read tool.
+#[derive(Clone, Debug, Default, Deserialize, PartialEq, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ReadToolDetails {
+    /// Truncation metadata when head truncation applied.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub truncation: Option<TruncationResult>,
+}
+
+/// Options for [`ReadTool`].
+#[derive(Clone, Debug)]
+pub struct ReadToolOptions {
+    /// Working directory used to resolve relative paths.
+    pub cwd: PathBuf,
+    /// Whether to auto-resize images to provider inline limits. Default: true.
+    pub auto_resize_images: bool,
+    /// When `Some` and the model does not accept images, append the non-vision note.
+    pub model: Option<Model>,
+}
+
+impl ReadToolOptions {
+    /// Builds options for `cwd` with default image resizing and no model.
+    #[must_use]
+    pub fn new(cwd: impl Into<PathBuf>) -> Self {
+        Self {
+            cwd: cwd.into(),
+            auto_resize_images: true,
+            model: None,
+        }
+    }
+
+    /// Sets the model used for non-vision image omission notes.
+    #[must_use]
+    pub fn with_model(mut self, model: Option<Model>) -> Self {
+        self.model = model;
+        self
+    }
+
+    /// Enables or disables automatic image resizing.
+    #[must_use]
+    pub fn with_auto_resize_images(mut self, auto_resize_images: bool) -> Self {
+        self.auto_resize_images = auto_resize_images;
+        self
+    }
+}
+
+/// Agent tool that reads text and supported image files.
+#[derive(Clone, Debug)]
+pub struct ReadTool {
+    cwd: PathBuf,
+    auto_resize_images: bool,
+    model: Option<Model>,
+    parameters: Value,
+    description: String,
+}
+
+impl ReadTool {
+    /// Creates a read tool rooted at `cwd`.
+    #[must_use]
+    pub fn new(cwd: impl Into<PathBuf>) -> Self {
+        Self::with_options(ReadToolOptions::new(cwd))
+    }
+
+    /// Creates a read tool from explicit options.
+    #[must_use]
+    pub fn with_options(options: ReadToolOptions) -> Self {
+        let description = format!(
+            "Read the contents of a file. Supports text files and images (jpg, png, gif, webp, bmp). Images are sent as attachments. For text files, output is truncated to {DEFAULT_MAX_LINES} lines or {}KB (whichever is hit first). Use offset/limit for large files. When you need the full file, continue with offset until complete.",
+            DEFAULT_MAX_BYTES / 1024
+        );
+        Self {
+            cwd: options.cwd,
+            auto_resize_images: options.auto_resize_images,
+            model: options.model,
+            parameters: read_parameters_schema(),
+            description,
+        }
+    }
+
+    /// Returns the JSON Schema for read arguments (normalized `TypeBox` shape).
+    #[must_use]
+    pub fn parameters_schema() -> Value {
+        read_parameters_schema()
+    }
+
+    /// Validates raw tool arguments into [`ReadToolInput`].
+    ///
+    /// # Errors
+    ///
+    /// Returns [`ToolError`] when required fields are missing or mistyped.
+    pub fn parse_input(args: &Map<String, Value>) -> Result<ReadToolInput, ToolError> {
+        serde_json::from_value(Value::Object(args.clone()))
+            .map_err(|error| ToolError::new(format!("Read tool input is invalid. {error}")))
+    }
+}
+
+impl AgentTool for ReadTool {
+    fn name(&self) -> &'static str {
+        "read"
+    }
+
+    fn label(&self) -> &'static str {
+        "read"
+    }
+
+    fn description(&self) -> &str {
+        &self.description
+    }
+
+    fn parameters(&self) -> &Value {
+        &self.parameters
+    }
+
+    fn validate_arguments(
+        &self,
+        args: &Map<String, Value>,
+    ) -> Result<Map<String, Value>, ToolError> {
+        let _ = Self::parse_input(args)?;
+        Ok(args.clone())
+    }
+
+    fn execute(
+        &self,
+        _tool_call_id: &str,
+        args: Map<String, Value>,
+        cancel: CancellationToken,
+        _updates: ToolUpdates,
+    ) -> BoxFuture<'static, Result<AgentToolResult, ToolError>> {
+        let cwd = self.cwd.clone();
+        let auto_resize_images = self.auto_resize_images;
+        let model = self.model.clone();
+        async move {
+            throw_if_cancelled(&cancel)?;
+            let input = ReadTool::parse_input(&args)?;
+            let absolute_path =
+                resolve_read_path_async(&input.path, cwd.to_string_lossy().as_ref())
+                    .await
+                    .map_err(|error| path_error(&error))?;
+            throw_if_cancelled(&cancel)?;
+
+            // Readable access check (TypeScript fs.access R_OK).
+            ensure_readable(&absolute_path).await?;
+            throw_if_cancelled(&cancel)?;
+
+            let bytes = tokio::fs::read(&absolute_path).await.map_err(|error| {
+                ToolError::new(format!("Could not read file {absolute_path}: {error}"))
+            })?;
+            throw_if_cancelled(&cancel)?;
+
+            let sniff_len = bytes.len().min(IMAGE_TYPE_SNIFF_BYTES);
+            if let Some(mime) = detect_supported_image_mime_type(&bytes[..sniff_len]) {
+                let non_vision = non_vision_image_note(model.as_ref());
+                let processed = {
+                    let cancel = cancel.clone();
+                    task::spawn_blocking(move || {
+                        throw_if_cancelled(&cancel)?;
+                        Ok::<ProcessImageResult, ToolError>(process_image_bytes(
+                            &bytes,
+                            &mime,
+                            auto_resize_images,
+                        ))
+                    })
+                    .await
+                    .map_err(|error| {
+                        ToolError::new(format!("image processing failed: {error}"))
+                    })??
+                };
+                throw_if_cancelled(&cancel)?;
+                return Ok(image_tool_result(processed, non_vision.as_deref()));
+            }
+
+            // Byte-preserving UTF-8 decode (lossy only at invalid sequences, matching
+            // Node Buffer.toString("utf-8") replacement behavior for invalid bytes).
+            let text_content = String::from_utf8_lossy(&bytes).into_owned();
+            let result = build_text_result(&input, &text_content)?;
+            throw_if_cancelled(&cancel)?;
+            Ok(result)
+        }
+        .boxed()
+    }
+}
+
+fn build_text_result(
+    input: &ReadToolInput,
+    text_content: &str,
+) -> Result<AgentToolResult, ToolError> {
+    // TypeScript split("\n") keeps a trailing empty entry in totalFileLines.
+    let all_lines: Vec<&str> = text_content.split('\n').collect();
+    let total_file_lines = all_lines.len();
+    let offset = input.offset.map(floored_nonnegative_usize);
+    let limit = input.limit.map(floored_nonnegative_usize);
+
+    let start_line = offset.map_or(0, |value| value.saturating_sub(1));
+
+    if start_line >= all_lines.len() {
+        return Err(ToolError::new(format!(
+            "Offset {} is beyond end of file ({total_file_lines} lines total)",
+            offset.unwrap_or(0)
+        )));
+    }
+    let start_line_display = start_line + 1;
+
+    let (selected_content, user_limited_lines) = if let Some(limit) = limit {
+        let end_line = start_line.saturating_add(limit).min(all_lines.len());
+        let selected = all_lines[start_line..end_line].join("\n");
+        (selected, Some(end_line - start_line))
+    } else {
+        (all_lines[start_line..].join("\n"), None)
+    };
+
+    let truncation = truncate_head(
+        &selected_content,
+        TruncationOptions {
+            max_lines: Some(DEFAULT_MAX_LINES),
+            max_bytes: Some(DEFAULT_MAX_BYTES),
+        },
+    );
+
+    let (output_text, details) = if truncation.first_line_exceeds_limit {
+        let first_line_size =
+            format_size(u64::try_from(all_lines[start_line].len()).unwrap_or(u64::MAX));
+        let output = format!(
+            "[Line {start_line_display} is {first_line_size}, exceeds {} limit. Use bash: sed -n '{start_line_display}p' {} | head -c {DEFAULT_MAX_BYTES}]",
+            format_size(u64::try_from(DEFAULT_MAX_BYTES).unwrap_or(u64::MAX)),
+            input.path
+        );
+        (
+            output,
+            Some(ReadToolDetails {
+                truncation: Some(truncation),
+            }),
+        )
+    } else if truncation.truncated {
+        let end_line_display = start_line_display + truncation.output_lines - 1;
+        let next_offset = end_line_display + 1;
+        let mut output = truncation.content.clone();
+        match truncation.truncated_by {
+            Some(super::TruncatedBy::Lines) => {
+                write!(
+                    output,
+                    "\n\n[Showing lines {start_line_display}-{end_line_display} of {total_file_lines}. Use offset={next_offset} to continue.]"
+                )
+                .map_err(|error| ToolError::new(format!("Could not format read output: {error}")))?;
+            }
+            _ => {
+                write!(
+                    output,
+                    "\n\n[Showing lines {start_line_display}-{end_line_display} of {total_file_lines} ({} limit). Use offset={next_offset} to continue.]",
+                    format_size(u64::try_from(DEFAULT_MAX_BYTES).unwrap_or(u64::MAX))
+                )
+                .map_err(|error| ToolError::new(format!("Could not format read output: {error}")))?;
+            }
+        }
+        (
+            output,
+            Some(ReadToolDetails {
+                truncation: Some(truncation),
+            }),
+        )
+    } else if let Some(user_limited) = user_limited_lines {
+        if start_line + user_limited < all_lines.len() {
+            let remaining = all_lines.len() - (start_line + user_limited);
+            let next_offset = start_line + user_limited + 1;
+            (
+                format!(
+                    "{}\n\n[{remaining} more lines in file. Use offset={next_offset} to continue.]",
+                    truncation.content
+                ),
+                None,
+            )
+        } else {
+            (truncation.content, None)
+        }
+    } else {
+        (truncation.content, None)
+    };
+
+    Ok(AgentToolResult {
+        content: vec![ToolResultContent::Text(TextContent::new(output_text))],
+        details: details_value(details),
+        added_tool_names: None,
+        terminate: None,
+    })
+}
+
+fn details_value(details: Option<ReadToolDetails>) -> Value {
+    match details {
+        Some(details) => serde_json::to_value(details).unwrap_or_else(|_| json!({})),
+        None => Value::Null,
+    }
+}
+
+fn image_tool_result(processed: ProcessImageResult, non_vision: Option<&str>) -> AgentToolResult {
+    match processed {
+        ProcessImageResult::Failed(error) => {
+            let mut text_note = format!("Read image file [{}]\n{}", error.mime_type, error.message);
+            if let Some(note) = non_vision {
+                text_note.push('\n');
+                text_note.push_str(note);
+            }
+            AgentToolResult {
+                content: vec![ToolResultContent::Text(TextContent::new(text_note))],
+                details: Value::Null,
+                added_tool_names: None,
+                terminate: None,
+            }
+        }
+        ProcessImageResult::Ok(processed) => {
+            let ProcessedImage {
+                data,
+                mime_type,
+                hints,
+                ..
+            } = processed;
+            let mut text_note = format!("Read image file [{mime_type}]");
+            if !hints.is_empty() {
+                text_note.push('\n');
+                text_note.push_str(&hints.join("\n"));
+            }
+            if let Some(note) = non_vision {
+                text_note.push('\n');
+                text_note.push_str(note);
+            }
+            let mut content = vec![ToolResultContent::Text(TextContent::new(text_note))];
+            if non_vision.is_none() {
+                content.push(ToolResultContent::Image(ImageContent::new(data, mime_type)));
+            }
+            AgentToolResult {
+                content,
+                details: Value::Null,
+                added_tool_names: None,
+                terminate: None,
+            }
+        }
+    }
+}
+
+fn non_vision_image_note(model: Option<&Model>) -> Option<String> {
+    let model = model?;
+    if model.input.contains(&ModelInput::Image) {
+        None
+    } else {
+        Some(
+            "[Current model does not support images. The image will be omitted from this request.]"
+                .to_owned(),
+        )
+    }
+}
+
+async fn ensure_readable(path: &str) -> Result<(), ToolError> {
+    match tokio::fs::metadata(path).await {
+        Ok(meta) if meta.is_file() || meta.is_dir() => {
+            // Open for read to mirror access(R_OK).
+            tokio::fs::File::open(path)
+                .await
+                .map_err(|error| ToolError::new(format!("Could not read file {path}: {error}")))?;
+            Ok(())
+        }
+        Ok(_) => Err(ToolError::new(format!(
+            "Could not read file {path}: not a regular file"
+        ))),
+        Err(error) => Err(ToolError::new(format!(
+            "Could not read file {path}: {error}"
+        ))),
+    }
+}
+
+// ---------------------------------------------------------------------------
+// MIME sniffing (mime.ts)
+// ---------------------------------------------------------------------------
+
+/// Detects a supported inline image MIME type from magic bytes.
+#[must_use]
+pub fn detect_supported_image_mime_type(buffer: &[u8]) -> Option<String> {
+    if starts_with(buffer, &[0xff, 0xd8, 0xff]) {
+        return if buffer.get(3) == Some(&0xf7) {
+            None
+        } else {
+            Some("image/jpeg".to_owned())
+        };
+    }
+    if starts_with(buffer, &PNG_SIGNATURE) {
+        return if is_png(buffer) && !is_animated_png(buffer) {
+            Some("image/png".to_owned())
+        } else {
+            None
+        };
+    }
+    if starts_with_ascii(buffer, 0, b"GIF") {
+        return Some("image/gif".to_owned());
+    }
+    if starts_with_ascii(buffer, 0, b"RIFF") && starts_with_ascii(buffer, 8, b"WEBP") {
+        return Some("image/webp".to_owned());
+    }
+    if starts_with_ascii(buffer, 0, b"BM") && is_bmp(buffer) {
+        return Some("image/bmp".to_owned());
+    }
+    None
+}
+
+fn is_png(buffer: &[u8]) -> bool {
+    buffer.len() >= 16
+        && read_u32_be(buffer, PNG_SIGNATURE.len()) == Some(13)
+        && starts_with_ascii(buffer, 12, b"IHDR")
+}
+
+fn is_animated_png(buffer: &[u8]) -> bool {
+    let mut offset = PNG_SIGNATURE.len();
+    while offset + 8 <= buffer.len() {
+        let Some(chunk_length) = read_u32_be(buffer, offset) else {
+            return false;
+        };
+        let chunk_type_offset = offset + 4;
+        if starts_with_ascii(buffer, chunk_type_offset, b"acTL") {
+            return true;
+        }
+        if starts_with_ascii(buffer, chunk_type_offset, b"IDAT") {
+            return false;
+        }
+        let next_offset = usize::try_from(chunk_length)
+            .ok()
+            .and_then(|chunk_length| offset.checked_add(8 + chunk_length))
+            .and_then(|v| v.checked_add(4));
+        let Some(next_offset) = next_offset else {
+            return false;
+        };
+        if next_offset <= offset || next_offset > buffer.len() {
+            return false;
+        }
+        offset = next_offset;
+    }
+    false
+}
+
+fn is_bmp(buffer: &[u8]) -> bool {
+    if buffer.len() < 26 {
+        return false;
+    }
+    let Some(declared_file_size) = read_u32_le(buffer, 2) else {
+        return false;
+    };
+    let Some(pixel_data_offset) = read_u32_le(buffer, 10) else {
+        return false;
+    };
+    let Some(dib_header_size) = read_u32_le(buffer, 14) else {
+        return false;
+    };
+    if declared_file_size != 0 && declared_file_size < 26 {
+        return false;
+    }
+    if pixel_data_offset < 14 + dib_header_size {
+        return false;
+    }
+    if declared_file_size != 0 && pixel_data_offset >= declared_file_size {
+        return false;
+    }
+
+    let (color_planes, bits_per_pixel) = if dib_header_size == 12 {
+        (
+            read_u16_le(buffer, 22).unwrap_or(0),
+            read_u16_le(buffer, 24).unwrap_or(0),
+        )
+    } else if (40..=124).contains(&dib_header_size) {
+        if buffer.len() < 30 {
+            return false;
+        }
+        (
+            read_u16_le(buffer, 26).unwrap_or(0),
+            read_u16_le(buffer, 28).unwrap_or(0),
+        )
+    } else {
+        return false;
+    };
+
+    color_planes == 1 && matches!(bits_per_pixel, 1 | 4 | 8 | 16 | 24 | 32)
+}
+
+fn read_u16_le(buffer: &[u8], offset: usize) -> Option<u16> {
+    let bytes = buffer.get(offset..)?.get(..2)?.try_into().ok()?;
+    Some(u16::from_le_bytes(bytes))
+}
+
+fn read_u32_be(buffer: &[u8], offset: usize) -> Option<u32> {
+    let bytes = buffer.get(offset..)?.get(..4)?.try_into().ok()?;
+    Some(u32::from_be_bytes(bytes))
+}
+
+fn read_u32_le(buffer: &[u8], offset: usize) -> Option<u32> {
+    let bytes = buffer.get(offset..)?.get(..4)?.try_into().ok()?;
+    Some(u32::from_le_bytes(bytes))
+}
+
+fn starts_with(buffer: &[u8], bytes: &[u8]) -> bool {
+    buffer.len() >= bytes.len() && buffer[..bytes.len()] == *bytes
+}
+
+fn starts_with_ascii(buffer: &[u8], offset: usize, text: &[u8]) -> bool {
+    buffer
+        .get(offset..offset + text.len())
+        .is_some_and(|slice| slice == text)
+}
+
+// ---------------------------------------------------------------------------
+// Image processing (image-process.ts + image-resize-core.ts)
+// ---------------------------------------------------------------------------
+
+/// Successfully processed image data ready for an inline attachment.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ProcessedImage {
+    /// Base64-encoded attachment bytes.
+    pub data: String,
+    /// MIME type of the encoded attachment.
+    pub mime_type: String,
+    /// Human-readable conversion and resize hints.
+    pub hints: Vec<String>,
+    /// Original and delivered dimensions when the resize pipeline decoded them.
+    pub dimensions: Option<ProcessedImageDimensions>,
+}
+
+/// Original and delivered image dimensions.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct ProcessedImageDimensions {
+    /// Width after applying EXIF orientation, before resizing.
+    pub original_width: u32,
+    /// Height after applying EXIF orientation, before resizing.
+    pub original_height: u32,
+    /// Delivered attachment width.
+    pub width: u32,
+    /// Delivered attachment height.
+    pub height: u32,
+    /// Whether the delivered bytes were re-encoded by the resize pipeline.
+    pub was_resized: bool,
+}
+
+/// Failure produced when image bytes cannot become a supported attachment.
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub struct ProcessImageError {
+    /// MIME type detected for the source bytes.
+    pub mime_type: String,
+    /// Exact user-facing omission notice.
+    pub message: String,
+}
+
+/// Result of [`process_image_bytes`].
+#[derive(Clone, Debug, Eq, PartialEq)]
+pub enum ProcessImageResult {
+    /// Supported attachment data.
+    Ok(ProcessedImage),
+    /// Conversion or resizing failure.
+    Failed(ProcessImageError),
+}
+
+struct NormalizedImage {
+    bytes: Vec<u8>,
+    mime_type: String,
+    converted_from: Option<String>,
+}
+
+struct ResizedImage {
+    data: String,
+    mime_type: String,
+    original_width: u32,
+    original_height: u32,
+    width: u32,
+    height: u32,
+    was_resized: bool,
+}
+
+/// Processes detected image bytes using the same pipeline as [`ReadTool`].
+///
+/// Supported JPEG/PNG/GIF/WebP bytes are preserved when already within
+/// provider limits. BMP and other decodable inputs are normalized to PNG.
+/// With `auto_resize_images`, EXIF orientation is applied and output is kept
+/// below the 2000×2000 and 4.5 MiB base64 limits.
+#[must_use]
+pub fn process_image_bytes(
+    bytes: &[u8],
+    mime_type: &str,
+    auto_resize_images: bool,
+) -> ProcessImageResult {
+    let Some(normalized) = normalize_image(bytes, mime_type) else {
+        return ProcessImageResult::Failed(ProcessImageError {
+            mime_type: mime_type.to_owned(),
+            message: "[Image omitted: could not be converted to a supported inline image format.]"
+                .to_owned(),
+        });
+    };
+
+    if auto_resize_images {
+        let Some(resized) = resize_image(&normalized.bytes, &normalized.mime_type) else {
+            return ProcessImageResult::Failed(ProcessImageError {
+                mime_type: normalized.mime_type,
+                message: "[Image omitted: could not be resized below the inline image size limit.]"
+                    .to_owned(),
+            });
+        };
+        let mut hints = Vec::new();
+        if let Some(hint) =
+            conversion_hint(normalized.converted_from.as_deref(), &resized.mime_type)
+        {
+            hints.push(hint);
+        }
+        if let Some(note) = format_dimension_note(&resized) {
+            hints.push(note);
+        }
+        let dimensions = ProcessedImageDimensions {
+            original_width: resized.original_width,
+            original_height: resized.original_height,
+            width: resized.width,
+            height: resized.height,
+            was_resized: resized.was_resized,
+        };
+        return ProcessImageResult::Ok(ProcessedImage {
+            data: resized.data,
+            mime_type: resized.mime_type,
+            hints,
+            dimensions: Some(dimensions),
+        });
+    }
+
+    let mut hints = Vec::new();
+    if let Some(hint) = conversion_hint(normalized.converted_from.as_deref(), &normalized.mime_type)
+    {
+        hints.push(hint);
+    }
+    ProcessImageResult::Ok(ProcessedImage {
+        data: BASE64.encode(&normalized.bytes),
+        mime_type: normalized.mime_type,
+        hints,
+        dimensions: None,
+    })
+}
+
+fn base_mime_type(mime_type: &str) -> String {
+    mime_type
+        .split(';')
+        .next()
+        .unwrap_or(mime_type)
+        .trim()
+        .to_ascii_lowercase()
+}
+
+fn normalize_supported_image_mime_type(mime_type: &str) -> Option<&'static str> {
+    match base_mime_type(mime_type).as_str() {
+        "image/png" => Some("image/png"),
+        "image/jpeg" | "image/jpg" => Some("image/jpeg"),
+        "image/gif" => Some("image/gif"),
+        "image/webp" => Some("image/webp"),
+        _ => None,
+    }
+}
+
+fn normalize_image(bytes: &[u8], mime_type: &str) -> Option<NormalizedImage> {
+    if let Some(normalized) = normalize_supported_image_mime_type(mime_type) {
+        return Some(NormalizedImage {
+            bytes: bytes.to_vec(),
+            mime_type: normalized.to_owned(),
+            converted_from: None,
+        });
+    }
+
+    let png_bytes = convert_image_bytes_to_png(bytes)?;
+    Some(NormalizedImage {
+        bytes: png_bytes,
+        mime_type: "image/png".to_owned(),
+        converted_from: Some(base_mime_type(mime_type)),
+    })
+}
+
+fn conversion_hint(from: Option<&str>, to: &str) -> Option<String> {
+    let from = from?;
+    if from == to {
+        None
+    } else {
+        Some(format!("[Image converted from {from} to {to}.]"))
+    }
+}
+
+/// Decode bytes into PNG, applying the decoder's reported orientation.
+///
+/// Shared with the clipboard/Kitty display paths so the image decoder is not
+/// duplicated. Returns `None` when the bytes cannot be decoded.
+#[must_use]
+pub fn convert_image_bytes_to_png(bytes: &[u8]) -> Option<Vec<u8>> {
+    let mut reader = ImageReader::new(Cursor::new(bytes))
+        .with_guessed_format()
+        .ok()?;
+    reader.no_limits();
+    let mut decoder = reader.into_decoder().ok()?;
+    let orientation = decoder
+        .orientation()
+        .unwrap_or(image::metadata::Orientation::NoTransforms);
+    let mut image = DynamicImage::from_decoder(decoder).ok()?;
+    image.apply_orientation(orientation);
+    let mut out = Vec::new();
+    image
+        .write_to(&mut Cursor::new(&mut out), ImageFormat::Png)
+        .ok()?;
+    Some(out)
+}
+
+fn resize_image(input_bytes: &[u8], mime_type: &str) -> Option<ResizedImage> {
+    let input_base64_size = input_bytes.len().div_ceil(3) * 4;
+
+    let mut reader = ImageReader::new(Cursor::new(input_bytes))
+        .with_guessed_format()
+        .ok()?;
+    reader.no_limits();
+    let mut decoder = reader.into_decoder().ok()?;
+    let orientation = decoder
+        .orientation()
+        .unwrap_or(image::metadata::Orientation::NoTransforms);
+    let mut image = DynamicImage::from_decoder(decoder).ok()?;
+    image.apply_orientation(orientation);
+
+    let original_width = image.width();
+    let original_height = image.height();
+    let format = mime_type.split('/').nth(1).unwrap_or("png");
+
+    if original_width <= IMAGE_MAX_DIMENSION
+        && original_height <= IMAGE_MAX_DIMENSION
+        && input_base64_size < IMAGE_MAX_BASE64_BYTES
+    {
+        return Some(ResizedImage {
+            data: BASE64.encode(input_bytes),
+            mime_type: if mime_type.is_empty() {
+                format!("image/{format}")
+            } else {
+                mime_type.to_owned()
+            },
+            original_width,
+            original_height,
+            width: original_width,
+            height: original_height,
+            was_resized: false,
+        });
+    }
+
+    let mut target_width = original_width;
+    let mut target_height = original_height;
+    if target_width > IMAGE_MAX_DIMENSION {
+        target_height = rounded_scaled_dimension(target_height, IMAGE_MAX_DIMENSION, target_width);
+        target_width = IMAGE_MAX_DIMENSION;
+    }
+    if target_height > IMAGE_MAX_DIMENSION {
+        target_width = rounded_scaled_dimension(target_width, IMAGE_MAX_DIMENSION, target_height);
+        target_height = IMAGE_MAX_DIMENSION;
+    }
+    target_width = target_width.max(1);
+    target_height = target_height.max(1);
+
+    let mut quality_steps = vec![IMAGE_JPEG_QUALITY, 85, 70, 55, 40];
+    quality_steps.sort_unstable();
+    quality_steps.dedup();
+    // Preserve first-try order: preferred quality first, then the rest descending-ish.
+    let mut ordered = vec![IMAGE_JPEG_QUALITY];
+    for q in [85_u8, 70, 55, 40] {
+        if q != IMAGE_JPEG_QUALITY {
+            ordered.push(q);
+        }
+    }
+
+    let mut current_width = target_width;
+    let mut current_height = target_height;
+
+    loop {
+        let candidates = try_encodings(&image, current_width, current_height, &ordered);
+        for candidate in candidates {
+            if candidate.encoded_size < IMAGE_MAX_BASE64_BYTES {
+                return Some(ResizedImage {
+                    data: candidate.data,
+                    mime_type: candidate.mime_type,
+                    original_width,
+                    original_height,
+                    width: current_width,
+                    height: current_height,
+                    was_resized: true,
+                });
+            }
+        }
+
+        if current_width == 1 && current_height == 1 {
+            break;
+        }
+        let next_width = if current_width == 1 {
+            1
+        } else {
+            current_width.saturating_mul(3) / 4
+        };
+        let next_height = if current_height == 1 {
+            1
+        } else {
+            current_height.saturating_mul(3) / 4
+        };
+        if next_width == current_width && next_height == current_height {
+            break;
+        }
+        current_width = next_width;
+        current_height = next_height;
+    }
+
+    None
+}
+
+struct EncodedCandidate {
+    data: String,
+    encoded_size: usize,
+    mime_type: String,
+}
+
+fn try_encodings(
+    image: &DynamicImage,
+    width: u32,
+    height: u32,
+    jpeg_qualities: &[u8],
+) -> Vec<EncodedCandidate> {
+    let resized = if image.width() == width && image.height() == height {
+        image.clone()
+    } else {
+        image.resize_exact(width, height, FilterType::Lanczos3)
+    };
+
+    let mut candidates = Vec::new();
+    if let Some(png) = encode_png(&resized) {
+        candidates.push(encode_candidate(&png, "image/png"));
+    }
+    for &quality in jpeg_qualities {
+        if let Some(jpeg) = encode_jpeg(&resized, quality) {
+            candidates.push(encode_candidate(&jpeg, "image/jpeg"));
+        }
+    }
+    candidates
+}
+
+fn encode_candidate(bytes: &[u8], mime_type: &str) -> EncodedCandidate {
+    let data = BASE64.encode(bytes);
+    let encoded_size = data.len();
+    EncodedCandidate {
+        data,
+        encoded_size,
+        mime_type: mime_type.to_owned(),
+    }
+}
+
+fn encode_png(image: &DynamicImage) -> Option<Vec<u8>> {
+    let mut out = Vec::new();
+    image
+        .write_to(&mut Cursor::new(&mut out), ImageFormat::Png)
+        .ok()?;
+    Some(out)
+}
+
+fn encode_jpeg(image: &DynamicImage, quality: u8) -> Option<Vec<u8>> {
+    let rgb = image.to_rgb8();
+    let mut out = Vec::new();
+    let mut encoder = JpegEncoder::new_with_quality(&mut out, quality);
+    encoder
+        .encode(
+            rgb.as_raw(),
+            rgb.width(),
+            rgb.height(),
+            image::ExtendedColorType::Rgb8,
+        )
+        .ok()?;
+    Some(out)
+}
+
+fn format_dimension_note(result: &ResizedImage) -> Option<String> {
+    if !result.was_resized {
+        return None;
+    }
+    let scale = f64::from(result.original_width) / f64::from(result.width.max(1));
+    Some(format!(
+        "[Image: original {}x{}, displayed at {}x{}. Multiply coordinates by {:.2} to map to original image.]",
+        result.original_width, result.original_height, result.width, result.height, scale
+    ))
+}
+
+// ---------------------------------------------------------------------------
+// Schema helpers
+// ---------------------------------------------------------------------------
+
+fn read_parameters_schema() -> Value {
+    normalize_tool_schema(schemars::schema_for!(ReadToolInput))
+}
+
+fn normalize_tool_schema(schema: schemars::Schema) -> Value {
+    let mut value = serde_json::to_value(schema).unwrap_or_else(|_| Value::Object(Map::new()));
+    if let Value::Object(map) = &mut value {
+        map.remove("$schema");
+        map.remove("title");
+        map.remove("description");
+        map.remove("additionalProperties");
+        normalize_schema_node(map);
+    }
+    value
+}
+
+fn normalize_schema_node(map: &mut Map<String, Value>) {
+    map.remove("format");
+    // schemars represents Option<T> as ["number","null"]; TypeBox optional
+    // numbers are just "number".
+    if let Some(Value::Array(types)) = map.get("type").cloned() {
+        let non_null: Vec<Value> = types
+            .into_iter()
+            .filter(|t| t.as_str() != Some("null"))
+            .collect();
+        if non_null.len() == 1 {
+            map.insert("type".to_owned(), non_null[0].clone());
+        } else if !non_null.is_empty() {
+            map.insert("type".to_owned(), Value::Array(non_null));
+        }
+    }
+    let keys: Vec<String> = map.keys().cloned().collect();
+    for key in keys {
+        match map.get_mut(&key) {
+            Some(Value::Object(child)) => normalize_schema_node(child),
+            Some(Value::Array(items)) => {
+                for item in items {
+                    if let Value::Object(child) = item {
+                        normalize_schema_node(child);
+                    }
+                }
+            }
+            _ => {}
+        }
+    }
+}
+
+fn throw_if_cancelled(cancel: &CancellationToken) -> Result<(), ToolError> {
+    if cancel.is_cancelled() {
+        Err(ToolError::new("Operation aborted"))
+    } else {
+        Ok(())
+    }
+}
+
+fn path_error(error: &PathResolveError) -> ToolError {
+    ToolError::new(error.to_string())
+}
+
+/// Builds an [`Arc<dyn AgentTool>`] read tool for `cwd`.
+#[must_use]
+pub fn create_read_tool(cwd: impl Into<PathBuf>) -> Arc<dyn AgentTool> {
+    Arc::new(ReadTool::new(cwd))
+}
+
+fn floored_nonnegative_usize(value: f64) -> usize {
+    if !value.is_finite() || value <= 0.0 {
+        return 0;
+    }
+    value.floor().to_string().parse().unwrap_or(usize::MAX)
+}
+
+fn rounded_scaled_dimension(value: u32, numerator: u32, denominator: u32) -> u32 {
+    let denominator = u64::from(denominator);
+    let scaled = u64::from(value) * u64::from(numerator);
+    u32::try_from((scaled + denominator / 2) / denominator).unwrap_or(u32::MAX)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use pi_ai::types::ModelCost;
+    use serde_json::json;
+    use tempfile::tempdir;
+
+    fn fixture_schema() -> Result<Value, serde_json::Error> {
+        let text = include_str!("../../../tests/fixtures/tool-schemas/read.json");
+        serde_json::from_str(text)
+    }
+
+    fn text_model() -> Model {
+        Model {
+            id: "text-only".to_owned(),
+            name: "text-only".to_owned(),
+            api: "test".to_owned(),
+            provider: "test".to_owned(),
+            base_url: String::new(),
+            reasoning: false,
+            input: vec![ModelInput::Text],
+            cost: ModelCost {
+                input: 0.0,
+                output: 0.0,
+                cache_read: 0.0,
+                cache_write: 0.0,
+                tiers: None,
+            },
+            context_window: 8_000,
+            max_tokens: 1_024,
+            headers: None,
+            compat: None,
+            thinking_level_map: None,
+            extra: std::collections::BTreeMap::default(),
+        }
+    }
+
+    fn vision_model() -> Model {
+        let mut model = text_model();
+        model.id = "vision".to_owned();
+        model.name = "vision".to_owned();
+        model.input = vec![ModelInput::Text, ModelInput::Image];
+        model
+    }
+
+    fn json_map(value: Value) -> Result<Map<String, Value>, &'static str> {
+        if let Value::Object(map) = value {
+            Ok(map)
+        } else {
+            Err("expected JSON object")
+        }
+    }
+
+    fn text_of(result: &AgentToolResult) -> String {
+        match result.content.first() {
+            Some(ToolResultContent::Text(text)) => text.text.to_string(),
+            _ => String::new(),
+        }
+    }
+
+    fn tiny_bmp_1x1_red() -> Vec<u8> {
+        let mut buffer = vec![0_u8; 58];
+        buffer[0] = b'B';
+        buffer[1] = b'M';
+        buffer[2..6].copy_from_slice(&58_u32.to_le_bytes());
+        buffer[10..14].copy_from_slice(&54_u32.to_le_bytes());
+        buffer[14..18].copy_from_slice(&40_u32.to_le_bytes());
+        buffer[18..22].copy_from_slice(&1_i32.to_le_bytes());
+        buffer[22..26].copy_from_slice(&1_i32.to_le_bytes());
+        buffer[26..28].copy_from_slice(&1_u16.to_le_bytes());
+        buffer[28..30].copy_from_slice(&24_u16.to_le_bytes());
+        buffer[30..34].copy_from_slice(&0_u32.to_le_bytes());
+        buffer[34..38].copy_from_slice(&4_u32.to_le_bytes());
+        buffer[56] = 0xff;
+        buffer
+    }
+
+    fn solid_png(width: u32, height: u32) -> Result<Vec<u8>, image::ImageError> {
+        let img = DynamicImage::ImageRgb8(image::RgbImage::from_pixel(
+            width,
+            height,
+            image::Rgb([10, 20, 30]),
+        ));
+        let mut out = Vec::new();
+        img.write_to(&mut Cursor::new(&mut out), ImageFormat::Png)?;
+        Ok(out)
+    }
+
+    #[test]
+    fn schema_matches_typebox_fixture() -> Result<(), Box<dyn std::error::Error>> {
+        let schema = ReadTool::parameters_schema();
+        assert_eq!(schema, fixture_schema()?);
+        Ok(())
+    }
+
+    #[test]
+    fn detects_bmp_and_png_magic() -> Result<(), Box<dyn std::error::Error>> {
+        assert_eq!(
+            detect_supported_image_mime_type(&tiny_bmp_1x1_red()).as_deref(),
+            Some("image/bmp")
+        );
+        let png = solid_png(2, 2)?;
+        assert_eq!(
+            detect_supported_image_mime_type(&png).as_deref(),
+            Some("image/png")
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn public_image_helper_preserves_small_supported_bytes()
+    -> Result<(), Box<dyn std::error::Error>> {
+        let png = solid_png(3, 2)?;
+        let result = process_image_bytes(&png, "image/png", true);
+        let ProcessImageResult::Ok(processed) = result else {
+            return Err("expected processed image".into());
+        };
+        assert_eq!(processed.mime_type, "image/png");
+        assert_eq!(
+            BASE64.decode(&processed.data).ok().as_deref(),
+            Some(png.as_slice())
+        );
+        assert!(processed.hints.is_empty());
+        assert_eq!(
+            processed.dimensions,
+            Some(ProcessedImageDimensions {
+                original_width: 3,
+                original_height: 2,
+                width: 3,
+                height: 2,
+                was_resized: false,
+            })
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn offset_beyond_end_errors() -> Result<(), Box<dyn std::error::Error>> {
+        let dir = tempdir()?;
+        let path = dir.path().join("lines.txt");
+        tokio::fs::write(&path, "a\nb\nc").await?;
+        let tool = ReadTool::new(dir.path());
+        let result = tool
+            .execute(
+                "1",
+                json_map(json!({"path": "lines.txt", "offset": 10}))?,
+                CancellationToken::new(),
+                ToolUpdates::noop(),
+            )
+            .await;
+        let Err(err) = result else {
+            return Err("expected offset error".into());
+        };
+        assert_eq!(
+            err.message(),
+            "Offset 10 is beyond end of file (3 lines total)"
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn first_huge_line_notice() -> Result<(), Box<dyn std::error::Error>> {
+        let dir = tempdir()?;
+        let path = dir.path().join("huge.txt");
+        let huge = "x".repeat(DEFAULT_MAX_BYTES + 10);
+        tokio::fs::write(&path, &huge).await?;
+        let tool = ReadTool::new(dir.path());
+        let result = tool
+            .execute(
+                "1",
+                json_map(json!({"path": "huge.txt"}))?,
+                CancellationToken::new(),
+                ToolUpdates::noop(),
+            )
+            .await?;
+        let text = text_of(&result);
+        assert!(
+            text.contains("exceeds") && text.contains("sed -n '1p'"),
+            "unexpected: {text}"
+        );
+        assert!(result.details.get("truncation").is_some());
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn continuation_notices_for_limit_and_truncation()
+    -> Result<(), Box<dyn std::error::Error>> {
+        let dir = tempdir()?;
+        let path = dir.path().join("many.txt");
+        let mut content = String::new();
+        for i in 1..=10 {
+            writeln!(content, "line{i}")?;
+        }
+        tokio::fs::write(&path, &content).await?;
+        let tool = ReadTool::new(dir.path());
+        let result = tool
+            .execute(
+                "1",
+                json_map(json!({"path": "many.txt", "offset": 1, "limit": 3}))?,
+                CancellationToken::new(),
+                ToolUpdates::noop(),
+            )
+            .await?;
+        let text = text_of(&result);
+        assert!(
+            text.contains("more lines in file. Use offset=4 to continue."),
+            "{text}"
+        );
+
+        // Force line truncation via many short lines.
+        let path2 = dir.path().join("lots.txt");
+        let mut lots = String::new();
+        for i in 0..(DEFAULT_MAX_LINES + 50) {
+            writeln!(lots, "L{i}")?;
+        }
+        tokio::fs::write(&path2, &lots).await?;
+        let result = tool
+            .execute(
+                "2",
+                json_map(json!({"path": "lots.txt"}))?,
+                CancellationToken::new(),
+                ToolUpdates::noop(),
+            )
+            .await?;
+        let text = text_of(&result);
+        assert!(
+            text.contains("Showing lines 1-") && text.contains("Use offset="),
+            "{text}"
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn missing_file_errors() -> Result<(), Box<dyn std::error::Error>> {
+        let dir = tempdir()?;
+        let tool = ReadTool::new(dir.path());
+        let result = tool
+            .execute(
+                "1",
+                json_map(json!({"path": "nope.txt"}))?,
+                CancellationToken::new(),
+                ToolUpdates::noop(),
+            )
+            .await;
+        let Err(err) = result else {
+            return Err("expected missing-file error".into());
+        };
+        assert!(
+            err.message().contains("Could not read file")
+                || err.message().contains("No such file")
+                || err.message().contains("not found")
+                || err.message().contains("os error"),
+            "{}",
+            err.message()
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn cancellation_wins() -> Result<(), Box<dyn std::error::Error>> {
+        let dir = tempdir()?;
+        let path = dir.path().join("a.txt");
+        tokio::fs::write(&path, "hi").await?;
+        let tool = ReadTool::new(dir.path());
+        let cancel = CancellationToken::new();
+        cancel.cancel();
+        let result = tool
+            .execute(
+                "1",
+                json_map(json!({"path": "a.txt"}))?,
+                cancel,
+                ToolUpdates::noop(),
+            )
+            .await;
+        let Err(err) = result else {
+            return Err("expected cancellation error".into());
+        };
+        assert_eq!(err.message(), "Operation aborted");
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn supported_image_passthrough_and_bmp_conversion()
+    -> Result<(), Box<dyn std::error::Error>> {
+        let dir = tempdir()?;
+        let png_path = dir.path().join("tiny.png");
+        let png = solid_png(4, 4)?;
+        tokio::fs::write(&png_path, &png).await?;
+        let tool = ReadTool::with_options(
+            ReadToolOptions::new(dir.path()).with_model(Some(vision_model())),
+        );
+        let result = tool
+            .execute(
+                "1",
+                json_map(json!({"path": "tiny.png"}))?,
+                CancellationToken::new(),
+                ToolUpdates::noop(),
+            )
+            .await?;
+        assert!(matches!(
+            result.content.get(1),
+            Some(ToolResultContent::Image(_))
+        ));
+        let text = text_of(&result);
+        assert!(text.starts_with("Read image file [image/png]"), "{text}");
+
+        let bmp_path = dir.path().join("tiny.bmp");
+        tokio::fs::write(&bmp_path, tiny_bmp_1x1_red()).await?;
+        let result = tool
+            .execute(
+                "2",
+                json_map(json!({"path": "tiny.bmp"}))?,
+                CancellationToken::new(),
+                ToolUpdates::noop(),
+            )
+            .await?;
+        let text = text_of(&result);
+        assert!(
+            text.contains("[Image converted from image/bmp to image/png.]"),
+            "{text}"
+        );
+        match result.content.get(1) {
+            Some(ToolResultContent::Image(image)) => {
+                assert_eq!(image.mime_type, "image/png");
+                let decoded = BASE64.decode(&image.data)?;
+                assert_eq!(&decoded[..4], &[0x89, b'P', b'N', b'G']);
+            }
+            other => return Err(format!("expected image content, got {other:?}").into()),
+        }
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn resize_dimensions_and_size() -> Result<(), Box<dyn std::error::Error>> {
+        let dir = tempdir()?;
+        let path = dir.path().join("big.png");
+        // Large solid image forces dimension reduction.
+        let png = solid_png(2500, 100)?;
+        tokio::fs::write(&path, &png).await?;
+        let tool = ReadTool::with_options(
+            ReadToolOptions::new(dir.path()).with_model(Some(vision_model())),
+        );
+        let result = tool
+            .execute(
+                "1",
+                json_map(json!({"path": "big.png"}))?,
+                CancellationToken::new(),
+                ToolUpdates::noop(),
+            )
+            .await?;
+        let text = text_of(&result);
+        assert!(
+            text.contains("original 2500x100") && text.contains("displayed at"),
+            "{text}"
+        );
+        match result.content.get(1) {
+            Some(ToolResultContent::Image(image)) => {
+                assert!(image.data.len() < IMAGE_MAX_BASE64_BYTES);
+            }
+            other => return Err(format!("expected image, got {other:?}").into()),
+        }
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn non_vision_note_omits_image() -> Result<(), Box<dyn std::error::Error>> {
+        let dir = tempdir()?;
+        let path = dir.path().join("pic.png");
+        tokio::fs::write(&path, solid_png(8, 8)?).await?;
+        let tool =
+            ReadTool::with_options(ReadToolOptions::new(dir.path()).with_model(Some(text_model())));
+        let result = tool
+            .execute(
+                "1",
+                json_map(json!({"path": "pic.png"}))?,
+                CancellationToken::new(),
+                ToolUpdates::noop(),
+            )
+            .await?;
+        assert_eq!(result.content.len(), 1);
+        let text = text_of(&result);
+        assert!(
+            text.contains(
+                "[Current model does not support images. The image will be omitted from this request.]"
+            ),
+            "{text}"
+        );
+        Ok(())
+    }
+
+    #[test]
+    fn sniffs_only_first_chunk_size_constant() {
+        // Guard the constant used by file sniffing parity.
+        assert_eq!(IMAGE_TYPE_SNIFF_BYTES, 4100);
+    }
+}