caudate-cli 0.1.0__py3-none-any.whl

execution/tools/python_tool.py

@@ -0,0 +1,61 @@
+"""Python execution tool — run Python code in a subprocess."""
+
+from __future__ import annotations
+
+import asyncio
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from core.schemas import ToolResult
+from execution.tools.base import BaseTool
+
+
+class PythonExecTool(BaseTool):
+    mutates = True
+    name = "PythonExec"
+    description = "Execute Python code in an isolated subprocess and return stdout. Use for calculations, data processing, or testing code snippets."
+
+    @property
+    def input_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "code": {
+                    "type": "string",
+                    "description": "Python code to execute",
+                },
+            },
+            "required": ["code"],
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        code = kwargs.get("code", "")
+        if not code:
+            return self._error("No code provided")
+
+        # Write to temp file and execute in subprocess for isolation
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+            f.write(code)
+            tmp_path = f.name
+
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                "python3", tmp_path,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=30)
+            output = stdout.decode().strip()
+            errors = stderr.decode().strip()
+
+            if proc.returncode == 0:
+                return self._success(output or "(no output)")
+            else:
+                return self._error(f"Exit code {proc.returncode}: {errors}")
+        except asyncio.TimeoutError:
+            return self._error("Execution timed out after 30s")
+        except Exception as e:
+            return self._error(str(e))
+        finally:
+            Path(tmp_path).unlink(missing_ok=True)

execution/tools/respond_tool.py

