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

connectonion/tui/footer.py

@@ -1,4 +1,12 @@
 """
+Purpose: Simple footer tips display for terminal UI
+LLM-Note:
+  Dependencies: imports from [rich.text.Text] | imported by [tui/chat.py, tui/input.py] | tested by [tests/tui/test_footer.py]
+  Data flow: Footer(tips) → render() → formats tips as dimmed text with separators
+  State/Effects: no state (pure function)
+  Integration: exposes Footer(tips: list[str]) with render() → Text | displays help hints at bottom of TUI
+  Performance: trivial (string join)
+  Errors: none
 Footer - Simple tips display.
 
 Usage:

connectonion/tui/fuzzy.py

@@ -1,4 +1,14 @@
-"""Fuzzy matching utilities."""
+"""
+Purpose: Fuzzy string matching for autocomplete with scoring and highlight positions
+LLM-Note:
+  Dependencies: imports from [rich.text.Text] | imported by [tui/dropdown.py, tui/providers.py, tui/input.py] | tested by [tests/tui/test_fuzzy.py]
+  Data flow: fuzzy_match(query, text) → finds characters from query in text → calculates score based on sequential matches → returns (matched, score, positions) | highlight_match(text, positions) → creates Rich Text with highlighted characters
+  State/Effects: no state (pure functions)
+  Integration: exposes fuzzy_match(query, text) → (bool, int, list[int]), highlight_match(text, positions, highlight_style) → Text | used by autocomplete providers for filtering and highlighting
+  Performance: O(n*m) matching (acceptable for short strings) | early exit if no match
+  Errors: none (handles empty query)
+Fuzzy matching utilities.
+"""
 
 from rich.text import Text
 

connectonion/tui/input.py

@@ -1,7 +1,28 @@
-"""Input - smart input component with triggers and autocomplete.
+"""
+Purpose: Smart terminal input component with trigger-based autocomplete and bracketed paste support
+LLM-Note:
+  Dependencies: imports from [rich.console/live, tui/keys.py, tui/dropdown.py, tui/providers.py, tui/status_bar.py] | imported by [tui/chat.py, cli/commands/] | tested by [tests/tui/test_input.py]
+  Data flow: Input(prompt, triggers, on_submit) → read_input() enables bracketed paste → keys.read_key() captures input → handles triggers (/, @) → providers.search() filters items → Dropdown renders matches → arrow keys navigate → Enter selects/submits → returns final value
+  State/Effects: modifies terminal (enables bracketed paste, raw mode) | restores terminal on exit | maintains buffer state during input session
+  Integration: exposes Input(prompt, placeholder, triggers, status_segments, on_submit) with read_input() → str | triggers dict maps trigger char to Provider | uses keys.py for raw input, dropdown.py for rendering, providers.py for search
+  Performance: live terminal updates via Rich Live | efficient re-render only on buffer/dropdown changes | bracketed paste handles large pastes atomically
+  Errors: restores terminal mode on exception | handles paste detection failures gracefully
+Input - smart input component with triggers and autocomplete.
 
 Clean, minimal design that works on light and dark terminals.
 Inspired by powerlevel10k terminal prompts.
+
+Features:
+- Trigger-based autocomplete (e.g., @ for files, / for commands)
+- Arrow key navigation in dropdown
+- Bracketed paste mode for reliable paste handling
+- Keyboard shortcuts (Shift+Tab, Escape, etc.)
+
+Paste Handling:
+    Uses bracketed paste mode to detect and handle pasted text atomically.
+    This prevents display glitches when pasting (multiple prompt lines,
+    truncated text). The entire paste is received as one event and
+    added to the buffer in a single operation.
 """
 
 import random
@@ -10,7 +31,7 @@ from rich.console import Console, Group
 from rich.text import Text
 from rich.live import Live
 
-from .keys import read_key
+from .keys import read_key, enable_bracketed_paste, disable_bracketed_paste
 from .dropdown import Dropdown
 from .providers import FileProvider
 
@@ -59,6 +80,7 @@ class Input:
         max_visible: int = 8,
         console: Console = None,
         style: str = "modern",
