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

connectonion/useful_tools/bash.py

@@ -0,0 +1,69 @@
+"""
+Bash tool for executing terminal commands (Unix/Mac only).
+
+Usage:
+    from connectonion import Agent, bash
+
+    agent = Agent("coder", tools=[bash])
+
+    # Agent can now use:
+    # - bash(command) - Execute bash command, returns output
+    # - bash(command, cwd="/path") - Execute in specific directory
+    # - bash(command, timeout=60) - Execute with custom timeout
+
+Note: This tool is for Unix/Mac systems. For cross-platform usage, use Shell class instead.
+"""
+
+import subprocess
+import platform
+
+
+def bash(command: str, cwd: str = ".", timeout: int = 120) -> str:
+    """Execute a bash command, returns output (Unix/Mac only).
+
+    Args:
+        command: Bash command to execute (e.g., "ls -la", "git status")
+        cwd: Working directory (default: current directory)
+        timeout: Seconds before timeout (default: 120, max: 600)
+
+    Returns:
+        Command output (stdout + stderr)
+    """
+    # Check platform
+    if platform.system() == "Windows":
+        return "Error: bash tool is for Unix/Mac only. Use Shell class for Windows."
+
+    # Cap timeout at 10 minutes
+    timeout = min(timeout, 600)
+
+    try:
+        result = subprocess.run(
+            command,
+            shell=True,
+            executable="/bin/bash",
+            capture_output=True,
+            text=True,
+            cwd=cwd,
+            timeout=timeout
+        )
+    except subprocess.TimeoutExpired:
+        return f"Error: Command timed out after {timeout} seconds"
+    except FileNotFoundError:
+        return "Error: /bin/bash not found. This tool requires bash shell."
+
+    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)"
+
+    # Truncate large outputs
+    max_chars = 10000
+    if len(output) > max_chars:
+        output = output[:max_chars] + f"\n... (truncated, {len(output):,} total chars)"
+
+    return output

connectonion/useful_tools/diff_writer.py

@@ -1,19 +1,21 @@
 """
-Purpose: Human-in-the-loop file writing tool with diff preview and approval workflow
+Purpose: Web-based file writing tool with Claude Code-style permission modes
 LLM-Note:
-  Dependencies: imports from [difflib, pathlib, rich.console, rich.panel, rich.text, connectonion.tui.pick] | imported by [useful_tools/__init__.py] | tested by [tests/unit/test_diff_writer.py, tests/unit/test_diff_writer_tool.py]
-  Data flow: Agent calls DiffWriter.write(path, content) → reads existing file → generates unified diff → displays via Rich panel → pick() prompts for approval → writes if approved → returns status string
-  State/Effects: reads and writes files on filesystem | displays Rich-formatted diff in terminal | blocks for user input (unless auto_approve=True) | creates new files if path doesn't exist
-  Integration: exposes DiffWriter class with write(path, content), diff(path, content), read(path) | used as agent tool via Agent(tools=[DiffWriter()]) | auto_approve=True for automation
-  Performance: file I/O per operation | difflib is O(n) for diff generation | Rich rendering is fast | blocks on user input
-  Errors: returns error string if file unreadable | returns "Cancelled" if user rejects | no exceptions raised
+  Dependencies: imports from [difflib, pathlib, typing] | imported by [useful_tools/__init__.py, __init__.py] | tested by [tests/unit/test_diff_writer.py]
+  Data flow: Agent calls DiffWriter.write(path, content) -> show diff via io -> ask approval via io -> write file -> return status
+  State/Effects: reads and writes files on filesystem | sends diff_preview and ask_user events via io | requires io channel for approval
+  Integration: exposes DiffWriter class with write(path, content), diff(path, content), read(path) | used as agent tool via Agent(tools=[DiffWriter()])
+  Errors: returns error string if file unreadable | returns user feedback on rejection | no exceptions raised
 
-DiffWriter - Human-in-the-loop file writing with diff display.
+Permission Modes (like Claude Code's Shift+Tab cycle):
+  - normal: Prompt for every edit (default)
+  - auto: Auto-approve all edits without prompting
+  - plan: Read-only mode, no writes allowed
 
 Usage:
     from connectonion import Agent, DiffWriter
 
-    writer = DiffWriter()
+    writer = DiffWriter()  # mode="normal" by default
     agent = Agent("coder", tools=[writer])
 
     # Agent can now use:
@@ -24,25 +26,36 @@ Usage:
 
 import difflib
 from pathlib import Path
+from typing import Optional, Tuple
 
-from rich.console import Console
-from rich.panel import Panel
-from rich.text import Text
 
-from connectonion.tui import pick
+# Permission modes (like Claude Code's Shift+Tab cycle)
+MODE_NORMAL = "normal"      # Prompt for every edit
+MODE_AUTO = "auto"          # Auto-approve edits
+MODE_PLAN = "plan"          # Read-only, no writes
 
 
 class DiffWriter:
-    """File writer with diff display and human approval."""
+    """File writer with Claude Code-style permission modes (web mode).
 
-    def __init__(self, auto_approve: bool = False):
+    Requires io channel for approval prompts. Without io, falls back to auto-approve.
+
+    Usage:
+        writer = DiffWriter(mode="normal")  # Prompt for every edit
+        writer = DiffWriter(mode="auto")    # Auto-approve all edits
+        writer = DiffWriter(mode="plan")    # Read-only, preview only
+    """
+
+    def __init__(self, mode: str = MODE_NORMAL, preview_limit: int = 2000):
         """Initialize DiffWriter.
 
         Args:
-            auto_approve: If True, skip approval prompts (for automation)
+            mode: Permission mode - "normal" (prompt), "auto" (auto-approve), "plan" (read-only)
+            preview_limit: Max chars to include in diff preview
         """
-        self.auto_approve = auto_approve
-        self._console = Console()
+        self.mode = mode
+        self.preview_limit = preview_limit
+        self.io = None  # Set by agent's _sync_tool_io event handler
 
     def write(self, path: str, content: str) -> str:
         """Write content to a file with diff display and approval.
@@ -52,31 +65,42 @@ class DiffWriter:
             content: Content to write
 
         Returns:
-            Success message, rejection message, or user feedback for agent
+            Success message, rejection message with feedback, or plan mode preview
         """
         file_path = Path(path)
+        file_exists = file_path.exists()
 
-        if not self.auto_approve:
+        # Plan mode = read-only, just show what would happen
+        if self.mode == MODE_PLAN:
             diff_text = self._generate_diff(path, content)
-            if diff_text:
-                self._display_diff(diff_text, path)
-            else:
-                self._display_new_file(path, content)
+            preview = self._build_preview(diff_text, content, file_exists)
+            return f"[Plan mode] Would write {len(content)} bytes to {path}\n\nPreview:\n{preview[:500]}"
+
+        # Generate diff for display
+        diff_text = self._generate_diff(path, content)
+        preview = self._build_preview(diff_text, content, file_exists)
+        preview, truncated = self._truncate_preview(preview)
 
-            choice = self._ask_approval(path)
+        # Send diff preview to UI (best-effort, doesn't block)
+        self._send_preview(path, preview, truncated, file_exists)
+
+        # Check approval based on mode
+        if self.mode == MODE_NORMAL:
+            choice = self._ask_approval(path, preview, truncated)
 
             if choice == "reject":
-                self._console.print()
-                self._console.print("[bold yellow]What should the agent do instead?[/]")
-                feedback = input("> ")
+                feedback = self._ask_feedback(path)
                 return f"User rejected changes to {path}. Feedback: {feedback}"
 
             if choice == "approve_all":
-                self.auto_approve = True
+                self.mode = MODE_AUTO  # Switch to auto mode for rest of session
 
+        # Auto mode or approved: write file
         file_path.parent.mkdir(parents=True, exist_ok=True)
-        file_path.write_text(content, encoding='utf-8')
-        return f"Wrote {len(content)} bytes to {path}"
+        file_path.write_text(content, encoding="utf-8")
+
+        mode_note = "" if self.mode == MODE_NORMAL else f" [{self.mode} mode]"
+        return f"Wrote {len(content)} bytes to {path}{mode_note}"
 
     def diff(self, path: str, content: str) -> str:
         """Show diff without writing (preview mode).
@@ -90,7 +114,6 @@ class DiffWriter:
         """
         diff_text = self._generate_diff(path, content)
         if diff_text:
-            self._display_diff(diff_text, path)
             return diff_text
         return f"No changes to {path}"
 
@@ -106,37 +129,126 @@ class DiffWriter:
         file_path = Path(path)
         if not file_path.exists():
             return f"Error: File {path} not found"
-        return file_path.read_text(encoding='utf-8')
+        return file_path.read_text(encoding="utf-8")
+
+    # =========================================================================
+    # IO Communication (Web Mode)
+    # =========================================================================
 
-    def _ask_approval(self, path: str) -> str:
-        """Ask user for approval with single keypress.
+    def _get_io(self):
+        """Return active io channel if available."""
+        return self.io
+
+    def _send_preview(self, path: str, preview: str, truncated: bool, file_exists: bool) -> None:
+        """Send diff preview event to UI client.
+
+        This is informational - UI can render a nice diff view.
+        Does not block or wait for response.
+        """
+        io = self._get_io()
+        if not io:
+            return
+        io.send({
+            "type": "diff_preview",
+            "path": path,
+            "preview": preview,
+            "truncated": truncated,
+            "file_exists": file_exists,
+        })
+
+    def _ask_approval(self, path: str, preview: str, truncated: bool) -> str:
+        """Ask user for approval via io channel.
 
         Returns:
-            'approve', 'approve_all', or 'reject'
+            "approve" - Apply this change
+            "approve_all" - Apply and switch to auto mode
+            "reject" - Reject and ask for feedback
         """
-        self._console.print()
-        self._console.print(f"[bold cyan]File:[/] {path}")
-
-        choice = pick(
-            f"Apply changes to {path}?",
-            {
-                "1": "Yes, apply this change",
-                "2": "Yes to all (auto-approve for session)",
-                "3": "No, and tell agent what to do instead",
-            },
-            console=self._console,
+        io = self._get_io()
+        if not io:
+            # No io channel = auto-approve (for non-web usage)
+            return "approve"
+
+        question = f"Apply changes to {path}?"
+        if truncated:
+            question += " (preview truncated)"
+
+        response = self._ask_user(
+            question,
+            options=[
+                "Yes, apply this change",
+                "Yes to all (auto-approve)",
+                "No, reject and give feedback",
+            ],
         )
-        return {"1": "approve", "2": "approve_all", "3": "reject"}[choice]
+
+        # Parse response
+        if response == "Yes to all (auto-approve)":
+            return "approve_all"
+        if response == "Yes, apply this change":
+            return "approve"
+
+        # Handle free-text responses
+        if response:
+            lowered = response.strip().lower()
+            if "yes to all" in lowered or lowered == "auto":
+                return "approve_all"
+            if lowered.startswith("yes") or lowered == "approve":
+                return "approve"
+
+        return "reject"
+
+    def _ask_feedback(self, path: str) -> str:
+        """Ask user for feedback when changes are rejected."""
+        feedback = self._ask_user(f"What should the agent do instead for {path}?")
+        return feedback or "No feedback provided"
+
+    def _ask_user(self, question: str, options: Optional[list] = None) -> str:
+        """Send ask_user event and block until user responds.
+
+        Args:
+            question: Question to display
+            options: List of option strings (buttons in UI)
+
+        Returns:
+            User's answer string
+        """
+        io = self._get_io()
+        if not io:
+            return ""
+
+        # Send ask_user event
+        io.send({
+            "type": "ask_user",
+            "question": question,
+            "options": options,
+        })
+
+        # Block waiting for response
+        response = io.receive()
+
+        # Handle connection closed
+        if response.get("type") == "io_closed":
+            return ""
+
+        # Extract answer
+        answer = response.get("answer", "")
+        if isinstance(answer, list):
+            return ", ".join([str(a) for a in answer])
+        return str(answer) if answer is not None else ""
+
+    # =========================================================================
+    # Diff Generation
+    # =========================================================================
 
     def _generate_diff(self, path: str, new_content: str) -> str:
         """Generate unified diff between existing file and new content."""
         file_path = Path(path)
 
-        if file_path.exists():
-            original_lines = file_path.read_text(encoding='utf-8').splitlines(keepends=True)
-        else:
-            return ""  # New file, no diff
+        if not file_path.exists():
+            return ""  # New file, no diff to show
 
+        original_lines = file_path.read_text(encoding="utf-8").splitlines(keepends=True)
         new_lines = new_content.splitlines(keepends=True)
 
         diff = difflib.unified_diff(
@@ -146,47 +258,27 @@ class DiffWriter:
             tofile=f"b/{path}",
         )
 
-        return ''.join(diff)
-
-    def _display_diff(self, diff_text: str, path: str):
-        """Display colorized diff."""
-        styled = Text()
-
-        for line in diff_text.splitlines():
-            if line.startswith('+++') or line.startswith('---'):
-                styled.append(line + '\n', style="bold white")
-            elif line.startswith('@@'):
-                styled.append(line + '\n', style="cyan")
-            elif line.startswith('+'):
-                styled.append(line + '\n', style="green")
-            elif line.startswith('-'):
-                styled.append(line + '\n', style="red")
-            else:
-                styled.append(line + '\n', style="dim")
-
-        panel = Panel(
-            styled,
-            title=f"[bold yellow]Changes to {path}[/]",
-            border_style="yellow",
-            padding=(0, 1)
-        )
-        self._console.print(panel)
-
-    def _display_new_file(self, path: str, content: str):
-        """Display preview of new file."""
-        styled = Text()
+        return "".join(diff)
 
+    def _build_preview(self, diff_text: str, content: str, file_exists: bool) -> str:
+        """Build human-readable preview for approval dialog."""
+        if diff_text:
+            return diff_text
+        if file_exists:
+            return "(no changes)"
+        return self._new_file_preview(content)
+
+    def _truncate_preview(self, preview: str) -> Tuple[str, bool]:
+        """Truncate preview to configured limit."""
+        if len(preview) <= self.preview_limit:
+            return preview, False
+        return preview[: self.preview_limit] + "\n...(truncated)", True
+
+    def _new_file_preview(self, content: str, max_lines: int = 50) -> str:
+        """Create preview for new file (no existing file to diff against)."""
         lines = content.splitlines()
-        for line in lines[:50]:  # Limit preview to 50 lines
-            styled.append(f"+ {line}\n", style="green")
-
-        if len(lines) > 50:
-            styled.append(f"... ({len(lines) - 50} more lines)\n", style="dim")
-
-        panel = Panel(
-            styled,
-            title=f"[bold yellow]New file: {path}[/]",
-            border_style="yellow",
-            padding=(0, 1)
-        )
-        self._console.print(panel)
+        preview_lines = lines[:max_lines]
+        preview = "\n".join([f"+ {line}" for line in preview_lines])
+        if len(lines) > max_lines:
+            preview += f"\n... ({len(lines) - max_lines} more lines)"
+        return preview

connectonion/useful_tools/edit.py

@@ -0,0 +1,102 @@
+"""
+Purpose: Edit tool for precise string replacement (Claude Code-style)
+LLM-Note:
+  Dependencies: imports from [pathlib] | imported by [useful_tools/__init__]
+  Data flow: Agent calls edit(file_path, old_string, new_string) -> validates -> replaces -> writes
+  State/Effects: reads and writes file on filesystem
+  Integration: exposes edit(file_path, old_string, new_string) function | used as agent tool
+  Errors: returns error if file not found | returns error if old_string not found | returns error if old_string not unique
+
+Usage:
+    edit("app.py", "def foo():", "def bar():")
+    edit("config.json", '"debug": false', '"debug": true')
+    edit("README.md", "v1.0", "v2.0", replace_all=True)
+"""
+
+from pathlib import Path
+
+
+def edit(
+    file_path: str,
+    old_string: str,
+    new_string: str,
+    replace_all: bool = False,
+) -> str:
+    """
+    Replace a string in a file with precise matching.
+
+    More token-efficient than rewriting entire files. Use for small, targeted changes.
+    The old_string must exist in the file (and be unique unless replace_all=True).
+
+    Args:
+        file_path: Path to the file to edit
+        old_string: Exact string to replace (must be unique in file)
+        new_string: String to replace with
+        replace_all: If True, replace all occurrences; if False, old_string must be unique
+
+    Returns:
+        Success message or error description
+
+    Examples:
+        edit("app.py", "def foo():", "def bar():")
+        edit("config.json", '"debug": false', '"debug": true')
+        edit("README.md", "v1.0", "v2.0", replace_all=True)
+    """
+    path = Path(file_path)
+
+    if not path.exists():
+        return f"Error: File '{file_path}' does not exist"
+
+    if not path.is_file():
+        return f"Error: '{file_path}' is not a file"
+
+    content = path.read_text(encoding="utf-8")
+
+    # Check if old_string exists
+    count = content.count(old_string)
+
+    if count == 0:
+        # Try to help debug: show similar strings
+        lines_with_similar = []
+        for i, line in enumerate(content.splitlines(), 1):
+            # Check if any significant part of old_string is in the line
+            if len(old_string) > 10:
+                # For longer strings, check first 20 chars
+                if old_string[:20] in line or old_string[-20:] in line:
+                    lines_with_similar.append(f"  Line {i}: {line[:80]}")
+            elif old_string.strip() in line:
+                lines_with_similar.append(f"  Line {i}: {line[:80]}")
+
+        msg = f"Error: String not found in '{file_path}'"
+        if lines_with_similar:
+            msg += f"\n\nSimilar content found:\n" + "\n".join(lines_with_similar[:5])
+        return msg
+
+    if count > 1 and not replace_all:
+        # Show where the duplicates are
+        lines_with_match = []
+        for i, line in enumerate(content.splitlines(), 1):
+            if old_string in line:
+                lines_with_match.append(f"  Line {i}: {line[:80]}")
+
+        return (
+            f"Error: String appears {count} times in '{file_path}'. "
+            f"Use replace_all=True to replace all, or provide more context to make it unique.\n\n"
+            f"Found at:\n" + "\n".join(lines_with_match[:10])
+        )
+
+    # Perform replacement
+    if replace_all:
+        new_content = content.replace(old_string, new_string)
+        replaced_count = count
+    else:
+        new_content = content.replace(old_string, new_string, 1)
+        replaced_count = 1
+
+    # Write back
+    path.write_text(new_content, encoding="utf-8")
+
+    if replace_all and replaced_count > 1:
+        return f"Replaced {replaced_count} occurrences in '{file_path}'"
+    else:
+        return f"Successfully edited '{file_path}'"

connectonion/useful_tools/glob_files.py

@@ -0,0 +1,97 @@
+"""
+Purpose: Glob tool for file pattern matching
+LLM-Note:
+  Dependencies: imports from [pathlib, typing] | imported by [useful_tools/__init__, grep]
+  Data flow: Agent calls glob(pattern) -> searches directory -> returns matching paths
+  State/Effects: reads filesystem (no writes)
+  Integration: exposes glob(pattern, path) function | used as agent tool | shared IGNORE_DIRS constant
+
+Usage:
+    glob("**/*.py")           # All Python files
+    glob("src/**/*.tsx")      # All TSX files in src/
+    glob("**/test_*.py")      # All test files
+    glob("*.md", "docs")      # Markdown files in docs/
+"""
+
+from pathlib import Path
+from typing import Optional
+
+IGNORE_DIRS = {
+    ".git",
+    "node_modules",
+    "__pycache__",
+    ".venv",
+    "venv",
+    ".env",
+    "dist",
+    "build",
+    ".next",
+    ".nuxt",
+    "target",
+    ".idea",
+    ".vscode",
+    "*.egg-info",
+}
+
+
+def glob(pattern: str, path: Optional[str] = None) -> str:
+    """
+    Search for files matching a glob pattern.
+
+    Args:
+        pattern: Glob pattern (e.g., "**/*.py", "src/**/*.ts")
+        path: Directory to search in (default: current directory)
+
+    Returns:
+        Matching file paths, one per line, sorted by modification time (newest first)
+
+    Examples:
+        glob("**/*.py")           # All Python files
+        glob("src/**/*.tsx")      # All TSX files in src/
+        glob("**/test_*.py")      # All test files
+        glob("*.md", "docs")      # Markdown files in docs/
+    """
+    base = Path(path) if path else Path.cwd()
+
+    if not base.exists():
+        return f"Error: Path '{base}' does not exist"
+
+    if not base.is_dir():
+        return f"Error: Path '{base}' is not a directory"
+
+    matches = []
+    for p in base.glob(pattern):
+        if p.is_file() and not _should_ignore(p):
+            matches.append(p)
+
+    if not matches:
+        return f"No files found matching '{pattern}'"
+
+    # Sort by modification time (newest first)
+    matches.sort(key=lambda p: p.stat().st_mtime, reverse=True)
+
+    # Format output
+    results = []
+    for p in matches[:100]:  # Limit to 100 results
+        rel_path = p.relative_to(base) if path else p.relative_to(Path.cwd())
+        results.append(str(rel_path))
+
+    output = "\n".join(results)
+
+    if len(matches) > 100:
+        output += f"\n\n... and {len(matches) - 100} more files"
+
+    return output
+
+
+def _should_ignore(path: Path) -> bool:
+    """Check if path should be ignored."""
+    parts = path.parts
+    for part in parts:
+        if part in IGNORE_DIRS:
+            return True
+        # Handle patterns like *.egg-info
+        for ignore in IGNORE_DIRS:
+            if "*" in ignore and Path(part).match(ignore):
+                return True
+    return False