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

connectonion/useful_tools/grep_files.py

@@ -0,0 +1,171 @@
+"""
+Purpose: Grep tool for content searching
+LLM-Note:
+  Dependencies: imports from [re, pathlib, typing, .glob_files] | imported by [useful_tools/__init__]
+  Data flow: Agent calls grep(pattern) -> searches files -> returns matches
+  State/Effects: reads filesystem (no writes)
+  Integration: exposes grep(pattern, path, file_pattern, output_mode) function | used as agent tool
+
+Usage:
+    grep("def main")                           # Find "def main" in all files
+    grep("TODO|FIXME", file_pattern="*.py")   # Find TODOs in Python files
+    grep("class.*Agent", output_mode="content") # Show matching lines
+    grep("import", output_mode="count")        # Count imports per file
+"""
+
+import re
+from pathlib import Path
+from typing import Optional, Literal
+
+from .glob_files import IGNORE_DIRS
+
+
+def grep(
+    pattern: str,
+    path: Optional[str] = None,
+    file_pattern: Optional[str] = None,
+    output_mode: Literal["files", "content", "count"] = "files",
+    context_lines: int = 0,
+    ignore_case: bool = False,
+    max_results: int = 50,
+) -> str:
+    """
+    Search for content in files using regex.
+
+    Args:
+        pattern: Regular expression pattern to search for
+        path: File or directory to search in (default: current directory)
+        file_pattern: Glob pattern to filter files (e.g., "*.py", "*.ts")
+        output_mode:
+            - "files": Return only matching file paths (default)
+            - "content": Return matching lines with context
+            - "count": Return match counts per file
+        context_lines: Number of lines to show before/after match (for content mode)
+        ignore_case: Case insensitive search
+        max_results: Maximum number of results to return
+
+    Returns:
+        Search results based on output_mode
+
+    Examples:
+        grep("def main")                           # Find "def main" in all files
+        grep("TODO|FIXME", file_pattern="*.py")   # Find TODOs in Python files
+        grep("class.*Agent", output_mode="content") # Show matching lines
+        grep("import", output_mode="count")        # Count imports per file
+    """
+    base = Path(path) if path else Path.cwd()
+
+    if not base.exists():
+        return f"Error: Path '{base}' does not exist"
+
+    # Compile regex
+    flags = re.IGNORECASE if ignore_case else 0
+    try:
+        regex = re.compile(pattern, flags)
+    except re.error as e:
+        return f"Error: Invalid regex pattern: {e}"
+
+    # Collect files to search
+    if base.is_file():
+        files = [base]
+    else:
+        if file_pattern:
+            files = list(base.glob(f"**/{file_pattern}"))
+        else:
+            files = list(base.glob("**/*"))
+
+        files = [f for f in files if f.is_file() and not _should_ignore(f) and _is_text_file(f)]
+
+    results = []
+    total_matches = 0
+
+    for file in files:
+        if total_matches >= max_results:
+            break
+
+        try:
+            content = file.read_text(encoding="utf-8", errors="ignore")
+            lines = content.splitlines()
+        except Exception:
+            continue
+
+        file_matches = []
+        for i, line in enumerate(lines):
+            if regex.search(line):
+                file_matches.append((i + 1, line))  # 1-indexed line number
+
+        if not file_matches:
+            continue
+
+        rel_path = _relative_path(file, base)
+
+        if output_mode == "files":
+            results.append(str(rel_path))
+            total_matches += 1
+
+        elif output_mode == "count":
+            results.append(f"{rel_path}: {len(file_matches)} matches")
+            total_matches += 1
+
+        elif output_mode == "content":
+            results.append(f"\n{rel_path}:")
+            for line_num, line_text in file_matches[:10]:  # Limit per file
+                # Add context if requested
+                if context_lines > 0:
+                    start = max(0, line_num - 1 - context_lines)
+                    end = min(len(lines), line_num + context_lines)
+                    for ctx_i in range(start, end):
+                        prefix = ">" if ctx_i == line_num - 1 else " "
+                        results.append(f"  {prefix} {ctx_i + 1}: {lines[ctx_i]}")
+                    results.append("")
+                else:
+                    results.append(f"  {line_num}: {line_text}")
+                total_matches += 1
+
+                if total_matches >= max_results:
+                    break
+
+    if not results:
+        return f"No matches found for '{pattern}'"
+
+    output = "\n".join(results)
+
+    if total_matches >= max_results:
+        output += f"\n\n... results truncated at {max_results}"
+
+    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
+        for ignore in IGNORE_DIRS:
+            if "*" in ignore and Path(part).match(ignore):
+                return True
+    return False
+
+
+def _is_text_file(path: Path) -> bool:
+    """Check if file is likely a text file."""
+    # Skip binary file extensions
+    binary_extensions = {
+        ".pyc", ".pyo", ".so", ".dylib", ".dll", ".exe",
+        ".png", ".jpg", ".jpeg", ".gif", ".ico", ".svg",
+        ".pdf", ".doc", ".docx", ".xls", ".xlsx",
+        ".zip", ".tar", ".gz", ".rar", ".7z",
+        ".mp3", ".mp4", ".wav", ".avi", ".mov",
+        ".ttf", ".woff", ".woff2", ".eot",
+        ".lock", ".bin", ".dat",
+    }
+    return path.suffix.lower() not in binary_extensions
+
+
+def _relative_path(path: Path, base: Path) -> Path:
+    """Get relative path, handling edge cases."""
+    try:
+        return path.relative_to(base)
+    except ValueError:
+        return path

connectonion/useful_tools/multi_edit.py

@@ -0,0 +1,116 @@
+"""
+Purpose: Atomic multiple string replacements in a single file (Claude Code-style)
+LLM-Note:
+  Dependencies: imports from [pathlib, typing] | imported by [useful_tools/__init__]
+  Data flow: Agent calls multi_edit(file_path, edits) -> validates all edits -> applies sequentially -> returns status
+  State/Effects: reads and writes file on filesystem | atomic (all succeed or none applied)
+  Integration: exposes multi_edit(file_path, edits) function | used as agent tool
+  Errors: returns error if file not found | returns error if any old_string not found | rolls back on failure
+
+Usage:
+    multi_edit("app.py", [
+        {"old_string": "def foo():", "new_string": "def bar():"},
+        {"old_string": "return None", "new_string": "return True"},
+    ])
+"""
+
+from pathlib import Path
+from typing import List, TypedDict
+
+
+class EditOperation(TypedDict, total=False):
+    """Single edit operation."""
+    old_string: str              # Required: exact string to replace
+    new_string: str              # Required: replacement string
+    replace_all: bool            # Optional: replace all occurrences (default: False)
+
+
+def multi_edit(
+    file_path: str,
+    edits: List[EditOperation],
+) -> str:
+    """
+    Apply multiple string replacements to a file atomically.
+
+    All edits succeed or none are applied. Edits are applied sequentially,
+    so earlier edits affect the text that later edits search for.
+
+    Args:
+        file_path: Path to the file to edit
+        edits: List of edit operations, each with:
+            - old_string: Exact string to replace
+            - new_string: Replacement string
+            - replace_all: If True, replace all occurrences (default: False)
+
+    Returns:
+        Success message or error description
+
+    Examples:
+        multi_edit("app.py", [
+            {"old_string": "def foo():", "new_string": "def bar():"},
+            {"old_string": "foo()", "new_string": "bar()", "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"
+
+    if not edits:
+        return "Error: No edits provided"
+
+    # Read original content
+    original_content = path.read_text(encoding="utf-8")
+    content = original_content
+
+    # Validate and apply edits
+    applied = []
+    for i, edit in enumerate(edits):
+        old_string = edit.get("old_string", "")
+        new_string = edit.get("new_string", "")
+        replace_all = edit.get("replace_all", False)
+
+        if not old_string:
+            return f"Error: Edit {i+1} missing 'old_string'"
+
+        # Check if old_string exists in current content
+        count = content.count(old_string)
+
+        if count == 0:
+            # Show what edits were successful before failure
+            if applied:
+                applied_msg = "\n".join([f"  {j+1}. Replaced '{e['old']}'" for j, e in enumerate(applied)])
+                return (
+                    f"Error: Edit {i+1} failed - string not found after previous edits.\n"
+                    f"Looking for: {repr(old_string[:100])}\n\n"
+                    f"Successfully applied before failure:\n{applied_msg}\n\n"
+                    f"No changes were saved (atomic operation)."
+                )
+            return f"Error: Edit {i+1} - string not found in '{file_path}': {repr(old_string[:100])}"
+
+        if count > 1 and not replace_all:
+            return (
+                f"Error: Edit {i+1} - string appears {count} times. "
+                f"Use replace_all=True or provide more context.\n"
+                f"String: {repr(old_string[:100])}"
+            )
+
+        # Apply this edit
+        if replace_all:
+            content = content.replace(old_string, new_string)
+            applied.append({"old": old_string[:50], "count": count})
+        else:
+            content = content.replace(old_string, new_string, 1)
+            applied.append({"old": old_string[:50], "count": 1})
+
+    # All edits validated and applied in memory - now write to file
+    path.write_text(content, encoding="utf-8")
+
+    # Build success message
+    total_replacements = sum(e["count"] for e in applied)
+    if len(edits) == 1:
+        return f"Successfully edited '{file_path}'"
+    return f"Successfully applied {len(edits)} edits ({total_replacements} replacements) to '{file_path}'"

connectonion/useful_tools/read_file.py

@@ -0,0 +1,73 @@
+"""
+Purpose: Read file tool with line numbers
+LLM-Note:
+  Dependencies: imports from [pathlib, typing] | imported by [useful_tools/__init__]
+  Data flow: Agent calls read_file(path) -> reads file -> returns content with line numbers
+  State/Effects: reads file from filesystem
+  Integration: exposes read_file(path, offset, limit) function | used as agent tool
+
+Usage:
+    read_file("app.py")                    # Read entire file
+    read_file("large.log", offset=100)     # Start from line 100
+    read_file("data.csv", limit=50)        # First 50 lines
+"""
+
+from pathlib import Path
+from typing import Optional
+
+
+def read_file(
+    path: str,
+    offset: Optional[int] = None,
+    limit: Optional[int] = None,
+) -> str:
+    """
+    Read and return the contents of a file with line numbers.
+
+    Args:
+        path: Path to the file to read
+        offset: Line number to start from (1-indexed, default: 1)
+        limit: Number of lines to read (default: 2000)
+
+    Returns:
+        File contents with line numbers
+
+    Examples:
+        read_file("app.py")                    # Read entire file
+        read_file("large.log", offset=100)     # Start from line 100
+        read_file("data.csv", limit=50)        # First 50 lines
+    """
+    file_path = Path(path)
+
+    if not file_path.exists():
+        return f"Error: File '{path}' does not exist"
+
+    if not file_path.is_file():
+        return f"Error: '{path}' is not a file"
+
+    content = file_path.read_text(encoding="utf-8", errors="replace")
+    lines = content.splitlines()
+
+    total_lines = len(lines)
+
+    # Apply offset and limit
+    start = (offset - 1) if offset and offset > 0 else 0
+    end = (start + limit) if limit else len(lines)
+
+    selected_lines = lines[start:end]
+
+    # Format with line numbers
+    result_lines = []
+    for i, line in enumerate(selected_lines, start=start + 1):
+        # Truncate very long lines
+        if len(line) > 500:
+            line = line[:500] + "..."
+        result_lines.append(f"{i:>6}\t{line}")
+
+    result = "\n".join(result_lines)
+
+    # Add info about truncation
+    if end < total_lines:
+        result += f"\n\n... ({total_lines - end} more lines)"
+
+    return result

connectonion/useful_tools/shell.py

@@ -1,14 +1,5 @@
 """
