connectonion 0.6.2__py3-none-any.whl → 0.6.3__py3-none-any.whl

connectonion/__init__.py

@@ -1,13 +1,23 @@
-"""ConnectOnion - A simple agent framework with behavior tracking."""
+"""
+Purpose: Main package entry point exposing public API for ConnectOnion framework
+LLM-Note:
+  Dependencies: imports from [core/, logger.py, llm_do.py, transcribe.py, prompts.py, debug/, useful_tools/, network/, address.py] | imported by [user code, tests/, examples/] | no direct tests (integration tests import from here)
+  Data flow: loads .env from cwd via load_dotenv() → exports all public API symbols → user imports `from connectonion import Agent, llm_do, ...`
+  State/Effects: auto-loads .env file from current working directory (NOT module directory) at import time
+  Integration: exposes complete public API: Agent, LLM, Logger, create_tool_from_function, llm_do, transcribe, xray, event decorators, built-in tools, networking functions | __all__ defines explicit public exports
+  Performance: .env loading happens once at first import (dotenv caches)
+  Errors: none (import errors bubble from submodules)
+ConnectOnion - A simple agent framework with behavior tracking.
+"""
 
-__version__ = "0.6.2"
+__version__ = "0.6.3"
 
 # Auto-load .env files for the entire framework
 from dotenv import load_dotenv
 from pathlib import Path as _Path
 
-# Load from current working directory (where user runs their script)
-# NOT from the module's location (framework directory)
+# SDK only loads from current working directory (where user runs their script)
+# CLI commands (co ai, co browser, etc.) handle global fallback separately
 load_dotenv(_Path.cwd() / ".env")
 
 from .core import Agent, LLM, create_tool_from_function
@@ -27,12 +37,20 @@ from .llm_do import llm_do
 from .transcribe import transcribe
 from .prompts import load_system_prompt
 from .debug import xray, auto_debug_exception, replay, xray_replay
-from .useful_tools import send_email, get_emails, mark_read, mark_unread, Memory, Gmail, GoogleCalendar, Outlook, MicrosoftCalendar, WebFetch, Shell, DiffWriter, pick, yes_no, autocomplete, TodoList, SlashCommand
-from .network import connect, RemoteAgent, host, create_app, Connection
+from .useful_tools import (
+    send_email, get_emails, mark_read, mark_unread,
+    Memory, Gmail, GoogleCalendar, Outlook, MicrosoftCalendar,
+    WebFetch, Shell, bash, DiffWriter, MODE_NORMAL, MODE_AUTO, MODE_PLAN,
+    pick, yes_no, autocomplete, TodoList, SlashCommand,
+    # Claude Code-style file tools
+    read_file, edit, multi_edit, glob, grep, write, FileWriter,
+)
+from .network import connect, RemoteAgent, Response, host, create_app, IO
 from .network import relay, announce
 from . import address
 
 __all__ = [
+    # Core
     "Agent",
     "LLM",
     "Logger",
@@ -43,10 +61,13 @@ __all__ = [
     "xray",
     "replay",
     "xray_replay",
+    "auto_debug_exception",
+    # Email tools
     "send_email",
     "get_emails",
     "mark_read",
     "mark_unread",
+    # Class-based tools
     "Memory",
     "Gmail",
     "GoogleCalendar",
@@ -54,21 +75,37 @@ __all__ = [
     "MicrosoftCalendar",
     "WebFetch",
     "Shell",
+    "bash",
     "DiffWriter",
+    "MODE_NORMAL",
+    "MODE_AUTO",
+    "MODE_PLAN",
+    # TUI helpers
     "pick",
     "yes_no",
     "autocomplete",
+    # Task management
     "TodoList",
     "SlashCommand",
-    "auto_debug_exception",
+    # Claude Code-style file tools
+    "read_file",
+    "edit",
+    "multi_edit",
+    "glob",
+    "grep",
+    "write",
+    "FileWriter",
+    # Networking
     "connect",
     "RemoteAgent",
+    "Response",
     "host",
     "create_app",
-    "Connection",
+    "IO",
     "relay",
     "announce",
     "address",
+    # Event decorators
     "after_user_input",
     "before_llm",
     "after_llm",
@@ -77,5 +114,5 @@ __all__ = [
     "after_each_tool",
     "after_tools",
     "on_error",
-    "on_complete"
+    "on_complete",
 ]

connectonion/cli/__init__.py

@@ -1,3 +1,13 @@
-"""ConnectOnion CLI module."""
+"""
+Purpose: CLI module entry point with version metadata
+LLM-Note:
+  Dependencies: none | imported by [cli/main.py, setup.py] | no direct tests
+  Data flow: pure metadata (version string)
+  State/Effects: no state
+  Integration: exposes __version__ for CLI about/version commands
+  Performance: trivial
+  Errors: none
+ConnectOnion CLI module.
+"""
 
 __version__ = "0.0.1b5"

connectonion/cli/browser_agent/__init__.py

@@ -1,4 +1,14 @@
-"""Browser agent module for ConnectOnion CLI."""
+"""
+Purpose: Browser agent module exports for CLI browser automation
+LLM-Note:
+  Dependencies: imports from [browser.py] | imported by [cli/commands/browser_commands.py] | no direct tests
+  Data flow: re-exports execute_browser_command and BrowserAutomation
+  State/Effects: no state
+  Integration: exposes execute_browser_command(), BrowserAutomation class for `co browser` command
+  Performance: trivial
+  Errors: none
+Browser agent module for ConnectOnion CLI.
+"""
 
 from .browser import execute_browser_command, BrowserAutomation
 

connectonion/cli/browser_agent/browser.py

@@ -1,4 +1,13 @@
-"""Browser Agent for CLI - Natural language browser automation.
+"""
+Purpose: Natural language browser automation via Playwright with Chrome profile support
+LLM-Note:
+  Dependencies: imports from [playwright.sync_api, connectonion Agent/llm_do, cli/browser_agent/element_finder, pydantic, pathlib, dotenv] | imported by [cli/commands/browser_commands.py] | tested by [tests/cli/test_browser_agent.py]
+  Data flow: BrowserAutomation() initializes Playwright → copies Chrome profile to .browser_agent_profile/ → opens browser with context → provides tools (navigate, find_element, fill_form, screenshot, scroll, wait_for_login) → Agent uses these tools via natural language → element_finder.py uses vision LLM to locate elements | screenshots saved to .tmp/ directory
+  State/Effects: maintains browser/page/context state | copies Chrome profile on first run | writes screenshots to .tmp/{timestamp}.png | modifies form_data dict for form fills | auto-closes browser in __del__
+  Integration: exposes BrowserAutomation(use_chrome_profile, headless) with methods: navigate(url), find_element(description), fill_form(field_values), screenshot(viewport), scroll(direction, description), click(description), type_text(description, text), wait_for_login(seconds) | FormField Pydantic model for form parsing | used by `co browser` CLI command
+  Performance: headless by default (faster) | Chrome profile copy (one-time, slow first run) | vision model for element finding (slower but accurate) | screenshots base64-encoded for LLM analysis
+  Errors: returns error string if Playwright not installed | returns "Browser already open" if reinitializing | element not found returns descriptive error | Chrome must be closed when using profile
+Browser Agent for CLI - Natural language browser automation.
 
 This module provides a browser automation agent that understands natural language
 requests for browser operations via the ConnectOnion CLI.
@@ -96,8 +105,9 @@ class BrowserAutomation:
         self.playwright = sync_playwright().start()
 
         if self.use_chrome_profile:
-            # Use Chromium with Chrome profile copy
-            chromium_profile = Path.cwd() / "chromium_automation_profile"
+            # Use Chromium with Chrome profile copy in global ~/.co/ folder
+            chromium_profile = Path.home() / ".co" / "browser_profile"
+            chromium_profile.parent.mkdir(parents=True, exist_ok=True)
 
             if not chromium_profile.exists():
                 import shutil

connectonion/cli/browser_agent/element_finder.py

@@ -1,4 +1,12 @@
 """
+Purpose: Find interactive elements on web pages using natural language descriptions via vision LLM
+LLM-Note:
+  Dependencies: imports from [playwright.sync_api Page, connectonion llm_do, pydantic, pathlib] | imported by [cli/browser_agent/browser.py] | tested by [tests/cli/test_element_finder.py]
+  Data flow: extract_elements(page) → evaluates extract_elements.js → injects data-browser-agent-id on all interactive elements → returns list[InteractiveElement] with locators | find_element(page, description, elements) → formats elements for LLM → calls llm_do with vision model + screenshot → LLM selects matching element by index → returns InteractiveElement with pre-built locator
+  State/Effects: modifies DOM by injecting data-browser-agent-id attributes (temporary, removed on navigation) | takes screenshot for vision analysis | no persistent state
+  Integration: exposes extract_elements(page) → list[InteractiveElement], find_element(page, description, elements, screenshot) → InteractiveElement|None, highlight_element(page, element) for visual feedback | InteractiveElement model has tag, text, role, aria_label, placeholder, x, y, width, height, locator | ElementMatch model for LLM response
+  Performance: JavaScript extraction is fast | LLM matching uses vision model (slower) | limits to 150 elements for context window | pre-built locators (no retry needed)
+  Errors: returns None if no matching element found | raises if Playwright page not available | element may be stale if page navigates
 Element Finder - Find interactive elements by natural language description.
 
 Inspired by browser-use (https://github.com/browser-use/browser-use).

connectonion/cli/browser_agent/highlight_screenshot.py

@@ -1,4 +1,12 @@
 """
+Purpose: Draw bounding boxes and element indices on screenshots for visual element identification
+LLM-Note:
+  Dependencies: imports from [PIL Image/ImageDraw/ImageFont, pathlib, cli/browser_agent/element_finder] | imported by [cli/browser_agent/browser.py] | tested by [tests/cli/test_highlight.py]
+  Data flow: highlight_screenshot(screenshot_path, elements) → loads PNG image → iterates InteractiveElement list → draws dashed rectangle around each element → draws index label with colored background → saves highlighted image | highlight_current_page(page) → takes screenshot → extracts elements → calls highlight_screenshot() → returns path
+  State/Effects: reads screenshot PNG from disk | writes highlighted PNG to disk | deletes raw screenshot after highlighting | creates screenshots/ directory if missing
+  Integration: exposes highlight_screenshot(screenshot_path, elements, output_path) → str, highlight_current_page(page, output_path) → str | ELEMENT_COLORS dict maps tag names to hex colors | get_font(size) → ImageFont for cross-platform text rendering | draw_dashed_rect() utility for styled boxes
+  Performance: PIL image processing (fast for typical webpage screenshots) | processes all elements in one pass | minimal memory (single image in RAM)
+  Errors: skips elements with width/height < 5px (too small to render) | falls back to default font if system fonts unavailable | raises if PIL/Pillow not installed
 Screenshot highlighting - draw bounding boxes and indices on screenshots.
 Inspired by browser-use's python_highlights.py approach.
 """
@@ -6,7 +14,7 @@ Inspired by browser-use's python_highlights.py approach.
 from PIL import Image, ImageDraw, ImageFont
 from pathlib import Path
 from typing import List
-import element_finder
+from . import element_finder
 
 # Color scheme for different element types
 ELEMENT_COLORS = {

connectonion/cli/browser_agent/scroll.py

@@ -1,4 +1,12 @@
 """
+Purpose: Intelligent page scrolling with AI strategy selection and fallback mechanisms
+LLM-Note:
+  Dependencies: imports from [playwright Page, connectonion llm_do, pydantic, pathlib, PIL Image] | imported by [cli/browser_agent/browser.py] | tested by [tests/cli/test_scroll.py]
+  Data flow: scroll(page, take_screenshot, times, description) → takes before screenshot → tries strategies: AI-generated JS → element scroll → page scroll → takes after screenshot → compares via _screenshots_different() → returns on first successful change | _ai_scroll() extracts scrollable elements + HTML → llm_do generates ScrollStrategy → executes JS | fallbacks use simpler JS approaches
+  State/Effects: writes before/after screenshots to screenshots/ directory | executes JavaScript on page (modifies scrollTop or window.scrollY) | no persistent state
+  Integration: exposes scroll(page, take_screenshot, times, description) → str | ScrollStrategy Pydantic model with method, selector, javascript, explanation | uses scroll_strategy.md prompt for LLM | verifies success via pixel difference (>1% change threshold)
+  Performance: tries AI first (slower but accurate) → falls back to faster heuristics | 0.5-1s sleep between scrolls for content loading | PIL pixel comparison (fast for typical screenshots)
+  Errors: returns "Browser not open" if page None | returns "All scroll strategies failed" if no strategy changes content | prints strategy attempts for debugging | catches exceptions per strategy and continues
 Unified scroll module - AI-powered with fallback strategies.
 
 Usage:

connectonion/cli/co_ai/__init__.py

@@ -0,0 +1,6 @@
+"""co-ai: AI coding agent built with ConnectOnion framework."""
+
+from connectonion.cli.co_ai.agent import create_coding_agent
+
+__version__ = "0.1.0"
+__all__ = ["create_coding_agent"]

connectonion/cli/co_ai/agent.py

@@ -0,0 +1,87 @@
+"""Main coding agent module."""
+
+from pathlib import Path
+
+from .context import load_project_context
+from .prompts.assembler import assemble_prompt
+from .tools import (
+    glob, grep, edit, read_file, task,
+    enter_plan_mode, exit_plan_mode, write_plan,
+    ask_user,
+    run_background, task_output, kill_task,
+    load_guide,
+)
+from .skills import skill
+from .plugins import reminder_plugin
+from connectonion import Agent, bash, after_user_input, FileWriter, MODE_AUTO, MODE_NORMAL, TodoList
+from connectonion.useful_plugins import re_act, eval
+
+
+PROMPTS_DIR = Path(__file__).parent / "prompts"
+
+
+@after_user_input
+def _sync_tool_io(agent) -> None:
+    io = getattr(agent, "io", None) or getattr(agent, "connection", None)
+    if not io:
+        return
+    # ToolRegistry does not expose instances publicly; use best-effort access.
+    instances = getattr(agent.tools, "_instances", {})
+    for instance in instances.values():
+        if hasattr(instance, "io"):
+            instance.io = io
+
+
+def create_coding_agent(
+    model: str = "co/claude-opus-4-5",
+    max_iterations: int = 20,
+    auto_approve: bool = False,
+    web_mode: bool = False,
+) -> Agent:
+    writer = FileWriter(mode=MODE_AUTO if auto_approve else MODE_NORMAL)
+    todo = TodoList()
+
+    tools = [
+        glob,
+        grep,
+        read_file,
+        edit,
+        writer,
+        bash,
+        task,
+        enter_plan_mode,
+        exit_plan_mode,
+        write_plan,
+        todo,
+        skill,
+        run_background,
+        task_output,
+        kill_task,
+        load_guide,
+        ask_user,
+    ]
+
+    base_prompt = assemble_prompt(
+        prompts_dir=str(PROMPTS_DIR),
+        tools=tools,
+    )
+
+    project_context = load_project_context()
+    system_prompt = base_prompt
+    if project_context:
+        system_prompt += f"\n\n---\n\n{project_context}"
+
+    plugins = [re_act, eval, reminder_plugin]
+
+    agent = Agent(
+        name="oo",
+        tools=tools,
+        plugins=plugins,
+        on_events=[_sync_tool_io],
+        system_prompt=system_prompt,
+        model=model,
+        max_iterations=max_iterations,
+    )
+
+    agent.writer = writer
+    return agent

connectonion/cli/co_ai/agents/__init__.py

@@ -0,0 +1,5 @@
+"""Sub-agents for OO."""
+
+from connectonion.cli.co_ai.agents.registry import SUBAGENTS, get_subagent
+
+__all__ = ["SUBAGENTS", "get_subagent"]

connectonion/cli/co_ai/agents/registry.py

@@ -0,0 +1,57 @@
+"""Sub-agent registry and factory."""
+
+from typing import Dict, Any, Optional
+from connectonion import Agent
+
+from connectonion.cli.co_ai.tools import glob, grep, read_file
+
+
+# Sub-agent configurations
+SUBAGENTS: Dict[str, Dict[str, Any]] = {
+    "explore": {
+        "description": "Fast agent for exploring codebases. Find files, search code, answer questions about structure.",
+        "tools": [glob, grep, read_file],
+        "model": "co/gemini-2.5-flash",  # Fast model for exploration
+        "max_iterations": 15,
+    },
+    "plan": {
+        "description": "Design implementation plans. Analyze architecture, identify files to change, plan steps.",
+        "tools": [glob, grep, read_file],
+        "model": "co/gemini-2.5-pro",  # Smarter model for planning
+        "max_iterations": 10,
+    },
+}
+
+
+def get_subagent(agent_type: str) -> Optional[Agent]:
+    """
+    Create a sub-agent instance by type.
+
+    Args:
+        agent_type: Type of sub-agent ("explore", "plan", etc.)
+
+    Returns:
+        Configured Agent instance or None if type not found
+    """
+    if agent_type not in SUBAGENTS:
+        return None
+
+    config = SUBAGENTS[agent_type]
+
+    # Load prompt from co_ai/prompts/agents/
+    from pathlib import Path
+    prompt_path = Path(__file__).parent.parent / "prompts" / "agents" / f"{agent_type}.md"
+
+    if prompt_path.exists():
+        system_prompt = prompt_path.read_text(encoding="utf-8")
+    else:
+        system_prompt = f"You are an {agent_type} agent. {config['description']}"
+
+    return Agent(
+        name=f"oo-{agent_type}",
+        tools=config["tools"],
+        plugins=[],
+        system_prompt=system_prompt,
+        model=config["model"],
+        max_iterations=config["max_iterations"],
+    )

connectonion/cli/co_ai/commands/__init__.py

@@ -0,0 +1,45 @@
+"""Built-in commands for OO CLI."""
+
+from connectonion.cli.co_ai.commands.init import cmd_init
+from connectonion.cli.co_ai.commands.help import cmd_help
+from connectonion.cli.co_ai.commands.cost import cmd_cost, set_agent as set_cost_agent
+from connectonion.cli.co_ai.commands.compact import cmd_compact, set_agent as set_compact_agent
+from connectonion.cli.co_ai.commands.tasks import cmd_tasks
+from connectonion.cli.co_ai.commands.export import cmd_export, set_agent as set_export_agent
+from connectonion.cli.co_ai.commands.sessions import cmd_sessions, cmd_new, cmd_resume, set_agent as set_sessions_agent
+from connectonion.cli.co_ai.commands.undo import cmd_undo, cmd_redo, set_agent as set_undo_agent
+
+BUILTIN_COMMANDS = {
+    "init": cmd_init,
+    "help": cmd_help,
+    "cost": cmd_cost,
+    "compact": cmd_compact,
+    "tasks": cmd_tasks,
+    "export": cmd_export,
+    "sessions": cmd_sessions,
+    "new": cmd_new,
+    "resume": cmd_resume,
+    "undo": cmd_undo,
+    "redo": cmd_redo,
+}
+
+
+def set_agent_for_commands(agent):
+    """Set agent reference for commands that need it."""
+    set_cost_agent(agent)
+    set_compact_agent(agent)
+    set_export_agent(agent)
+    set_sessions_agent(agent)
+    set_undo_agent(agent)
+
+
+__all__ = [
+    "BUILTIN_COMMANDS",
+    "cmd_init",
+    "cmd_help",
+    "cmd_cost",
+    "cmd_compact",
+    "cmd_tasks",
+    "cmd_export",
+    "set_agent_for_commands",
+]

connectonion/cli/co_ai/commands/compact.py

@@ -0,0 +1,173 @@
+"""Compact command for compressing conversation context using LLM summarization."""
+
+from pathlib import Path
+from rich.console import Console
+from rich.panel import Panel
+from connectonion import llm_do
+
+console = Console()
+
+# Module-level storage for agent reference
+_current_agent = None
+
+# Summarization prompt
+SUMMARIZATION_PROMPT = Path(__file__).parent.parent / "prompts" / "summarization.md"
+
+
+def set_agent(agent):
+    """Set the current agent for compact operation."""
+    global _current_agent
+    _current_agent = agent
+
+
+def _format_messages_for_summary(messages: list) -> str:
+    """Format messages into a readable format for summarization."""
+    formatted = []
+    for msg in messages:
+        role = msg.get('role', 'unknown')
+        content = msg.get('content', '')
+
+        # Handle tool_calls in assistant messages
+        if role == 'assistant' and 'tool_calls' in msg:
+            tool_calls = msg.get('tool_calls', [])
+            tools_str = ", ".join(tc.get('function', {}).get('name', 'unknown') for tc in tool_calls)
+            formatted.append(f"[assistant] Called tools: {tools_str}")
+            if content:
+                formatted.append(f"[assistant] {content[:500]}...")
+        elif role == 'tool':
+            # Truncate long tool results
+            tool_name = msg.get('name', 'unknown')
+            result = content[:200] + "..." if len(content) > 200 else content
+            formatted.append(f"[tool:{tool_name}] {result}")
+        elif role == 'system':
+            # Keep system messages brief
+            formatted.append(f"[system] {content[:300]}...")
+        else:
+            formatted.append(f"[{role}] {content}")
+
+    return "\n\n".join(formatted)
+
+
+def _create_summary_message(summary: str) -> dict:
+    """Create a summary message to replace old context."""
+    return {
+        'role': 'user',
+        'content': f"""## Previous Conversation Summary
+
+{summary}
+
+---
+*The conversation continues below. Use the summary above for context.*"""
+    }
+
+
+def cmd_compact(args: str = "") -> str:
+    """
+    Compress conversation history using LLM summarization.
+
+    This creates an intelligent summary of older messages while preserving:
+    - User's explicit requests and intents
+    - Key technical decisions and code patterns
+    - File names and important code snippets
+    - Errors encountered and how they were fixed
+    - Recent messages (last 5)
+
+    Use when context usage is high (>70%).
+    """
+    if _current_agent is None:
+        console.print("[yellow]No agent session active.[/]")
+        return "No session"
+
+    agent = _current_agent
+
+    # Check if we have a session
+    if not hasattr(agent, 'current_session') or not agent.current_session:
+        console.print("[yellow]No conversation history to compact.[/]")
+        return "No history"
+
+    messages = agent.current_session.get('messages', [])
+    if len(messages) < 8:
+        console.print("[yellow]Conversation too short to compact (< 8 messages).[/]")
+        return "Too short"
+
+    # Get context usage before
+    context_before = getattr(agent, 'context_percent', 0)
+
+    # Separate messages
+    system_msg = messages[0] if messages and messages[0].get('role') == 'system' else None
+    recent_count = 5
+    recent_msgs = messages[-recent_count:]
+    old_msgs = messages[1:-recent_count] if system_msg else messages[:-recent_count]
+
+    if len(old_msgs) < 3:
+        console.print("[yellow]Not enough old messages to compact.[/]")
+        return "Nothing to compact"
+
+    console.print("[cyan]Summarizing conversation...[/]")
+
+    # Load summarization prompt
+    summarization_instructions = ""
+    if SUMMARIZATION_PROMPT.exists():
+        summarization_instructions = SUMMARIZATION_PROMPT.read_text(encoding="utf-8")
+
+    # Format messages for summarization
+    conversation_text = _format_messages_for_summary(old_msgs)
+
+    # Use LLM to create intelligent summary
+    summary_prompt = f"""{summarization_instructions}
+
+## Conversation to Summarize
+
+{conversation_text}
+
+---
+
+Create a concise but complete summary following the structure above. Focus on:
+1. What the user wanted to accomplish
+2. Key files and code that were discussed or modified
+3. Any errors and how they were fixed
+4. Important decisions made
+
+Keep the summary under 1000 words but preserve all critical technical details."""
+
+    summary = llm_do(
+        summary_prompt,
+        model="co/gemini-2.5-flash",  # Fast model for summarization
+    )
+
+    # Create compacted messages
+    summary_message = _create_summary_message(summary)
+
+    new_messages = []
+    if system_msg:
+        new_messages.append(system_msg)
+    new_messages.append(summary_message)
+    new_messages.extend(recent_msgs)
+
+    # Update agent session
+    agent.current_session['messages'] = new_messages
+
+    # Calculate savings
+    old_count = len(messages)
+    new_count = len(new_messages)
+    saved = old_count - new_count
+
+    # Display result
+    console.print(Panel(
+        f"[green]✓ Conversation compacted[/]\n\n"
+        f"Messages: {old_count} → {new_count} ([green]-{saved}[/])\n"
+        f"Context before: {context_before:.0f}%\n\n"
+        f"[dim]Preserved:[/]\n"
+        f"  • System prompt\n"
+        f"  • AI-generated summary of older context\n"
+        f"  • Recent {recent_count} messages\n\n"
+        f"[dim]Summary includes:[/]\n"
+        f"  • User requests and intents\n"
+        f"  • Key files and code patterns\n"
+        f"  • Errors and fixes\n"
+        f"  • Technical decisions",
+        title="📦 Compact",
+        border_style="green"
+    ))
+
+    return f"Compacted: {old_count} → {new_count} messages"