caudate-cli 0.1.0__py3-none-any.whl

execution/tools/grep_tool.py

@@ -0,0 +1,89 @@
+"""Grep tool — regex content search across files."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from core.schemas import ToolResult
+from execution.tools.base import BaseTool
+
+
+class GrepTool(BaseTool):
+    name = "Grep"
+    description = (
+        "Search for a regex pattern across files. Returns matching lines "
+        "with file:line:text. Supports include-glob filtering."
+    )
+
+    @property
+    def input_schema(self) -> dict:
+        return {
+            "type": "object",
+            "properties": {
+                "pattern": {
+                    "type": "string",
+                    "description": "Regex pattern to search for",
+                },
+                "path": {
+                    "type": "string",
+                    "description": "Root directory to search. Defaults to cwd.",
+                },
+                "include": {
+                    "type": "string",
+                    "description": "Glob to restrict files, e.g. '**/*.py'",
+                    "default": "**/*",
+                },
+                "case_insensitive": {
+                    "type": "boolean",
+                    "description": "If true, ignore case. Default false.",
+                    "default": False,
+                },
+                "limit": {
+                    "type": "integer",
+                    "description": "Maximum matching lines to return (default 200)",
+                    "default": 200,
+                },
+            },
+            "required": ["pattern"],
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        pattern = kwargs.get("pattern", "")
+        if not pattern:
+            return self._error("No pattern provided")
+
+        root = Path(kwargs.get("path") or ".").resolve()
+        include = kwargs.get("include", "**/*")
+        flags = re.IGNORECASE if kwargs.get("case_insensitive") else 0
+        limit = int(kwargs.get("limit", 200))
+
+        try:
+            regex = re.compile(pattern, flags)
+        except re.error as e:
+            return self._error(f"Invalid regex: {e}")
+
+        matches: list[str] = []
+        try:
+            for path in root.glob(include):
+                if not path.is_file():
+                    continue
+                try:
+                    # Skip obviously binary files
+                    text = path.read_text(errors="ignore")
+                except Exception:
+                    continue
+                for i, line in enumerate(text.splitlines(), 1):
+                    if regex.search(line):
+                        matches.append(f"{path}:{i}: {line.rstrip()}")
+                        if len(matches) >= limit:
+                            break
+                if len(matches) >= limit:
+                    break
+        except Exception as e:
+            return self._error(str(e))
+
+        if not matches:
+            return self._success(f"No matches for /{pattern}/ in {root}/{include}")
+        return self._success("\n".join(matches))

execution/tools/http_request_tool.py

@@ -0,0 +1,224 @@
+"""HttpRequest — generic REST tool for any HTTP API.
+
+Inspired by the Vercel AI SDK's universal-tool pattern: instead of
+writing a custom tool per service, give the LLM one well-shaped HTTP
+tool and let it figure out the right URL/headers/body for whatever
+API the user names.
+
+Safety:
+  - Defaults timeout to 30s
+  - Caps response size (so a 1GB response can't OOM the agent)
+  - No follow-redirects to private network ranges by default (basic
+    SSRF guard — overridable for advanced users)
+  - Body size limited
+  - Only HTTP/HTTPS schemes accepted
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import json
+import logging
+import re
+import socket
+from typing import Any
+from urllib.parse import urlparse
+
+import httpx
+
+from core.schemas import ToolResult
+from execution.tools.base import BaseTool
+
+logger = logging.getLogger(__name__)
+
+
+_ALLOWED_METHODS = frozenset(("GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"))
+_MAX_RESPONSE_BYTES = 5 * 1024 * 1024   # 5 MB
+
+
+def _is_private_host(host: str) -> bool:
+    """Return True if the hostname resolves into a private network
+    range (RFC1918, link-local, loopback, IPv6 ULA, etc). Used as a
+    basic SSRF guard so the LLM can't accidentally probe localhost
+    services or the user's LAN."""
+    try:
+        ip = ipaddress.ip_address(host)
+    except ValueError:
+        # Not a literal IP — try DNS lookup. Multiple A records may
+        # come back; conservatively flag as private if ANY of them is.
+        try:
+            infos = socket.getaddrinfo(host, None)
+        except OSError:
+            return False
+        for info in infos:
+            sockaddr = info[4]
+            try:
+                if ipaddress.ip_address(sockaddr[0]).is_private:
+                    return True
+                if ipaddress.ip_address(sockaddr[0]).is_loopback:
+                    return True
+                if ipaddress.ip_address(sockaddr[0]).is_link_local:
+                    return True
+            except ValueError:
+                continue
+        return False
+    return ip.is_private or ip.is_loopback or ip.is_link_local
+
+
+class HttpRequestTool(BaseTool):
+    mutates = True
+    name = "HttpRequest"
+    description = (
+        "Make a generic HTTP request to any public API. Use when the "
+        "user asks to interact with a service that doesn't have a "
+        "dedicated Cognos tool — e.g. 'fetch this Stripe customer', "
+        "'POST to my webhook', 'get the GitHub rate limit'. Specify "
+        "method, URL, headers (auth tokens go here), and optional "
+        "JSON body. Doesn't follow links into private networks by "
+        "default; set `allow_private=true` ONLY if the user explicitly "
+        "wants to hit localhost/LAN."
+    )
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "method": {
+                    "type": "string",
+                    "enum": list(_ALLOWED_METHODS),
+                    "description": "HTTP method.",
+                },
+                "url": {
+                    "type": "string",
+                    "description": "Full URL (must be http:// or https://).",
+                },
+                "headers": {
+                    "type": "object",
+                    "description": "Optional headers as a JSON object. Auth tokens go here.",
+                    "additionalProperties": {"type": "string"},
+                },
+                "body_json": {
+                    "type": "object",
+                    "description": "Optional JSON request body (sent as application/json).",
+                },
+                "body_text": {
+                    "type": "string",
+                    "description": "Optional raw text request body. Use body_json or body_text, not both.",
+                },
+                "timeout_s": {
+                    "type": "number",
+                    "description": "Timeout in seconds (default 30, max 120).",
+                },
+                "allow_private": {
+                    "type": "boolean",
+                    "description": "Set true only when explicitly hitting localhost/LAN endpoints.",
+                    "default": False,
+                },
+            },
+            "required": ["method", "url"],
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        method = (kwargs.get("method") or "").upper().strip()
+        url = (kwargs.get("url") or "").strip()
+        headers = kwargs.get("headers") or {}
+        body_json = kwargs.get("body_json")
+        body_text = kwargs.get("body_text")
+        timeout_s = float(kwargs.get("timeout_s") or 30.0)
+        allow_private = bool(kwargs.get("allow_private") or False)
+
+        # Validate
+        if method not in _ALLOWED_METHODS:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"unsupported method {method!r}",
+            )
+        timeout_s = max(1.0, min(120.0, timeout_s))
+        parsed = urlparse(url)
+        if parsed.scheme not in ("http", "https"):
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"only http/https schemes allowed, got {parsed.scheme!r}",
+            )
+        if not parsed.hostname:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="missing hostname in URL",
+            )
+        if not allow_private and _is_private_host(parsed.hostname):
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=(f"refusing to call private host {parsed.hostname!r}; "
+                       f"set allow_private=true if you really mean it"),
+            )
+        if body_json is not None and body_text is not None:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="provide body_json OR body_text, not both",
+            )
+
+        # Send
+        request_kwargs: dict[str, Any] = {
+            "method":   method,
+            "url":      url,
+            "headers":  dict(headers) if headers else None,
+            "timeout":  timeout_s,
+        }
+        if body_json is not None:
+            request_kwargs["json"] = body_json
+        elif body_text is not None:
+            request_kwargs["content"] = body_text
+
+        try:
+            async with httpx.AsyncClient(follow_redirects=True) as client:
+                resp = await client.request(**request_kwargs)
+        except httpx.TimeoutException:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"timed out after {timeout_s}s",
+            )
+        except httpx.RequestError as e:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"network error: {e}",
+            )
+
+        # Read body, capped
+        body_bytes = resp.content[:_MAX_RESPONSE_BYTES]
+        truncated = len(resp.content) > _MAX_RESPONSE_BYTES
+        ctype = resp.headers.get("content-type", "")
+
+        # Decode best-effort
+        body_repr: Any
+        if "json" in ctype:
+            try:
+                body_repr = json.loads(body_bytes.decode("utf-8", errors="replace"))
+                body_str = json.dumps(body_repr, indent=2)[:4000]
+            except Exception:
+                body_str = body_bytes.decode("utf-8", errors="replace")[:4000]
+                body_repr = body_str
+        elif ctype.startswith("text/") or "html" in ctype or "xml" in ctype:
+            body_str = body_bytes.decode("utf-8", errors="replace")[:4000]
+            body_repr = body_str
+        else:
+            body_str = f"<binary {ctype} {len(body_bytes)}B>"
+            body_repr = None
+
+        out = (
+            f"{method} {url}\n"
+            f"  status:  {resp.status_code} {resp.reason_phrase}\n"
+            f"  type:    {ctype or '?'}\n"
+            f"  bytes:   {len(resp.content)}{' (truncated)' if truncated else ''}\n"
+            f"\n--- body ---\n{body_str}"
+        )
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output=out,
+            metadata={
+                "status_code": resp.status_code,
+                "headers":     dict(resp.headers),
+                "body":        body_repr,
+                "url":         str(resp.url),
+            },
+        )