+        on_special_key: callable = None,
     ):
         """
         Args:
@@ -70,6 +92,7 @@ class Input:
             max_visible: Max dropdown items
             console: Rich console
             style: "modern", "minimal", or "classic"
+            on_special_key: Callback for special keys (shift+tab, etc). Return True to consume.
         """
         self.prompt = prompt
         self.triggers = triggers or {}
@@ -79,6 +102,7 @@ class Input:
         self.max_visible = max_visible
         self.console = console or Console()
         self.style = style
+        self.on_special_key = on_special_key
 
         # State
         self.buffer = ""
@@ -192,87 +216,111 @@ class Input:
         global _input_count
         _input_count += 1
 
-        with Live(self._render(), console=self.console, auto_refresh=False) as live:
-            while True:
-                key = read_key()
+        # Enable bracketed paste mode for proper paste detection
+        enable_bracketed_paste()
+
+        try:
+            with Live(self._render(), console=self.console, auto_refresh=False) as live:
+                while True:
+                    key = read_key()
+
+                    # Handle pasted text (from bracketed paste mode)
+                    if key.startswith('paste:'):
+                        pasted_text = key[6:]  # Remove 'paste:' prefix
+                        if self.active_trigger:
+                            self.filter_text += pasted_text
+                            self._update_dropdown()
+                        else:
+                            self.buffer += pasted_text
+                        live.update(self._render(), refresh=True)
+                        continue
+
+                    # Special key callback (shift+tab, etc)
+                    if self.on_special_key and key in ('shift+tab',):
+                        if self.on_special_key(key):
+                            live.update(self._render(), refresh=True)
+                            continue
+
+                    # Enter - submit or accept selection
+                    if key in ('\r', '\n'):
+                        if self.active_trigger:
+                            if not self.dropdown.is_empty:
+                                if self._accept_selection():
+                                    live.update(self._render(), refresh=True)
+                                    continue
+                                live.update(self._render(), refresh=True)
+                            else:
+                                self._exit_autocomplete()
+                                live.update(self._render(), refresh=True)
+                        else:
+                            return self.buffer
 
-                # Enter - submit or accept selection
-                if key in ('\r', '\n'):
-                    if self.active_trigger:
-                        if not self.dropdown.is_empty:
+                    # Tab - accept selection
+                    elif key == '\t':
+                        if self.active_trigger and not self.dropdown.is_empty:
                             if self._accept_selection():
                                 live.update(self._render(), refresh=True)
                                 continue
                             live.update(self._render(), refresh=True)
-                        else:
+
+                    # Escape - cancel autocomplete
+                    elif key == 'esc':
+                        if self.active_trigger:
+                            if self.buffer.endswith(self.active_trigger):
+                                self.buffer = self.buffer[:-1]
                             self._exit_autocomplete()
                             live.update(self._render(), refresh=True)
-                    else:
-                        return self.buffer
 
-                # Tab - accept selection
-                elif key == '\t':
-                    if self.active_trigger and not self.dropdown.is_empty:
-                        if self._accept_selection():
+                    # Ctrl+C / Ctrl+D
+                    elif key == '\x03':
+                        raise KeyboardInterrupt()
+                    elif key == '\x04':
+                        raise EOFError()
+
+                    # Backspace
+                    elif key in ('\x7f', '\x08'):
+                        if self.active_trigger:
+                            if self.filter_text:
+                                self.filter_text = self.filter_text[:-1]
+                                self._update_dropdown()
+                            else:
+                                provider = self.triggers.get(self.active_trigger)
+                                if isinstance(provider, FileProvider) and provider.context:
+                                    provider.back()
+                                    self._update_dropdown()
+                                else:
+                                    if self.buffer.endswith(self.active_trigger):
+                                        self.buffer = self.buffer[:-1]
+                                    self._exit_autocomplete()
                             live.update(self._render(), refresh=True)
-                            continue
+                        elif self.buffer:
+                            self.buffer = self.buffer[:-1]
+                            live.update(self._render(), refresh=True)
+
+                    # Arrow keys
+                    elif key == 'up' and self.active_trigger:
+                        self.dropdown.up()
+                        live.update(self._render(), refresh=True)
+                    elif key == 'down' and self.active_trigger:
+                        self.dropdown.down()
                         live.update(self._render(), refresh=True)
 
