devorch 0.1.2__py3-none-any.whl

tools/terminal_session.py

@@ -0,0 +1,298 @@
+"""
+Managed terminal session tool — lets the LLM start long-running processes,
+read their output, send input, and stop them, all within the conversation.
+
+Session data is stored as a simple in-process dict (sessions survive for the
+lifetime of one DevOrch run). Each session gets a temp log file so the LLM
+can poll output without blocking.
+"""
+
+import os
+import subprocess
+import tempfile
+import threading
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from tools.base import Tool
+
+# ── In-memory session registry ──────────────────────────────────────────────
+# { session_id: { "process": Popen, "log_file": str, "command": str } }
+_SESSIONS: dict[str, dict] = {}
+_LOCK = threading.Lock()
+
+
+def _stream_to_file(process: subprocess.Popen, log_path: str) -> None:
+    """Background thread: read stdout+stderr and append to log file."""
+    try:
+        with open(log_path, "ab") as f:
+            for line in process.stdout:  # type: ignore[union-attr]
+                f.write(line)
+                f.flush()
+    except Exception:
+        pass
+
+
+# ── Schema ───────────────────────────────────────────────────────────────────
+
+
+class TerminalSessionSchema(BaseModel):
+    action: str = Field(
+        ...,
+        description=(
+            "Action to perform. One of: "
+            "'start' — launch a command in a managed background session; "
+            "'read'  — get recent output from a running session; "
+            "'send'  — send a line of text/input to a running session's stdin; "
+            "'stop'  — terminate a session; "
+            "'list'  — list all active sessions."
+        ),
+    )
+    session_id: str | None = Field(
+        None,
+        description=(
+            "Identifier for the session. Required for 'start', 'read', 'send', 'stop'. "
+            "Choose a short, descriptive name, e.g. 'frontend', 'api-server', 'worker'."
+        ),
+    )
+    command: str | None = Field(
+        None,
+        description="Shell command to run. Required for 'start'.",
+    )
+    input: str | None = Field(
+        None,
+        description=(
+            "Text to send to the process stdin. Required for 'send'. "
+            "Include a newline (\\n) if the program expects Enter to be pressed."
+        ),
+    )
+    lines: int = Field(
+        50,
+        description="Number of recent output lines to return for 'read'. Default 50.",
+    )
+
+
+# ── Tool ──────────────────────────────────────────────────────────────────────
+
+
+class TerminalSessionTool(Tool):
+    name = "terminal_session"
+    description = """\
+Manages long-running background terminal sessions so you can interact with them
+across multiple conversation turns.
+
+Actions:
+- **start**  — Start a command in a named background session (e.g. `npm run dev`).
+               The process runs in the background; use `read` to see its output.
+- **read**   — Read recent stdout/stderr output from a running session.
+- **send**   — Send a line of input to the process stdin (e.g. to restart nodemon with `rs\\n`).
+- **stop**   — Kill a running session.
+- **list**   — Show all currently active sessions and their status.
+
+Example workflow:
+1. `start` session_id="server" command="npm run dev"
+2. `read`  session_id="server"          # check startup logs
+3. `send`  session_id="server" input="rs\\n"  # restart nodemon
+4. `stop`  session_id="server"
+
+Use `open_terminal` instead if you want an interactive visible terminal window.
+Use this tool when you need programmatic access to a process (check output, send input)."""
+    args_schema = TerminalSessionSchema
+
+    # ── helpers ──────────────────────────────────────────────────────────────
+
+    def _get_session(self, session_id: str) -> dict | None:
+        with _LOCK:
+            return _SESSIONS.get(session_id)
+
+    def _session_alive(self, session: dict) -> bool:
+        return session["process"].poll() is None
+
+    # ── actions ──────────────────────────────────────────────────────────────
+
+    def _start(self, session_id: str, command: str) -> str:
+        with _LOCK:
+            if session_id in _SESSIONS:
+                existing = _SESSIONS[session_id]
+                if existing["process"].poll() is None:
+                    return (
+                        f"Error: Session '{session_id}' is already running. "
+                        f"Use stop first or choose a different session_id."
+                    )
+                # Dead session — clean up and restart
+                del _SESSIONS[session_id]
+
+        # Create a temp log file for stdout+stderr
+        log_fd, log_path = tempfile.mkstemp(prefix=f"devorch_{session_id}_", suffix=".log")
+        os.close(log_fd)
+
+        try:
+            process = subprocess.Popen(
+                command,
+                shell=True,
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                cwd=os.getcwd(),
+                bufsize=0,  # unbuffered for real-time output
+            )
+        except Exception as e:
+            os.unlink(log_path)
+            return f"Error starting session '{session_id}': {e}"
+
+        # Background thread streams process output to the log file
+        t = threading.Thread(
+            target=_stream_to_file,
+            args=(process, log_path),
+            daemon=True,
+            name=f"devorch-session-{session_id}",
+        )
+        t.start()
+
+        with _LOCK:
+            _SESSIONS[session_id] = {
+                "process": process,
+                "log_path": log_path,
+                "command": command,
+            }
+
+        return (
+            f"✓ Session '{session_id}' started (PID {process.pid})\n\n"
+            f"Command: {command}\n\n"
+            f"Use read action to see output. Use send to send input. Use stop to terminate."
+        )
+
+    def _read(self, session_id: str, lines: int) -> str:
+        session = self._get_session(session_id)
+        if not session:
+            return f"Error: No session named '{session_id}'. Use list to see active sessions."
+
+        log_path = session["log_path"]
+        alive = self._session_alive(session)
+        status = "running" if alive else f"exited (code {session['process'].returncode})"
+
+        try:
+            with open(log_path, "rb") as f:
+                content = f.read()
+
+            text = content.decode("utf-8", errors="replace")
+            output_lines = text.splitlines()
+
+            if not output_lines:
+                return f"[Session '{session_id}' — {status}]\nNo output yet."
+
+            tail = output_lines[-lines:]
+            skipped = max(0, len(output_lines) - lines)
+            prefix = f"[... {skipped} earlier lines omitted ...]\n" if skipped else ""
+
+            return f"[Session '{session_id}' — {status}]\n\n{prefix}" + "\n".join(tail)
+
+        except Exception as e:
+            return f"Error reading session '{session_id}' output: {e}"
+
+    def _send(self, session_id: str, input_text: str) -> str:
+        session = self._get_session(session_id)
+        if not session:
+            return f"Error: No session named '{session_id}'."
+
+        if not self._session_alive(session):
+            return f"Error: Session '{session_id}' is no longer running."
+
+        process = session["process"]
+        if not process.stdin:
+            return f"Error: Session '{session_id}' does not have an open stdin pipe."
+
+        try:
+            encoded = input_text.encode("utf-8")
+            process.stdin.write(encoded)
+            process.stdin.flush()
+            return f"✓ Sent to '{session_id}': {repr(input_text)}"
+        except Exception as e:
+            return f"Error sending input to '{session_id}': {e}"
+
+    def _stop(self, session_id: str) -> str:
+        session = self._get_session(session_id)
+        if not session:
+            return f"Error: No session named '{session_id}'."
+
+        process = session["process"]
+        if not self._session_alive(session):
+            with _LOCK:
+                _SESSIONS.pop(session_id, None)
+            return f"Session '{session_id}' was already stopped."
+
+        try:
+            process.terminate()
+            try:
+                process.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                process.wait()
+
+            # Clean up log file
+            log_path = session.get("log_path", "")
+            try:
+                if log_path and os.path.exists(log_path):
+                    os.unlink(log_path)
+            except Exception:
+                pass
+
+            with _LOCK:
+                _SESSIONS.pop(session_id, None)
+
+            return f"✓ Session '{session_id}' stopped."
+
+        except Exception as e:
+            return f"Error stopping session '{session_id}': {e}"
+
+    def _list(self) -> str:
+        with _LOCK:
+            sessions = dict(_SESSIONS)
+
+        if not sessions:
+            return "No active sessions."
+
+        lines = ["Active sessions:\n"]
+        for sid, s in sessions.items():
+            alive = s["process"].poll() is None
+            status = "● running" if alive else f"✗ exited ({s['process'].returncode})"
+            lines.append(f"  {sid:20s} {status:20s}  {s['command']}")
+
+        return "\n".join(lines)
+
+    # ── dispatch ─────────────────────────────────────────────────────────────
+
+    def run(self, arguments: dict[str, Any]) -> Any:
+        action = (arguments.get("action") or "").lower().strip()
+        session_id = (arguments.get("session_id") or "").strip()
+        command = arguments.get("command", "")
+        input_text = arguments.get("input", "")
+        lines = int(arguments.get("lines") or 50)
+
+        if action == "list":
+            return self._list()
+
+        if not session_id:
+            return "Error: session_id is required for this action."
+
+        if action == "start":
+            if not command:
+                return "Error: command is required for 'start'."
+            return self._start(session_id, command)
+
+        elif action == "read":
+            return self._read(session_id, lines)
+
+        elif action == "send":
+            if input_text is None:
+                return "Error: input is required for 'send'."
+            return self._send(session_id, input_text)
+
+        elif action == "stop":
+            return self._stop(session_id)
+
+        else:
+            return (
+                f"Error: Unknown action '{action}'. Valid actions: start, read, send, stop, list."
+            )

tools/websearch.py

@@ -0,0 +1,166 @@
+"""Web search tool using DuckDuckGo (no API key required)."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from tools.base import Tool
+
+try:
+    from duckduckgo_search import DDGS
+
+    DDGS_AVAILABLE = True
+except ImportError:
+    DDGS_AVAILABLE = False
+
+
+class WebSearchSchema(BaseModel):
+    query: str = Field(..., description="The search query to look up on the web")
+    max_results: int = Field(5, description="Maximum number of results to return (1-10)")
+
+
+class WebSearchTool(Tool):
+    """
+    Search the web using DuckDuckGo.
+
+    Use this tool when you need:
+    - Current information (news, recent events)
+    - Documentation or API references
+    - Solutions to programming problems
+    - Package/library information
+    - Any information you're unsure about
+    """
+
+    name = "websearch"
+    description = """Search the web for current information. Use when you need:
+- Up-to-date information (news, releases, docs)
+- Programming solutions or best practices
+- Package/library documentation
+- Any factual information you're uncertain about"""
+
+    args_schema = WebSearchSchema
+
+    def run(self, arguments: dict[str, Any]) -> str:
+        if not DDGS_AVAILABLE:
+            return "Error: Web search not available. Install with: pip install duckduckgo-search"
+
+        query = arguments.get("query", "")
+        max_results = min(max(arguments.get("max_results", 5), 1), 10)
+
+        if not query:
+            return "Error: No search query provided."
+
+        try:
+            results = self._search(query, max_results)
+
+            if not results:
+                return f"No results found for: {query}"
+
+            # Format results
+            output = f"Search results for: {query}\n\n"
+
+            for i, result in enumerate(results, 1):
+                title = result.get("title", "No title")
+                url = result.get("href", result.get("link", ""))
+                snippet = result.get("body", result.get("snippet", ""))
+
+                output += f"{i}. **{title}**\n"
+                if url:
+                    output += f"   URL: {url}\n"
+                if snippet:
+                    output += f"   {snippet}\n"
+                output += "\n"
+
+            return output.strip()
+
+        except Exception as e:
+            return f"Error searching: {str(e)}"
+
+    def _search(self, query: str, max_results: int) -> list[dict]:
+        """Perform the actual search."""
+        with DDGS() as ddgs:
+            results = list(ddgs.text(query, max_results=max_results))
+            return results
+
+
+class WebFetchSchema(BaseModel):
+    url: str = Field(..., description="The URL to fetch content from")
+
+
+class WebFetchTool(Tool):
+    """
+    Fetch and read content from a URL.
+
+    Use this tool to read documentation pages, articles, or any web content.
+    """
+
+    name = "webfetch"
+    description = """Fetch and read content from a specific URL. Use when:
+- You need to read a documentation page
+- User provides a specific URL to check
+- You found a relevant URL from search results"""
+
+    args_schema = WebFetchSchema
+
+    def run(self, arguments: dict[str, Any]) -> str:
+        url = arguments.get("url", "")
+
+        if not url:
+            return "Error: No URL provided."
+
+        try:
+            import httpx
+
+            # Fetch the page
+            headers = {"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"}
+
+            with httpx.Client(timeout=15.0, follow_redirects=True) as client:
+                response = client.get(url, headers=headers)
+                response.raise_for_status()
+                html = response.text
+
+            # Simple HTML to text conversion
+            text = self._html_to_text(html)
+
+            # Truncate if too long
+            max_length = 4000
+            if len(text) > max_length:
+                text = text[:max_length] + "\n\n[Content truncated...]"
+
+            return f"Content from {url}:\n\n{text}"
+
+        except Exception as e:
+            return f"Error fetching URL: {str(e)}"
+
+    def _html_to_text(self, html: str) -> str:
+        """Convert HTML to readable text."""
+        import re
+        from html import unescape
+
+        # Remove script and style elements
+        html = re.sub(r"<script[^>]*>.*?</script>", "", html, flags=re.DOTALL | re.IGNORECASE)
+        html = re.sub(r"<style[^>]*>.*?</style>", "", html, flags=re.DOTALL | re.IGNORECASE)
+
+        # Remove HTML comments
+        html = re.sub(r"<!--.*?-->", "", html, flags=re.DOTALL)
+
+        # Replace common elements with newlines
+        html = re.sub(r"<br[^>]*>", "\n", html, flags=re.IGNORECASE)
+        html = re.sub(r"<p[^>]*>", "\n\n", html, flags=re.IGNORECASE)
+        html = re.sub(r"<div[^>]*>", "\n", html, flags=re.IGNORECASE)
+        html = re.sub(r"<h[1-6][^>]*>", "\n\n", html, flags=re.IGNORECASE)
+        html = re.sub(r"</h[1-6]>", "\n", html, flags=re.IGNORECASE)
+        html = re.sub(r"<li[^>]*>", "\n- ", html, flags=re.IGNORECASE)
+
+        # Remove all other HTML tags
+        html = re.sub(r"<[^>]+>", "", html)
+
+        # Unescape HTML entities
+        text = unescape(html)
+
+        # Clean up whitespace
+        text = re.sub(r"\n\s*\n", "\n\n", text)
+        text = re.sub(r" +", " ", text)
+        text = text.strip()
+
+        return text

utils/logger.py

@@ -0,0 +1,52 @@
+import logging
+
+from rich.console import Console
+from rich.panel import Panel
+
+# Global rich console instance
+console = Console()
+
+
+def setup_logger(name: str) -> logging.Logger:
+    """Sets up a standard python logger if needed for file logging, etc."""
+    logger = logging.getLogger(name)
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        formatter = logging.Formatter("%(name)s - %(levelname)s - %(message)s")
+        handler.setFormatter(formatter)
+        logger.addHandler(handler)
+        logger.setLevel(logging.INFO)
+    return logger
+
+
+def print_error(msg: str):
+    """Prints an error message in bold red."""
+    console.print(f"[bold red]Error: {msg}[/bold red]")
+
+
+def print_warning(msg: str):
+    """Prints a warning message in bold yellow."""
+    console.print(f"[bold yellow]Warning: {msg}[/bold yellow]")
+
+
+def print_success(msg: str):
+    """Prints a success message in bold green."""
+    console.print(f"[bold green]{msg}[/bold green]")
+
+
+def print_info(msg: str):
+    """Prints an info message in blue."""
+    console.print(f"[blue]{msg}[/blue]")
+
+
+def print_panel(content, title: str = "", border_style: str = "blue", fit: bool = False):
+    """Prints a rich Panel."""
+    if fit:
+        console.print(Panel.fit(content, title=title, border_style=border_style))
+    else:
+        console.print(Panel(content, title=title, border_style=border_style))
+
+
+def get_console() -> Console:
+    """Returns the global rich Console instance to be used for status spinners, etc."""
+    return console