fix(vision): guard image pixel dimensions (8000px cap), not just bytes

agent/conversation_compression.py

@@ -646,6 +646,11 @@ def try_shrink_image_parts_in_messages(api_messages: list) -> bool:
     # much larger; shrinking to 4 MB here loses quality but only fires
     # after a confirmed provider rejection, so the alternative is failure.
     target_bytes = 4 * 1024 * 1024
+    # Anthropic enforces an 8000px per-side dimension cap independently of
+    # the 5 MB byte cap.  A tall screenshot can be well under 5 MB yet far
+    # over 8000px (e.g. 1200×12000 at 0.06 MB).  We check pixel dimensions
+    # even when the byte budget is fine.
+    max_dimension = 8000
     changed_count = 0
     # Track parts that are over the target but could NOT be shrunk under it.
     # If any survive, retrying is pointless — the same oversized payload will
@@ -658,9 +663,30 @@ def _shrink_data_url(url: str) -> Optional[str]:
         """Return a smaller data URL, or None if shrink can't help."""
         if not isinstance(url, str) or not url.startswith("data:"):
             return None
-        if len(url) <= target_bytes:
-            # This specific image wasn't the oversized one.
-            return None
+
+        # Check both byte size AND pixel dimensions.
+        needs_shrink = len(url) > target_bytes  # over byte budget
+        if not needs_shrink:
+            # Even if bytes are fine, check pixel dimensions against
+            # Anthropic's 8000px cap.  A tall image can be tiny in bytes
+            # yet huge in pixels.
+            try:
+                import base64 as _b64_dim
+                header_d, _, data_d = url.partition(",")
+                if not data_d:
+                    return None
+                raw_d = _b64_dim.b64decode(data_d)
+                from PIL import Image as _PILImage
+                import io as _io_dim
+                with _PILImage.open(_io_dim.BytesIO(raw_d)) as _img:
+                    if max(_img.size) <= max_dimension:
+                        return None  # both bytes and pixels are fine
+                needs_shrink = True  # pixels exceed limit, force shrink
+            except Exception:
+                # If we can't check dimensions (Pillow unavailable, corrupt
+                # image, etc.), fall back to byte-only check.
+                return None
+
         try:
             header, _, data = url.partition(",")
             mime = "image/jpeg"
@@ -684,6 +710,7 @@ def _shrink_data_url(url: str) -> Optional[str]:
                     Path(tmp.name),
                     mime_type=mime,
                     max_base64_bytes=target_bytes,
+                    max_dimension=max_dimension,
                 )
             finally:
                 try:

agent/error_classifier.py

@@ -171,6 +171,9 @@ def is_auth(self) -> bool:
     "image too large",      # generic
     "image_too_large",      # error_code variant
     "image size exceeds",   # variant
+    "image dimensions exceed",  # Anthropic: "image dimensions exceed max allowed size: 8000 pixels"
+    "dimensions exceed max allowed size",  # Anthropic dimension-cap (wording variant)
+    "max allowed size: 8000",  # Anthropic dimension-cap (explicit pixel ceiling)
     # "request_too_large" on a request known to contain an image → image is
     # the likely culprit; we still try the shrink path before giving up.
 ]

pyproject.toml

@@ -127,6 +127,14 @@ pty = [
   # without pulling in extra packages.
 ]
 honcho = ["honcho-ai==2.0.1"]
+# Image resize recovery for the vision tools.  Pillow is a soft dependency:
+# vision_tools / conversation_compression degrade gracefully without it (they
+# log and skip the resize), but without it the byte AND pixel-dimension shrink
+# paths silently no-op, so an oversized image (>5 MB or >8000px) bakes into
+# immutable history and bricks the session on Anthropic's non-retryable 400.
+# Declared here so packagers (Nix, Homebrew) ship it with [all] and so
+# `pip install hermes-agent[vision]` / the lazy-install path can resolve it.
+vision = ["Pillow==12.2.0"]
 # CVE-2026-48710 (BadHost): Starlette is pulled transitively by mcp's
 # sse-starlette / HTTP-SSE stack (and by fastapi in the `web` extra). Before
 # 1.0.1, a malformed Host header makes `request.url.path` desync from the path

scripts/release.py