-                # Escape - cancel autocomplete
-                elif key == 'esc':
-                    if self.active_trigger:
-                        if self.buffer.endswith(self.active_trigger):
-                            self.buffer = self.buffer[:-1]
-                        self._exit_autocomplete()
+                    # Trigger char
+                    elif key in self.triggers:
+                        self.active_trigger = key
+                        self.filter_text = ""
+                        self.buffer += key
+                        self._update_dropdown()
                         live.update(self._render(), refresh=True)
 
-                # Ctrl+C / Ctrl+D
-                elif key == '\x03':
-                    raise KeyboardInterrupt()
-                elif key == '\x04':
-                    raise EOFError()
-
-                # Backspace
-                elif key in ('\x7f', '\x08'):
-                    if self.active_trigger:
-                        if self.filter_text:
-                            self.filter_text = self.filter_text[:-1]
+                    # Regular input (single char)
+                    elif len(key) == 1 and key.isprintable():
+                        if self.active_trigger:
+                            self.filter_text += key
                             self._update_dropdown()
                         else:
-                            provider = self.triggers.get(self.active_trigger)
-                            if isinstance(provider, FileProvider) and provider.context:
-                                provider.back()
-                                self._update_dropdown()
-                            else:
-                                if self.buffer.endswith(self.active_trigger):
-                                    self.buffer = self.buffer[:-1]
-                                self._exit_autocomplete()
+                            self.buffer += key
                         live.update(self._render(), refresh=True)
-                    elif self.buffer:
-                        self.buffer = self.buffer[:-1]
-                        live.update(self._render(), refresh=True)
-
-                # Arrow keys
-                elif key == 'up' and self.active_trigger:
-                    self.dropdown.up()
-                    live.update(self._render(), refresh=True)
-                elif key == 'down' and self.active_trigger:
-                    self.dropdown.down()
-                    live.update(self._render(), refresh=True)
-
-                # Trigger char
-                elif key in self.triggers:
-                    self.active_trigger = key
-                    self.filter_text = ""
-                    self.buffer += key
-                    self._update_dropdown()
-                    live.update(self._render(), refresh=True)
-
-                # Regular input
-                elif key.isprintable():
-                    if self.active_trigger:
-                        self.filter_text += key
-                        self._update_dropdown()
-                    else:
-                        self.buffer += key
-                    live.update(self._render(), refresh=True)
+        finally:
+            # Always disable bracketed paste mode
+            disable_bracketed_paste()

connectonion/tui/keys.py

@@ -1,10 +1,72 @@
-"""Low-level keyboard input primitives."""
+"""
+Purpose: Low-level keyboard input primitives with bracketed paste and arrow key support
+LLM-Note:
+  Dependencies: imports from [sys, tty, termios, select] | imported by [tui/input.py] | tested by [tests/tui/test_keys.py]
+  Data flow: enable_bracketed_paste() sends ESC[?2004h → read_key() reads from sys.stdin.buffer → detects paste markers (ESC[200~/ESC[201~) → returns Key enum or paste string | disable_bracketed_paste() sends ESC[?2004l → restore_terminal() resets termios
+  State/Effects: modifies terminal mode (raw mode via tty.setraw) | enables/disables bracketed paste mode | stores original termios settings | reads from stdin (blocking)
+  Integration: exposes enable_bracketed_paste(), disable_bracketed_paste(), restore_terminal(), read_key() → Key|str | Key enum for special keys (UP, DOWN, ENTER, BACKSPACE, etc.) | used by Input widget for character-by-character input
+  Performance: blocking read with select() for responsiveness | minimal overhead (direct termios)
+  Errors: restores terminal on exception | paste detection falls back to raw characters if markers missing
+Low-level keyboard input primitives with bracketed paste support.
+
+This module provides raw keyboard input handling for terminal applications,
+including support for:
+- Single character input without Enter
+- Arrow keys and special keys (Shift+Tab, Escape)
+- Bracketed paste mode for reliable paste detection
+
+Bracketed Paste Mode:
+    Modern terminals support bracketed paste mode where pasted text is
+    wrapped in special escape sequences:
+    - ESC[?2004h  - Enable bracketed paste
+    - ESC[200~    - Paste start marker
+    - ESC[201~    - Paste end marker
+    - ESC[?2004l  - Disable bracketed paste
+
+    This allows us to detect paste operations and handle all pasted text
+    atomically, preventing display glitches during paste.
+"""
 
 import sys
 
 