@@ -0,0 +1,40 @@
+"""Respond tool — present information back to the user."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rich.console import Console
+from rich.panel import Panel
+
+from core.schemas import ToolResult
+from execution.tools.base import BaseTool
+
+console = Console()
+
+
+class RespondTool(BaseTool):
+    name = "Respond"
+    description = "Present a response or answer to the user. Use this to communicate results, explanations, or any information."
+
+    @property
+    def input_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "message": {
+                    "type": "string",
+                    "description": "The message to show the user",
+                },
+            },
+            "required": ["message"],
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        message = kwargs.get("message", "")
+        if not message:
+            return self._error("No message provided")
+
+        console.print(Panel(message, title="Cognos", border_style="green"))
+        preview = message[:100] + "..." if len(message) > 100 else message
+        return self._success(f"Responded to user: {preview}")

execution/tools/sandbox_tool.py

@@ -0,0 +1,378 @@
+"""Sandbox — unified lifecycle + snapshot tool for the local sandbox.
+
+Inspired by Vercel Sandbox's API (`Sandbox.create`, `runCommand`,
+`snapshot`, `stop`, source-from-snapshot). Applied to our LOCAL 50GB
+ext4 loopback at `/home/raveuk/cognos/sandbox/` — no cloud dependency,
+no billing, no Vercel account.
+
+Modes the LLM can use:
+
+  status            — mount state, free space, snapshot count
+  run               — execute a shell command with cwd locked to sandbox/
+  snapshot [label]  — tar+zstd the current sandbox state into a snapshot
+  list_snapshots    — show all snapshots with size + age + label
+  restore <id>      — wipe sandbox + extract a snapshot (auto-checkpoints
+                      the pre-restore state first, so restores are
+                      reversible)
+  delete_snapshot <id> — remove a snapshot artifact
+
+Snapshots live at `~/.cognos/sandbox-snapshots/<id>.tar.zst` with a
+sidecar `.meta.json`. Each `restore` auto-creates an
+`auto-pre-restore-<src>` snapshot first, so a bad restore is just
+another restore away.
+
+The `run` mode is the key isolation primitive: it locks `cwd` to the
+sandbox dir and uses a constrained env, so the LLM can't accidentally
+mutate the rest of the filesystem via this tool. (For full freedom
+the LLM still has the `Bash` tool.)
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from core.schemas import ToolResult
+from execution.tools.base import BaseTool
+
+logger = logging.getLogger(__name__)
+
+
+_SANDBOX_DIR = Path("/home/raveuk/cognos/sandbox")
+_SNAPSHOT_DIR = Path.home() / ".cognos" / "sandbox-snapshots"
+_BIN_DIR = Path("/home/raveuk/cognos/bin")
+_RUN_TIMEOUT_S = 60.0
+
+
+def _fmt_bytes(n: int) -> str:
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if n < 1024 or unit == "TB":
+            return f"{n:.1f}{unit}" if unit != "B" else f"{n}B"
+        n /= 1024
+    return f"{n}TB"
+
+
+def _is_mounted() -> bool:
+    if not _SANDBOX_DIR.exists():
+        return False
+    # /proc/mounts is fastest + always accurate
+    try:
+        with open("/proc/mounts") as f:
+            return any(str(_SANDBOX_DIR) in line for line in f)
+    except OSError:
+        return False
+
+
+def _disk_usage() -> tuple[int, int, int]:
+    """Return (total, used, avail) bytes for the sandbox FS."""
+    s = shutil.disk_usage(_SANDBOX_DIR)
+    return s.total, s.used, s.free
+
+
+def _list_snapshots() -> list[dict[str, Any]]:
+    if not _SNAPSHOT_DIR.exists():
+        return []
+    out: list[dict[str, Any]] = []
+    for archive in sorted(_SNAPSHOT_DIR.glob("*.tar.zst")):
+        sid = archive.stem
+        meta_path = _SNAPSHOT_DIR / f"{sid}.meta.json"
+        meta: dict[str, Any] = {}
+        if meta_path.exists():
+            try:
+                import json
+                meta = json.loads(meta_path.read_text())
+            except Exception:
+                pass
+        out.append({
+            "id":        sid,
+            "label":     meta.get("label", "-"),
+            "created":   meta.get("created_utc", ""),
+            "size_bytes": archive.stat().st_size,
+            "path":      str(archive),
+        })
+    return out
+
+
+class SandboxTool(BaseTool):
+    mutates = True
+    name = "Sandbox"
+    description = (
+        "Unified sandbox lifecycle + snapshot tool. The sandbox is a "
+        "50GB ext4 loopback at /home/raveuk/cognos/sandbox/. Modes: "
+        "'status' (mount + disk + snapshot summary), 'run' (execute a "
+        "shell command with cwd locked to the sandbox), 'snapshot' "
+        "(tar+zstd current state to ~/.cognos/sandbox-snapshots/), "
+        "'restore' (wipe + extract a snapshot — auto-checkpoints first "
+        "so it's reversible), 'list_snapshots', 'delete_snapshot'. "
+        "Use 'snapshot' before letting the LLM rewrite a project so "
+        "you can roll back. 'run' for sandbox-scoped commands; for "
+        "full-system commands use the Bash tool instead."
+    )
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "action": {
+                    "type": "string",
+                    "enum": [
+                        "status", "run", "snapshot",
+                        "list_snapshots", "restore", "delete_snapshot",
+                    ],
+                    "description": "What to do.",
+                },
+                "cmd": {
+                    "type": "string",
+                    "description": "For 'run' mode: shell command to execute (cwd locked to sandbox).",
+                },
+                "label": {
+                    "type": "string",
+                    "description": "For 'snapshot' mode: short label for the snapshot.",
+                },
+                "id": {
+                    "type": "string",
+                    "description": "For 'restore' / 'delete_snapshot' mode: snapshot id.",
+                },
+                "timeout_s": {
+                    "type": "number",
+                    "description": "For 'run' mode: timeout in seconds (default 60, max 300).",
+                },
+            },
+            "required": ["action"],
+        }
+
+    # -- mode dispatch ---------------------------------------------------
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        action = (kwargs.get("action") or "").lower().strip()
+        try:
+            if action == "status":
+                return self._status()
+            if action == "run":
+                return await self._run(kwargs)
+            if action == "snapshot":
+                return self._snapshot(kwargs)
+            if action == "list_snapshots":
+                return self._list_snapshots()
+            if action == "restore":
+                return self._restore(kwargs)
+            if action == "delete_snapshot":
+                return self._delete_snapshot(kwargs)
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"unknown action {action!r}; expected one of: status, run, snapshot, list_snapshots, restore, delete_snapshot",
+            )
+        except Exception as e:
+            logger.exception("Sandbox tool failed")
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"{type(e).__name__}: {e}",
+            )
+
+    # -- modes -----------------------------------------------------------
+
+    def _status(self) -> ToolResult:
+        mounted = _is_mounted()
+        snapshots = _list_snapshots()
+        out_lines = [f"sandbox path:  {_SANDBOX_DIR}"]
+        out_lines.append(f"  mounted:     {mounted}")
+        if mounted:
+            total, used, avail = _disk_usage()
+            out_lines.append(
+                f"  disk usage:  {_fmt_bytes(used)} used / {_fmt_bytes(total)} total "
+                f"({_fmt_bytes(avail)} free)"
+            )
+        out_lines.append(f"snapshots:    {len(snapshots)} stored at {_SNAPSHOT_DIR}")
+        if snapshots:
+            recent = snapshots[-3:]
+            for s in recent:
+                out_lines.append(
+                    f"  - {s['id']}  ({_fmt_bytes(s['size_bytes'])})  {s['label']}"
+                )
+            if len(snapshots) > 3:
+                out_lines.append(f"  ... and {len(snapshots) - 3} more (use list_snapshots)")
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output="\n".join(out_lines),
+            metadata={
+                "mounted":   mounted,
+                "snapshot_count": len(snapshots),
+            },
+        )
+
+    async def _run(self, kwargs: dict) -> ToolResult:
+        cmd = (kwargs.get("cmd") or "").strip()
+        if not cmd:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="`cmd` is required for run mode",
+            )
+        if not _is_mounted():
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"sandbox not mounted at {_SANDBOX_DIR}",
+            )
+        timeout = max(1.0, min(300.0, float(kwargs.get("timeout_s") or _RUN_TIMEOUT_S)))
+
+        # cwd locked to the sandbox; env minimal so commands don't pick
+        # up the user's full shell setup
+        env = {
+            "HOME":     str(_SANDBOX_DIR),
+            "PATH":     "/usr/local/bin:/usr/bin:/bin",
+            "USER":     os.environ.get("USER", "raveuk"),
+            "LANG":     "C.UTF-8",
+            "TMPDIR":   str(_SANDBOX_DIR / ".tmp"),
+        }
+        (_SANDBOX_DIR / ".tmp").mkdir(exist_ok=True)
+
+        try:
+            proc = await asyncio.create_subprocess_shell(
+                cmd,
+                cwd=str(_SANDBOX_DIR),
+                env=env,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            stdout_b, stderr_b = await asyncio.wait_for(
+                proc.communicate(), timeout=timeout
+            )
+        except asyncio.TimeoutError:
+            try: proc.kill()
+            except Exception: pass
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"command timed out after {timeout}s",
+            )
+
+        stdout = stdout_b.decode("utf-8", errors="replace")
+        stderr = stderr_b.decode("utf-8", errors="replace")
+        rc = proc.returncode if proc.returncode is not None else -1
+
+        out = (
+            f"$ {cmd}\n"
+            f"  cwd:  {_SANDBOX_DIR}\n"
+            f"  exit: {rc}\n"
+        )
+        if stdout:
+            out += f"--- stdout ---\n{stdout[:4000]}"
+            if len(stdout) > 4000:
+                out += f"\n... ({len(stdout) - 4000} more chars)"
+        if stderr:
+            out += f"\n--- stderr ---\n{stderr[:2000]}"
+        return ToolResult(
+            tool_name=self.name,
+            status="success" if rc == 0 else "error",
+            output=out.rstrip(),
+            error=None if rc == 0 else f"exit code {rc}",
+            metadata={
+                "exit_code": rc,
+                "stdout":    stdout,
+                "stderr":    stderr,
+            },
+        )
+
+    def _snapshot(self, kwargs: dict) -> ToolResult:
+        label = (kwargs.get("label") or "snapshot").strip()
+        script = _BIN_DIR / "cognos-sandbox-snapshot"
+        if not script.exists():
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"helper script missing: {script}",
+            )
+        try:
+            result = subprocess.run(
+                [str(script), label],
+                capture_output=True, text=True, timeout=300,
+            )
+        except subprocess.TimeoutExpired:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="snapshot timed out (>5 min)",
+            )
+        if result.returncode != 0:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"snapshot failed: {result.stderr or result.stdout}",
+            )
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output=result.stdout.strip(),
+            metadata={"label": label},
+        )
+
+    def _list_snapshots(self) -> ToolResult:
+        snapshots = _list_snapshots()
+        if not snapshots:
+            return ToolResult(
+                tool_name=self.name, status="success",
+                output="no snapshots yet — use action='snapshot' to create one",
+                metadata={"snapshots": []},
+            )
+        lines = [f"{len(snapshots)} snapshot(s):"]
+        for s in snapshots:
+            lines.append(
+                f"  {s['id']}  {_fmt_bytes(s['size_bytes']):>10}  "
+                f"{s['created']}  {s['label']}"
+            )
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output="\n".join(lines),
+            metadata={"snapshots": snapshots},
+        )
+
+    def _restore(self, kwargs: dict) -> ToolResult:
+        sid = (kwargs.get("id") or "").strip()
+        if not sid:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="`id` is required for restore mode",
+            )
+        script = _BIN_DIR / "cognos-sandbox-restore"
+        try:
+            result = subprocess.run(
+                [str(script), sid, "-y"],
+                capture_output=True, text=True, timeout=300,
+            )
+        except subprocess.TimeoutExpired:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="restore timed out (>5 min)",
+            )
+        if result.returncode != 0:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"restore failed: {result.stderr or result.stdout}",
+            )
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output=result.stdout.strip(),
+            metadata={"restored_id": sid},
+        )
+
+    def _delete_snapshot(self, kwargs: dict) -> ToolResult:
+        sid = (kwargs.get("id") or "").strip()
+        if not sid:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="`id` is required for delete_snapshot mode",
+            )
+        archive = _SNAPSHOT_DIR / f"{sid}.tar.zst"
+        meta = _SNAPSHOT_DIR / f"{sid}.meta.json"
+        if not archive.exists():
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"snapshot not found: {sid}",
+            )
+        archive.unlink()
+        meta.unlink(missing_ok=True)
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output=f"deleted snapshot {sid}",
+            metadata={"deleted_id": sid},
+        )

execution/tools/search_tool.py

@@ -0,0 +1,153 @@
+"""WebSearch tool — real web search via DuckDuckGo HTML.
+
+Uses the no-JS HTML endpoint (`html.duckduckgo.com`) which returns a list
+of titled results without needing an API key. Falls back to the instant-
+answer JSON API if the HTML scrape fails (some networks block it).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import html as html_lib
+import json
+import re
+import urllib.parse
+from typing import Any
+
+from core.schemas import ToolResult
+from execution.tools.base import BaseTool
+
+
+# Loose patterns over the rendered HTML. DuckDuckGo's HTML layout is
+# stable enough that these have held for years; if they break, the JSON
+# fallback below still returns *something*.
+_RESULT_BLOCK_RE = re.compile(
+    r'<a[^>]*class="result__a"[^>]*href="([^"]+)"[^>]*>(.*?)</a>'
+    r'(?:.*?<a[^>]*class="result__snippet"[^>]*>(.*?)</a>)?',
+    re.DOTALL,
+)
+_TAG_RE = re.compile(r"<[^>]+>")
+
+
+class WebSearchTool(BaseTool):
+    name = "WebSearch"
+    description = (
+        "Search the web with DuckDuckGo and return ranked results "
+        "(title, URL, snippet). Use to find current information, docs, "
+        "or sources before fetching a specific page with WebFetch."
+    )
+
+    @property
+    def input_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "query": {
+                    "type": "string",
+                    "description": "The search query",
+                },
+                "max_results": {
+                    "type": "integer",
+                    "description": "Max results to return (default 8)",
+                    "default": 8,
+                },
+            },
+            "required": ["query"],
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        query = (kwargs.get("query") or "").strip()
+        if not query:
+            return self._error("No query provided")
+        max_results = max(1, int(kwargs.get("max_results", 8)))
+
+        # 1. Real HTML results
+        try:
+            html = await _curl(
+                f"https://html.duckduckgo.com/html/?q={urllib.parse.quote(query)}",
+                method="POST",
+                data=f"q={urllib.parse.quote(query)}",
+            )
+        except Exception as e:
+            html = ""
+
+        results = _parse_html_results(html, max_results) if html else []
+
+        # 2. Fallback to instant-answer JSON if HTML scrape produced nothing
+        if not results:
+            try:
+                raw = await _curl(
+                    f"https://api.duckduckgo.com/?q={urllib.parse.quote(query)}"
+                    f"&format=json&no_html=1",
+                )
+                data = json.loads(raw) if raw else {}
+            except Exception:
+                data = {}
+            if data.get("Abstract"):
+                results.append({
+                    "title": data.get("AbstractSource", "Summary"),
+                    "url": data.get("AbstractURL", ""),
+                    "snippet": data["Abstract"],
+                })
+            for topic in data.get("RelatedTopics", [])[:max_results]:
+                if isinstance(topic, dict) and topic.get("Text"):
+                    results.append({
+                        "title": topic.get("Text", "")[:80],
+                        "url": topic.get("FirstURL", ""),
+                        "snippet": topic.get("Text", ""),
+                    })
+
+        if not results:
+            return self._success(f"No results found for: {query}")
+
+        lines = [f"# Search results for: {query}", ""]
+        for i, r in enumerate(results, 1):
+            lines.append(f"{i}. **{r['title']}**")
+            if r.get("url"):
+                lines.append(f"   {r['url']}")
+            if r.get("snippet"):
+                lines.append(f"   {r['snippet']}")
+            lines.append("")
+        return self._success("\n".join(lines))
+
+
+async def _curl(
+    url: str, method: str = "GET", data: str | None = None,
+) -> str:
+    """Run curl in a subprocess, return decoded body (best effort)."""
+    args = [
+        "curl", "-sSL", "--max-time", "20",
+        "-A", "Mozilla/5.0 (cognos)",
+    ]
+    if method == "POST":
+        args += ["-X", "POST"]
+    if data:
+        args += ["--data", data]
+    args.append(url)
+    proc = await asyncio.create_subprocess_exec(
+        *args,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+    stdout, _ = await asyncio.wait_for(proc.communicate(), timeout=22)
+    return stdout.decode(errors="ignore")
+
+
+def _parse_html_results(html: str, limit: int) -> list[dict[str, str]]:
+    out: list[dict[str, str]] = []
+    for match in _RESULT_BLOCK_RE.finditer(html):
+        url = match.group(1)
+        # DDG wraps real urls in /l/?uddg=<encoded>
+        if "uddg=" in url:
+            try:
+                qs = urllib.parse.parse_qs(urllib.parse.urlparse(url).query)
+                url = qs.get("uddg", [url])[0]
+            except Exception:
+                pass
+        title = html_lib.unescape(_TAG_RE.sub("", match.group(2) or "")).strip()
+        snippet = html_lib.unescape(_TAG_RE.sub("", match.group(3) or "")).strip()
+        if title and url:
+            out.append({"title": title, "url": url, "snippet": snippet})
+        if len(out) >= limit:
+            break
+    return out