connectonion 0.5.8__py3-none-any.whl

connectonion/useful_tools/shell.py

@@ -0,0 +1,97 @@
+"""
+Purpose: Shell command execution tool for running terminal commands from agent context
+LLM-Note:
+  Dependencies: imports from [subprocess] | imported by [useful_tools/__init__.py] | tested by [tests/unit/test_shell_tool.py]
+  Data flow: Agent calls Shell.run(command) → subprocess.run() executes in shell → captures stdout+stderr → returns combined output string
+  State/Effects: executes shell commands on host system | can modify filesystem, install packages, run programs | uses working directory specified in constructor | no persistent state
+  Integration: exposes Shell class with run(command), run_in_dir(command, directory) | used as agent tool via Agent(tools=[Shell()])
+  Performance: process spawn overhead per command | command execution time varies | no caching
+  Errors: returns error message if command fails | captures stderr in output | no exceptions raised (returns error strings)
+
+Shell tool for executing terminal commands.
+
+Usage:
+    from connectonion import Agent, Shell
+
+    shell = Shell()
+    agent = Agent("coder", tools=[shell])
+
+    # Agent can now use:
+    # - run(command) - Execute shell command, returns output
+    # - run_in_dir(command, directory) - Execute in specific directory
+"""
+
+import subprocess
+
+
+class Shell:
+    """Shell command execution tool."""
+
+    def __init__(self, cwd: str = "."):
+        """Initialize Shell tool.
+
+        Args:
+            cwd: Default working directory
+        """
+        self.cwd = cwd
+
+    def run(self, command: str) -> str:
+        """Execute a shell command, returns output.
+
+        Args:
+            command: Shell command to execute (e.g., "ls -la", "git status")
+
+        Returns:
+            Command output (stdout + stderr)
+        """
+        result = subprocess.run(
+            command,
+            shell=True,
+            capture_output=True,
+            text=True,
+            cwd=self.cwd
+        )
+
+        parts = []
+        if result.stdout:
+            parts.append(result.stdout.rstrip())
+        if result.stderr:
+            parts.append(f"STDERR:\n{result.stderr.rstrip()}")
+        if result.returncode != 0:
+            parts.append(f"\nExit code: {result.returncode}")
+
+        output = "\n".join(parts) if parts else "(no output)"
+        if len(output) > 1000:
+            output = output[:1000] + f"\n... (truncated, {len(output):,} total chars)"
+        return output
+
+    def run_in_dir(self, command: str, directory: str) -> str:
+        """Execute command in a specific directory.
+
+        Args:
+            command: Shell command to execute
+            directory: Directory to run the command in
+
+        Returns:
+            Command output (stdout + stderr)
+        """
+        result = subprocess.run(
+            command,
+            shell=True,
+            capture_output=True,
+            text=True,
+            cwd=directory
+        )
+
+        parts = []
+        if result.stdout:
+            parts.append(result.stdout.rstrip())
+        if result.stderr:
+            parts.append(f"STDERR:\n{result.stderr.rstrip()}")
+        if result.returncode != 0:
+            parts.append(f"\nExit code: {result.returncode}")
+
+        output = "\n".join(parts) if parts else "(no output)"
+        if len(output) > 1000:
+            output = output[:1000] + f"\n... (truncated, {len(output):,} total chars)"
+        return output

connectonion/useful_tools/slash_command.py

@@ -0,0 +1,201 @@
+"""
+Purpose: Load and execute slash commands from markdown files with YAML frontmatter
+LLM-Note:
+  Dependencies: imports from [yaml, pathlib, typing] | imported by [useful_tools/__init__.py] | tested by [tests/unit/test_slash_command.py]
+  Data flow: SlashCommand.load(name) → searches .co/commands/*.md and commands/*.md → parses YAML frontmatter for metadata → extracts prompt body → SlashCommand.filter_tools() filters available tools → returns filtered tool list
+  State/Effects: reads markdown files from filesystem | no persistent state | no network I/O | command files can specify tool restrictions
+  Integration: exposes SlashCommand class with load(name), list_all(), filter_tools(tools) | command format: YAML frontmatter (name, description, tools) + markdown prompt body | used by CLI and agent for custom commands
+  Performance: file I/O per load | YAML parsing is fast | list_all() scans directories once
+  Errors: returns None if command not found | raises ValueError for invalid YAML | no other exceptions
+
+SlashCommand - Load and execute slash commands from markdown files.
+
+Usage:
+    from connectonion import SlashCommand
+
+    # Load command
+    cmd = SlashCommand.load("today")
+
+    # Get prompt and filter tools
+    prompt = cmd.prompt
+    filtered_tools = cmd.filter_tools(all_tools)
+
+    # List all commands
+    commands = SlashCommand.list_all()
+
+Command file format (.co/commands/*.md or commands/*.md):
+---
+name: today
+description: Daily email briefing
+tools:
+  - Gmail.search_emails    # Specific method
+  - WebFetch               # Whole class
+  - my_function            # Standalone function
+---
+Your command prompt here...
+"""
+
+import yaml
+from pathlib import Path
+from typing import Dict, Optional, List
+
+
+class SlashCommand:
+    """Represents a slash command loaded from a markdown file."""
+
+    def __init__(self, name: str, description: str, prompt: str, tools: Optional[List[str]] = None, is_custom: bool = False):
+        """Initialize a SlashCommand.
+
+        Args:
+            name: Command name
+            description: Command description
+            prompt: Command prompt template
+            tools: List of allowed tools (None = all tools allowed)
+            is_custom: Whether this is a user custom command
+        """
+        self.name = name
+        self.description = description
+        self.prompt = prompt
+        self.tools = tools
+        self.is_custom = is_custom
+
+    @classmethod
+    def load(cls, command_name: str) -> Optional["SlashCommand"]:
+        """Load command from .co/commands/ (user) or commands/ (built-in).
+
+        Args:
+            command_name: Name of the command (without .md extension)
+
+        Returns:
+            SlashCommand instance or None if not found
+        """
+        # Check user custom first
+        custom_path = Path(".co/commands") / f"{command_name}.md"
+        if custom_path.exists():
+            return cls._parse_file(custom_path, is_custom=True)
+
+        # Check built-in
+        builtin_path = Path("commands") / f"{command_name}.md"
+        if builtin_path.exists():
+            return cls._parse_file(builtin_path, is_custom=False)
+
+        return None
+
+    @classmethod
+    def _parse_file(cls, filepath: Path, is_custom: bool = False) -> "SlashCommand":
+        """Parse markdown file with YAML frontmatter.
+
+        Args:
+            filepath: Path to .md file
+            is_custom: Whether this is a user custom command
+
+        Returns:
+            SlashCommand instance
+
+        Raises:
+            yaml.YAMLError: If frontmatter is invalid
+            ValueError: If required fields missing
+        """
+        content = filepath.read_text()
+
+        # Split frontmatter and prompt
+        if not content.startswith("---"):
+            raise ValueError(f"Command file {filepath} missing YAML frontmatter")
+
+        parts = content.split("---", 2)
+        if len(parts) < 3:
+            raise ValueError(f"Command file {filepath} has malformed frontmatter")
+
+        # Parse YAML (let it raise naturally if invalid)
+        frontmatter = yaml.safe_load(parts[1])
+        prompt = parts[2].strip()
+
+        # Validate required fields
+        if "name" not in frontmatter:
+            raise ValueError(f"Command file {filepath} missing 'name' field")
+        if "description" not in frontmatter:
+            raise ValueError(f"Command file {filepath} missing 'description' field")
+
+        return cls(
+            name=frontmatter["name"],
+            description=frontmatter["description"],
+            prompt=prompt,
+            tools=frontmatter.get("tools"),
+            is_custom=is_custom
+        )
+
+    def filter_tools(self, available_tools: List) -> List:
+        """Filter tools based on allowed list from command file.
+
+        Args:
+            available_tools: List of all available tool instances or functions
+
+        Returns:
+            Filtered list of tools
+
+        Example:
+            tools = ["Gmail.search_emails", "Agent.input"]
+            # Only allows Gmail.search_emails and Agent.input methods
+        """
+        if self.tools is None:
+            return available_tools
+
+        filtered = []
+
+        for tool in available_tools:
+            tool_name = getattr(tool, '__name__', None)
+
+            # Handle class-based tools (have __self__ attribute)
+            if hasattr(tool, '__self__'):
+                class_name = tool.__self__.__class__.__name__
+                method_name = tool.__name__
+                full_name = f"{class_name}.{method_name}"
+
+                # Check if specific method or whole class is allowed
+                if full_name in self.tools or class_name in self.tools:
+                    filtered.append(tool)
+
+            # Handle function-based tools
+            elif tool_name and tool_name in self.tools:
+                filtered.append(tool)
+
+        return filtered
+
+    @classmethod
+    def list_all(cls) -> Dict[str, "SlashCommand"]:
+        """List all available commands (built-in and custom).
+
+        Returns:
+            Dict mapping command names to SlashCommand instances
+            Custom commands override built-ins
+        """
+        commands = {}
+
+        # Load built-ins first
+        builtin_dir = Path("commands")
+        if builtin_dir.exists():
+            for filepath in builtin_dir.glob("*.md"):
+                cmd = cls._parse_file(filepath, is_custom=False)
+                commands[cmd.name] = cmd
+
+        # Load customs (override built-ins)
+        custom_dir = Path(".co/commands")
+        if custom_dir.exists():
+            for filepath in custom_dir.glob("*.md"):
+                cmd = cls._parse_file(filepath, is_custom=True)
+                commands[cmd.name] = cmd
+
+        return commands
+
+    @classmethod
+    def is_custom(cls, command_name: str) -> bool:
+        """Check if command is a custom override.
+
+        Args:
+            command_name: Name of the command
+
+        Returns:
+            True if custom command exists in .co/commands/
+        """
+        custom_path = Path(".co/commands") / f"{command_name}.md"
+        return custom_path.exists()

connectonion/useful_tools/terminal.py

@@ -0,0 +1,285 @@
+"""
+Purpose: CLI input utilities for single keypress selection, file browsing, and @ autocomplete
+LLM-Note:
+  Dependencies: imports from [sys, typing, rich.console, termios/tty (Unix), msvcrt (Windows)] | imported by [useful_tools/__init__.py, tui/__init__.py] | tested by [tests/unit/test_terminal.py]
+  Data flow: pick(prompt, options) → displays numbered options → _getch()/_read_key() waits for keypress → returns selected option text or key | browse_files() → displays directory listing with rich.live → arrow keys navigate → returns selected file path | input_with_at() → standard input with @ triggering file browser
+  State/Effects: blocks on user input | uses raw terminal mode via termios/tty (Unix) or msvcrt (Windows) | no persistent state | no network I/O
+  Integration: exposes pick(), yes_no(), browse_files(), input_with_at(), autocomplete() | pick() accepts list (numbered) or dict (custom keys) | used for human-in-the-loop agent tools
+  Performance: instant response after keypress | no computation overhead | blocks on user input
+  Errors: returns None if user cancels | handles keyboard interrupts gracefully | no exceptions raised
+
+CLI input utilities - single keypress select, file browser, and @ autocomplete.
+
+Usage:
+    from connectonion import pick, yes_no, browse_files, input_with_at
+
+    # Recommended: Numbered options (1, 2, 3) for agent interactions
+    choice = pick("Apply this command?", [
+        "Yes, apply",
+        "Yes for same command",
+        "No, I'll tell agent how to do it"
+    ])
+    # Press 1 → "Yes, apply", 2 → "Yes for same command", 3 → "No, I'll tell agent how to do it"
+    # Or use arrow keys + Enter
+
+    # Pick from list (returns option text)
+    choice = pick("Pick a color", ["Red", "Green", "Blue"])
+    # Press 1 → "Red", 2 → "Green", 3 → "Blue"
+
+    # Pick with custom keys (returns key)
+    choice = pick("Continue?", {
+        "y": "Yes, continue",
+        "n": "No, cancel",
+    })
+    # Press y → "y", n → "n"
+
+    # Yes/No confirmation (simple binary choice)
+    ok = yes_no("Are you sure?")
+    # Press y → True, n → False
+
+    # Browse files and folders
+    path = browse_files()
+    # Navigate with arrow keys, Enter on folders to open, Enter on files to select
+    # Returns: "src/agent.py"
+
+    # Input with @ autocomplete
+    cmd = input_with_at("> ")
+    # User types: "edit @"
+    # File browser opens automatically
+    # Returns: "edit src/agent.py"
+"""
+
+import sys
+from typing import Union
+
+from rich.console import Console
+
+
+def _getch():
+    """Read a single character from stdin without waiting for Enter."""
+    try:
+        import termios
+        import tty
+        fd = sys.stdin.fileno()
+        old_settings = termios.tcgetattr(fd)
+        try:
+            tty.setraw(fd)
+            ch = sys.stdin.read(1)
+        finally:
+            termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
+        return ch
+    except ImportError:
+        import msvcrt
+        return msvcrt.getch().decode('utf-8', errors='ignore')
+
+
+def _read_key():
+    """Read a key, handling arrow key escape sequences."""
+    ch = _getch()
+    if ch == '\x1b':  # Escape sequence
+        ch2 = _getch()
+        if ch2 == '[':
+            ch3 = _getch()
+            if ch3 == 'A':
+                return 'up'
+            elif ch3 == 'B':
+                return 'down'
+            elif ch3 == 'C':
+                return 'right'
+            elif ch3 == 'D':
+                return 'left'
+    return ch
+
+
+def pick(
+    title: str,
+    options: Union[list, dict],
+    console: Console = None,
+) -> str:
+    """Pick one option - arrow keys or number/letter selection.
+
+    Args:
+        title: The question/title to display
+        options: Either a list (numbered 1,2,3...) or dict (custom keys)
+        console: Optional Rich console instance
+
+    Returns:
+        If list: the selected option text
+        If dict: the selected key
+
+    Example:
+        choice = pick("Pick one", ["Apple", "Banana"])
+        # Press 2 or arrow down + Enter → "Banana"
+
+        action = pick("Continue?", {"y": "Yes", "n": "No"})
+        # Press y → "y"
+    """
+    if console is None:
+        console = Console()
+
+    # Build key map and items list
+    if isinstance(options, list):
+        key_map = {}
+        items = []
+        for i, opt in enumerate(options, 1):
+            key = str(i)
+            key_map[key] = opt
+            items.append((key, opt))
+    else:
+        key_map = options
+        items = list(options.items())
+
+    selected = 0  # Current selection index
+
+    def render(first=False):
+        """Render the menu with current selection highlighted."""
+        if not first:
+            # Move cursor up to redraw
+            lines_to_clear = len(items) + (2 if title else 1)
+            sys.stdout.write(f"\033[{lines_to_clear}A")  # Move up
+            sys.stdout.write("\033[J")  # Clear from cursor to end
+
+        if title:
+            console.print(f"[bold]{title}[/]")
+        console.print()
+
+        for i, (key, desc) in enumerate(items):
+            if i == selected:
+                console.print(f"  [bold cyan]❯[/] [bold cyan]{key}[/]  [bold]{desc}[/]")
+            else:
+                console.print(f"    [dim]{key}[/]  {desc}")
+
+    # Initial render
+    render(first=True)
+
+    # Hide cursor
+    print("\033[?25l", end="", flush=True)
+
+    try:
+        while True:
+            key = _read_key()
+
+            if key == 'up':
+                selected = (selected - 1) % len(items)
+                render(first=False)
+            elif key == 'down':
+                selected = (selected + 1) % len(items)
+                render(first=False)
+            elif key in ('\r', '\n'):  # Enter
+                print("\033[?25h", end="", flush=True)
+                chosen_key = items[selected][0]
+                if isinstance(options, list):
+                    return key_map[chosen_key]
+                return chosen_key
+            elif key in key_map:
+                print("\033[?25h", end="", flush=True)
+                if isinstance(options, list):
+                    return key_map[key]
+                return key
+            elif key in ("\x03", "\x04"):  # Ctrl+C, Ctrl+D
+                print("\033[?25h", end="", flush=True)
+                raise KeyboardInterrupt()
+    finally:
+        print("\033[?25h", end="", flush=True)
+
+
+def yes_no(
+    message: str,
+    default: bool = True,
+    console: Console = None,
+) -> bool:
+    """Yes/No confirmation - single keypress.
+
+    Args:
+        message: The question to ask
+        default: Default value if Enter is pressed
+        console: Optional Rich console instance
+
+    Returns:
+        True for yes, False for no
+    """
+    if console is None:
+        console = Console()
+
+    yes_key = "Y" if default else "y"
+    no_key = "n" if default else "N"
+
+    console.print()
+    console.print(f"[bold]{message}[/] [dim]({yes_key}/{no_key})[/] ", end="")
+
+    while True:
+        ch = _getch().lower()
+        if ch == "y":
+            console.print("yes")
+            return True
+        elif ch == "n":
+            console.print("no")
+            return False
+        elif ch in ("\r", "\n"):  # Enter
+            console.print("yes" if default else "no")
+            return default
+        elif ch in ("\x03", "\x04"):  # Ctrl+C, Ctrl+D
+            raise KeyboardInterrupt()
+
+
+def autocomplete(suggestions: list, max_visible: int = 5) -> Union[str, None]:
+    """Show inline autocomplete dropdown with arrow key navigation.
+
+    Pure UI component - displays suggestions and handles selection.
+    Does NOT handle filtering or search logic - that's the caller's job.
+
+    Args:
+        suggestions: List of strings to display
+        max_visible: Maximum suggestions to show (default: 5)
+
+    Returns:
+        Selected string or None if cancelled (ESC pressed)
+
+    Example:
+        from connectonion import autocomplete
+
+        files = ["agent.py", "main.py", "utils.py"]
+        selected = autocomplete(files)
+        if selected:
+            print(f"Selected: {selected}")
+    """
+    from rich.live import Live
+    from rich.table import Table
+
+    if not suggestions:
+        return None
+
+    # Limit to max visible
+    suggestions = suggestions[:max_visible]
+    selected = 0
+
+    def create_table():
+        """Create table with current selection highlighted."""
+        table = Table(show_header=False, box=None, padding=(0, 1), show_edge=False)
+        for i, item in enumerate(suggestions):
+            if i == selected:
+                table.add_row(f"[cyan]❯ {item}[/]")
+            else:
+                table.add_row(f"[dim]  {item}[/]")
+        return table
+
+    # Show live display with keyboard navigation
+    with Live(create_table(), refresh_per_second=10, auto_refresh=False) as live:
+        while True:
+            key = _read_key()
+
+            if key == '\x1b':  # ESC - cancel
+                return None
+
+            elif key in ('\r', '\n', '\t'):  # Enter/Tab - accept
+                return suggestions[selected]
+
+            elif key == 'up':
+                selected = (selected - 1) % len(suggestions)
+                live.update(create_table(), refresh=True)
+
+            elif key == 'down':
+                selected = (selected + 1) % len(suggestions)
+                live.update(create_table(), refresh=True)
+
+