-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.
+Shell tool for executing terminal commands (cross-platform).
 
 Usage:
     from connectonion import Agent, Shell
@@ -19,13 +10,16 @@ Usage:
     # Agent can now use:
     # - run(command) - Execute shell command, returns output
     # - run_in_dir(command, directory) - Execute in specific directory
+
+Note: Uses system default shell (bash/sh on Unix, cmd on Windows).
+For Unix-specific bash, use the `bash` function from bash.py instead.
 """
 
 import subprocess
 
 
 class Shell:
-    """Shell command execution tool."""
+    """Shell command execution tool (cross-platform)."""
 
     def __init__(self, cwd: str = "."):
         """Initialize Shell tool.
@@ -35,54 +29,61 @@ class Shell:
         """
         self.cwd = cwd
 
-    def run(self, command: str) -> str:
+    def run(self, command: str, timeout: int = 120) -> str:
         """Execute a shell command, returns output.
 
         Args:
             command: Shell command to execute (e.g., "ls -la", "git status")
+            timeout: Seconds before timeout (default: 120, max: 600)
 
         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:
+        timeout = min(timeout, 600)
+
+        try:
+            result = subprocess.run(
+                command,
+                shell=True,
+                capture_output=True,
+                text=True,
+                cwd=self.cwd,
+                timeout=timeout
+            )
+        except subprocess.TimeoutExpired:
+            return f"Error: Command timed out after {timeout} seconds"
+
+        return self._format_output(result)
+
+    def run_in_dir(self, command: str, directory: str, timeout: int = 120) -> str:
         """Execute command in a specific directory.
 
         Args:
             command: Shell command to execute
             directory: Directory to run the command in
+            timeout: Seconds before timeout (default: 120, max: 600)
 
         Returns:
             Command output (stdout + stderr)
         """
