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

connectonion/cli/co_ai/tools/ask_user.py

@@ -0,0 +1,35 @@
+"""
+Purpose: Ask user a question during agent execution via connection
+LLM-Note:
+  Dependencies: imports from [typing] | imported by [useful_tools/__init__.py]
+  Data flow: agent calls ask_user tool → sends ask_user event via connection → waits for response → returns answer
+  State/Effects: blocks until user responds via connection
+  Integration: requires agent.connection to be set | agent parameter injected by tool_executor
+"""
+
+from typing import List, Optional
+
+
+def ask_user(
+    agent,
+    question: str,
+    options: Optional[List[str]] = None,
+    multi_select: bool = False
+) -> str:
+    """Ask the user a question and wait for their response.
+
+    Args:
+        question: The question to ask the user
+        options: Optional list of choices for the user to select from
+        multi_select: If True, user can select multiple options
+
+    Returns:
+        The user's answer (or comma-separated answers if multi_select)
+    """
+    agent.connection.send({
+        "type": "ask_user",
+        "question": question,
+        "options": options,
+        "multi_select": multi_select
+    })
+    return agent.connection.receive().get("answer", "")

connectonion/cli/co_ai/tools/background.py

@@ -0,0 +1,201 @@
+"""Background task execution for long-running operations."""
+
+import subprocess
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Dict, Optional
+from enum import Enum
+
+
+class TaskStatus(Enum):
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+@dataclass
+class BackgroundTask:
+    """A background task with its process and output."""
+    id: str
+    command: str
+    process: subprocess.Popen
+    output: list = field(default_factory=list)
+    status: TaskStatus = TaskStatus.RUNNING
+    start_time: float = field(default_factory=time.time)
+    end_time: Optional[float] = None
+
+
+# Global task registry
+_tasks: Dict[str, BackgroundTask] = {}
+_task_counter = 0
+_lock = threading.Lock()
+
+
+def _reset_for_testing():
+    """Reset state for testing. Not for production use."""
+    global _tasks, _task_counter
+    with _lock:
+        for task in _tasks.values():
+            if task.status == TaskStatus.RUNNING:
+                task.process.terminate()
+        _tasks.clear()
+        _task_counter = 0
+
+
+def _read_output(task: BackgroundTask):
+    """Read output from process in background thread."""
+    for line in iter(task.process.stdout.readline, ""):
+        if not line:
+            break
+        task.output.append(line.rstrip())
+
+    task.process.wait()
+    task.end_time = time.time()
+    task.status = TaskStatus.COMPLETED if task.process.returncode == 0 else TaskStatus.FAILED
+
+
+def run_background(command: str, description: str = "") -> str:
+    """
+    Run a shell command in the background.
+
+    Use this for long-running operations like builds, tests, or servers.
+    Returns immediately with a task ID. Use task_output() to check results.
+
+    Args:
+        command: Shell command to run (e.g., "npm run build", "pytest")
+        description: Optional description for the task
+
+    Returns:
+        Task ID and confirmation message
+
+    Example:
+        run_background("npm run build")  # Returns: "Task bg_1 started: npm run build"
+        task_output("bg_1")  # Check output later
+    """
+    global _task_counter
+
+    with _lock:
+        _task_counter += 1
+        task_id = f"bg_{_task_counter}"
+
+    process = subprocess.Popen(
+        command,
+        shell=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        bufsize=1,
+    )
+
+    task = BackgroundTask(
+        id=task_id,
+        command=command,
+        process=process,
+    )
+
+    with _lock:
+        _tasks[task_id] = task
+
+    # Start output reader thread
+    thread = threading.Thread(target=_read_output, args=(task,), daemon=True)
+    thread.start()
+
+    desc = f" ({description})" if description else ""
+    return f"Task {task_id} started{desc}: {command}"
+
+
+def task_output(task_id: str, tail: int = 50) -> str:
+    """
+    Get output from a background task.
+
+    Args:
+        task_id: The task ID (e.g., "bg_1")
+        tail: Number of recent lines to show (default: 50)
+
+    Returns:
+        Task status and output
+
+    Example:
+        task_output("bg_1")  # Get output from task bg_1
+        task_output("bg_1", tail=100)  # Get last 100 lines
+    """
+    with _lock:
+        task = _tasks.get(task_id)
+
+    if not task:
+        available = list(_tasks.keys())
+        if available:
+            return f"Task '{task_id}' not found. Available: {', '.join(available)}"
+        return f"Task '{task_id}' not found. No background tasks running."
+
+    elapsed = time.time() - task.start_time
+    if task.end_time:
+        elapsed = task.end_time - task.start_time
+
+    status_line = f"Task {task_id}: {task.status.value} ({elapsed:.1f}s)"
+    status_line += f"\nCommand: {task.command}"
+
+    if task.status == TaskStatus.FAILED:
+        status_line += f"\nExit code: {task.process.returncode}"
+
+    output_lines = task.output[-tail:] if task.output else []
+    if output_lines:
+        output_text = "\n".join(output_lines)
+        if len(task.output) > tail:
+            output_text = f"... ({len(task.output) - tail} lines omitted)\n{output_text}"
+        return f"{status_line}\n\nOutput:\n{output_text}"
+
+    return f"{status_line}\n\n(no output yet)"
+
+
+def kill_task(task_id: str) -> str:
+    """
+    Kill a running background task.
+
+    Args:
+        task_id: The task ID to kill (e.g., "bg_1")
+
+    Returns:
+        Confirmation message
+    """
+    with _lock:
+        task = _tasks.get(task_id)
+
+    if not task:
+        return f"Task '{task_id}' not found."
+
+    if task.status != TaskStatus.RUNNING:
+        return f"Task '{task_id}' is not running (status: {task.status.value})"
+
+    task.process.terminate()
+    task.status = TaskStatus.FAILED
+    task.end_time = time.time()
+
+    return f"Task '{task_id}' terminated."
+
+
+def list_tasks() -> str:
+    """
+    List all background tasks.
+
+    Returns:
+        Table of all tasks with their status
+    """
+    with _lock:
+        tasks = list(_tasks.values())
+
+    if not tasks:
+        return "No background tasks."
+
+    lines = ["Background Tasks:", ""]
+    for t in tasks:
+        elapsed = time.time() - t.start_time
+        if t.end_time:
+            elapsed = t.end_time - t.start_time
+
+        status_icon = {"running": "⏳", "completed": "✓", "failed": "✗"}[t.status.value]
+        cmd_short = t.command[:40] + "..." if len(t.command) > 40 else t.command
+        lines.append(f"  {status_icon} {t.id}: {cmd_short} ({elapsed:.1f}s)")
+
+    return "\n".join(lines)