@@ -46,6 +46,7 @@
 # Auto-extracted from noreply emails + manual overrides
 AUTHOR_MAP = {
     "zhaolei.vc@bytedance.com": "zhaoleibd",
+    "kyssta-exe@users.noreply.github.com": "kyssta-exe",
     "copii.list@gmail.com": "stremtec",
     "solaiagent@gmail.com": "solaitken",
     "prostoandrei9@gmail.com": "vladkvlchk",

tests/run_agent/test_image_shrink_recovery.py

@@ -143,7 +143,7 @@ def test_oversized_image_url_dict_shape_rewritten(self, monkeypatch):
         oversized_url = _big_png_data_url(5000)  # ~5 MB raw → ~6.7 MB b64
         shrunk = "data:image/jpeg;base64," + "A" * 1000  # small
 
-        def _fake_resize(path, mime_type=None, max_base64_bytes=None):
+        def _fake_resize(path, mime_type=None, max_base64_bytes=None, max_dimension=None):
             return shrunk
 
         monkeypatch.setattr(

tests/tools/test_vision_tools.py

@@ -15,6 +15,8 @@
     _determine_mime_type,
     _image_to_base64_data_url,
     _resize_image_for_vision,
+    _image_exceeds_dimension,
+    _EMBED_MAX_DIMENSION,
     _is_image_size_error,
     _MAX_BASE64_BYTES,
     _RESIZE_TARGET_BYTES,
@@ -889,6 +891,72 @@ def test_no_pillow_returns_original(self, tmp_path):
                 assert len(result) > 100
 
 
+# ---------------------------------------------------------------------------
+# _image_exceeds_dimension — proactive embed-time pixel-cap detector
+# ---------------------------------------------------------------------------
+
+
+class TestImageExceedsDimension:
+    """The proactive embed path checks pixel dimensions, not just bytes.
+
+    A tall full-page screenshot can be well under the byte budget yet far
+    over Anthropic's 8000px per-side cap (e.g. 1200x12000 at 0.06 MB). The
+    byte-only embed guard let it slip into immutable history un-resized,
+    bricking the session on a non-retryable 400. This helper flags it so the
+    embed-time resize fires on dimensions too.
+    """
+
+    def test_tall_small_byte_image_flagged(self, tmp_path):
+        try:
+            from PIL import Image
+        except ImportError:
+            pytest.skip("Pillow not installed")
+        # 1200x12000 solid color: trips the pixel cap, tiny in bytes.
+        img = Image.new("RGB", (1200, 12000), (40, 40, 40))
+        path = tmp_path / "tall.png"
+        img.save(path, "PNG")
+        assert _image_exceeds_dimension(path, _EMBED_MAX_DIMENSION) is True
+
+    def test_small_image_not_flagged(self, tmp_path):
+        try:
+            from PIL import Image
+        except ImportError:
+            pytest.skip("Pillow not installed")
+        img = Image.new("RGB", (800, 600), (10, 200, 10))
+        path = tmp_path / "small.png"
+        img.save(path, "PNG")
+        assert _image_exceeds_dimension(path, _EMBED_MAX_DIMENSION) is False
+
+    def test_exactly_at_cap_not_flagged(self, tmp_path):
+        try:
+            from PIL import Image
+        except ImportError:
+            pytest.skip("Pillow not installed")
+        img = Image.new("RGB", (_EMBED_MAX_DIMENSION, 100), (1, 2, 3))
+        path = tmp_path / "edge.png"
+        img.save(path, "PNG")
+        # max == cap is fine; only strictly greater forces a resize.
+        assert _image_exceeds_dimension(path, _EMBED_MAX_DIMENSION) is False
+
+    def test_missing_pillow_returns_false(self, tmp_path):
+        # Without Pillow we can't inspect dimensions — return False so the
+        # byte-based checks still apply and a missing soft dep never breaks
+        # the embed path.
+        path = tmp_path / "x.png"
+        path.write_bytes(b"\x89PNG\r\n\x1a\n" + b"\x00" * 100)
+        with patch.dict("sys.modules", {"PIL": None, "PIL.Image": None}):
+            assert _image_exceeds_dimension(path, _EMBED_MAX_DIMENSION) is False
+
+    def test_corrupt_file_returns_false(self, tmp_path):
+        try:
+            import PIL  # noqa: F401
+        except ImportError:
+            pytest.skip("Pillow not installed")
+        path = tmp_path / "corrupt.png"
+        path.write_bytes(b"not an image at all")
+        assert _image_exceeds_dimension(path, _EMBED_MAX_DIMENSION) is False
+
+
 # ---------------------------------------------------------------------------
 # _is_image_size_error — detect size-related API errors
 # ---------------------------------------------------------------------------

tools/lazy_deps.py

@@ -175,6 +175,12 @@
         "uvicorn[standard]==0.41.0",
         "starlette==1.0.1",  # CVE-2026-48710 (BadHost) — keep lazy-install in sync with pyproject [web]
     ),
+    # Vision image-resize recovery (Pillow). Soft dependency: vision_tools and
+    # conversation_compression degrade gracefully without it, but the byte AND
+    # pixel-dimension shrink paths no-op when it's absent, so an oversized
+    # image can brick a session on Anthropic's non-retryable 400. Keep in sync
+    # with pyproject [vision].
+    "tool.vision": ("Pillow==12.2.0",),
 }
 
 

