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

connectonion/cli/co_ai/skills/tool.py

@@ -0,0 +1,46 @@
+"""Skill tool - allows agent to invoke skills."""
+
+from typing import Optional
+from connectonion.cli.co_ai.skills.loader import get_skill, load_skills, SKILLS_REGISTRY
+
+
+def skill(name: str, args: Optional[str] = None) -> str:
+    """
+    Invoke a skill by name.
+
+    Skills are specialized instruction sets that guide you through specific tasks.
+    When you recognize a task matches a skill's description, call this tool to
+    load the full instructions.
+
+    Args:
+        name: The skill name (e.g., "commit", "review-pr")
+        args: Optional arguments to pass to the skill
+
+    Returns:
+        The full skill instructions (SKILL.md content)
+
+    Example:
+        skill("commit")  # Load commit instructions
+        skill("review-pr", args="123")  # Load PR review with PR number
+    """
+    # Ensure skills are loaded
+    if not SKILLS_REGISTRY:
+        load_skills()
+
+    skill_info = get_skill(name)
+
+    if not skill_info:
+        available = list(SKILLS_REGISTRY.keys())
+        if available:
+            return f"Skill '{name}' not found. Available skills: {', '.join(available)}"
+        else:
+            return f"Skill '{name}' not found. No skills are currently loaded."
+
+    # Load the full skill content
+    content = skill_info.load_content()
+
+    # If args provided, append them
+    if args:
+        content += f"\n\n---\n## Arguments\n{args}"
+
+    return content

connectonion/cli/co_ai/tools/__init__.py

@@ -0,0 +1,92 @@
+"""
+Coding tools for the AI agent (Claude Code-style).
+
+File Tools:
+    - read_file: Read file with line numbers
+    - edit: Precise string replacement (str_replace)
+    - multi_edit: Multiple atomic string replacements
+    - write: Full file overwrite with approval
+    - Write: Class-based write with mode control
+
+Search Tools:
+    - glob: Find files by pattern
+    - grep: Search file contents
+
+Task Tools:
+    - task: Spawn sub-agent for complex tasks
+    - run_background: Run command in background
+    - task_output: Get background task output
+    - kill_task: Stop background task
+
+Planning Tools:
+    - enter_plan_mode: Switch to planning mode
+    - exit_plan_mode: Exit planning mode
+    - write_plan: Write plan content
+
+Interaction Tools:
+    - ask_user: Ask user a question via io
+    - load_guide: Load documentation/guide
+
+Utility Classes:
+    - DiffWriter: Low-level file writer with diff preview
+    - TodoList: Task list management
+
+Note: File tools are re-exported from connectonion.useful_tools for consistency.
+"""
+
+# File tools (Claude Code-style) - re-export from useful_tools
+from connectonion.useful_tools import (
+    read_file,
+    edit,
+    multi_edit,
+    glob,
+    grep,
+    write,
+    FileWriter,
+    DiffWriter,
+    MODE_NORMAL,
+    MODE_AUTO,
+    MODE_PLAN,
+    TodoList,
+)
+
+# Task tools (CLI-specific)
+from connectonion.cli.co_ai.tools.task import task
+from connectonion.cli.co_ai.tools.background import run_background, task_output, kill_task
+
+# Planning tools (CLI-specific)
+from connectonion.cli.co_ai.tools.plan_mode import enter_plan_mode, exit_plan_mode, write_plan
+
+# Interaction tools (CLI-specific)
+from connectonion.cli.co_ai.tools.ask_user import ask_user
+from connectonion.cli.co_ai.tools.load_guide import load_guide
+
+__all__ = [
+    # File tools (Claude Code-style)
+    "read_file",
+    "edit",
+    "multi_edit",
+    "write",
+    "FileWriter",
+    "DiffWriter",
+    "MODE_NORMAL",
+    "MODE_AUTO",
+    "MODE_PLAN",
+    # Search tools
+    "glob",
+    "grep",
+    # Task tools
+    "task",
+    "run_background",
+    "task_output",
+    "kill_task",
+    # Planning tools
+    "enter_plan_mode",
+    "exit_plan_mode",
+    "write_plan",
+    # Interaction tools
+    "ask_user",
+    "load_guide",
+    # Utility classes
+    "TodoList",
+]

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