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

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

@@ -6,6 +6,81 @@ This project uses GitHub Releases for detailed generated release notes. This fil
 
 ## Unreleased
 
+## 0.35.0 - 2026-09-03
+
+### Added
+
+- Added Google Gemini 3.8 Flash (`gemini-3.8-flash`): 1M-token context, 64K
+  output, vision and function calling, and `low`/`medium`/`high` thinking
+  levels. It omits Google's deprecated temperature parameter and is now the
+  default Google model.
+- **Descriptive session titles.** Sessions now get a natural-language title
+  and a short description generated in the background by the active LLM after
+  substantive turns, while the stable session name keeps its role as the
+  peer-addressing handle. `/retitle` regenerates them on demand, a dedicated
+  Session card in the sidebar shows them, and the header, status dashboard,
+  startup banner, and `sessions` CLI output all display the title.
+- **`kolega-code gateway restart` and auto-restart on update.** The new
+  subcommand restarts an installed gateway service in place (systemd user
+  unit on Linux, launchd agent on macOS). `kolega-code update`, the `/update`
+  TUI command, and the shell installer now restart the gateway automatically
+  when the service is installed, so an update picks up the new build without
+  a manual daemon restart.
+
+### Changed
+
+- OpenRouter catalog refreshed from the live endpoint (2026-09-03 snapshot):
+  277 tool-capable models (20 featured), adding `google/gemini-3.8-flash` and
+  the `meta/muse-spark-1.3` pair, with featured order re-ranked by the latest
+  weekly token volume.
+
+## 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.35.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kolega-code
-Version: 0.33.0
+Version: 0.35.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.35.0}/kolega_code/__init__.py

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

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

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

{kolega_code-0.33.0 → kolega_code-0.35.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.35.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.35.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.35.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.35.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.35.0/kolega_code/agent/session_metadata.py

@@ -0,0 +1,165 @@
+"""Generate descriptive session title and description via the active LLM."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import re
+from dataclasses import dataclass
+from typing import Any, List, Optional, Sequence
+
+from kolega_code.gateway.redaction import scrub
+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
+
+logger = logging.getLogger(__name__)
+
+SESSION_METADATA_MIN_MESSAGES = 2
+SESSION_METADATA_MAX_TOKENS = 256
+SESSION_METADATA_HEAD_CHARS = 2000
+SESSION_METADATA_TAIL_CHARS = 6000
+
+TITLE_MAX_CHARS = 60
+DESCRIPTION_MAX_CHARS = 200
+
+SESSION_METADATA_SYSTEM_PROMPT = """\
+You are an assistant that summarizes developer coding sessions.
+Analyze the provided conversation transcript and generate:
+1. title: A concise, descriptive title in Natural Title Case (e.g. "Fix Authentication Middleware", "Add PostgreSQL Connection Pool", "Investigate Bug 662"). Maximum 60 characters. No surrounding quotes or Markdown formatting.
+2. description: A clear 1 to 2 sentence summary of what the session is working on, goals, and key progress or findings so far. Maximum 200 characters.
+
+Respond ONLY with valid JSON in this exact structure:
+{
+  "title": "Natural Title Case Title",
+  "description": "One or two sentences describing the session."
+}
+"""
+
+
+@dataclass(frozen=True)
+class SessionMetadata:
+    """The generated descriptive metadata for a session."""
+
+    title: str
+    description: str
+
+
+class SessionMetadataCancelledError(Exception):
+    """Raised when metadata generation is cancelled."""
+
+
+def _truncate_transcript(transcript: str) -> str:
+    """Bound the transcript sent to the metadata generator."""
+    total_budget = SESSION_METADATA_HEAD_CHARS + SESSION_METADATA_TAIL_CHARS
+    if len(transcript) <= total_budget:
+        return transcript
+    head = transcript[:SESSION_METADATA_HEAD_CHARS]
+    tail = transcript[-SESSION_METADATA_TAIL_CHARS:]
+    return f"{head}\n\n[... middle conversation omitted ...]\n\n{tail}"
+
+
+def parse_session_metadata_json(raw_text: str) -> Optional[SessionMetadata]:
+    """Parse and sanitize the JSON returned by the model."""
+    text = raw_text.strip()
+    if not text:
+        return None
+
+    # Strip code fences if present
+    fence_match = re.search(r"```(?:json)?\s*([\s\S]*?)\s*```", text)
+    if fence_match:
+        text = fence_match.group(1).strip()
+
+    data: Optional[dict[str, Any]] = None
+    try:
+        parsed = json.loads(text)
+        if isinstance(parsed, dict):
+            data = parsed
+    except Exception:
+        # Fallback regex extraction for title and description
+        title_match = re.search(r'"title"\s*:\s*"([^"]+)"', text)
+        desc_match = re.search(r'"description"\s*:\s*"([^"]+)"', text)
+        if title_match:
+            data = {
+                "title": title_match.group(1),
+                "description": desc_match.group(1) if desc_match else "",
+            }
+
+    if not data or not isinstance(data.get("title"), str):
+        return None
+
+    raw_title = data["title"].strip().strip("\"'")
+    # Clean control characters and normalize spaces
+    cleaned_title = " ".join(raw_title.split())
+    if not cleaned_title:
+        return None
+
+    if len(cleaned_title) > TITLE_MAX_CHARS:
+        cleaned_title = cleaned_title[:TITLE_MAX_CHARS].rstrip()
+
+    raw_description = str(data.get("description") or "").strip()
+    cleaned_description = " ".join(raw_description.split())
+    if len(cleaned_description) > DESCRIPTION_MAX_CHARS:
+        cleaned_description = cleaned_description[:DESCRIPTION_MAX_CHARS].rstrip()
+
+    return SessionMetadata(title=cleaned_title, description=cleaned_description)
+
+
+async def generate_session_metadata(
+    messages: List[Message],
+    *,
+    llm: Any,
+    model: str,
+    temperature: float = 0.2,
+    cancel_event: Optional[asyncio.Event] = None,
+    secret_values: Sequence[str] = (),
+) -> Optional[SessionMetadata]:
+    """Summarize ``messages`` into a title and description via the active LLM.
+
+    Returns ``None`` if generation fails or is cancelled. Never raises.
+    """
+    if len(messages) < SESSION_METADATA_MIN_MESSAGES:
+        return None
+
+    if cancel_event is None:
+        cancel_event = asyncio.Event()
+
+    try:
+        stripped = replace_image_blocks_with_placeholders(list(messages), model)
+        transcript = render_transcript(stripped)
+        bounded_transcript = _truncate_transcript(transcript)
+        scrubbed_transcript = scrub(bounded_transcript, secret_values)
+
+        user_content = f"Conversation transcript:\n\n{scrubbed_transcript}"
+        request_messages = MessageHistory([Message(role="user", content=[TextBlock(text=user_content)])])
+        system_message = Message(role="system", content=[TextBlock(text=SESSION_METADATA_SYSTEM_PROMPT)])
+
+        if cancel_event.is_set():
+            return None
+
+        with llm_call_origin(helper_origin("session_metadata")):
+            stream_cm = await llm.stream(
+                messages=request_messages,
+                system=system_message,
+                temperature=temperature,
+                model=model,
+                max_completion_tokens=SESSION_METADATA_MAX_TOKENS,
+                thinking=None,
+            )
+            async with stream_cm as stream:
+                async for _event in stream:
+                    if cancel_event.is_set():
+                        return None
+
+            if cancel_event.is_set():
+                return None
+
+            response = await stream.get_final_message()
+            raw_output = response.get_text_content()
+            return parse_session_metadata_json(raw_output)
+    except Exception as exc:
+        logger.warning("Failed to generate session metadata: %s", exc)
+        return None