+# Bracketed paste mode sequences
+PASTE_START = '\x1b[200~'  # Sent by terminal when paste begins
+PASTE_END = '\x1b[201~'    # Sent by terminal when paste ends
+
+
+def enable_bracketed_paste():
+    """Enable bracketed paste mode.
+
+    When enabled, the terminal wraps pasted text in special sequences:
+    ESC[200~ ... pasted text ... ESC[201~
+
+    This allows detection of paste operations vs typed input.
+    Must call disable_bracketed_paste() when done to restore terminal.
+    """
+    sys.stdout.write('\x1b[?2004h')
+    sys.stdout.flush()
+
+
+def disable_bracketed_paste():
+    """Disable bracketed paste mode.
+
+    Always call this when done with input to restore normal terminal behavior.
+    Should be called in a finally block to ensure cleanup on errors.
+    """
+    sys.stdout.write('\x1b[?2004l')
+    sys.stdout.flush()
+
+
 def getch() -> str:
-    """Read single character without waiting for Enter."""
+    """Read single character without waiting for Enter.
+
+    Uses raw terminal mode to read one character immediately.
+    Works on Unix (termios) and Windows (msvcrt).
+
+    Returns:
+        Single character string
+    """
     try:
         import termios
         import tty
@@ -12,24 +74,89 @@ def getch() -> str:
         old = termios.tcgetattr(fd)
         tty.setraw(fd)
         ch = sys.stdin.read(1)
-        termios.tcsetattr(fd, termios.TCSADRAIN, old)
+        # Use TCSANOW for immediate restore (prevents paste data loss)
+        termios.tcsetattr(fd, termios.TCSANOW, old)
         return ch
     except ImportError:
         import msvcrt
         return msvcrt.getch().decode('utf-8', errors='ignore')
 
 
+def _read_until_paste_end() -> str:
+    """Read all characters until paste end sequence (ESC[201~).
+
+    Called after paste start (ESC[200~) is detected.
+    Collects all pasted characters until the end marker.
+
+    Returns:
+        The pasted text without the escape sequences
+    """
+    chars = []
+    buffer = ""
+
+    while True:
+        ch = getch()
+        buffer += ch
+
+        # Check for paste end sequence
+        if buffer.endswith(PASTE_END[1:]):  # Already got ESC, check for [201~
+            # Remove the end sequence from collected chars
+            if chars and len(chars) >= 4:
+                # Remove [201~ (4 chars after ESC)
+                return ''.join(chars[:-4])
+            return ''.join(chars)
+
+        # Keep building buffer for sequence detection
+        if ch == '\x1b':
+            buffer = ch
+            chars.append(ch)
+        elif len(buffer) <= len(PASTE_END):
+            chars.append(ch)
+        else:
+            # Not a sequence, add buffer to chars and reset
+            chars.append(ch)
+            buffer = ""
+
+    return ''.join(chars)
+
+
 def read_key() -> str:
-    """Read key with arrow/escape sequence handling.
+    """Read key with arrow/escape sequence and bracketed paste handling.
 
     Returns:
-        Single char, or 'up'/'down'/'left'/'right' for arrows, 'esc' for escape
+        Single char, or special key names:
+        - 'up'/'down'/'left'/'right' for arrows
+        - 'shift+tab' for Shift+Tab
+        - 'esc' for escape
+        - Multi-char string for pasted text (with 'paste:' prefix)
     """
     ch = getch()
+
+    # Handle escape sequences
     if ch == '\x1b':
         ch2 = getch()
         if ch2 == '[':
             ch3 = getch()
-            return {'A': 'up', 'B': 'down', 'C': 'right', 'D': 'left'}.get(ch3, 'esc')
+
+            # Shift+Tab is ESC [ Z
+            if ch3 == 'Z':
+                return 'shift+tab'
+
+            # Arrow keys
+            if ch3 in 'ABCD':
+                return {'A': 'up', 'B': 'down', 'C': 'right', 'D': 'left'}[ch3]
+
+            # Bracketed paste start: ESC [ 2 0 0 ~
+            if ch3 == '2':
+                ch4 = getch()
+                ch5 = getch()
+                ch6 = getch()
+                if ch4 == '0' and ch5 == '0' and ch6 == '~':
+                    # Paste start detected - read until paste end
+                    pasted = _read_until_paste_end()
+                    return 'paste:' + pasted
+
+            return 'esc'
         return 'esc'
+
     return ch

connectonion/tui/providers.py

@@ -1,4 +1,14 @@
-"""Providers for CommandPalette and Input autocomplete."""
+"""
+Purpose: Autocomplete providers for Input widget with fuzzy search and file/command completion
+LLM-Note:
+  Dependencies: imports from [pathlib, typing.Protocol, tui/fuzzy.py, tui/dropdown.py] | imported by [tui/input.py, tui/chat.py] | tested by [tests/tui/test_providers.py]
+  Data flow: Provider.search(query) → fuzzy_match() filters items → returns list[DropdownItem] sorted by score | StaticProvider for fixed lists | FileProvider for filesystem completion | CommandProvider for slash commands
+  State/Effects: FileProvider reads filesystem via Path.glob() | no persistent state
+  Integration: exposes Provider protocol with search(query) → list[DropdownItem|tuple], StaticProvider(items), FileProvider(base_path), CommandProvider(commands) | used by Input triggers dict (e.g., {"/": CommandProvider, "@": FileProvider})
+  Performance: fuzzy matching is fast for typical item counts (<1000) | file provider lazy-loads on search | sorted by score for relevance
+  Errors: FileProvider handles missing directories gracefully | returns empty list if no matches
+Providers for CommandPalette and Input autocomplete.
+"""
 
 from pathlib import Path
 from typing import Protocol, runtime_checkable, Union

connectonion/tui/status_bar.py

@@ -1,4 +1,13 @@
-"""StatusBar - Powerline-style info bar with segments.
+"""
+Purpose: Powerline-style status bar with colored segments for terminal UI
+LLM-Note:
+  Dependencies: imports from [rich.text.Text, dataclasses] | imported by [tui/chat.py, tui/input.py] | tested by [tests/tui/test_status_bar.py]
+  Data flow: StatusBar(segments) → render() → formats segments with powerline arrows → colored backgrounds → returns Rich Text
+  State/Effects: no state (pure function)
+  Integration: exposes StatusBar(segments: list[tuple[icon, label, color]]) with render() → Text | uses powerline characters (requires powerline fonts) | fallback to simple arrows if fonts unavailable
+  Performance: trivial (string formatting)
+  Errors: none (handles missing fonts with fallback)
+StatusBar - Powerline-style info bar with segments.
 
 Creates a professional terminal prompt bar like powerlevel10k.
 """

connectonion/useful_events_handlers/__init__.py

@@ -1,4 +1,12 @@
 """
+Purpose: Event handlers package re-exporting reflect and other lifecycle event handlers
+LLM-Note:
+  Dependencies: imports from [reflect.py] | imported by [__init__.py main package, user code] | tested via handler tests
+  Data flow: re-exports event handler functions/lists
+  State/Effects: no state
+  Integration: exposes reflect event handler (fires after_tools) | used via Agent(on_events=[reflect])
+  Performance: trivial
+  Errors: none
 Useful event handlers for ConnectOnion agents.
 
 Event handlers fire at specific points in the agent lifecycle.

connectonion/useful_events_handlers/reflect.py

@@ -1,4 +1,12 @@
 """
+Purpose: Reflection event handler for generating reasoning after tool execution
+LLM-Note:
+  Dependencies: imports from [core/events.py after_tools, llm_do.py, pathlib, typing] | imported by [useful_events_handlers/__init__.py, user code] | tested by [tests/events/test_reflect.py]
+  Data flow: fires after_tools event → _compress_messages() truncates tool results to 150 chars → llm_do generates reflection using reflect.md prompt → adds reflection as user message to session → LLM sees reflection in next iteration
+  State/Effects: modifies agent.current_session['messages'] by appending user reflection message | calls llm_do (costs tokens) | no persistent state
+  Integration: exposes reflect event handler (use via on_events=[reflect]) | uses after_tools (not after_each_tool) to fire ONCE after ALL tools | loads prompt from prompt_files/reflect.md | compresses messages to reduce context size
+  Performance: one LLM call per tool batch (not per tool) | message compression limits token usage | truncates tool results to 150 chars
+  Errors: none (fails silently if llm_do errors to avoid breaking agent execution)
 Reflect event handler - Adds reflection after tool execution.
 
 Fires ONCE after ALL tools in a batch complete (when LLM returns multiple tool_calls).
