kolega-code 0.33.0__tar.gz → 0.34.0__tar.gz

{kolega_code-0.33.0 → kolega_code-0.34.0}/CHANGELOG.md

@@ -6,6 +6,53 @@ This project uses GitHub Releases for detailed generated release notes. This fil
 
 ## Unreleased
 
+## 0.34.0 - 2026-09-02
+
+### Added
+
+- **Telegram gateway.** The new `kolega-code gateway` daemon drives Kolega Code
+  agents from Telegram: each chat maps to a durable session, and agent turns
+  stream back as edit-in-place chat messages. `kolega-code gateway telegram
+  setup --verify` saves your @BotFather token, `kolega-code gateway run
+  --adapter telegram` starts the daemon (an LLM-free `echo` adapter is
+  included for transport testing), and `gateway install` registers it as a
+  systemd user service or launchd agent — a new Gateway page in Settings
+  covers configuration. Access is by sender allowlist with pairing-code
+  onboarding (`gateway pairing`), group chats stay silent unless the bot is
+  @mentioned or replied to, and each chat gets slash commands (`/model`,
+  `/permissions`, `/status`) as ordinary messages. Permission prompts and
+  agent questions arrive as tappable inline buttons. Voice notes are
+  transcribed, photos attach as vision input, documents are saved where the
+  agent's tools can reach them, sessions survive gateway restarts, and the
+  working directory defaults to `~/kolega-code-workspace` — never the daemon's
+  own. Outbound messages are redacted for known secrets, including the bot
+  token.
+- **`/handoff`.** `/handoff [focus instructions]` summarizes the current
+  session with a one-shot LLM call and switches to a brand-new session whose
+  entire context is that structured document (Goal, Constraints &
+  Preferences, Progress, Key Decisions, Critical Context, Next Steps). The
+  old session stays intact and resumable, recorded as the new session's
+  parent; Esc during generation cancels cooperatively and leaves the session
+  untouched.
+- **Groq as a first-party provider, plus remote voice transcription.** Groq is
+  now a catalogued provider — `openai/gpt-oss-120b`, `openai/gpt-oss-20b`,
+  `qwen/qwen3-32b`, `qwen/qwen3.6-27b`, and the Llama 4 Scout/Maverick pair,
+  all 131K context — with its own entry on the Providers page and the `groq`
+  API key. Gateway voice notes transcribe through Groq's hosted
+  `whisper-large-v3-turbo` (Settings → Tools → Voice transcription), reusing
+  that same key; transcription is remote-only.
+- **GLM-5.3-Flash on Z.AI.** The GLM Coding Plan catalog adds `glm-5.3-flash`
+  — 1M-token context, 128K max output, `high`/`max` reasoning effort
+  (default `max`), and the first GLM-5 model with native vision input.
+
+### Changed
+
+- Provider catalogs refreshed from live endpoints (2026-09-02 snapshots):
+  OpenRouter (274 tool-capable models, 20 featured), Tinker (27 models,
+  +`zai-org/GLM-5.3`), Ollama Cloud (19 models, +`glm-5.3`/`glm-5.3-flash`,
+  deepseek `:preview` tags dropped), and Perplexity Agent (46 models,
+  +`anthropic/claude-fable-5-1`).
+
 ## 0.33.0 - 2026-08-26
 
 ### Added