-        result = subprocess.run(
-            command,
-            shell=True,
-            capture_output=True,
-            text=True,
-            cwd=directory
-        )
-
+        timeout = min(timeout, 600)
+
+        try:
+            result = subprocess.run(
+                command,
+                shell=True,
+                capture_output=True,
+                text=True,
+                cwd=directory,
+                timeout=timeout
+            )
+        except subprocess.TimeoutExpired:
+            return f"Error: Command timed out after {timeout} seconds"
+
+        return self._format_output(result)
+
+    def _format_output(self, result: subprocess.CompletedProcess) -> str:
+        """Format subprocess result into readable output."""
         parts = []
         if result.stdout:
             parts.append(result.stdout.rstrip())
@@ -92,6 +93,10 @@ class Shell:
             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
+
+        # 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/write_file.py

@@ -0,0 +1,129 @@
+"""
+Purpose: Write file tool with Claude Code-style approval (web mode)
+LLM-Note:
+  Dependencies: imports from [.diff_writer] | imported by [useful_tools/__init__]
+  Data flow: Agent calls write(path, content) -> DiffWriter handles approval via io -> writes file
+  State/Effects: writes file to filesystem | sends events via io for approval
+  Integration: exposes write(path, content) function and Write class | used as agent tool
+
+This is a wrapper around DiffWriter for simpler function-based usage.
+For class-based usage with mode control, use DiffWriter directly.
+"""
+
+from pathlib import Path
+from typing import Optional
+
+from .diff_writer import DiffWriter, MODE_NORMAL, MODE_AUTO, MODE_PLAN
+
+
+# Global writer instance for function-based API
+_writer: Optional[DiffWriter] = None
+
+
+def _get_writer() -> DiffWriter:
+    """Get or create the global writer instance."""
+    global _writer
+    if _writer is None:
+        _writer = DiffWriter(mode=MODE_AUTO)  # Default to auto for function API
+    return _writer
+
+
+def write(path: str, content: str) -> str:
+    """
+    Write content to a file (full overwrite).
+
+    For new files or when replacing most of the content.
+    Use edit() for small, targeted changes instead.
+
+    Args:
+        path: File path to write to
+        content: Complete file content
+
+    Returns:
+        Success message or error description
+
+    Examples:
+        write("new_file.py", "print('hello')")
+        write("config.json", '{"debug": true}')
+    """
+    writer = _get_writer()
+    return writer.write(path, content)
+
+
+class FileWriter:
+    """File writer with Claude Code-style permission modes (web mode).
+
+    Use this class when you need mode control (normal/auto/plan).
+    For simple writes, use the write() function instead.
+
+    Usage:
+        writer = FileWriter(mode="normal")  # Prompt for every write
+        writer = FileWriter(mode="auto")    # Auto-approve all writes
+        writer = FileWriter(mode="plan")    # Read-only, preview only
+    """
+
+    def __init__(self, mode: str = MODE_NORMAL):
+        """Initialize Write tool.
+
+        Args:
+            mode: Permission mode - "normal" (prompt), "auto" (auto-approve), "plan" (read-only)
+        """
+        self._writer = DiffWriter(mode=mode)
+
+    @property
+    def io(self):
+        """IO channel for web mode."""
+        return self._writer.io
+
+    @io.setter
+    def io(self, value):
+        """Set IO channel."""
+        self._writer.io = value
+
+    @property
+    def mode(self):
+        """Current permission mode."""
+        return self._writer.mode
+
+    @mode.setter
+    def mode(self, value):
+        """Set permission mode."""
+        self._writer.mode = value
+
+    def write(self, path: str, content: str) -> str:
+        """Write content to a file. Both path and content are REQUIRED.
+
+        Args:
+            path: File path to write to (REQUIRED)
+            content: Complete file content (REQUIRED)
+
+        Returns:
+            Success message or error
+
+        Example:
+            write(path="/tmp/agent.py", content="from connectonion import Agent...")
+        """
+        return self._writer.write(path, content)
+
+    def diff(self, path: str, content: str) -> str:
+        """Show diff without writing (preview mode).
+
+        Args:
+            path: File path to compare against
+            content: New content to compare
+
+        Returns:
+            Diff string in unified format
+        """
+        return self._writer.diff(path, content)
+
+    def read(self, path: str) -> str:
+        """Read file contents.
+
+        Args:
+            path: File path to read
+
+        Returns:
+            File contents or error message
+        """
+        return self._writer.read(path)

{connectonion-0.6.1.dist-info → connectonion-0.6.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: connectonion
-Version: 0.6.1
+Version: 0.6.3
 Summary: A simple Python framework for creating AI agents with behavior tracking
 Project-URL: Homepage, https://github.com/openonion/connectonion
 Project-URL: Documentation, https://docs.connectonion.com
@@ -334,9 +334,16 @@ analyst = Agent("analyst", tools=[analyze], plugins=[reflection])
 - **Reusable capabilities**: Package event handlers into bundles
 - **Simple pattern**: A plugin is just a list of event handlers
 - **Easy composition**: Combine multiple plugins together
-- **Built-in examples**: Reflection, logging, todo tracking, and more
+- **Built-in plugins**: re_act, eval, system_reminder, image_result_formatter, and more
 
-[Learn more about plugins](docs/plugin.md)
+**Built-in plugins** are ready to use:
+```python
+from connectonion.useful_plugins import re_act, system_reminder
+
+agent = Agent("assistant", tools=[search], plugins=[re_act, system_reminder])
+```
+
+[Learn more about plugins](docs/plugin.md) | [Built-in plugins](docs/useful_plugins/)
 
 ## 🔧 Core Concepts