@@ -16,6 +24,7 @@ Usage:
     agent = Agent("assistant", tools=[search], on_events=[reflect])
 """
 
+import time
 from pathlib import Path
 from typing import TYPE_CHECKING, List, Dict
 from ..core.events import after_tools
@@ -72,12 +81,12 @@ def reflect(agent: 'Agent') -> None:
     """
     trace = agent.current_session['trace'][-1]
 
-    if trace['type'] != 'tool_execution':
+    if trace['type'] != 'tool_result':
         return
 
     user_prompt = agent.current_session.get('user_prompt', '')
-    tool_name = trace['tool_name']
-    tool_args = trace['arguments']
+    tool_name = trace['name']
+    tool_args = trace['args']
     status = trace['status']
 
     conversation = _compress_messages(agent.current_session['messages'])
@@ -110,7 +119,13 @@ Error: {error}"""
 
     agent.logger.print("[dim]/reflecting...[/dim]")
 
+    agent._record_trace({
+        'type': 'thinking',
+        'kind': 'reflect',
+        'content': reasoning,
+    })
+
     agent.current_session['messages'].append({
         'role': 'assistant',
-        'content': f"🤔 {reasoning}"
+        'content': reasoning
     })

connectonion/useful_plugins/__init__.py

@@ -17,5 +17,7 @@ from .shell_approval import shell_approval
 from .gmail_plugin import gmail_plugin
 from .calendar_plugin import calendar_plugin
 from .ui_stream import ui_stream
+from .system_reminder import system_reminder
+from .tool_approval import tool_approval
 
-__all__ = ['re_act', 'eval', 'image_result_formatter', 'shell_approval', 'gmail_plugin', 'calendar_plugin', 'ui_stream']
+__all__ = ['re_act', 'eval', 'image_result_formatter', 'shell_approval', 'gmail_plugin', 'calendar_plugin', 'ui_stream', 'system_reminder', 'tool_approval']

connectonion/useful_plugins/eval.py

@@ -75,9 +75,9 @@ def _summarize_trace(trace: List[Dict]) -> str:
     """Summarize what actions were taken."""
     actions = []
     for entry in trace:
-        if entry['type'] == 'tool_execution':
+        if entry['type'] == 'tool_result':
             status = entry['status']
-            tool = entry['tool_name']
+            tool = entry['name']
             if status == 'success':
                 result = str(entry.get('result', ''))[:100]
                 actions.append(f"- {tool}: {result}")

connectonion/useful_plugins/gmail_plugin.py

@@ -135,14 +135,14 @@ def check_email_approval(agent: 'Agent') -> None:
 def sync_crm_after_send(agent: 'Agent') -> None:
     """Update CRM data after each email send - last_contact, clear next_contact_date."""
     trace = agent.current_session['trace'][-1]
-    if trace['type'] != 'tool_execution':
+    if trace['type'] != 'tool_result':
         return
-    if trace['tool_name'] not in SEND_METHODS:
+    if trace['name'] not in SEND_METHODS:
         return
     if trace['status'] != 'success':
         return
 
-    to = trace['arguments'].get('to', '')
+    to = trace['args'].get('to', '')
     if not to:
         return
 

connectonion/useful_plugins/image_result_formatter.py

@@ -74,12 +74,12 @@ def _format_image_result(agent: 'Agent') -> None:
     """
     trace = agent.current_session['trace'][-1]
 
-    if trace['type'] != 'tool_execution' or trace['status'] != 'success':
+    if trace['type'] != 'tool_result' or trace['status'] != 'success':
         return
 
     result = trace['result']
-    tool_call_id = trace.get('call_id')  # Fixed: trace uses 'call_id' not 'tool_call_id'
-    tool_name = trace.get('tool_name', 'unknown')
+    tool_call_id = trace.get('call_id')
+    tool_name = trace.get('name', 'unknown')
 
     # Check if result contains base64 image
     is_image, mime_type, base64_data = _is_base64_image(result)