tools/vision_tools.py

@@ -326,6 +326,15 @@ def _image_to_base64_data_url(image_path: Path, mime_type: Optional[str] = None)
 # whether we resize proactively or reactively.
 _EMBED_TARGET_BYTES = 4 * 1024 * 1024
 
+# Proactive embed dimension cap (px, longest side).  Anthropic enforces an
+# 8000px per-side ceiling INDEPENDENTLY of the 5 MB byte cap — a tall full-page
+# screenshot can be well under 5 MB yet far over 8000px (e.g. 1200×12000 at
+# 0.06 MB), so the byte-only embed check above lets it slip into immutable
+# history un-resized and the session bricks on a non-retryable 400.  We cap at
+# 7900 (headroom under 8000) so the proactive resize shrinks tall small-byte
+# images before they are embedded.
+_EMBED_MAX_DIMENSION = 7900
+
 # Target size when auto-resizing on API failure (5 MB).  After a provider
 # rejects an image, we downscale to this target and retry once.
 _RESIZE_TARGET_BYTES = 5 * 1024 * 1024
@@ -341,21 +350,59 @@ def _is_image_size_error(error: Exception) -> bool:
     ))
 
 
+def _image_exceeds_dimension(image_path: Path, max_dimension: int) -> bool:
+    """True if the image's longest side exceeds ``max_dimension`` px.
+
+    Anthropic enforces an 8000px per-side cap independently of the 5 MB byte
+    cap, so a tall small-byte screenshot can pass every byte check yet trip a
+    non-retryable 400.  Returns False (don't force a resize) when Pillow is
+    unavailable or the file can't be read as an image — the byte-based checks
+    still apply, and we never want a missing soft dependency to break the
+    embed path.
+    """
+    try:
+        from PIL import Image as _PILImage
+        with _PILImage.open(image_path) as _img:
+            return max(_img.size) > max_dimension
+    except Exception:
+        return False
+
+
 def _resize_image_for_vision(image_path: Path, mime_type: Optional[str] = None,
-                              max_base64_bytes: int = _RESIZE_TARGET_BYTES) -> str:
+                              max_base64_bytes: int = _RESIZE_TARGET_BYTES,
+                              max_dimension: Optional[int] = None) -> str:
     """Convert an image to a base64 data URL, auto-resizing if too large.
 
     Tries Pillow first to progressively downscale oversized images.  If Pillow
     is not installed or resizing still exceeds the limit, falls back to the raw
     bytes and lets the caller handle the size check.
 
+    Args:
+        max_dimension: If set, images whose longest side exceeds this pixel
+            count are forcibly downscaled even if they're under the byte
+            budget.  Anthropic enforces an 8000 px per-side cap independently
+            of the 5 MB byte cap.
+
     Returns the base64 data URL string.
     """
     # Quick file-size estimate: base64 expands by ~4/3, plus data URL header.
     # Skip the expensive full-read + encode if Pillow can resize directly.
     file_size = image_path.stat().st_size
     estimated_b64 = (file_size * 4) // 3 + 100  # ~header overhead
-    if estimated_b64 <= max_base64_bytes:
+    needs_resize_for_bytes = estimated_b64 > max_base64_bytes
+
+    # Check pixel dimensions even if bytes are fine.
+    needs_resize_for_dims = False
+    if max_dimension is not None:
+        try:
+            from PIL import Image as _PILQuick
+            with _PILQuick.open(image_path) as _quick_img:
+                if max(_quick_img.size) > max_dimension:
+                    needs_resize_for_dims = True
+        except Exception:
+            pass  # can't check; Pillow path below will handle or skip
+
+    if not needs_resize_for_bytes and not needs_resize_for_dims:
         # Small enough — just encode directly.
         data_url = _image_to_base64_data_url(image_path, mime_type=mime_type)
         if len(data_url) <= max_base64_bytes:
