dsh-ops 0.0.0-stage → 0.2.2

package/vendor/fastctx/src/read_tool/image_file.rs

@@ -0,0 +1,88 @@
+//! Image magic-byte detection and MCP image-content construction for read.
+
+use crate::model::{ToolContent, ToolResponse};
+use crate::paths::io_error_message;
+use base64::Engine;
+use std::fs::File;
+use std::io::Read;
+use std::path::Path;
+
+const MAX_IMAGE_BYTES: usize = 8 * 1024 * 1024;
+
+pub(super) fn detect_image_mime(path: &Path, bytes: &[u8]) -> Option<&'static str> {
+    if bytes.starts_with(&[0x89, b'P', b'N', b'G', 0x0D, 0x0A, 0x1A, 0x0A]) {
+        return Some("image/png");
+    }
+    if bytes.starts_with(&[0xFF, 0xD8, 0xFF]) {
+        return Some("image/jpeg");
+    }
+    if bytes.starts_with(b"GIF87a") || bytes.starts_with(b"GIF89a") {
+        return Some("image/gif");
+    }
+    if bytes.len() >= 12 && bytes.starts_with(b"RIFF") && &bytes[8..12] == b"WEBP" {
+        return Some("image/webp");
+    }
+    if bytes.starts_with(b"BM") {
+        return Some("image/bmp");
+    }
+
+    match path
+        .extension()
+        .and_then(|extension| extension.to_str())
+        .map(str::to_ascii_lowercase)
+        .as_deref()
+    {
+        Some("png") => Some("image/png"),
+        Some("jpg" | "jpeg") => Some("image/jpeg"),
+        Some("gif") => Some("image/gif"),
+        Some("webp") => Some("image/webp"),
+        Some("bmp") => Some("image/bmp"),
+        _ => None,
+    }
+}
+
+pub(super) fn read_image(path: &Path) -> ToolResponse {
+    let mut file = match File::open(path) {
+        Ok(file) => file,
+        Err(error) => return ToolResponse::error(io_error_message(path, &error)),
+    };
+    let reported_size = match file.metadata() {
+        Ok(metadata) => metadata.len(),
+        Err(error) => return ToolResponse::error(io_error_message(path, &error)),
+    };
+    if reported_size > MAX_IMAGE_BYTES as u64 {
+        return oversized_image(reported_size);
+    }
+    let mut bytes = Vec::with_capacity(reported_size as usize);
+    if let Err(error) = file
+        .by_ref()
+        .take(MAX_IMAGE_BYTES as u64 + 1)
+        .read_to_end(&mut bytes)
+    {
+        return ToolResponse::error(io_error_message(path, &error));
+    }
+    if bytes.len() > MAX_IMAGE_BYTES {
+        return oversized_image(bytes.len() as u64);
+    }
+    let Some(mime_type) = detect_image_mime(path, &bytes) else {
+        return ToolResponse::error(format!(
+            "Cannot read image file: {}. Retry after confirming it is a PNG, JPG, GIF, WebP, or BMP file.",
+            crate::paths::display_path(path)
+        ));
+    };
+    ToolResponse {
+        content: vec![ToolContent::Image {
+            data: base64::engine::general_purpose::STANDARD.encode(bytes),
+            mime_type: mime_type.to_string(),
+            detail: None,
+        }],
+        is_error: false,
+    }
+}
+
+fn oversized_image(size: u64) -> ToolResponse {
+    let mib = ((size as f64 / (1024.0 * 1024.0)) * 10.0).ceil() / 10.0;
+    ToolResponse::error(format!(
+        "Image file too large: {mib:.1} MiB (limit: 8 MiB). Resize or convert it externally."
+    ))
+}

package/vendor/fastctx/src/read_tool/mod.rs

@@ -0,0 +1,245 @@
+//! Text, image, PDF, and raw-byte dispatch for the file-inspection tool.
+
+mod batch;
+mod hex_file;
+mod image_file;
+#[cfg(feature = "pdf")]
+mod pdf;
+#[cfg(not(feature = "pdf"))]
+#[path = "pdf_disabled.rs"]
+mod pdf;
+#[cfg(feature = "pdf")]
+mod pdf_engine;
+mod text_file;
+
+use crate::binary::detect_binary_type;
+use crate::budget::{READ_TOKEN_BUDGET_ENV, tool_token_budget};
+use crate::model::ToolResponse;
+use crate::paths::{
+    canonical_existing, display_path, io_error_message, missing_read_file_message,
+    parse_local_path_input,
+};
+use schemars::JsonSchema;
+use serde::Deserialize;
+use std::fs;
+use std::io::Read;
+
+/// Line window for a text read that omits `limit`: unbounded, so the token budget is the only
+/// ceiling on how much one call returns.
+///
+/// A second fixed window would silently cap every default read far below the configured budget,
+/// forcing continuation calls the budget was raised to avoid. Do not reintroduce a numeric default
+/// here; page explicitly with `limit` instead. (2026-07-25)
+const UNBOUNDED_LINE_LIMIT: usize = usize::MAX;
+/// Line window for a hex read that omits `limit`.
+///
+/// Hex keeps a fixed default where text does not: a dump exists to inspect a byte range rather
+/// than to deliver a whole binary, and its candidate window is estimated from the budget with a
+/// deliberately loose factor, so an unbounded default would buffer hundreds of thousands of
+/// rendered lines before the budget trimmed them back. (2026-07-25)
+const DEFAULT_HEX_LINE_LIMIT: usize = 2_000;
+const MAX_LINE_CHARS: usize = 2_000;
+const TOTAL_COUNT_SIZE_LIMIT: u64 = 64 * 1024 * 1024;
+
+/// Automatic channel dispatch or raw-byte viewing.
+#[derive(Clone, Copy, Debug, Default, Deserialize, JsonSchema, Eq, PartialEq)]
+#[serde(rename_all = "lowercase")]
+enum ViewMode {
+    /// Select the text, image, or PDF channel from the file type.
+    #[default]
+    Auto,
+    /// Return a paged hexadecimal dump of the raw bytes.
+    Hex,
+}
+
+/// Parameters for the file-inspection tool; offset is a one-based line number.
+#[derive(Clone, Debug, Deserialize, JsonSchema)]
+#[serde(deny_unknown_fields)]
+pub struct ReadRequest {
+    /// File to inspect; mutually exclusive with files.
+    #[schemars(description = crate::model_guidance::local_path_description(
+        "File to inspect; both / and \\\\ are accepted. Mutually exclusive with files."
+    ))]
+    pub file_path: Option<String>,
+    /// Batch form: an array of {"path", "offset"?, "limit"?, "encoding"?} objects for
+    /// 1-32 text ranges in one call. Repeat a path for distinct ranges, each with its own
+    /// offset/limit, and freely mix ranges from multiple files. Each entry behaves like its
+    /// own single-file text request; results stay in request order. Mutually exclusive with
+    /// file_path and with the top-level offset/encoding/pages/pdf_mode/view parameters.
+    #[schemars(length(min = 1, max = 32))]
+    pub files: Option<Vec<BatchReadEntry>>,
+    /// The 1-based line number to start reading from. Use for paging through large files.
+    #[schemars(range(min = 1))]
+    pub offset: Option<usize>,
+    /// The number of lines to return. With files, this is the default for entries that omit
+    /// limit; an entry's own limit takes precedence. Otherwise, omit it to let the output budget
+    /// decide.
+    #[schemars(range(min = 1))]
+    pub limit: Option<usize>,
+    /// Page range for PDF files, e.g. "1-5", "3", "10-20". Max 20 pages per call. Required in text mode for PDFs with more than 10 pages.
+    pub pages: Option<String>,
+    /// PDF only: "text" (default) returns the selected pages' text layer; "image" returns each selected page rendered as a PNG image.
+    #[schemars(with = "Option<pdf::PdfMode>")]
+    pub pdf_mode: Option<String>,
+    /// Text files only. Known source encoding as a WHATWG label, e.g. "gbk", "shift_jis", "big5", "euc-kr", "windows-1252", "utf-16le", plus "utf-32le"/"utf-32be". Selects how source bytes are decoded; output is always UTF-8. Omit for auto-detection; set it when you know the source encoding or the tool reports an ambiguous or undecodable encoding.
+    pub encoding: Option<String>,
+    /// "auto" (default) picks the channel by file type; "hex" returns a paged hex dump of the raw bytes of any file — the way to inspect binary files.
+    #[schemars(with = "Option<ViewMode>")]
+    pub view: Option<String>,
+}
+
+/// One text range in a batch inspection request.
+#[derive(Clone, Debug, Deserialize, JsonSchema)]
+#[serde(deny_unknown_fields)]
+pub struct BatchReadEntry {
+    /// Text file to inspect.
+    #[schemars(description = crate::model_guidance::local_path_description(
+        "Text file to inspect; both / and \\\\ are accepted."
+    ))]
+    pub path: String,
+    /// The 1-based line number to start reading from.
+    #[schemars(range(min = 1))]
+    pub offset: Option<usize>,
+    /// Maximum lines to return from this range in this call. Overrides the top-level limit when
+    /// both are present; omit it to inherit that default or let the shared budget decide.
+    #[schemars(range(min = 1))]
+    pub limit: Option<usize>,
+    /// Known source encoding for this file, using the same labels as the top-level encoding parameter.
+    pub encoding: Option<String>,
+}
+
+/// Reads text, images, PDFs, or raw bytes and surfaces every expected failure explicitly.
+pub fn read_file(request: ReadRequest) -> ToolResponse {
+    match (request.file_path.as_deref(), request.files.as_ref()) {
+        (Some(_), Some(_)) | (None, None) => {
+            return ToolResponse::error("Provide exactly one of file_path or files.");
+        }
+        (None, Some(_)) => return batch::read_text_files(request),
+        (Some(_), None) => {}
+    }
+    let file_path = request
+        .file_path
+        .as_deref()
+        .expect("single-file shape was validated");
+    let parsed = match parse_local_path_input(file_path) {
+        Ok(path) => path,
+        Err(message) => return ToolResponse::error(message),
+    };
+    let input_display = display_path(&parsed);
+    if !parsed.is_absolute() {
+        return ToolResponse::error(missing_read_file_message(&input_display));
+    }
+    let metadata = match fs::metadata(&parsed) {
+        Ok(metadata) => metadata,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+            return ToolResponse::error(missing_read_file_message(&input_display));
+        }
+        Err(error) => return ToolResponse::error(io_error_message(&parsed, &error)),
+    };
+    let path = canonical_existing(&parsed).unwrap_or(parsed);
+    let path_display = display_path(&path);
+    if metadata.is_dir() {
+        return ToolResponse::error(format!(
+            "{path_display} is a directory, not a file. Use the glob tool to list its contents."
+        ));
+    }
+    if !metadata.is_file() {
+        return ToolResponse::error(format!(
+            "Cannot read non-regular file: {path_display}. Only regular files are supported."
+        ));
+    }
+    let mut prefix = Vec::new();
+    let prefix_result =
+        fs::File::open(&path).and_then(|file| file.take(8 * 1024).read_to_end(&mut prefix));
+    if let Err(error) = prefix_result {
+        return ToolResponse::error(io_error_message(&path, &error));
+    }
+
+    let view = match parse_view(request.view.as_deref()) {
+        Ok(view) => view,
+        Err(message) => return ToolResponse::error(message),
+    };
+    if view == ViewMode::Hex {
+        for (parameter, present) in [
+            ("pdf_mode", request.pdf_mode.is_some()),
+            ("pages", request.pages.is_some()),
+            ("encoding", request.encoding.is_some()),
+        ] {
+            if present {
+                return ToolResponse::error(format!(
+                    "The {parameter} parameter cannot be combined with view=\"hex\"."
+                ));
+            }
+        }
+        let budget = match tool_token_budget(READ_TOKEN_BUDGET_ENV) {
+            Ok(budget) => budget,
+            Err(message) => return ToolResponse::error(message),
+        };
+        return hex_file::read_hex_file(&path, request.offset, request.limit, budget);
+    }
+
+    if pdf::is_pdf(&path, &prefix) {
+        if request.encoding.is_some() {
+            return ToolResponse::error("The encoding parameter only applies to text files.");
+        }
+        let mode = match pdf::parse_pdf_mode(request.pdf_mode.as_deref()) {
+            Ok(mode) => mode,
+            Err(message) => return ToolResponse::error(message),
+        };
+        let budget = if mode == pdf::PdfMode::Text {
+            match tool_token_budget(READ_TOKEN_BUDGET_ENV) {
+                Ok(budget) => Some(budget),
+                Err(message) => return ToolResponse::error(message),
+            }
+        } else {
+            None
+        };
+        return pdf::read_pdf(&path, request.pages.as_deref(), mode, budget);
+    }
+    if request.pages.is_some() {
+        return ToolResponse::error("The pages parameter only applies to PDF files.");
+    }
+    if request.pdf_mode.is_some() {
+        return ToolResponse::error("The pdf_mode parameter only applies to PDF files.");
+    }
+    if image_file::detect_image_mime(&path, &prefix).is_some() {
+        if request.encoding.is_some() {
+            return ToolResponse::error("The encoding parameter only applies to text files.");
+        }
+        return image_file::read_image(&path);
+    }
+    let budget = match tool_token_budget(READ_TOKEN_BUDGET_ENV) {
+        Ok(budget) => budget,
+        Err(message) => return ToolResponse::error(message),
+    };
+    text_file::read_text_file(
+        &path,
+        &path_display,
+        request.offset,
+        request.limit,
+        request.encoding.as_deref(),
+        detect_binary_type(&prefix),
+        budget,
+    )
+}
+
+fn parse_view(value: Option<&str>) -> Result<ViewMode, String> {
+    match value {
+        None | Some("auto") => Ok(ViewMode::Auto),
+        Some("hex") => Ok(ViewMode::Hex),
+        Some(value) => Err(format!(
+            "Invalid view value \"{value}\". Use \"auto\" or \"hex\"."
+        )),
+    }
+}
+
+fn binary_error(path_display: &str, binary_type: Option<&str>) -> ToolResponse {
+    ToolResponse::error(binary_error_message(path_display, binary_type))
+}
+
+fn binary_error_message(path_display: &str, binary_type: Option<&str>) -> String {
+    let kind = binary_type.map_or_else(String::new, |kind| format!(" (looks like {kind})"));
+    format!(
+        "Cannot read binary file as text: {path_display}{kind}. Use view=\"hex\" to inspect its raw bytes."
+    )
+}