kolega-code 0.7.2__tar.gz → 0.8.1__tar.gz

{kolega_code-0.7.2 → kolega_code-0.8.1}/.env.example

@@ -7,6 +7,7 @@ OPENAI_API_KEY=
 # (no key needed). Optional override of the OAuth client id, for testing only:
 # KOLEGA_CODE_CHATGPT_CLIENT_ID=
 GOOGLE_API_KEY=
+FIREWORKS_API_KEY=
 MOONSHOT_API_KEY=
 DEEPSEEK_API_KEY=
 ZAI_API_KEY=

{kolega_code-0.7.2 → kolega_code-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kolega-code
-Version: 0.7.2
+Version: 0.8.1
 Summary: Local-first AI coding agent for the terminal
 Project-URL: Homepage, https://kolega-ai.github.io/kolega-code/
 Project-URL: Documentation, https://kolega-ai.github.io/kolega-code/
@@ -54,6 +54,7 @@ Requires-Dist: nest-asyncio==1.6.0
 Requires-Dist: openai==1.109.1
 Requires-Dist: packaging==25.0
 Requires-Dist: pathspec==1.1.1
+Requires-Dist: pillow==12.2.0
 Requires-Dist: playwright==1.59.0
 Requires-Dist: psutil==7.2.2
 Requires-Dist: pydantic==2.13.4

{kolega_code-0.7.2 → kolega_code-0.8.1}/docs/src/content/docs/concepts/agents.md

@@ -12,10 +12,10 @@ agent can hand off to the others when a task benefits from focus.
 | Agent | Specialty | Can edit files? |
 | --- | --- | --- |
 | **Coder** | The main, general-purpose coding agent. Full toolset. | Yes |
-| **Investigation** | Read-only exploration of the codebase. | No |
+| **Investigation** | Read-only exploration of the codebase. Can run investigative commands. | No |
 | **Browser** | Web navigation and interaction via Playwright. | No (browser tools only) |
 | **General** | A flexible agent that can read and dispatch other agents. | Limited |
-| **Planning** | Drives [Plan mode](../../tui/modes/): investigates and writes a plan, read-only. | No |
+| **Planning** | Drives [Plan mode](../../tui/modes/): investigates and writes a plan. Can run commands but cannot edit files. | No |
 
 ## Dispatching sub-agents
 

{kolega_code-0.7.2 → kolega_code-0.8.1}/docs/src/content/docs/concepts/tools.md

@@ -61,13 +61,16 @@ and `dispatch_general_agent`.
 ## Read-only vs. full access
 
 Tools are gated by mode. In a read-only context — like [Plan mode](../../tui/modes/)
-or an investigation sub-agent — only non-mutating tools are available
+or an investigation sub-agent — the agent can read and search the codebase
 (`list_directory`, `read_entire_file`, `read_file_section`, `search_codebase`,
 `find_files_by_pattern`, `web_search`, `web_fetch`, `think_hard`, and reading
-memory). Editing files and running commands require Build mode's full toolset.
+memory) **and** run shell commands to investigate. Editing files still requires
+Build mode's full toolset.
 
-This separation is what makes Plan mode safe to run against any codebase: the
-planning agent can look but not touch.
+This separation is what keeps Plan mode safe to run against any codebase: the
+planning agent can look and run investigative commands, but it has no file-edit
+tools. Shell commands are further gated by the active permission mode — in `ask`
+they prompt before running.
 
 In the Textual TUI, Build mode defaults to `ask` permission mode. Shell commands
 and file edits must be approved before they run unless you switch to `auto` or

{kolega_code-0.7.2 → kolega_code-0.8.1}/docs/src/content/docs/configuration/environment-variables.md

@@ -118,6 +118,7 @@ starting point:
 # Pick one provider's key (or several)
 MOONSHOT_API_KEY=
 DEEPSEEK_API_KEY=
+FIREWORKS_API_KEY=
 ANTHROPIC_API_KEY=
 
 # Optional: choose models per role
@@ -125,6 +126,10 @@ KOLEGA_CODE_PROVIDER=moonshot
 KOLEGA_CODE_MODEL=kimi-k2.7-code
 KOLEGA_CODE_THINKING_EFFORT=auto
 
+# Fireworks example:
+# KOLEGA_CODE_PROVIDER=fireworks
+# KOLEGA_CODE_MODEL=accounts/fireworks/models/glm-5p2
+
 # Optional: web search
 KOLEGA_CODE_WEB_SEARCH_BACKEND=duckduckgo
 

{kolega_code-0.7.2 → kolega_code-0.8.1}/docs/src/content/docs/configuration/providers-and-models.mdx

@@ -45,11 +45,21 @@ with thinking effort `auto` (enabled) requests route to **K2.7 Code**, and with
 (disabled) they route to **K2.6**. Set `KIMI_CODING_API_KEY` to your Kimi Coding Plan key.
 </Aside>
 
+<Aside type="tip">
+**Fireworks.ai.** The `fireworks` provider targets Fireworks' OpenAI-compatible
+serverless endpoint (`https://api.fireworks.ai/inference/v1`) with `FIREWORKS_API_KEY`.
+Fireworks model IDs use resource names such as `accounts/fireworks/models/glm-5p2`.
+Kolega Code exposes GLM-5.2, GLM-5.1, Kimi K2.7 Code, DeepSeek V4 Pro/Flash,
+MiniMax M3, and Qwen 3.7 Plus through the Settings UI and CLI. Fireworks reasoning
+models return `reasoning_content`; Kolega Code exposes `none`, `low`, `medium`,
+`high`, and `max` as `reasoning_effort` values for these models.
+</Aside>
+
 <Aside type="note">
-The **Settings tab** in the TUI currently offers a curated shortlist —
-**Moonshot (Kimi K2.7 Code and Kimi K2.6)** and **DeepSeek (DeepSeek V4 Pro)**.
-The full provider list above is available through environment variables and CLI
-flags. See [Settings & API Keys](../settings-and-api-keys/).
+The **Settings tab** in the TUI is generated from Kolega Code's model registry, so
+new entries in the supported model catalog appear there automatically. You can also
+select any supported provider/model through environment variables and CLI flags.
+See [Settings & API Keys](../settings-and-api-keys/).
 </Aside>
 
 ## Model roles
@@ -153,6 +163,7 @@ models in the TUI.
 | Moonshot `kimi-k2.6` | `auto`, `none` | `auto` |
 | Z.AI `glm-5.2` | `high`, `max` | `max` |
 | Z.AI `glm-5.1` | `auto`, `none` | `auto` |
+| Fireworks serverless reasoning models | `none`, `low`, `medium`, `high`, `max` | `medium` |
 | Google `gemini-2.5-pro` | `auto`, `low`, `medium`, `high` | `medium` |
 | OpenAI reasoning models | `low`, `medium`, `high` | `medium` |
 

{kolega_code-0.7.2 → kolega_code-0.8.1}/docs/src/content/docs/tui/modes.md

@@ -35,6 +35,8 @@ produces a plan.
 While planning, the agent can:
 
 - Read and search the codebase.
+- Run shell commands to investigate (e.g. `git log`, `grep`, running tests) —
+  subject to the current permission mode, so commands prompt for approval in `ask`.
 - Maintain a shared **task list** (visible in the Planning tab).
 - Write a structured plan, which appears in the **Planning** tab.
 

{kolega_code-0.7.2 → kolega_code-0.8.1}/kolega_code/__init__.py

@@ -18,6 +18,7 @@ from .agent.planningagent import PlanningAgent
 from .agent.compression import HistoryCompressor
 from .agent.context import AgentContext, AgentServices, Telemetry, WorkspaceInfo
 from .agent.conversation import Conversation
+from .agent.errors import AgentError, MaxAgentIterationsExceeded
 from .events import AgentEventEmitter
 
 # Configuration
@@ -86,6 +87,8 @@ __all__ = [
     "AgentContext",
     "AgentServices",
     "Telemetry",
+    "AgentError",
+    "MaxAgentIterationsExceeded",
     "WorkspaceInfo",
     "Conversation",
     "HistoryCompressor",
@@ -148,4 +151,4 @@ __all__ = [
     "parse_git_status_output",
 ]
 
-__version__ = "0.7.2"
+__version__ = "0.8.1"

{kolega_code-0.7.2 → kolega_code-0.8.1}/kolega_code/agent/__init__.py

@@ -8,6 +8,9 @@ from .browseragent import BrowserAgent
 from .generalagent import GeneralAgent
 from .planningagent import PlanningAgent
 
+# Export agent errors
+from .errors import AgentError, MaxAgentIterationsExceeded
+
 # Export agent models
 from kolega_code.events import AgentStatus, AgentEvent
 
@@ -25,6 +28,8 @@ __all__ = [
     "BrowserAgent",
     "GeneralAgent",
     "PlanningAgent",
+    "AgentError",
+    "MaxAgentIterationsExceeded",
     "AgentStatus",
     "AgentEvent",
     "AgentConfig",
@@ -39,4 +44,4 @@ __all__ = [
     "ToolExtension",
 ]
 
-__version__ = "0.7.2"
+__version__ = "0.8.1"

{kolega_code-0.7.2 → kolega_code-0.8.1}/kolega_code/agent/baseagent.py

@@ -12,10 +12,11 @@ from typing import Any, AsyncGenerator, Dict, List, Optional
 
 from .common import LogMixin
 from .compression import CompactionResult, HistoryCompressor
+from .errors import MaxAgentIterationsExceeded
 from kolega_code.config import AgentConfig, ModelProvider
 from kolega_code.events import AgentConnectionManager
 from .context import AgentContext, AgentServices, Telemetry, WorkspaceInfo
-from .conversation import Conversation
+from .conversation import Conversation, adapt_history_for_provider
 from kolega_code.events import AgentEventEmitter
 from kolega_code.hooks import (
     NO_OP_DISPATCHER,
@@ -34,7 +35,7 @@ from kolega_code.llm.exceptions import (
 )
 from kolega_code.llm.models import ImageBlock, Message, MessageHistory, TextBlock, ToolCall, ToolResult
 from kolega_code.llm.providers.models import TokenCount
-from kolega_code.llm.specs import get_model_specs
+from kolega_code.llm.specs import get_model_specs, supports_vision as model_supports_vision
 from kolega_code.permissions import (
     PermissionDecision,
     PermissionMode,
@@ -90,10 +91,6 @@ class BaseAgent(LogMixin):
     long_content_tool_calls = ["create_file", "replace_entire_file"]
     max_tool_result_chars_in_history = 100_000
     skill_content_pattern = re.compile(r'<skill_content name="[^"]+">')
-    deepseek_image_unsupported_message = (
-        "DeepSeek V4 Pro does not support image input via the DeepSeek API. "
-        "Remove the image or switch to a vision-capable model for this request."
-    )
 
     def __init__(
         self,
@@ -123,6 +120,7 @@ class BaseAgent(LogMixin):
         sub_agent_recorder: Optional[Any] = None,
         hook_dispatcher: Optional[HookDispatcher] = None,
         context: Optional[AgentContext] = None,
+        max_iterations: Optional[int] = None,
     ) -> None:
         """
         Initialize a new BaseAgent instance.
@@ -207,7 +205,11 @@ class BaseAgent(LogMixin):
         if hook_dispatcher is not None:
             context.hook_dispatcher = hook_dispatcher
 
+        if max_iterations is not None and max_iterations < 1:
+            raise ValueError("max_iterations must be a positive integer or None")
+
         self.context = context
+        self.max_iterations = max_iterations
 
         # Flat attributes kept for compatibility with subclasses, tools, and hosts.
         self.project_path = context.workspace.project_path
@@ -270,6 +272,11 @@ class BaseAgent(LogMixin):
         self.model_context_length = model_specs["context_length"]
         self.model_completion_tokens = model_specs["max_completion_tokens"]
         self.model_default_temperature = model_specs.get("default_temperature", 1.0)
+        # Whether this agent's primary model can accept image input. Read by the
+        # ToolCollection read_image tool gate (so non-vision models never see the
+        # tool) and used by _unsupported_attachment_message to reject image
+        # attachments for non-vision models with a clear message.
+        self.supports_vision = bool(model_specs.get("supports_vision", False))
 
         self.llm = context.create_llm_client(agent_name=self.agent_name)
 
@@ -365,6 +372,26 @@ class BaseAgent(LogMixin):
         """
         return self.conversation.repaired(messages)
 
+    def _history_for_llm(self) -> MessageHistory:
+        """Build the message history to send to the LLM for this turn.
+
+        Compaction-aware and tool-call-repaired. For non-vision models, any
+        ``ImageBlock`` carried over from earlier turns (user attachments or
+        ``read_image`` tool results) is replaced with a text placeholder on this
+        request copy only — the stored history is never mutated, so switching
+        back to a vision-capable model restores the images.
+        """
+        effective = self.get_effective_history_for_llm()
+        fixed = self.fix_incomplete_tool_calls(list(effective))
+        provider = getattr(self.primary_model_config.provider, "value", self.primary_model_config.provider)
+        fixed = adapt_history_for_provider(
+            fixed,
+            target_provider=str(provider),
+            target_model=self.primary_model_config.model,
+            supports_vision=self.supports_vision,
+        )
+        return MessageHistory(fixed)
+
     def mark_cache_checkpoint(self) -> None:
         """
         Mark the last message in history for caching and remove cache_control from all other messages.
@@ -480,18 +507,22 @@ class BaseAgent(LogMixin):
     # ------------------------------------------------------------------
 
     def _unsupported_attachment_message(self, attachments: Optional[List[Dict[str, Any]]]) -> Optional[str]:
+        if not any(attachment.get("type") == "image" for attachment in attachments or []):
+            return None
+
         provider = getattr(
             self.primary_model_config.provider,
             "value",
             self.primary_model_config.provider,
         )
-        if provider != ModelProvider.DEEPSEEK.value:
+        if model_supports_vision(provider, self.primary_model_config.model):
             return None
 
-        if any(attachment.get("type") == "image" for attachment in attachments or []):
-            return self.deepseek_image_unsupported_message
-
-        return None
+        return (
+            f"{self.primary_model_config.model} does not support image input. "
+            "Your message was not sent to the model. "
+            "Remove the image attachment or switch to a vision-capable model with /model."
+        )
 
     def _attachment_blocks(self, attachments: Optional[List[Dict[str, Any]]]) -> List[Any]:
         """Convert attachment payloads into content blocks for a user message."""
@@ -518,9 +549,9 @@ class BaseAgent(LogMixin):
 
     async def count_current_context(self) -> TokenCount:
         self._sanitize_oversized_tool_results()
-        # Fix history before counting to get accurate count for what LLM will see
-        effective = self.get_effective_history_for_llm()
-        fixed_history = MessageHistory(self.fix_incomplete_tool_calls(list(effective)))
+        # History sent to the LLM (and to token counting): tool-call-repaired and,
+        # for non-vision models, stripped of image blocks from earlier turns.
+        fixed_history = self._history_for_llm()
         token_count = await self.llm.count_tokens(
             system=self.system_prompt,
             messages=fixed_history,
@@ -1257,7 +1288,15 @@ class BaseAgent(LogMixin):
 
         stop_reason = None
         stop_overrides = 0
+        iterations = 0
         while stop_reason not in ["end_turn", "max_tokens", "stop_sequence"]:
+            iterations += 1
+            if self.max_iterations is not None and iterations > self.max_iterations:
+                raise MaxAgentIterationsExceeded(
+                    f"Agent '{self.agent_name}' exceeded max_iterations={self.max_iterations} "
+                    "without reaching a terminal stop reason"
+                )
+
             self.mark_cache_checkpoint()
 
             try:
@@ -1304,9 +1343,9 @@ class BaseAgent(LogMixin):
                 response_uuid = str(uuid.uuid4())
                 thinking_uuid = str(uuid.uuid4())
 
-                # Fix history before sending to LLM to ensure valid tool call sequences
-                effective = self.get_effective_history_for_llm()
-                fixed_history = MessageHistory(self.fix_incomplete_tool_calls(list(effective)))
+                # History sent to the LLM: tool-call-repaired and, for non-vision
+                # models, stripped of image blocks carried over from earlier turns.
+                fixed_history = self._history_for_llm()
 
                 async with await self.llm.stream(
                     system=self.system_prompt,

{kolega_code-0.7.2 → kolega_code-0.8.1}/kolega_code/agent/browseragent.py

@@ -45,6 +45,7 @@ class BrowserAgent(BaseAgent):
         usage_recorder: Optional[Any] = None,
         sub_agent_recorder: Optional[Any] = None,
         hook_dispatcher: Optional[Any] = None,
+        max_iterations: Optional[int] = None,
     ) -> None:
         """
         Initialize a new BrowserAgent instance.
@@ -97,6 +98,7 @@ class BrowserAgent(BaseAgent):
             usage_recorder=usage_recorder,
             sub_agent_recorder=sub_agent_recorder,
             hook_dispatcher=hook_dispatcher,
+            max_iterations=max_iterations,
         )
 
         self.tool_collection = ToolCollection(

{kolega_code-0.7.2 → kolega_code-0.8.1}/kolega_code/agent/coder.py

@@ -49,6 +49,7 @@ class CoderAgent(BaseAgent, LogMixin):
         usage_recorder: Optional[Any] = None,
         sub_agent_recorder: Optional[Any] = None,
         hook_dispatcher: Optional[Any] = None,
+        max_iterations: Optional[int] = None,
     ) -> None:
         """
         Initialize a new CoderAgent instance.
@@ -104,6 +105,7 @@ class CoderAgent(BaseAgent, LogMixin):
             usage_recorder=usage_recorder,
             sub_agent_recorder=sub_agent_recorder,
             hook_dispatcher=hook_dispatcher,
+            max_iterations=max_iterations,
         )
 
         # Configure tool collection with custom coder agent tools

{kolega_code-0.7.2 → kolega_code-0.8.1}/kolega_code/agent/conversation.py

@@ -11,11 +11,206 @@ import logging
 import re
 from typing import Any, Dict, List, Optional
 
-from kolega_code.llm.models import Message, MessageHistory, TextBlock, ToolCall, ToolResult
+from kolega_code.llm.models import (
+    ImageBlock,
+    Message,
+    MessageHistory,
+    RedactedThinkingBlock,
+    ResponsesReasoningBlock,
+    TextBlock,
+    ThinkingBlock,
+    ToolCall,
+    ToolResult,
+)
 
 logger = logging.getLogger(__name__)
 
 
+def _image_placeholder(media_type: str, model_name: str) -> str:
+    """Text substituted for an image block when the active model can't see images."""
+    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."""
+    count = 0
+    for message in messages:
+        if not isinstance(message.content, list):
+            continue
+        for block in message.content:
+            if isinstance(block, ImageBlock):
+                count += 1
+            elif isinstance(block, ToolResult) and isinstance(block.content, list):
+                count += sum(1 for inner in block.content if isinstance(inner, ImageBlock))
+    return count
+
+
+def _provider_value(provider: Any) -> str:
+    value = getattr(provider, "value", provider)
+    return str(value or "")
+
+
+def _message_with_content(message: Message, content: List[Any]) -> Message:
+    return Message(
+        role=message.role,
+        content=content,
+        stop_reason=message.stop_reason,
+        tool_calls=message.tool_calls,
+        usage_metadata=message.usage_metadata,
+    )
+
+
+def _tool_result_with_content(tool_result: ToolResult, content: List[Any]) -> ToolResult:
+    return ToolResult(
+        tool_use_id=tool_result.tool_use_id,
+        content=content,
+        name=tool_result.name,
+        is_error=tool_result.is_error,
+        cache_checkpoint=tool_result.cache_checkpoint,
+        execution_id=tool_result.execution_id,
+    )
+
+
+def replace_image_blocks_with_placeholders(messages: List[Message], model_name: str) -> List[Message]:
+    """Return a new message list with every ``ImageBlock`` replaced by a text placeholder.
+
+    Non-mutating: messages without images are returned as-is. When a replacement
+    occurs, new ``Message``/``ToolResult`` objects are built so the caller's stored
+    history is never altered — switching back to a vision-capable model restores
+    the original images. ``ImageBlock``s nested inside a ``ToolResult.content`` list
+    (e.g. from the ``read_image`` tool) are handled too.
+    """
+    result: List[Message] = []
+    for message in messages:
+        if not isinstance(message.content, list):
+            result.append(message)
+            continue
+        new_blocks: List[Any] = []
+        changed = False
+        for block in message.content:
+            if isinstance(block, ImageBlock):
+                new_blocks.append(TextBlock(text=_image_placeholder(block.media_type, model_name)))
+                changed = True
+            elif isinstance(block, ToolResult) and isinstance(block.content, list):
+                inner_new: List[Any] = []
+                inner_changed = False
+                for inner in block.content:
+                    if isinstance(inner, ImageBlock):
+                        inner_new.append(TextBlock(text=_image_placeholder(inner.media_type, model_name)))
+                        inner_changed = True
+                    else:
+                        inner_new.append(inner)
+                if inner_changed:
+                    new_blocks.append(_tool_result_with_content(block, inner_new))
+                    changed = True
+                else:
+                    new_blocks.append(block)
+            else:
+                new_blocks.append(block)
+        if changed:
+            result.append(_message_with_content(message, new_blocks))
+        else:
+            result.append(message)
+    return result
+
+
+# Groups of providers whose reasoning is mutually replayable. The api-key
+# `openai` and the ChatGPT-subscription `openai_chatgpt` are both the OpenAI
+# Responses API, so encrypted reasoning produced by one replays cleanly to the
+# other — the one exception to "only replay reasoning to the same provider".
+_REASONING_COMPATIBLE_GROUPS: tuple[frozenset[str], ...] = (frozenset({"openai", "openai_chatgpt"}),)
+
+
+def _preserve_reasoning_block(block: Any, *, source_provider: str, target_provider: str) -> bool:
+    if not source_provider:
+        return False
+    if source_provider == target_provider:
+        return True
+    return any(
+        source_provider in group and target_provider in group for group in _REASONING_COMPATIBLE_GROUPS
+    )
+
+
+def _reasoning_placeholder(block: Any, source_provider: str) -> TextBlock:
+    source = source_provider or "unknown provider"
+    if isinstance(block, RedactedThinkingBlock):
+        return TextBlock(text=f"[Prior redacted reasoning from {source} omitted for compatibility.]")
+    return TextBlock(text=f"[Prior reasoning from {source} omitted for compatibility.]")
+
+
+def _adapt_content_blocks_for_provider(
+    blocks: List[Any], *, source_provider: str, target_provider: str, target_model: str, supports_vision: bool
+) -> tuple[List[Any], bool]:
+    adapted: List[Any] = []
+    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
+        elif isinstance(block, (ThinkingBlock, RedactedThinkingBlock, ResponsesReasoningBlock)):
+            if _preserve_reasoning_block(block, source_provider=source_provider, target_provider=target_provider):
+                adapted.append(block)
+            else:
+                adapted.append(_reasoning_placeholder(block, source_provider))
+                changed = True
+        elif isinstance(block, ToolResult) and 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,
+            )
+            if inner_changed:
+                adapted.append(_tool_result_with_content(block, inner))
+                changed = True
+            else:
+                adapted.append(block)
+        else:
+            adapted.append(block)
+
+    return adapted, changed
+
+
+def adapt_history_for_provider(
+    messages: List[Message], *, target_provider: str, target_model: str, supports_vision: bool
+) -> List[Message]:
+    """Return a request-safe history for the target provider without mutating storage.
+
+    Provider-managed reasoning blocks are not portable across providers, but
+    reasoning produced by a provider is safe to send back to the same provider.
+    Preserve same-provider reasoning; convert foreign or unknown reasoning
+    blocks to text placeholders. Image blocks are preserved for vision models
+    and replaced with placeholders for non-vision models, matching the previous
+    image compatibility behavior.
+    """
+    target_provider = _provider_value(target_provider)
+    result: List[Message] = []
+    changed_any = False
+
+    for message in messages:
+        if not isinstance(message.content, list):
+            result.append(message)
+            continue
+
+        source_provider = _provider_value((message.usage_metadata or {}).get("provider"))
+        adapted_content, changed = _adapt_content_blocks_for_provider(
+            message.content,
+            source_provider=source_provider,
+            target_provider=target_provider,
+            target_model=target_model,
+            supports_vision=supports_vision,
+        )
+        if changed:
+            result.append(_message_with_content(message, adapted_content))
+            changed_any = True
+        else:
+            result.append(message)
+
+    return result if changed_any else messages
+
+
 class Conversation:
     """Message history plus the invariants that keep it valid for providers."""
 
@@ -31,8 +226,11 @@ class Conversation:
         # Compaction state: ``summary`` stands in for ``history[:compacted_through]``
         # in the effective view; messages from ``compacted_through`` onward are kept
         # verbatim. ``summary is None`` / ``compacted_through == 0`` means uncompacted.
+        # ``compacted_history_length`` is the history length captured when compaction
+        # ran, so the UI can place the summary after the retained tail on restore.
         self.summary: Optional[Message] = None
         self.compacted_through: int = 0
+        self.compacted_history_length: int = 0
         self.max_tool_result_chars = max_tool_result_chars
 
     # ------------------------------------------------------------------
@@ -51,6 +249,7 @@ class Conversation:
         self._history = value if isinstance(value, MessageHistory) else MessageHistory(list(value))
         self.summary = None
         self.compacted_through = 0
+        self.compacted_history_length = 0
 
     @property
     def last_compression_index(self) -> Optional[int]:
@@ -66,6 +265,7 @@ class Conversation:
         if value is None:
             self.summary = None
             self.compacted_through = 0
+            self.compacted_history_length = 0
         else:
             self.compacted_through = value + 1
 
@@ -74,6 +274,15 @@ class Conversation:
         self._history = MessageHistory([])
         self.summary = None
         self.compacted_through = 0
+        self.compacted_history_length = 0
+
+    def has_image_blocks(self) -> bool:
+        """True if the effective (compaction-aware) history still carries any images.
+
+        Images folded into a compaction summary are already gone, so this reflects
+        only what would actually be sent to the model.
+        """
+        return count_image_blocks(list(self.effective_history())) > 0
 
     # ------------------------------------------------------------------
     # Appending
@@ -439,6 +648,7 @@ class Conversation:
             summary if isinstance(summary, Message) else Message(role="user", content=[TextBlock(text=str(summary))])
         )
         self.compacted_through = len(self._history)
+        self.compacted_history_length = len(self._history)
 
     def apply_compaction(self, summary_text: str, split_point: int) -> None:
         """Record ``summary_text`` as standing in for ``history[:split_point]``.
@@ -448,6 +658,7 @@ class Conversation:
         """
         self.summary = Message(role="user", content=[TextBlock(text=summary_text)])
         self.compacted_through = max(0, min(split_point, len(self._history)))
+        self.compacted_history_length = len(self._history)
 
     def compaction_split_point(self, *, keep_recent: int, min_prefix: int) -> Optional[int]:
         """Index where the verbatim recent tail should begin.
@@ -500,13 +711,15 @@ class Conversation:
         return {
             "summary": self.summary.get_text_content() if self.summary is not None else "",
             "compacted_through": self.compacted_through,
+            "compacted_history_length": self.compacted_history_length,
         }
 
     def restore_compaction(self, data: Optional[Dict[str, Any]]) -> None:
         """Restore a compaction boundary saved by ``dump_compaction``.
 
         Call AFTER ``restore`` (which resets compaction). Assigns the boundary
-        fields directly so it does not trip the history setter's reset.
+        fields directly so it does not trip the history setter's reset. Old
+        sessions without ``compacted_history_length`` fall back to 0.
         """
         data = data or {}
         text = (data.get("summary") or "").strip()
@@ -514,6 +727,8 @@ class Conversation:
         if text and through > 0:
             self.summary = Message(role="user", content=[TextBlock(text=text)])
             self.compacted_through = min(through, len(self._history))
+            self.compacted_history_length = int(data.get("compacted_history_length") or 0)
         else:
             self.summary = None
             self.compacted_through = 0
+            self.compacted_history_length = 0

kolega_code-0.8.1/kolega_code/agent/errors.py

@@ -0,0 +1,9 @@
+"""Exceptions raised by agent runtime loops."""
+
+
+class AgentError(RuntimeError):
+    """Base class for catchable agent runtime errors."""
+
+
+class MaxAgentIterationsExceeded(AgentError):
+    """Raised when an opt-in agent loop iteration cap is exceeded."""