connectonion/cli/co_ai/tools/diff_writer.py

@@ -0,0 +1,291 @@
+"""
+Purpose: Web-based file writing tool with Claude Code-style permission modes
+LLM-Note:
+  Dependencies: imports from [difflib, pathlib, typing] | imported by [co_ai.tools.__init__]
+  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
+
+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
+
+Architecture:
+
+  Agent Thread                    WebSocketIO                    Browser
+       │                              │                             │
+       │  1. write("app.py", code)    │                             │
+       │                              │                             │
+       │  2. io.send({type: "diff_preview", path, diff, ...})       │
+       │─────────────────────────────▶│─────────────────────────────▶
+       │                              │                             │
+       │  3. io.send({type: "ask_user", question, options})         │
+       │─────────────────────────────▶│─────────────────────────────▶
+       │                              │                             │
+       │  4. io.receive() [BLOCKS]    │      User clicks option     │
+       │◀─────────────────────────────│◀────────────────────────────│
+       │                              │                             │
+       │  5. Write file or return rejection with feedback           │
+       │                              │                             │
+"""
+
+import difflib
+from pathlib import Path
+from typing import Optional, Tuple
+
+
+# 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 Claude Code-style permission modes (web mode).
+
+    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:
+            mode: Permission mode - "normal" (prompt), "auto" (auto-approve), "plan" (read-only)
+            preview_limit: Max chars to include in diff preview
+        """
+        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.
+
+        Args:
+            path: File path to write to
+            content: Content to write
+
+        Returns:
+            Success message, rejection message with feedback, or plan mode preview
+        """
+        file_path = Path(path)
+        file_exists = file_path.exists()
+
+        # Plan mode = read-only, just show what would happen
+        if self.mode == MODE_PLAN:
+            diff_text = self._generate_diff(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)
+
+        # 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":
+                feedback = self._ask_feedback(path)
+                return f"User rejected changes to {path}. Feedback: {feedback}"
+
+            if choice == "approve_all":
+                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")
+
+        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).
+
+        Args:
+            path: File path to compare against
+            content: New content to compare
+
+        Returns:
+            Diff string in unified format
+        """
+        diff_text = self._generate_diff(path, content)
+        if diff_text:
+            return diff_text
+        return f"No changes to {path}"
+
+    def read(self, path: str) -> str:
+        """Read file contents.
+
+        Args:
+            path: File path to read
+
+        Returns:
+            File contents or error message
+        """
+        file_path = Path(path)
+        if not file_path.exists():
+            return f"Error: File {path} not found"
+        return file_path.read_text(encoding="utf-8")
+
+    # =========================================================================
+    # IO Communication (Web Mode)
+    # =========================================================================
+
+    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" - Apply this change
+            "approve_all" - Apply and switch to auto mode
+            "reject" - Reject and ask for feedback
+        """
+        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",
+            ],
+        )
+
+        # 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 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(
+            original_lines,
+            new_lines,
+            fromfile=f"a/{path}",
+            tofile=f"b/{path}",
+        )
+
+        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()
+        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/cli/co_ai/tools/edit.py

@@ -0,0 +1,89 @@
+"""Edit tool for precise string replacement."""
+
+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/cli/co_ai/tools/glob.py

@@ -0,0 +1,84 @@
+"""Glob tool for file pattern matching."""
+
+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