@@ -368,14 +415,24 @@ def _resize_image_for_vision(image_path: Path, mime_type: Optional[str] = None,
         from PIL import Image
         import io as _io
     except ImportError:
-        logger.info("Pillow not installed — cannot auto-resize oversized image")
-        if data_url is None:
-            data_url = _image_to_base64_data_url(image_path, mime_type=mime_type)
-        return data_url  # caller will raise the size error
+        # Pillow is a lazy-installable soft dependency. Try a best-effort
+        # install (respects security.allow_lazy_installs; no-op if disabled or
+        # offline), then re-import. If it still isn't importable, fall back to
+        # the raw bytes and let the caller raise the size error.
+        try:
+            from tools.lazy_deps import ensure as _ensure_dep
+            _ensure_dep("tool.vision")
+            from PIL import Image
+            import io as _io
+        except Exception:
+            logger.info("Pillow not installed — cannot auto-resize oversized image")
+            if data_url is None:
+                data_url = _image_to_base64_data_url(image_path, mime_type=mime_type)
+            return data_url  # caller will raise the size error
 
-    logger.info("Image file is %.1f MB (estimated base64 %.1f MB, limit %.1f MB), auto-resizing...",
+    logger.info("Image file is %.1f MB (estimated base64 %.1f MB, limit %.1f MB, max_dimension=%s), auto-resizing...",
                 file_size / (1024 * 1024), estimated_b64 / (1024 * 1024),
-                max_base64_bytes / (1024 * 1024))
+                max_base64_bytes / (1024 * 1024), max_dimension)
 
     mime = mime_type or _determine_mime_type(image_path)
     # Choose output format: JPEG for photos (smaller), PNG for transparency
@@ -393,13 +450,20 @@ def _resize_image_for_vision(image_path: Path, mime_type: Optional[str] = None,
     if pil_format == "JPEG" and img.mode in {"RGBA", "P"}:
         img = img.convert("RGB")
 
-    # Strategy: halve dimensions until base64 fits, up to 4 rounds.
+    # Strategy: halve dimensions until both base64 fits AND pixel dimensions
+    # are within limits, up to 4 rounds.
     # For JPEG, also try reducing quality at each size step.
     # For PNG, quality is irrelevant — only dimension reduction helps.
     quality_steps = (85, 70, 50) if pil_format == "JPEG" else (None,)
     prev_dims = (img.width, img.height)
     candidate = None  # will be set on first loop iteration
 
+    def _dims_ok(w: int, h: int) -> bool:
+        """True if both pixel dimensions are within the limit."""
+        if max_dimension is None:
+            return True
+        return max(w, h) <= max_dimension
+
     for attempt in range(5):
         if attempt > 0:
             # Proportional scaling: halve the longer side and scale the
@@ -430,7 +494,7 @@ def _resize_image_for_vision(image_path: Path, mime_type: Optional[str] = None,
             img.save(buf, **save_kwargs)
             encoded = base64.b64encode(buf.getvalue()).decode("ascii")
             candidate = f"data:{out_mime};base64,{encoded}"
-            if len(candidate) <= max_base64_bytes:
+            if len(candidate) <= max_base64_bytes and _dims_ok(img.width, img.height):
                 logger.info("Auto-resized image fits: %.1f MB (quality=%s, %dx%d)",
                             len(candidate) / (1024 * 1024), q,
                             img.width, img.height)
@@ -669,15 +733,19 @@ async def _vision_analyze_native(
 
         # Proactive embed cap: this image gets baked into conversation
         # history and re-sent on every subsequent turn.  Anthropic rejects
-        # any single base64 image over 5 MB with a 400, and because history
-        # is immutable, an oversized embed permanently wedges the session —
-        # retries can't clear bytes that are already in the request.  Resize
-        # DOWN to the embed target (4 MB, headroom under 5 MB) whenever the
-        # payload exceeds it, not just at the 20 MB hard ceiling.
-        if len(image_data_url) > _EMBED_TARGET_BYTES:
+        # any single base64 image over 5 MB OR over 8000px per side with a
+        # 400, and because history is immutable, an oversized embed
+        # permanently wedges the session — retries can't clear bytes (or
+        # pixels) that are already in the request.  Resize DOWN to the embed
+        # target (4 MB / 7900px, headroom under both ceilings) whenever the
+        # payload exceeds either limit, not just at the 20 MB hard ceiling.
+        _over_bytes = len(image_data_url) > _EMBED_TARGET_BYTES
+        _over_dims = _image_exceeds_dimension(temp_image_path, _EMBED_MAX_DIMENSION)
+        if _over_bytes or _over_dims:
             image_data_url = _resize_image_for_vision(
                 temp_image_path, mime_type=detected_mime_type,
                 max_base64_bytes=_EMBED_TARGET_BYTES,
+                max_dimension=_EMBED_MAX_DIMENSION,
             )
             # If even resizing can't get under the absolute hard ceiling,
             # there's nothing more we can do — reject rather than embed a