execution/tools/load_skill_tool.py

@@ -0,0 +1,104 @@
+"""LoadSkill — fetch the full body of an installed skill.
+
+Skills are listed in the system prompt as a TOC (just name +
+description) to keep prompt size bounded. When the LLM decides a
+skill is relevant for the current turn, it calls this tool to get
+the full markdown instructions for that skill.
+
+Companion to `core/skills.py`. Reload via `RescanSkills` after the
+user runs `npx skills add ...`.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from core.schemas import ToolResult
+from core.skills import get_skills, reload_skills
+from execution.tools.base import BaseTool
+
+logger = logging.getLogger(__name__)
+
+
+class LoadSkillTool(BaseTool):
+    name = "LoadSkill"
+    description = (
+        "Fetch the full instructions for an installed skill. The system "
+        "prompt lists skills as a table of contents (name + one-line "
+        "description); call this tool to read the actual markdown body "
+        "of a skill that looks relevant to the current turn. Use the "
+        "exact `name` from the TOC."
+    )
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "description": "Skill name (exact, from the TOC).",
+                },
+            },
+            "required": ["name"],
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        name = (kwargs.get("name") or "").strip()
+        if not name:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="`name` is required",
+            )
+        registry = get_skills()
+        skill = registry.get(name)
+        if skill is None:
+            close = [n for n in registry.list_names()
+                     if name.lower() in n.lower() or n.lower() in name.lower()]
+            hint = (f" did you mean: {close[:5]}?" if close else
+                    f" available: {registry.list_names()[:10]}")
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"skill {name!r} not found.{hint}",
+            )
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output=(
+                f"# {skill.name}\n"
+                f"{skill.description}\n"
+                f"\n---\n\n{skill.body}"
+            ),
+            metadata={
+                "name":        skill.name,
+                "description": skill.description,
+                "path":        str(skill.path),
+                "source_dir":  str(skill.source_dir),
+            },
+        )
+
+
+class RescanSkillsTool(BaseTool):
+    name = "RescanSkills"
+    description = (
+        "Re-scan the skill directories after running `npx skills add` "
+        "or manually adding/removing a skill. Returns the new count + "
+        "list of names."
+    )
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {"type": "object", "properties": {}, "required": []}
+
+    async def execute(self, **_: Any) -> ToolResult:
+        registry = reload_skills()
+        names = registry.list_names()
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output=(
+                f"Rescanned. Found {len(names)} skill(s):\n"
+                + "\n".join(f"  - {n}" for n in names)
+                if names else "Rescanned. No skills found."
+            ),
+            metadata={"count": len(names), "names": names},
+        )