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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kolega-code
-Version: 0.7.1
+Version: 0.7.2
 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/

{kolega_code-0.7.1 → kolega_code-0.7.2}/RELEASING.md

@@ -20,6 +20,12 @@ release branch.
 2. Update `pyproject.toml`, `uv.lock`, and package `__version__` values to the
    release version.
 
+   Running `uv lock` advances the `exclude-newer` cutoff recorded in `uv.lock`,
+   because `pyproject.toml` sets `exclude-newer = "1 week"` as a relative
+   duration. The cutoff timestamp moving forward, and any dependency versions
+   released within the new one-week window being pulled in, is expected and
+   acceptable. Do not revert these changes.
+
 3. Run the fast test suite:
 
    ```bash

{kolega_code-0.7.1 → kolega_code-0.7.2}/docs/src/content/docs/hooks.md

@@ -63,6 +63,7 @@ Both files use the same shape:
 | `PreToolUse` | Before a tool runs (after the permission gate) | Denies the tool; the reason is returned to the agent as a tool error, so it can adjust |
 | `PostToolUse` | After a tool succeeds (and on failure) | Ends the turn; the reason is shown as a warning |
 | `PreCompact` | Before the conversation is compacted | Advisory |
+| `PostCompact` | After the conversation is compacted | Advisory; payload reports before/after token counts |
 | `Stop` | The agent is about to finish its turn | Keeps the agent working; the reason becomes its next instruction |
 | `SubagentStop` | A dispatched sub-agent finished | Advisory; can annotate the result the parent sees |
 | `Notification` | A permission prompt is about to be shown | Advisory (desktop notifications, sounds) |

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

@@ -148,4 +148,4 @@ __all__ = [
     "parse_git_status_output",
 ]
 
-__version__ = "0.7.1"
+__version__ = "0.7.2"

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

@@ -39,4 +39,4 @@ __all__ = [
     "ToolExtension",
 ]
 
-__version__ = "0.7.1"
+__version__ = "0.7.2"

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

@@ -11,7 +11,7 @@ from pathlib import Path
 from typing import Any, AsyncGenerator, Dict, List, Optional
 
 from .common import LogMixin
-from .compression import HistoryCompressor
+from .compression import CompactionResult, HistoryCompressor
 from kolega_code.config import AgentConfig, ModelProvider
 from kolega_code.events import AgentConnectionManager
 from .context import AgentContext, AgentServices, Telemetry, WorkspaceInfo
@@ -398,6 +398,14 @@ class BaseAgent(LogMixin):
         """Restores the message history from a list of dictionaries using custom methods."""
         self.conversation.restore(serialized_history)
 
+    def dump_compaction_state(self) -> Dict[str, Any]:
+        """Serialize the compaction boundary (summary + how many leading messages it folds)."""
+        return self.conversation.dump_compaction()
+
+    def restore_compaction_state(self, data: Optional[Dict[str, Any]]) -> None:
+        """Restore the compaction boundary; must be called after restore_message_history."""
+        self.conversation.restore_compaction(data)
+
     def _sanitize_oversized_tool_results(self) -> int:
         return self.conversation.sanitize_oversized_tool_results()
 
@@ -549,9 +557,12 @@ class BaseAgent(LogMixin):
             message=message,
         )
 
-    async def compress_history(self) -> None:
+    async def compress_history(self) -> CompactionResult:
         """
-        Non-destructively summarize the current history and mark a compression boundary.
+        Non-destructively summarize the current history, keeping recent turns
+        verbatim. Emits a compaction_status event around the work so the UI can
+        show progress, then recounts + emits a context_update so the gauge
+        refreshes. Returns the structured outcome.
         """
 
         async def on_info(message: str) -> None:
@@ -560,16 +571,34 @@ class BaseAgent(LogMixin):
         async def on_error(message: str) -> None:
             await self.log_error(message, sender=self.agent_name)
 
-        await self.compressor.summarize(
-            self.conversation,
-            llm=self.llm,
-            model=self.primary_model_config.model,
-            max_completion_tokens=self.model_completion_tokens,
-            temperature=self.model_default_temperature,
-            thinking=self.primary_model_config.thinking_effort,
-            on_info=on_info,
-            on_error=on_error,
+        await self.emitter.compaction_status("started", "Compacting conversation…")
+        try:
+            result = await self.compressor.summarize(
+                self.conversation,
+                llm=self.llm,
+                model=self.primary_model_config.model,
+                temperature=self.model_default_temperature,
+                # No extended thinking: a bounded summary doesn't need it, and the
+                # thinking budget could otherwise exceed the small summary max_tokens.
+                thinking=None,
+                on_info=on_info,
+                on_error=on_error,
+            )
+        finally:
+            # Recount + emit so the context gauge reflects post-compaction reality
+            # (even on a no-op the UI may have been stale).
+            await self.count_current_context()
+
+        phase = "finished" if result.ok else "error"
+        summary_text = (
+            self.conversation.summary.get_text_content() if result.ok and self.conversation.summary else ""
         )
+        await self.emitter.compaction_status(phase, result.message, summary=summary_text)
+        return result
+
+    def clear_history(self) -> None:
+        """Drop all history and reset compaction state."""
+        self.conversation.clear()
 
     # ------------------------------------------------------------------
     # Tool execution
@@ -1136,9 +1165,8 @@ class BaseAgent(LogMixin):
     #
     # process_message_stream is the single canonical loop shared by every
     # agent. Subclasses customize behavior through the hook methods below
-    # (build_user_content, apply_compression_fallback, on_tool_use_start,
-    # should_stop_after_tools, recap_agent_outcome) rather than overriding
-    # the loop itself.
+    # (build_user_content, on_tool_use_start, should_stop_after_tools,
+    # recap_agent_outcome) rather than overriding the loop itself.
     # ------------------------------------------------------------------
 
     completion_log_message = "Processing complete"
@@ -1166,21 +1194,6 @@ class BaseAgent(LogMixin):
 
         return content_blocks
 
-    def apply_compression_fallback(self) -> None:
-        """
-        Hard-truncate history when compression alone could not get under budget.
-
-        Default: keep the first message (the original task) plus any protected
-        skill-content messages.
-        """
-        first_message = self.history[0]
-        protected = [
-            message
-            for message in self.history
-            if message is not first_message and self._is_protected_skill_content(message)
-        ]
-        self.history = MessageHistory(protected + [first_message])
-
     async def on_tool_use_start(self, tool_call_delta: Dict[str, Any]) -> None:
         """
         Called when the provider streams a tool_use_start event (Anthropic only).
@@ -1252,20 +1265,35 @@ class BaseAgent(LogMixin):
                 logger.debug("Input token count: %s", token_count)
 
                 if self.compressor.over_budget(token_count.input_tokens, self.model_context_length):
+                    before_tokens = token_count.input_tokens
                     # PreCompact hooks (advisory): observe before history is compacted.
                     await self.fire_hook(
                         HookEvent.PRE_COMPACT,
                         {
                             "trigger": "auto",
-                            "input_tokens": token_count.input_tokens,
+                            "input_tokens": before_tokens,
                             "model_context_length": self.model_context_length,
                         },
                     )
-                    await self.compress_history()
+                    result = await self.compress_history()
                     token_count = await self.count_current_context()
 
-                    if self.compressor.over_budget(token_count.input_tokens, self.model_context_length):
-                        self.apply_compression_fallback()
+                    # PostCompact hooks (advisory): observe the outcome. There is no
+                    # destructive fallback — a bounded summary plus capped tool results
+                    # and a small verbatim tail keep us under budget; if somehow not, we
+                    # send as-is rather than wipe history.
+                    await self.fire_hook(
+                        HookEvent.POST_COMPACT,
+                        {
+                            "trigger": "auto",
+                            "ok": result.ok,
+                            "reason": result.reason,
+                            "summarized_messages": result.summarized_messages,
+                            "input_tokens_before": before_tokens,
+                            "input_tokens_after": token_count.input_tokens,
+                            "model_context_length": self.model_context_length,
+                        },
+                    )
 
                     self.mark_cache_checkpoint()
 

kolega_code-0.7.2/kolega_code/agent/compression.py

@@ -0,0 +1,146 @@
+"""History compression: summarize a conversation when it outgrows the context window."""
+
+import logging
+from dataclasses import dataclass
+from typing import Awaitable, Callable, Optional
+
+from .conversation import Conversation
+from kolega_code.llm.models import Message, MessageHistory, TextBlock
+from .prompts import (
+    build_compression_summary_user_prompt,
+    COMPRESSION_SUMMARY_SYSTEM_PROMPT,
+)
+
+logger = logging.getLogger(__name__)
+
+LogCallback = Callable[[str], Awaitable[None]]
+
+
+@dataclass(frozen=True)
+class CompactionResult:
+    """Outcome of a compaction attempt, surfaced to callers and the UI.
+
+    ``reason`` is a machine tag: "ok" | "too_few" | "nothing_to_summarize" | "llm_error".
+    ``message`` is a human-readable line for the command output / logs.
+    """
+
+    ok: bool
+    reason: str
+    summarized_messages: int = 0
+    message: str = ""
+
+
+class HistoryCompressor:
+    """Summarizes a conversation non-destructively when it crosses the budget threshold."""
+
+    MIN_MESSAGES_TO_COMPRESS = 5
+    # How many of the most recent messages to keep verbatim after the summary.
+    KEEP_RECENT_MESSAGES = 6
+    # Don't bother summarizing a trivially short prefix.
+    MIN_PREFIX_TO_SUMMARIZE = 3
+    # Cap the summary length: the prompt targets ~600 words (~900 tokens), so a
+    # small ceiling keeps it tight and avoids the model's full completion budget.
+    SUMMARY_MAX_TOKENS = 2048
+
+    def __init__(self, threshold: float = 0.8) -> None:
+        # Fraction of the model context window above which compression kicks in
+        self.threshold = threshold
+
+    def over_budget(self, input_tokens: int, model_context_length: int) -> bool:
+        return input_tokens > model_context_length * self.threshold
+
+    async def summarize(
+        self,
+        conversation: Conversation,
+        *,
+        llm,
+        model: str,
+        temperature: float,
+        thinking,
+        on_info: Optional[LogCallback] = None,
+        on_error: Optional[LogCallback] = None,
+    ) -> CompactionResult:
+        """
+        Non-destructively summarize the aged-out prefix while keeping the most
+        recent turns verbatim, and move the compaction boundary.
+
+        Incremental: only the messages that have aged out since the previous
+        boundary are summarized, with the prior summary folded in for continuity.
+        Returns a CompactionResult describing what happened — never a silent no-op.
+        """
+        history = conversation.history
+        if not history or len(history) < self.MIN_MESSAGES_TO_COMPRESS:
+            return CompactionResult(
+                ok=False,
+                reason="too_few",
+                message=(
+                    f"Nothing to compress yet ({len(history)} message(s); "
+                    f"need at least {self.MIN_MESSAGES_TO_COMPRESS})."
+                ),
+            )
+
+        split = conversation.compaction_split_point(
+            keep_recent=self.KEEP_RECENT_MESSAGES, min_prefix=self.MIN_PREFIX_TO_SUMMARIZE
+        )
+        prior_through = conversation.compacted_through if conversation.summary is not None else 0
+        if split is None or split <= prior_through:
+            return CompactionResult(
+                ok=False,
+                reason="nothing_to_summarize",
+                message="Already compact — no older messages to summarize.",
+            )
+
+        if on_info:
+            await on_info("Compressing message history...")
+
+        try:
+            prefix = MessageHistory(list(history[prior_through:split]))
+            prefix_markdown = prefix.get_markdown_conversation()
+            previous_summary = conversation.summary.get_text_content() if conversation.summary is not None else None
+            user_prompt_filled = build_compression_summary_user_prompt(
+                prefix_markdown, previous_summary=previous_summary
+            )
+
+            messages = MessageHistory([Message(role="user", content=[TextBlock(text=user_prompt_filled)])])
+            system_message = Message(role="system", content=[TextBlock(text=COMPRESSION_SUMMARY_SYSTEM_PROMPT)])
+
+            # Stream and drain rather than calling generate(): the Anthropic SDK
+            # rejects non-streaming requests whose max_tokens is large enough to risk
+            # a >10-minute response, which the model's full completion budget triggers.
+            async with await llm.stream(
+                messages=messages,
+                system=system_message,
+                temperature=temperature,
+                model=model,
+                max_completion_tokens=self.SUMMARY_MAX_TOKENS,
+                thinking=thinking,
+            ) as stream:
+                async for _event in stream:
+                    pass
+            response = await stream.get_final_message()
+
+            summary_text = response.get_text_content()
+            if not summary_text or not summary_text.strip():
+                msg = "Compression produced an empty summary; history left unchanged."
+                if on_error:
+                    await on_error(msg)
+                else:
+                    logger.error(msg)
+                return CompactionResult(ok=False, reason="llm_error", message=msg)
+
+            folded = split - prior_through
+            conversation.apply_compaction(summary_text, split)
+
+            done = f"Compressed {folded} older message(s) into a summary; kept the latest turns verbatim."
+            if on_info:
+                await on_info(done)
+            return CompactionResult(ok=True, reason="ok", summarized_messages=folded, message=done)
+
+        except Exception as e:
+            # Never swallow into a fake success: log the full traceback and surface
+            # the real error to the caller.
+            logger.exception("Failed to compress message history")
+            msg = f"Failed to compress message history: {type(e).__name__}: {e}"
+            if on_error:
+                await on_error(msg)
+            return CompactionResult(ok=False, reason="llm_error", message=msg)

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

@@ -27,11 +27,54 @@ class Conversation:
         *,
         max_tool_result_chars: int = 100_000,
     ) -> None:
-        self.history = MessageHistory(list(messages) if messages else [])
-        # Compression marker: index of the last message before a summary was appended
-        self.last_compression_index: Optional[int] = None
+        self._history = MessageHistory(list(messages) if messages else [])
+        # 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.
+        self.summary: Optional[Message] = None
+        self.compacted_through: int = 0
         self.max_tool_result_chars = max_tool_result_chars
 
+    # ------------------------------------------------------------------
+    # History access (compaction-aware)
+    # ------------------------------------------------------------------
+
+    @property
+    def history(self) -> MessageHistory:
+        return self._history
+
+    @history.setter
+    def history(self, value) -> None:
+        # Wholesale replacement of the log invalidates any compaction boundary.
+        # Internal mutators that must preserve an active summary assign to
+        # ``self._history`` directly instead of going through this setter.
+        self._history = value if isinstance(value, MessageHistory) else MessageHistory(list(value))
+        self.summary = None
+        self.compacted_through = 0
+
+    @property
+    def last_compression_index(self) -> Optional[int]:
+        """Back-compat: index of the last message folded into the summary, or None."""
+        if self.summary is not None and self.compacted_through > 0:
+            return self.compacted_through - 1
+        return None
+
+    @last_compression_index.setter
+    def last_compression_index(self, value: Optional[int]) -> None:
+        # Legacy setter. The only meaningful operation is clearing the boundary;
+        # a real summary is recorded through ``apply_compaction``/``record_compression``.
+        if value is None:
+            self.summary = None
+            self.compacted_through = 0
+        else:
+            self.compacted_through = value + 1
+
+    def clear(self) -> None:
+        """Drop all history and reset compaction state."""
+        self._history = MessageHistory([])
+        self.summary = None
+        self.compacted_through = 0
+
     # ------------------------------------------------------------------
     # Appending
     # ------------------------------------------------------------------
@@ -125,7 +168,9 @@ class Conversation:
     def extend(self, messages: List[Message]) -> None:
         """Extend history with multiple messages, repairing incomplete tool calls in the result."""
         all_messages = list(self.history) + messages
-        self.history = MessageHistory(self.repaired(all_messages))
+        # Assign to _history (not the public setter) so an active compaction survives
+        # appending live turns.
+        self._history = MessageHistory(self.repaired(all_messages))
 
     # ------------------------------------------------------------------
     # Views and validity
@@ -134,20 +179,17 @@ class Conversation:
     def effective_history(self) -> MessageHistory:
         """
         Return the subset of history to send to the LLM:
-        - If compressed: protected skill content + summary + all messages after the summary
-        - Else: the full history
+        - If compacted: protected skill content from the folded prefix, then the
+          summary, then the most-recent turns kept verbatim.
+        - Else: the full history.
         """
-        if self.last_compression_index is not None and self.history:
-            # Summary is the message immediately after the boundary
-            summary_idx = self.last_compression_index + 1
-            if summary_idx < len(self.history):
-                summary_msg = self.history[summary_idx]
-                protected = [message for message in self.history[:summary_idx] if self.is_protected(message)]
-                # Tail starts after the summary
-                tail = list(self.history[summary_idx + 1 :]) if summary_idx + 1 < len(self.history) else []
-                return MessageHistory(protected + [summary_msg] + tail)
-
-        return MessageHistory(list(self.history))
+        if self.summary is not None and self.compacted_through > 0 and self._history:
+            cut = min(self.compacted_through, len(self._history))
+            protected = [message for message in self._history[:cut] if self.is_protected(message)]
+            tail = list(self._history[cut:])
+            return MessageHistory(protected + [self.summary] + tail)
+
+        return MessageHistory(list(self._history))
 
     def is_protected(self, message: Message) -> bool:
         """True for user messages carrying skill content that must survive compression."""
@@ -388,9 +430,55 @@ class Conversation:
         return sanitized_count
 
     def record_compression(self, summary: Message) -> None:
-        """Append a compression summary and mark the boundary before it."""
-        self.history.append(summary)
-        self.last_compression_index = len(self.history) - 2
+        """Back-compat shim: fold the entire current history into ``summary``.
+
+        Newer callers use ``apply_compaction`` with an explicit split point so the
+        most recent turns are kept verbatim.
+        """
+        self.summary = (
+            summary if isinstance(summary, Message) else Message(role="user", content=[TextBlock(text=str(summary))])
+        )
+        self.compacted_through = len(self._history)
+
+    def apply_compaction(self, summary_text: str, split_point: int) -> None:
+        """Record ``summary_text`` as standing in for ``history[:split_point]``.
+
+        Non-destructive: the full history is untouched; only the compaction
+        boundary moves. Messages from ``split_point`` onward stay verbatim.
+        """
+        self.summary = Message(role="user", content=[TextBlock(text=summary_text)])
+        self.compacted_through = max(0, min(split_point, len(self._history)))
+
+    def compaction_split_point(self, *, keep_recent: int, min_prefix: int) -> Optional[int]:
+        """Index where the verbatim recent tail should begin.
+
+        Keeps the last ``keep_recent`` messages verbatim, then snaps the cut
+        backward so it never lands between an assistant tool_use and its
+        tool_result. Returns None when the prefix to summarize would be smaller
+        than ``min_prefix``.
+        """
+        n = len(self._history)
+        if n <= min_prefix:
+            return None
+        candidate = self._snap_to_safe_boundary(max(0, n - keep_recent))
+        if candidate < min_prefix:
+            return None
+        return candidate
+
+    def _snap_to_safe_boundary(self, idx: int) -> int:
+        """Move ``idx`` backward past any assistant tool_use so a tool_use/tool_result
+        group is never split across the compaction boundary."""
+        while idx > 0:
+            prev = self._history[idx - 1]
+            if (
+                prev.role == "assistant"
+                and isinstance(prev.content, list)
+                and any(isinstance(block, ToolCall) for block in prev.content)
+            ):
+                idx -= 1
+                continue
+            break
+        return idx
 
     # ------------------------------------------------------------------
     # Serialization
@@ -406,3 +494,26 @@ class Conversation:
         # Keep history authentic - no fixing here
         self.history = MessageHistory(parsed_messages)
         self.sanitize_oversized_tool_results()
+
+    def dump_compaction(self) -> Dict[str, Any]:
+        """Serialize the compaction boundary so it survives save/restore."""
+        return {
+            "summary": self.summary.get_text_content() if self.summary is not None else "",
+            "compacted_through": self.compacted_through,
+        }
+
+    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.
+        """
+        data = data or {}
+        text = (data.get("summary") or "").strip()
+        through = int(data.get("compacted_through") or 0)
+        if text and through > 0:
+            self.summary = Message(role="user", content=[TextBlock(text=text)])
+            self.compacted_through = min(through, len(self._history))
+        else:
+            self.summary = None
+            self.compacted_through = 0

kolega_code-0.7.2/kolega_code/agent/prompt_templates/auxiliary/compression/summary.system.md

@@ -0,0 +1,28 @@
+You are compacting an in-progress coding session so the work can continue seamlessly in a smaller context window. Produce a TIGHT continuity briefing — not a transcript.
+
+Hard rules:
+- Respond with the summary text ONLY. Do NOT call tools. Do NOT ask questions.
+- Be bounded: aim for under ~600 words. Omit anything not needed to keep working.
+- Quote identifiers EXACTLY: file paths, function/class names, variable names, error strings, commands, and config keys. Do not paraphrase code or paths.
+- Do not invent facts. If something is unknown or unfinished, say so briefly.
+- Preserve any `<skill_content name="...">` instructions referenced earlier — note them by name so they are not lost.
+
+Write these sections, each terse. Use `##` headers and keep them in this order:
+
+## Goal
+The user's overall objective and any explicit constraints, in 1-3 sentences.
+
+## State
+What is true RIGHT NOW: what has been built or changed, what works, what has been verified.
+
+## Files Touched
+A bullet list of exact paths read/created/modified, each with a 3-8 word note on what changed or why it matters. No code blocks unless a snippet is load-bearing.
+
+## Decisions
+Key technical decisions and their one-line rationale. Note approaches already tried and rejected.
+
+## Open Problems
+Exact open errors (quote them), failing tests, or unresolved questions. Write "None" if there are none.
+
+## Next Steps
+The concrete next actions to take, in order. Write "None" if the task appears complete.