{kolega_code-0.33.0 → kolega_code-0.34.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kolega-code
-Version: 0.33.0
+Version: 0.34.0
 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/
@@ -27,6 +27,7 @@ Classifier: Topic :: Software Development
 Classifier: Topic :: Utilities
 Requires-Python: >=3.11
 Requires-Dist: agent-client-protocol==0.12.0
+Requires-Dist: aiogram==3.30.0
 Requires-Dist: anthropic==0.101.0
 Requires-Dist: atif==1.7.0
 Requires-Dist: beautifulsoup4==4.14.3

{kolega_code-0.33.0 → kolega_code-0.34.0}/kolega_code/__init__.py

@@ -174,4 +174,4 @@ __all__ = [
     "parse_git_status_output",
 ]
 
-__version__ = "0.33.0"
+__version__ = "0.34.0"

{kolega_code-0.33.0 → kolega_code-0.34.0}/kolega_code/agent/__init__.py

@@ -51,4 +51,4 @@ __all__ = [
     "ToolExtension",
 ]
 
-__version__ = "0.33.0"
+__version__ = "0.34.0"

{kolega_code-0.33.0 → kolega_code-0.34.0}/kolega_code/agent/compression.py

@@ -33,7 +33,7 @@ class CompactionResult:
     message: str = ""
 
 
-def _render_transcript(messages: List[Message]) -> str:
+def render_transcript(messages: List[Message]) -> str:
     """Role-tagged plain text: JSON only for tool arguments, tool results raw.
 
     JSON-escaping newline-heavy tool output costs ~30% more tokens than
@@ -250,13 +250,13 @@ class HistoryCompressor:
                 omitted = tail_start - head_end
                 if omitted:
                     parts = [
-                        _render_transcript(prefix[:head_end]),
+                        render_transcript(prefix[:head_end]),
                         _omission_notice(omitted),
-                        _render_transcript(prefix[tail_start:]),
+                        render_transcript(prefix[tail_start:]),
                     ]
                     transcript = "\n\n".join(part for part in parts if part)
                 else:
-                    transcript = _render_transcript(prefix)
+                    transcript = render_transcript(prefix)
                 prompt = build_compression_summary_user_prompt(transcript, previous_summary=previous_summary)
                 return MessageHistory([Message(role="user", content=[TextBlock(text=prompt)])])
 

kolega_code-0.34.0/kolega_code/agent/handoff.py

@@ -0,0 +1,167 @@
+"""Handoff: summarize a session into a document that seeds a fresh session.
+
+Mirrors the helper-request pattern of ``compression.py``: a one-shot streamed
+LLM call that renders the session as a role-tagged transcript and asks for a
+structured handoff document. The result is injected as the sole context of a
+brand-new session, so the summary must stand alone.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from dataclasses import dataclass
+from typing import Any, List, Optional, Union
+
+from kolega_code.llm.ledger import helper_origin, llm_call_origin
+from kolega_code.llm.models import Message, MessageHistory, TextBlock
+
+from .compression import render_transcript
+from .conversation import replace_image_blocks_with_placeholders
+from .prompts import HANDOFF_SYSTEM_PROMPT, build_handoff_user_prompt
+
+logger = logging.getLogger(__name__)
+
+
+class HandoffCancelledError(Exception):
+    """Raised when the user cancels handoff document generation."""
+
+
+@dataclass(frozen=True)
+class HandoffResult:
+    """Outcome of a handoff document generation attempt.
+
+    ``reason`` is a machine tag: "ok" | "too_few" | "empty_summary" | "llm_error".
+    Cancellation is not a result — it raises :class:`HandoffCancelledError`.
+    """
+
+    ok: bool
+    reason: str
+    document: str = ""
+    message: str = ""
+
+
+# Don't summarize a session that has no real exchange to summarize.
+HANDOFF_MIN_MESSAGES = 2
+# Generous ceiling matching the compaction helper: reasoning models can consume
+# most of the budget on chain-of-thought before emitting the document.
+HANDOFF_MAX_TOKENS = 8192
+# Completed-but-empty documents (reasoning-only, whitespace, no text) are
+# retried on the same request before the attempt is reported unusable.
+HANDOFF_EMPTY_ATTEMPTS = 3
+
+
+def build_handoff_context_text(document: str) -> str:
+    """Wrap a handoff document for injection as a new session's opening context."""
+    return (
+        "<handoff-context>\n"
+        f"{document}\n"
+        "</handoff-context>\n\n"
+        "The above is a handoff document from a previous session. "
+        "Use this context to continue the work seamlessly."
+    )
+
+
+async def _stream_document(
+    llm: Any,
+    messages: MessageHistory,
+    system: Message,
+    temperature: float,
+    model: str,
+    thinking: Optional[Union[int, str]],
+    cancel_event: asyncio.Event,
+) -> Message:
+    """Issue the handoff helper request and return the completed message.
+
+    Stream and consume events rather than calling ``generate()``: the Anthropic
+    SDK rejects non-streaming requests whose max_tokens is large enough to risk
+    a >10-minute response. Cancellation is cooperative — the stream is closed
+    and :class:`HandoffCancelledError` raised when the event fires.
+    """
+    if cancel_event.is_set():
+        raise HandoffCancelledError()
+    with llm_call_origin(helper_origin("handoff")):
+        stream_cm = await llm.stream(
+            messages=messages,
+            system=system,
+            temperature=temperature,
+            model=model,
+            max_completion_tokens=HANDOFF_MAX_TOKENS,
+            thinking=thinking,
+        )
+        async with stream_cm as stream:
+            async for _event in stream:
+                if cancel_event.is_set():
+                    break
+        if cancel_event.is_set():
+            raise HandoffCancelledError()
+        return await stream.get_final_message()
+
+
+async def generate_handoff_document(
+    messages: List[Message],
+    *,
+    llm: Any,
+    model: str,
+    temperature: float,
+    thinking: Optional[Union[int, str]],
+    focus: Optional[str] = None,
+    cancel_event: Optional[asyncio.Event] = None,
+) -> HandoffResult:
+    """Summarize ``messages`` into a handoff document via a one-shot LLM call.
+
+    Images are replaced with placeholders (base64 must stay out of the
+    transcript); tool calls render as JSON arguments and tool results raw,
+    exactly like compaction's transcript. Raises :class:`HandoffCancelledError`
+    when ``cancel_event`` fires before a document is produced; otherwise never
+    raises — failures come back as ``HandoffResult(ok=False, ...)``.
+    """
+    if len(messages) < HANDOFF_MIN_MESSAGES:
+        return HandoffResult(
+            ok=False,
+            reason="too_few",
+            message=(f"Nothing to hand off ({len(messages)} message(s); need at least {HANDOFF_MIN_MESSAGES})."),
+        )
+
+    if cancel_event is None:
+        cancel_event = asyncio.Event()
+
+    try:
+        stripped = replace_image_blocks_with_placeholders(list(messages), model)
+        prompt = build_handoff_user_prompt(render_transcript(stripped), focus=focus)
+        request_messages = MessageHistory([Message(role="user", content=[TextBlock(text=prompt)])])
+        system_message = Message(role="system", content=[TextBlock(text=HANDOFF_SYSTEM_PROMPT)])
+
+        response = await _stream_document(
+            llm, request_messages, system_message, temperature, model, thinking, cancel_event
+        )
+        for attempt in range(1, HANDOFF_EMPTY_ATTEMPTS + 1):
+            document = response.get_text_content()
+            if document and document.strip():
+                return HandoffResult(ok=True, reason="ok", document=document.strip())
+            stop = getattr(response, "stop_reason", None)
+            stop_note = f" (stop_reason={stop})" if stop else ""
+            if attempt >= HANDOFF_EMPTY_ATTEMPTS:
+                break
+            logger.info(
+                "Handoff generation produced an empty document%s; retrying (%d/%d).",
+                stop_note,
+                attempt + 1,
+                HANDOFF_EMPTY_ATTEMPTS,
+            )
+            response = await _stream_document(
+                llm, request_messages, system_message, temperature, model, thinking, cancel_event
+            )
+
+        message = "Handoff generation produced an empty document; session left unchanged."
+        logger.error(message)
+        return HandoffResult(ok=False, reason="empty_summary", message=message)
+    except HandoffCancelledError:
+        raise
+    except Exception as exc:
+        logger.exception("Failed to generate handoff document")
+        return HandoffResult(
+            ok=False,
+            reason="llm_error",
+            message=f"Failed to generate handoff document: {type(exc).__name__}: {exc}",
+        )

kolega_code-0.34.0/kolega_code/agent/prompt_templates/auxiliary/handoff/document.system.md

@@ -0,0 +1,37 @@
+You are handing off an in-progress coding session to a fresh session that has NO access to this conversation. Write a handoff document that lets the new session continue seamlessly.
+
+Hard rules:
+- Output ONLY the handoff document. No preamble, no commentary, no wrapper text.
+- Capture exact technical state, not abstractions: file paths, symbol names, commands run, test results, observed failures, decisions made, and partial work affecting the next step.
+- 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.
+- Be thorough: completeness matters more than brevity here, because the new session cannot look anything up in this conversation.
+
+Use exactly this structure:
+
+## Goal
+What the user is trying to accomplish
+
+## Constraints & Preferences
+- Any constraints, preferences, or requirements mentioned
+
+## Progress
+### Done
+- [x] Completed tasks with specifics
+
+### In Progress
+- [ ] Current work, if any
+
+### Pending
+- [ ] Tasks mentioned but not started
+
+## Key Decisions
+- **Decision**: rationale
+
+## Critical Context
+- Code snippets, file paths, function/type names, error messages, and data essential to continue
+- Repository state if relevant
+
+## Next Steps
+1. What should happen next

kolega_code-0.34.0/kolega_code/agent/prompt_templates/auxiliary/handoff/document.user.md.j2

@@ -0,0 +1,11 @@
+Write a handoff document for the following coding session so the work can continue seamlessly in a new session that has no access to this conversation.
+
+<conversation_history>
+{{ transcript }}
+</conversation_history>
+
+Each transcript entry is tagged with its role; tool calls show their JSON arguments and tool results follow raw.
+{% if focus %}
+Additional focus: {{ focus }}
+{% endif %}
+Produce the handoff document exactly as specified in your instructions. Handoff document only — do not call tools.

{kolega_code-0.33.0 → kolega_code-0.34.0}/kolega_code/agent/prompts.py

@@ -38,6 +38,7 @@ def render_prompt_template(template_name: str, **variables: Any) -> str:
 
 
 COMPRESSION_SUMMARY_SYSTEM_PROMPT = render_prompt_template("auxiliary/compression/summary.system.md")
+HANDOFF_SYSTEM_PROMPT = render_prompt_template("auxiliary/handoff/document.system.md")
 SHELL_SAFETY_SYSTEM_PROMPT = render_prompt_template("auxiliary/terminal/safety.system.md")
 SHELL_COMPRESSION_SYSTEM_PROMPT = render_prompt_template("auxiliary/terminal/output_summary.system.md")
 SHARED_TASK_LIST_PROMPT = render_prompt_template("extensions/cli/shared_task_list.md")
@@ -71,6 +72,14 @@ def build_compression_summary_user_prompt(history: str, previous_summary: Option
     )
 
 
+def build_handoff_user_prompt(transcript: str, focus: Optional[str] = None) -> str:
+    return render_prompt_template(
+        "auxiliary/handoff/document.user.md.j2",
+        transcript=transcript,
+        focus=focus,
+    )
+
+
 def build_silent_turn_nudge(attempt: int) -> str:
     """Escalating reminder injected when the model ends a turn with no tool call and no visible text."""
     return render_prompt_template("auxiliary/agent_loop/silent_turn_nudge.user.md.j2", attempt=attempt)

{kolega_code-0.33.0 → kolega_code-0.34.0}/kolega_code/cli/app.py

@@ -61,6 +61,7 @@ from kolega_code.agent.prompts import (
     build_implement_plan_prompt,
     build_mode_switch_notice,
 )
+from kolega_code.agent.handoff import build_handoff_context_text
 from kolega_code.hooks import HookDispatcher, HookEvent
 from kolega_code.llm.models import Message, MessageHistory, TextBlock
 from kolega_code.memory import ProjectMemoryManager
@@ -309,6 +310,10 @@ class KolegaCodeApp(
         self._session_diff_timer: Optional[Timer] = None
         self._session_diff_baseline_id: Optional[int] = None
         self._rewind_running = False
+        # /handoff state: the guard flag plus the cancel event the Esc path sets
+        # while the handoff document is generating.
+        self._handoff_in_progress = False
+        self._handoff_cancel_event: Optional[asyncio.Event] = None
         self._workflow_activities: dict[str, tui_state.WorkflowActivity] = {}
         self._render_pending = False
         self._conversation_anchor_pending = False
@@ -966,6 +971,7 @@ class KolegaCodeApp(
             loop=dict(record.loop),
             usage=dict(record.usage),
             active_project_path=record.active_project_path,
+            parent_session_id=record.parent_session_id,
         )
 
     async def _save_session_async(self) -> None:
@@ -2827,6 +2833,140 @@ class KolegaCodeApp(
             tui_state.ConversationEntry(kind="progress", content=messages.THREAD_RESET_MESSAGE, complete=True)
         )
 
+    async def _handoff_session(self, document: str) -> None:
+        """Switch to a fresh session whose entire context is ``document``.
+
+        The caller has already generated the document and holds no running
+        turn or worker. The old session is flushed and left intact (resumable);
+        the new session records it as ``parent_session_id`` and restores the
+        document as its opening conversation.
+        """
+        # 1) Final durable flush of the old session while its agent/recorder are
+        #    still live and bound to the old session id.
+        await self._save_session_history_async()
+        await self._save_session_async()
+
+        # 2) Create the new session record first so the lineage notice can name it.
+        new_record = self.store.create(
+            self.project_path,
+            self.mode,
+            dict(self.session.config),
+            parent_session_id=self.session.session_id,
+        )
+
+        # 3) Lineage in the old journal: a trailing context message, then an epoch
+        #    boundary so the old session's replay shows where the work moved.
+        self._session_recorder.record_context_message(
+            Message(
+                role="user",
+                content=[TextBlock(text=messages.HANDOFF_OLD_SESSION_NOTICE.format(title=new_record.title))],
+            ),
+            actor="system",
+        )
+        await asyncio.to_thread(self._session_recorder.start_epoch, "handoff")
+
+        # 4) Tear down the old agent generation before any session object rebinds,
+        #    so nothing keeps writing into the old journal through it.
+        await self._cleanup_agent_generation()
+
+        # 5) Stop services bound to the old session.
+        if self._share_server is not None:
+            await self._stop_share_server()
+        if self._usage_sink is not None:
+            await self._usage_sink.aclose()
+            self._usage_sink = None
+        self._unregister_from_inbox()
+        await self._stop_inbox_socket()
+
+        # 6) Rebind the session-bound surface to the new id.
+        self.session = new_record
+        self._session_recorder = self.store.recorder(new_record.session_id)
+        journal = self.store.journal(new_record.session_id)
+        self.recording_connection_manager = RecordingConnectionManager(
+            self.connection_manager,
+            FileSessionEventStore(journal),
+            session_id=new_record.session_id,
+            artifact_store=FileArtifactStore(journal),
+        )
+        self._recording_primed = False
+        self.control_channel = control_channel_for(
+            new_record.session_id,
+            self.recording_connection_manager.broadcast_event,
+            workspace_id=new_record.workspace_id,
+            thread_id=new_record.thread_id,
+        )
+        self.control_channel.acquire(tui_constants.TUI_CLIENT_ID)
+        self.session_runtime = SessionRuntime(
+            session_id=new_record.session_id,
+            project_path=self.project_path,
+            control=self.control_channel,
+            permission_mode=self.permission_mode,
+            on_notice=lambda text: self._notify_user(text, severity="warning"),
+        )
+        self._register_with_inbox()
+        await self._start_inbox_socket()
+
+        # 7) Reset per-thread state (mirrors _reset_current_thread). The agent is
+        #    already torn down, so agent-side resets come from the fresh build.
+        self._close_sub_agent_inspector()
+        self.session.history = []
+        self.session.compaction = {}
+        self.session.task_list_markdown = ""
+        self._session_file_changes = []
+        self._session_diff_dirty = True
+        self._clear_queued_messages()
+        self._latest_plan = None
+        self._plan_pending = False
+        self._plan_reofferable = False
+        self._plan_decision_active = False
+        self._goal = None
+        self.session.goal = {}
+        self._goal_usage_mark = self._usage_ledger.snapshot()
+        self._scheduled_loop = None
+        self.session.loop = {}
+        self._loop_iteration_active = False
+        self._clear_runtime_output()
+        self._set_plan_actions_visible(False)
+        self._cancel_pending_approval()
+
+        # 8) Seed the new session with the handoff document as its only context,
+        #    both in the journal and in the in-memory projection.
+        handoff_message = Message(
+            role="user",
+            content=[TextBlock(text=build_handoff_context_text(document))],
+        )
+        self.session.history = [handoff_message.to_dict()]
+        self._session_recorder.record_context_message(handoff_message, actor="agent")
+
+        # 9) Fresh agent generation bound to the new session: the restore makes
+        #    the handoff document the agent's entire conversation.
+        config = self.config
+        assert config is not None  # an agent existed, so a config was built
+        self._session_started = False
+        await self._build_agent(config, rebuild=True, restore_transcript=True)
+
+        # 10) Usage persistence on the new journal.
+        usage_sink = SessionUsageSink(
+            self.store.journal(new_record.session_id),
+            self._session_recorder,
+            self._usage_ledger,
+            mode="tui",
+        )
+        self._usage_sink = usage_sink
+        self._usage_ledger.observer = usage_sink
+        await usage_sink.start()
+
+        # 11) Persist the new session and announce the switch.
+        await self._save_session_async()
+        self._refresh_status_dashboard()
+        self._add_conversation_entry(
+            tui_state.ConversationEntry(
+                kind="system",
+                content=messages.HANDOFF_SUCCESS.format(title=new_record.title),
+            )
+        )
+        self._log_status(messages.HANDOFF_SUCCESS.format(title=new_record.title), "ok")
+
     def _add_conversation_entry(self, entry: tui_state.ConversationEntry) -> None:
         self.conversation_entries.append(entry)
         if entry.uuid: