Merge pull request #5737 from Hmbown/feat/readmedia-byte-budget-20260830

feat(tui): read_media learns byte-budget delivery with an encoding ladder and an originals store

Author: Hmbown

crates/tui/src/exec_agent.rs

@@ -198,6 +198,7 @@ pub(crate) async fn run_exec_agent(
     let runtime_services = crate::tools::spec::RuntimeToolServices {
         shell_manager: Some(exec_shell_manager.clone()),
         persist_services_enabled,
+        media_originals_dir: crate::media_originals::default_store_dir(),
         ..crate::tools::spec::RuntimeToolServices::default()
     };
 

crates/tui/src/lib.rs

@@ -72,6 +72,7 @@ mod logging;
 mod lsp;
 mod mcp;
 mod mcp_server;
+mod media_originals;
 mod model_catalog;
 mod model_context;
 mod model_inventory;

crates/tui/src/media_originals.rs

@@ -0,0 +1,213 @@
+//! Content-addressed store for pre-compression image originals.
+//!
+//! When `read_media` downsamples or lossily re-encodes an image to fit the
+//! delivery budget, the model only ever sees the degraded copy. Persisting
+//! the pre-compression bytes — named by content hash — lets a later
+//! `read_media` call with a crop region read the full-resolution source back
+//! (the tool's delivery note points at the stored path), even if the
+//! workspace file has moved or changed since the first read.
+//!
+//! Design notes:
+//! - Content-addressed (sha256): repeated reads of the same image reuse one
+//!   file and repeated writes are idempotent.
+//! - Best effort: any filesystem failure returns `None`; media delivery never
+//!   blocks on persistence.
+//! - Size-capped: after each write the store is swept oldest-first (mtime)
+//!   until it fits [`MAX_TOTAL_BYTES`], so long sessions cannot fill the disk.
+//! - Placement: the production engine wires the store dir through
+//!   `RuntimeToolServices::media_originals_dir`
+//!   ([`default_store_dir`]); test and one-off contexts leave it `None`, which
+//!   disables persistence so unit tests never touch the real state dir.
+
+use std::path::{Path, PathBuf};
+
+use sha2::{Digest as _, Sha256};
+
+/// Total size ceiling for the store (1 GiB). Each admitted source is already
+/// capped at `read_media`'s 20 MiB source limit, so the store holds dozens of
+/// full-resolution originals before the sweep engages.
+pub const MAX_TOTAL_BYTES: u64 = 1024 * 1024 * 1024;
+
+/// Store subdirectory under the CodeWhale home directory.
+pub const MEDIA_ORIGINALS_SUBDIR: &str = "media-originals";
+
+/// The production store location: `<codewhale home>/media-originals`.
+///
+/// The directory is created lazily on first persist, not here, so resolving
+/// the path never has a filesystem side effect.
+#[must_use]
+pub fn default_store_dir() -> Option<PathBuf> {
+    codewhale_config::codewhale_home()
+        .ok()
+        .map(|home| home.join(MEDIA_ORIGINALS_SUBDIR))
+}
+
+fn extension_for_mime(mime_type: &str) -> &'static str {
+    match mime_type.trim().to_ascii_lowercase().as_str() {
+        "image/png" => "png",
+        "image/jpeg" | "image/jpg" => "jpg",
+        "image/gif" => "gif",
+        "image/webp" => "webp",
+        "image/bmp" => "bmp",
+        "image/tiff" => "tif",
+        _ => "img",
+    }
+}
+
+/// Persist `bytes` under `dir`, returning the content-addressed path.
+///
+/// Best effort: returns `None` on any filesystem failure. A same-named entry
+/// with the same length is reused as-is (content addressing makes a length
+/// match a content match for practical purposes).
+pub fn persist_original_image(bytes: &[u8], mime_type: &str, dir: &Path) -> Option<PathBuf> {
+    if bytes.is_empty() {
+        return None;
+    }
+    let digest = Sha256::digest(bytes);
+    let mut hash = String::with_capacity(32);
+    for byte in digest.iter().take(16) {
+        use std::fmt::Write as _;
+        let _ = write!(hash, "{byte:02x}");
+    }
+    let path = dir.join(format!("{hash}.{}", extension_for_mime(mime_type)));
+    std::fs::create_dir_all(dir).ok()?;
+    let write_needed = match std::fs::metadata(&path) {
+        Ok(meta) => meta.len() != bytes.len() as u64,
+        Err(_) => true,
+    };
+    if write_needed {
+        std::fs::write(&path, bytes).ok()?;
+    }
+    sweep_store(dir, MAX_TOTAL_BYTES);
+    std::fs::metadata(&path).ok()?;
+    Some(path)
+}
+
+/// Resolve `raw` as a read-back path inside the store.
+///
+/// Returns the canonical path only when the file exists and lives under
+/// `store_dir`. `read_media` uses this as a fallback after the workspace
+/// resolver rejects a path: the store only contains image bytes that already
+/// passed the tool's read guards, so read-back widens nothing.
+#[must_use]
+pub fn resolve_stored_original(raw: &str, workspace: &Path, store_dir: &Path) -> Option<PathBuf> {
+    let candidate = if Path::new(raw).is_absolute() {
+        PathBuf::from(raw)
+    } else {
+        workspace.join(raw)
+    };
+    let candidate = candidate.canonicalize().ok()?;
+    let store_dir = store_dir.canonicalize().ok()?;
+    candidate.starts_with(store_dir).then_some(candidate)
+}
+
+/// Oldest-first (mtime) sweep until the store fits `max_total_bytes`.
+/// Best effort: individual stat/unlink failures are skipped.
+fn sweep_store(dir: &Path, max_total_bytes: u64) {
+    let Ok(entries) = std::fs::read_dir(dir) else {
+        return;
+    };
+    let mut files: Vec<(PathBuf, u64, std::time::SystemTime)> = Vec::new();
+    for entry in entries.flatten() {
+        let Ok(meta) = entry.metadata() else {
+            continue;
+        };
+        if !meta.is_file() {
+            continue;
+        }
+        files.push((
+            entry.path(),
+            meta.len(),
+            meta.modified().unwrap_or(std::time::SystemTime::UNIX_EPOCH),
+        ));
+    }
+    let mut total: u64 = files.iter().map(|(_, len, _)| *len).sum();
+    if total <= max_total_bytes {
+        return;
+    }
+    files.sort_by_key(|(_, _, mtime)| *mtime);
+    for (path, len, _) in files {
+        if total <= max_total_bytes {
+            break;
+        }
+        if std::fs::remove_file(&path).is_ok() {
+            total = total.saturating_sub(len);
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn persist_is_content_addressed_and_idempotent() {
+        let dir = tempfile::tempdir().expect("tempdir");
+        let store = dir.path().join("media-originals");
+        let bytes = b"\x89PNG fake-but-deterministic payload";
+
+        let first = persist_original_image(bytes, "image/png", &store).expect("persist");
+        assert!(first.exists());
+        assert_eq!(first.parent(), Some(store.as_path()));
+        assert_eq!(
+            first.extension().and_then(|e| e.to_str()),
+            Some("png"),
+            "mime drives the extension"
+        );
+        let stem = first.file_stem().unwrap().to_str().unwrap().to_string();
+        assert_eq!(stem.len(), 32, "sha256 prefix names the file: {stem}");
+
+        let second = persist_original_image(bytes, "image/png", &store).expect("re-persist");
+        assert_eq!(first, second, "same bytes reuse one file");
+        assert_eq!(std::fs::read_dir(&store).unwrap().count(), 1);
+    }
+
+    #[test]
+    fn sweep_removes_oldest_until_under_cap() {
+        let dir = tempfile::tempdir().expect("tempdir");
+        let store = dir.path().to_path_buf();
+        let mut paths = Vec::new();
+        for i in 0..4u8 {
+            let path = store.join(format!("img{i}.png"));
+            std::fs::write(&path, vec![i; 100]).expect("write");
+            paths.push(path);
+        }
+        // 400 bytes total; cap at 250 -> at least the two oldest go.
+        sweep_store(&store, 250);
+        let remaining = std::fs::read_dir(&store).unwrap().count();
+        assert!(
+            remaining <= 2,
+            "sweep must evict oldest-first until under cap, {remaining} left"
+        );
+        let total: u64 = std::fs::read_dir(&store)
+            .unwrap()
+            .flatten()
+            .filter_map(|e| e.metadata().ok())
+            .map(|m| m.len())
+            .sum();
+        assert!(total <= 250);
+    }
+
+    #[test]
+    fn resolve_stored_original_admits_store_paths_only() {
+        let dir = tempfile::tempdir().expect("tempdir");
+        let store = dir.path().join("media-originals");
+        std::fs::create_dir_all(&store).unwrap();
+        let inside = store.join("abc123.png");
+        std::fs::write(&inside, b"png").unwrap();
+        let outside = dir.path().join("other.png");
+        std::fs::write(&outside, b"png").unwrap();
+
+        let resolved =
+            resolve_stored_original(inside.to_str().unwrap(), dir.path(), &store).expect("inside");
+        assert!(resolved.ends_with("abc123.png"));
+        assert!(
+            resolve_stored_original(outside.to_str().unwrap(), dir.path(), &store).is_none(),
+            "paths outside the store must not resolve through the fallback"
+        );
+        assert!(
+            resolve_stored_original("missing.png", dir.path(), &store).is_none(),
+            "non-existent files do not resolve"
+        );
+    }
+}

crates/tui/src/runtime_threads.rs

@@ -7682,6 +7682,7 @@ impl RuntimeThreadManager {
                     hook_executor: None,
                     handle_store: crate::tools::handle::new_shared_handle_store(),
                     rlm_sessions: crate::rlm::session::new_shared_rlm_session_store(),
+                    media_originals_dir: crate::media_originals::default_store_dir(),
                 },
                 subagent_model_overrides: if isolated_chat {
                     HashMap::new()