kolega_code-0.7.2/kolega_code/agent/prompt_templates/auxiliary/compression/summary.user.md.j2

@@ -0,0 +1,17 @@
+{% if previous_summary %}
+A prior summary already covers the earliest part of this session. Treat it as established context and fold its facts into your new summary (do not drop anything important from it):
+
+<previous_summary>
+{{ previous_summary }}
+</previous_summary>
+
+Below are the messages that have happened SINCE that summary and now need to be folded in as well:
+{% else %}
+Summarize the following coding session so far:
+{% endif %}
+
+<conversation_history>
+{{ history }}
+</conversation_history>
+
+Produce the continuity briefing exactly as specified in your instructions. Summary text only — do not call tools.

{kolega_code-0.7.1 → kolega_code-0.7.2}/kolega_code/agent/prompts.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from functools import lru_cache
 from pathlib import Path
-from typing import Any
+from typing import Any, Optional
 
 import jinja2
 
@@ -56,8 +56,12 @@ SKILL_CATALOG_PROMPT_TEMPLATE = prompt_template_source("extensions/skills/catalo
 PLANNING_AGENT_SYSTEM_PROMPT_TEMPLATE = prompt_template_source("system/agents/planning.md.j2")
 
 
-def build_compression_summary_user_prompt(history: str) -> str:
-    return render_prompt_template("auxiliary/compression/summary.user.md.j2", history=history)
+def build_compression_summary_user_prompt(history: str, previous_summary: Optional[str] = None) -> str:
+    return render_prompt_template(
+        "auxiliary/compression/summary.user.md.j2",
+        history=history,
+        previous_summary=previous_summary,
+    )
 
 
 def build_implement_plan_prompt(plan: str, gigacode_enabled: bool = False) -> str: