kolega-code 0.25.0__tar.gz → 0.25.2__tar.gz

{kolega_code-0.25.0 → kolega_code-0.25.2}/CHANGELOG.md

@@ -6,6 +6,22 @@ This project uses GitHub Releases for detailed generated release notes. This fil
 
 ## Unreleased
 
+## 0.25.2 - 2026-07-28
+
+### Fixed
+
+- Downscaled outbound image copies to satisfy Anthropic's per-image dimensions
+  and aggregate request-size limit, preventing image-heavy conversations from
+  failing later turns while preserving full-resolution history and artifacts.
+
+## 0.25.1 - 2026-07-28
+
+### Fixed
+
+- Resized oversized images only in outbound Anthropic request history while
+  preserving full originals in session artifacts and replay, preventing one
+  large image from breaking every later turn in a resumed conversation.
+
 ## 0.25.0 - 2026-07-28
 
 ### Added

{kolega_code-0.25.0 → kolega_code-0.25.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kolega-code
-Version: 0.25.0
+Version: 0.25.2
 Summary: Multi-agent coding in the terminal
 Project-URL: Homepage, https://kolega-ai.github.io/kolega-code/
 Project-URL: Documentation, https://kolega-ai.github.io/kolega-code/

{kolega_code-0.25.0 → kolega_code-0.25.2}/docs/src/assets/coverage.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="114" height="20" role="img" aria-label="coverage: 82.37%"><title>coverage: 82.37%</title><filter id="blur"><feGaussianBlur stdDeviation="16"/></filter><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="114" height="20" rx="3"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="53" height="20" fill="#67ac09"/><rect width="114" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><g transform="scale(.1)"><g aria-hidden="true" fill="#010101"><text x="315" y="150" fill-opacity=".8" filter="url(#blur)" textLength="510">coverage</text><text x="315" y="150" fill-opacity=".3" textLength="510">coverage</text></g><text x="315" y="140" textLength="510">coverage</text></g><g transform="scale(.1)"><g aria-hidden="true" fill="#010101"><text x="865" y="150" fill-opacity=".8" filter="url(#blur)" textLength="430">82.37%</text><text x="865" y="150" fill-opacity=".3" textLength="430">82.37%</text></g><text x="865" y="140" textLength="430">82.37%</text></g></g></svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="114" height="20" role="img" aria-label="coverage: 82.41%"><title>coverage: 82.41%</title><filter id="blur"><feGaussianBlur stdDeviation="16"/></filter><linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="r"><rect width="114" height="20" rx="3"/></clipPath><g clip-path="url(#r)"><rect width="61" height="20" fill="#555"/><rect x="61" width="53" height="20" fill="#67ac09"/><rect width="114" height="20" fill="url(#s)"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><g transform="scale(.1)"><g aria-hidden="true" fill="#010101"><text x="315" y="150" fill-opacity=".8" filter="url(#blur)" textLength="510">coverage</text><text x="315" y="150" fill-opacity=".3" textLength="510">coverage</text></g><text x="315" y="140" textLength="510">coverage</text></g><g transform="scale(.1)"><g aria-hidden="true" fill="#010101"><text x="865" y="150" fill-opacity=".8" filter="url(#blur)" textLength="430">82.41%</text><text x="865" y="150" fill-opacity=".3" textLength="430">82.41%</text></g><text x="865" y="140" textLength="430">82.41%</text></g></g></svg>

{kolega_code-0.25.0 → kolega_code-0.25.2}/kolega_code/__init__.py

@@ -151,4 +151,4 @@ __all__ = [
     "parse_git_status_output",
 ]
 
-__version__ = "0.25.0"
+__version__ = "0.25.2"

{kolega_code-0.25.0 → kolega_code-0.25.2}/kolega_code/agent/__init__.py

@@ -51,4 +51,4 @@ __all__ = [
     "ToolExtension",
 ]
 
-__version__ = "0.25.0"
+__version__ = "0.25.2"

{kolega_code-0.25.0 → kolega_code-0.25.2}/kolega_code/agent/conversation.py

@@ -23,6 +23,7 @@ from kolega_code.llm.models import (
     ToolCall,
     ToolResult,
 )
+from kolega_code.utils import images as image_utils
 from kolega_code.agent.tool_backend.hashline_v2 import strip_hashline_read_output
 
 logger = logging.getLogger(__name__)
@@ -33,18 +34,117 @@ def _image_placeholder(media_type: str, model_name: str) -> str:
     return f"[An image ({media_type}) was shared earlier in this thread but is not visible to {model_name}.]"
 
 
-def count_image_blocks(messages: List[Message]) -> int:
-    """Count ``ImageBlock`` instances across messages, including ones nested in tool results."""
+def _oversized_image_placeholder(media_type: str, model_name: str) -> str:
+    """Text substituted when a provider-safe image derivative cannot be made."""
+    return (
+        f"[An earlier image ({media_type}) exceeded {model_name}'s request limit and could not be resized safely, "
+        "so it was omitted from this request.]"
+    )
+
+
+def _adapt_image_block_for_provider(
+    block: ImageBlock,
+    *,
+    target_provider: str,
+    target_model: str,
+    supports_vision: bool,
+    max_image_dimension: Optional[int],
+    max_image_base64_bytes: int,
+) -> tuple[ContentBlock, bool]:
+    """Return a request-safe image block without mutating stored history."""
+    if not supports_vision:
+        return TextBlock(text=_image_placeholder(block.media_type, target_model)), True
+
+    if target_provider != "anthropic" or block.image_type != "base64":
+        return block, False
+
+    result = image_utils.resize_base64_image_to_limit(
+        block.data,
+        block.media_type,
+        max_base64_bytes=max_image_base64_bytes,
+        max_dimension=max_image_dimension,
+    )
+    if not result.succeeded:
+        logger.warning(
+            "Omitting oversized Anthropic history image that could not be resized: %s",
+            result.error or "unknown image conversion error",
+        )
+        return (
+            TextBlock(
+                text=_oversized_image_placeholder(block.media_type, target_model),
+                cache_checkpoint=block.cache_checkpoint,
+            ),
+            True,
+        )
+    if not result.resized:
+        return block, False
+
+    assert result.data is not None
+    assert result.media_type is not None
+    logger.info(
+        "Resized Anthropic history image from %d to %d base64 bytes",
+        len(block.data),
+        len(result.data),
+    )
+    return (
+        ImageBlock(
+            image_type="base64",
+            media_type=result.media_type,
+            data=result.data,
+            cache_checkpoint=block.cache_checkpoint,
+        ),
+        True,
+    )
+
+
+def _image_block_stats(messages: List[Message]) -> tuple[int, List[int]]:
+    """Return total image count and base64 lengths, including nested tool results."""
     count = 0
+    base64_sizes: List[int] = []
     for message in messages:
         if not isinstance(message.content, list):
             continue
         for block in message.content:
             if isinstance(block, ImageBlock):
                 count += 1
+                if block.image_type == "base64":
+                    base64_sizes.append(len(block.data))
             elif isinstance(block, ToolResult) and isinstance(block.content, list):
-                count += sum(1 for inner in block.content if isinstance(inner, ImageBlock))
-    return count
+                for inner in block.content:
+                    if isinstance(inner, ImageBlock):
+                        count += 1
+                        if inner.image_type == "base64":
+                            base64_sizes.append(len(inner.data))
+    return count, base64_sizes
+
+
+def count_image_blocks(messages: List[Message]) -> int:
+    """Count ``ImageBlock`` instances across messages, including ones nested in tool results."""
+    return _image_block_stats(messages)[0]
+
+
+def _anthropic_image_base64_limit(base64_sizes: List[int]) -> int:
+    """Return a shared per-image cap that keeps aggregate image data request-safe.
+
+    Images already below the shared cap remain byte-for-byte unchanged. Larger
+    images divide the remaining aggregate budget evenly after accounting for
+    those smaller images, avoiding unnecessary reductions when the request
+    already fits.
+    """
+    per_image_limit = image_utils.ANTHROPIC_MAX_IMAGE_BASE64_BYTES
+    aggregate_limit = image_utils.ANTHROPIC_MAX_REQUEST_IMAGE_BASE64_BYTES
+    projected_sizes = sorted(min(size, per_image_limit) for size in base64_sizes)
+    if sum(projected_sizes) <= aggregate_limit:
+        return per_image_limit
+
+    remaining_budget = aggregate_limit
+    for index, size in enumerate(projected_sizes):
+        remaining_images = len(projected_sizes) - index
+        shared_limit = remaining_budget // remaining_images
+        if size > shared_limit:
+            return max(4, min(per_image_limit, shared_limit))
+        remaining_budget -= size
+    return per_image_limit
 
 
 def _provider_value(provider: Any) -> str:
@@ -199,6 +299,8 @@ def _adapt_content_blocks_for_provider(
     target_provider: str,
     target_model: str,
     supports_vision: bool,
+    max_image_dimension: Optional[int] = None,
+    max_image_base64_bytes: int = image_utils.ANTHROPIC_MAX_IMAGE_BASE64_BYTES,
     target_edit_protocol: Optional[str] = None,
     tool_call_providers: Optional[Dict[str, str]] = None,
     tool_call_protocols: Optional[Dict[str, Optional[str]]] = None,
@@ -209,9 +311,17 @@ def _adapt_content_blocks_for_provider(
     changed = False
 
     for block in blocks:
-        if isinstance(block, ImageBlock) and not supports_vision:
-            adapted.append(TextBlock(text=_image_placeholder(block.media_type, target_model)))
-            changed = True
+        if isinstance(block, ImageBlock):
+            adapted_block, image_changed = _adapt_image_block_for_provider(
+                block,
+                target_provider=target_provider,
+                target_model=target_model,
+                supports_vision=supports_vision,
+                max_image_dimension=max_image_dimension,
+                max_image_base64_bytes=max_image_base64_bytes,
+            )
+            adapted.append(adapted_block)
+            changed = changed or image_changed
         elif isinstance(block, (ThinkingBlock, RedactedThinkingBlock, ResponsesReasoningBlock)):
             if _preserve_reasoning_block(block, source_provider=source_provider, target_provider=target_provider):
                 adapted.append(block)
@@ -240,7 +350,26 @@ def _adapt_content_blocks_for_provider(
                 source_edit_protocol=call_protocol,
                 target_edit_protocol=target_edit_protocol,
             ):
-                adapted.append(block)
+                if isinstance(block.content, list):
+                    inner, inner_changed = _adapt_content_blocks_for_provider(
+                        block.content,
+                        source_provider=source_provider,
+                        target_provider=target_provider,
+                        target_model=target_model,
+                        supports_vision=supports_vision,
+                        max_image_dimension=max_image_dimension,
+                        max_image_base64_bytes=max_image_base64_bytes,
+                        target_edit_protocol=target_edit_protocol,
+                        tool_call_providers=tool_call_providers,
+                        tool_call_protocols=tool_call_protocols,
+                        source_usage_metadata=source_usage_metadata,
+                        # Nested tool-result content is tool output, never assistant prose.
+                        message_role=None,
+                    )
+                    adapted.append(_tool_result_with_content(block, inner) if inner_changed else block)
+                    changed = changed or inner_changed
+                else:
+                    adapted.append(block)
             else:
                 adapted.append(_freeform_result_placeholder(block, call_source))
                 changed = True
@@ -271,6 +400,8 @@ def _adapt_content_blocks_for_provider(
                 target_provider=target_provider,
                 target_model=target_model,
                 supports_vision=supports_vision,
+                max_image_dimension=max_image_dimension,
+                max_image_base64_bytes=max_image_base64_bytes,
                 target_edit_protocol=target_edit_protocol,
                 tool_call_providers=tool_call_providers,
                 tool_call_protocols=tool_call_protocols,
@@ -315,8 +446,9 @@ def adapt_history_for_provider(
     blocks — substituting model-visible text there gets echoed back by the model
     and then persisted as real history. Assistant text carrying placeholders
     echoed by earlier builds is scrubbed for the same reason. Image blocks are
-    preserved for vision models and replaced with placeholders for non-vision
-    models, matching the previous image compatibility behavior.
+    preserved for vision models, except that oversized base64 images get an
+    ephemeral provider-safe derivative for Anthropic. Non-vision models receive
+    placeholders, matching the previous image compatibility behavior.
 
     An assistant message left with no content blocks is omitted from the returned
     history. That orphans nothing: tool calls are never dropped by this pass, so
@@ -327,6 +459,16 @@ def adapt_history_for_provider(
     target_provider = _provider_value(target_provider)
     if target_edit_protocol is not None:
         target_edit_protocol = _provider_value(target_edit_protocol)
+    max_image_dimension: Optional[int] = None
+    max_image_base64_bytes = image_utils.ANTHROPIC_MAX_IMAGE_BASE64_BYTES
+    if target_provider == "anthropic" and supports_vision:
+        image_count, base64_sizes = _image_block_stats(messages)
+        max_image_dimension = (
+            image_utils.ANTHROPIC_MANY_IMAGE_MAX_DIMENSION
+            if image_count > image_utils.ANTHROPIC_MANY_IMAGE_THRESHOLD
+            else image_utils.ANTHROPIC_MAX_IMAGE_DIMENSION
+        )
+        max_image_base64_bytes = _anthropic_image_base64_limit(base64_sizes)
     result: List[Message] = []
     changed_any = False
     tool_call_providers: Dict[str, str] = {}
@@ -351,6 +493,8 @@ def adapt_history_for_provider(
             target_provider=target_provider,
             target_model=target_model,
             supports_vision=supports_vision,
+            max_image_dimension=max_image_dimension,
+            max_image_base64_bytes=max_image_base64_bytes,
             target_edit_protocol=target_edit_protocol,
             tool_call_providers=tool_call_providers,
             tool_call_protocols=tool_call_protocols,

kolega_code-0.25.2/kolega_code/utils/images.py

@@ -0,0 +1,309 @@
+"""Shared image-encoding and MIME helpers for vision support.
+
+Used by the CLI attachment paths (@-mention detection, ``/attach`` slash
+command, clipboard paste, the ``ask --image`` flag) and by the agent
+``read_image`` tool backend. Keeping the MIME map and base64 encoding in one
+place avoids three copies of the logic and CLI<->agent import cycles.
+
+``ascii_thumbnail_from_base64`` is the display-only renderer used by
+``ImageBlock.to_markdown`` so that expanding an image tool call in the TUI
+shows a small ASCII-art preview instead of a wall of base64.
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+import math
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, Optional, Union
+
+from PIL import Image, ImageOps
+
+# Supported image extensions -> MIME types. These are the common web image
+# formats accepted by all four provider backends (Anthropic, OpenAI, Google,
+# ChatGPT/Responses).
+IMAGE_MIME_TYPES: Dict[str, str] = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".bmp": "image/bmp",
+}
+
+# Skip images larger than this to avoid blowing the context budget.
+MAX_IMAGE_BYTES = 20 * 1024 * 1024
+
+# Anthropic validates the encoded ``source.base64`` field itself, not the
+# decoded image size. A raw image just under 10 MiB may therefore exceed this
+# limit after base64's 4/3 expansion.
+ANTHROPIC_MAX_IMAGE_BASE64_BYTES = 10 * 1024 * 1024
+# Anthropic accepts images up to 8,000 px on either axis for ordinary
+# requests. Once the request contains more than 20 images, every image must
+# instead fit within 2,000 x 2,000 px.
+ANTHROPIC_MAX_IMAGE_DIMENSION = 8_000
+ANTHROPIC_MANY_IMAGE_THRESHOLD = 20
+ANTHROPIC_MANY_IMAGE_MAX_DIMENSION = 2_000
+# Anthropic rejects standard API requests above 32 MB. Keep aggregate base64
+# image data at 24 MiB so JSON, system prompts, tools, and text history retain
+# substantial request headroom.
+ANTHROPIC_MAX_REQUEST_IMAGE_BASE64_BYTES = 24 * 1024 * 1024
+
+# Leave headroom below the provider's hard boundary when producing a
+# derivative. This avoids repeatedly re-encoding an image for tiny accounting
+# differences and gives later request serialization a conservative margin.
+_IMAGE_RESIZE_SAFETY_RATIO = 0.95
+_IMAGE_RESIZE_MAX_ATTEMPTS = 12
+# Bound decoded working memory before Pillow copies/converts a provider
+# derivative. Forty megapixels can already require 160 MiB as RGBA.
+_IMAGE_RESIZE_MAX_PIXELS = 40_000_000
+
+# Dark -> light ramp for grayscale ASCII rendering. Index 0 (space) is the
+# darkest pixel; the last char (``@``) is the brightest.
+_ASCII_RAMP = " .:-=+*#%@"
+
+
+@dataclass(frozen=True)
+class ImageResizeResult:
+    """Result of fitting a base64 image to a provider payload limit."""
+
+    data: Optional[str]
+    media_type: Optional[str]
+    resized: bool
+    error: Optional[str] = None
+
+    @property
+    def succeeded(self) -> bool:
+        return self.data is not None and self.media_type is not None
+
+
+def base64_encoded_size(raw_size: int) -> int:
+    """Return the exact base64 length for ``raw_size`` bytes."""
+    if raw_size < 0:
+        raise ValueError("raw_size must be non-negative")
+    return 4 * ((raw_size + 2) // 3)
+
+
+def max_raw_size_for_base64_limit(encoded_limit: int) -> int:
+    """Return the largest raw byte count whose base64 fits ``encoded_limit``."""
+    if encoded_limit < 0:
+        raise ValueError("encoded_limit must be non-negative")
+    return 3 * (encoded_limit // 4)
+
+
+def resize_base64_image_to_limit(
+    data: str,
+    media_type: str,
+    *,
+    max_base64_bytes: int,
+    max_dimension: Optional[int] = None,
+) -> ImageResizeResult:
+    """Return a non-mutating provider-safe derivative of a base64 image.
+
+    Images already within the byte and optional dimension limits are returned
+    byte-for-byte unchanged. Oversized images are decoded and re-encoded as PNG
+    when transparency must be retained, or optimized JPEG otherwise.
+    Dimensions are reduced proportionally to the requested maximum first, then
+    iteratively until the payload has a safety margin below the provider limit.
+    Animated images use their first frame for the ephemeral provider copy.
+    """
+    if max_base64_bytes <= 0:
+        raise ValueError("max_base64_bytes must be positive")
+    if max_dimension is not None and max_dimension <= 0:
+        raise ValueError("max_dimension must be positive")
+
+    if not data.isascii():
+        return ImageResizeResult(None, None, resized=False, error="Image payload is not ASCII base64")
+    encoded_size = len(data)
+
+    # Existing byte-only callers keep the cheap path and never decode a valid
+    # image that already fits. A dimension constraint requires reading the
+    # image header before the same unchanged decision can be made.
+    if encoded_size <= max_base64_bytes and max_dimension is None:
+        return ImageResizeResult(data, media_type, resized=False)
+
+    try:
+        raw = base64.b64decode(data, validate=True)
+        with Image.open(io.BytesIO(raw)) as opened:
+            opened.seek(0)
+            width, height = opened.size
+            dimensions_fit = max_dimension is None or (width <= max_dimension and height <= max_dimension)
+            if encoded_size <= max_base64_bytes and dimensions_fit:
+                return ImageResizeResult(data, media_type, resized=False)
+            if width * height > _IMAGE_RESIZE_MAX_PIXELS:
+                return ImageResizeResult(
+                    None,
+                    None,
+                    resized=False,
+                    error=f"Image dimensions exceed the {_IMAGE_RESIZE_MAX_PIXELS:,}-pixel resize safety limit",
+                )
+            image = ImageOps.exif_transpose(opened).copy()
+    except Exception as exc:
+        return ImageResizeResult(None, None, resized=False, error=f"Could not decode image: {exc}")
+
+    has_transparency = "A" in image.getbands() or "transparency" in image.info
+    if max_dimension is not None and (image.width > max_dimension or image.height > max_dimension):
+        image.thumbnail((max_dimension, max_dimension), Image.Resampling.LANCZOS)
+
+    if has_transparency:
+        image = image.convert("RGBA")
+        output_format = "PNG"
+        output_media_type = "image/png"
+    else:
+        image = image.convert("RGB")
+        output_format = "JPEG"
+        output_media_type = "image/jpeg"
+
+    target_size = int(max_base64_bytes * _IMAGE_RESIZE_SAFETY_RATIO)
+    target_size -= target_size % 4
+    if target_size < 4:
+        return ImageResizeResult(
+            None,
+            None,
+            resized=False,
+            error=f"Could not fit image below the {max_base64_bytes}-byte base64 limit",
+        )
+
+    for _ in range(_IMAGE_RESIZE_MAX_ATTEMPTS):
+        output = io.BytesIO()
+        try:
+            if output_format == "PNG":
+                image.save(output, format=output_format, optimize=True, compress_level=9)
+            else:
+                image.save(output, format=output_format, quality=90, optimize=True, progressive=True)
+        except Exception as exc:
+            return ImageResizeResult(None, None, resized=False, error=f"Could not encode resized image: {exc}")
+
+        derivative = base64.b64encode(output.getvalue()).decode("ascii")
+        if len(derivative) <= target_size:
+            return ImageResizeResult(derivative, output_media_type, resized=True)
+
+        width, height = image.size
+        if width <= 1 and height <= 1:
+            break
+
+        # Encoded size trends with pixel area, so the square root estimates a
+        # useful one-step dimension ratio. The extra margin guarantees progress
+        # when compression ratios are nonlinear.
+        ratio = math.sqrt(target_size / len(derivative)) * 0.95
+        ratio = min(0.9, max(0.1, ratio))
+        next_width = max(1, int(width * ratio))
+        next_height = max(1, int(height * ratio))
+        if next_width == width and width > 1:
+            next_width -= 1
+        if next_height == height and height > 1:
+            next_height -= 1
+        image = image.resize((next_width, next_height), Image.Resampling.LANCZOS)
+
+    return ImageResizeResult(
+        None,
+        None,
+        resized=False,
+        error=f"Could not fit image below the {max_base64_bytes}-byte base64 limit",
+    )
+
+
+def image_media_type(path_or_suffix: Union[str, Path]) -> Optional[str]:
+    """Return the MIME type for an image path/suffix, or ``None`` if unsupported.
+
+    Args:
+        path_or_suffix: A file path (e.g. ``"assets/logo.png"``) or a bare
+            extension (e.g. ``".png"`` or ``"png"``). Case-insensitive.
+    """
+    text = str(path_or_suffix).lower()
+    if text.startswith("."):
+        suffix = text
+    else:
+        suffix = Path(text).suffix.lower()
+        if not suffix:  # bare extension like "png" with no dot or path sep
+            suffix = f".{text}" if "/" not in text and "\\" not in text else ""
+    return IMAGE_MIME_TYPES.get(suffix)
+
+
+def is_supported_image(path: Union[str, Path]) -> bool:
+    """True if ``path`` has a supported image extension."""
+    return image_media_type(path) is not None
+
+
+def encode_image_attachment(data: bytes, media_type: str, *, path: Optional[str] = None) -> Dict[str, Any]:
+    """Build an image attachment dict from raw bytes.
+
+    Args:
+        data: Raw image bytes.
+        media_type: MIME type (e.g. ``"image/png"``).
+        path: Optional source path included for display/debugging.
+
+    Returns:
+        ``{"type": "image", "media_type": ..., "data": "<base64>", ...}`` —
+        the shape consumed by ``BaseAgent._attachment_blocks``.
+    """
+    attachment: Dict[str, Any] = {
+        "type": "image",
+        "media_type": media_type,
+        "data": base64.b64encode(data).decode("ascii"),
+    }
+    if path:
+        attachment["path"] = path
+    return attachment
+
+
+def encode_image_file(path: Union[str, Path]) -> Optional[Dict[str, Any]]:
+    """Read, validate, and base64-encode an image file.
+
+    Returns ``None`` if the path is not a supported image format, the file is
+    missing/unreadable, or it exceeds ``MAX_IMAGE_BYTES`` (so callers can fall
+    back to a friendly message instead of crashing).
+    """
+    path = Path(path)
+    media_type = image_media_type(path)
+    if media_type is None:
+        return None
+    try:
+        if not path.is_file():
+            return None
+        size = path.stat().st_size
+    except OSError:
+        return None
+    if size > MAX_IMAGE_BYTES:
+        return None
+    try:
+        data = path.read_bytes()
+    except OSError:
+        return None
+    return encode_image_attachment(data, media_type, path=str(path))
+
+
+def ascii_thumbnail_from_base64(data: str, media_type: str, *, width: int = 40, height: int = 20) -> str:
+    """Render a grayscale ASCII-art thumbnail from a base64-encoded image.
+
+    Decodes the image with Pillow, converts to grayscale, downsamples to
+    ``width`` x ``height``, and maps each pixel's brightness to a character
+    in ``_ASCII_RAMP`` (dark = space, light = ``@``).
+
+    Returns the multi-line ASCII string. If the image cannot be decoded
+    (corrupt data, unsupported format, etc.), returns a short placeholder
+    string instead of raising — a malformed image must never crash the TUI.
+    """
+    try:
+        raw = base64.b64decode(data)
+        img = Image.open(io.BytesIO(raw))
+        img = img.convert("L").resize((width, height), Image.Resampling.LANCZOS)
+    except Exception:
+        return f"[Image — {media_type} — could not render preview]"
+
+    pixels = img.load()
+    if pixels is None:
+        return f"[Image — {media_type} — could not render preview]"
+    ramp_last = len(_ASCII_RAMP) - 1
+    lines: list[str] = []
+    for y in range(height):
+        chars: list[str] = []
+        for x in range(width):
+            v = pixels[x, y]
+            if isinstance(v, tuple):
+                v = v[0]
+            chars.append(_ASCII_RAMP[int(v) * ramp_last // 255])
+        lines.append("".join(chars))
+    return "\n".join(lines)

{kolega_code-0.25.0 → kolega_code-0.25.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "kolega-code"
-version = "0.25.0"
+version = "0.25.2"
 description = "Multi-agent coding in the terminal"
 readme = "README.md"
 license = {file = "LICENSE"}