caudate-cli 0.1.0__py3-none-any.whl

execution/tools/openapi_tool.py

@@ -0,0 +1,440 @@
+"""OpenAPI — universal REST adapter from any OpenAPI 3 spec.
+
+Inspired by the Vercel AI SDK's "AI Tool Maker" (generate tools from
+OpenAPI specs). Works against any documented REST API: pass a spec
+URL, browse its operations, then call them.
+
+This is the universal escape hatch when a service has an OpenAPI/
+Swagger spec but no Cognos-native or Agentic-marketplace tool. Single
+HTTP call to fetch the spec, all operations become callable.
+
+Modes:
+  - `browse`  : list operations in a spec (operation_id, method, path, summary)
+  - `call`    : execute one operation by operation_id with params
+  - `describe`: full input schema + parameter descriptions for one operation
+
+Optional auth: `bearer_token` or `headers` parameter; both are
+forwarded with the request. Specs are cached for 10 min so repeated
+calls don't re-fetch.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import time
+from typing import Any
+from urllib.parse import urljoin, urlparse
+
+import httpx
+
+from core.schemas import ToolResult
+from execution.tools.base import BaseTool
+
+logger = logging.getLogger(__name__)
+
+
+_DEFAULT_TIMEOUT_S = 30.0
+_SPEC_TTL_S = 600.0           # cache OpenAPI specs for 10 min
+_MAX_BODY_BYTES = 5 * 1024 * 1024
+
+
+# In-memory spec cache: spec_url → (fetched_at, parsed_spec)
+_CACHE: dict[str, tuple[float, dict[str, Any]]] = {}
+
+
+# ---------------------------------------------------------------------
+# Spec loading
+# ---------------------------------------------------------------------
+
+
+async def _load_spec(spec_url: str) -> dict[str, Any]:
+    """Fetch + parse an OpenAPI spec; cached. Supports JSON and YAML."""
+    now = time.time()
+    cached = _CACHE.get(spec_url)
+    if cached and (now - cached[0]) < _SPEC_TTL_S:
+        return cached[1]
+
+    async with httpx.AsyncClient(timeout=_DEFAULT_TIMEOUT_S) as client:
+        resp = await client.get(spec_url, follow_redirects=True)
+    resp.raise_for_status()
+    text = resp.text
+
+    # Detect JSON vs YAML by content sniffing first; fall back on extension.
+    ctype = resp.headers.get("content-type", "")
+    parsed: dict[str, Any]
+    text_stripped = text.strip()
+    if text_stripped.startswith("{") or "json" in ctype:
+        parsed = json.loads(text)
+    else:
+        try:
+            import yaml
+            parsed = yaml.safe_load(text)
+        except ImportError:
+            raise RuntimeError(
+                "spec appears to be YAML but PyYAML is not installed; "
+                "use a JSON spec or `pip install pyyaml`"
+            )
+
+    if not isinstance(parsed, dict):
+        raise ValueError("spec did not parse to a JSON object")
+    if not parsed.get("openapi") and not parsed.get("swagger"):
+        raise ValueError(
+            "document does not look like an OpenAPI/Swagger spec "
+            "(missing `openapi` / `swagger` key)"
+        )
+    _CACHE[spec_url] = (now, parsed)
+    return parsed
+
+
+def _server_base_url(spec: dict[str, Any], spec_url: str) -> str:
+    """Resolve the server base URL: spec.servers[0].url, falling back to
+    the host of the spec URL itself."""
+    servers = spec.get("servers") or []
+    if servers and isinstance(servers, list):
+        url = (servers[0].get("url") or "").strip()
+        if url:
+            # If relative (some specs do this), join with spec URL host
+            if url.startswith("/") or not urlparse(url).scheme:
+                p = urlparse(spec_url)
+                return f"{p.scheme}://{p.netloc}{url if url.startswith('/') else '/' + url}"
+            return url
+    # Swagger 2.0: host + basePath + schemes
+    host = spec.get("host")
+    base_path = spec.get("basePath", "") or ""
+    schemes = spec.get("schemes") or ["https"]
+    if host:
+        return f"{schemes[0]}://{host}{base_path}"
+    # Last resort: use the spec URL's origin
+    p = urlparse(spec_url)
+    return f"{p.scheme}://{p.netloc}"
+
+
+def _iter_operations(spec: dict[str, Any]):
+    """Yield (operation_id, method, path, op_dict) for each operation."""
+    paths = spec.get("paths") or {}
+    for path, item in paths.items():
+        if not isinstance(item, dict):
+            continue
+        for method in ("get", "post", "put", "patch", "delete", "head", "options"):
+            op = item.get(method)
+            if not isinstance(op, dict):
+                continue
+            op_id = op.get("operationId") or _slug(f"{method}_{path}")
+            yield op_id, method.upper(), path, op
+
+
+def _slug(s: str) -> str:
+    return re.sub(r"[^a-zA-Z0-9_]+", "_", s).strip("_")
+
+
+def _find_operation(spec: dict[str, Any], operation_id: str
+                    ) -> tuple[str, str, dict[str, Any]] | None:
+    for op_id, method, path, op in _iter_operations(spec):
+        if op_id == operation_id:
+            return method, path, op
+    return None
+
+
+def _build_url_and_body(
+    base_url: str, path: str, method: str,
+    op: dict[str, Any], params: dict[str, Any],
+) -> tuple[str, dict[str, Any], dict[str, Any], Any]:
+    """Substitute path params, split out query params, locate the body.
+
+    Returns (url, query, header_overrides, body).
+    """
+    parameters = op.get("parameters") or []
+    path_params: dict[str, str] = {}
+    query: dict[str, Any] = {}
+    header_overrides: dict[str, Any] = {}
+
+    consumed = set()
+    for pdef in parameters:
+        loc = pdef.get("in")
+        name = pdef.get("name")
+        if name not in params:
+            continue
+        if loc == "path":
+            path_params[name] = str(params[name])
+            consumed.add(name)
+        elif loc == "query":
+            query[name] = params[name]
+            consumed.add(name)
+        elif loc == "header":
+            header_overrides[name] = str(params[name])
+            consumed.add(name)
+        # cookie params: not commonly used by LLMs; skip
+
+    # Path substitution
+    rendered_path = path
+    for k, v in path_params.items():
+        rendered_path = rendered_path.replace("{" + k + "}", v)
+    url = base_url.rstrip("/") + "/" + rendered_path.lstrip("/")
+
+    # Body: anything in params not consumed by parameters[] and the op
+    # has a requestBody, treat the rest as the body
+    body: Any = None
+    if method in ("POST", "PUT", "PATCH") and op.get("requestBody"):
+        leftover = {k: v for k, v in params.items() if k not in consumed}
+        # If user passed `body` explicitly, use that
+        body = params.get("body", leftover or None)
+
+    return url, query, header_overrides, body
+
+
+# ---------------------------------------------------------------------
+# Tool
+# ---------------------------------------------------------------------
+
+
+class OpenAPITool(BaseTool):
+    name = "OpenAPI"
+    description = (
+        "Universal REST adapter for any service with an OpenAPI 3 (or "
+        "Swagger 2) spec. Three modes: 'browse' lists all operations "
+        "in a spec; 'describe' shows one operation's input schema; "
+        "'call' executes an operation by operation_id with params. "
+        "Use this when the service has a documented spec but no "
+        "Cognos-native or marketplace tool. Pass `bearer_token` or "
+        "`headers` for auth."
+    )
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "action": {
+                    "type": "string",
+                    "enum": ["browse", "describe", "call"],
+                    "description": "What to do: list ops / show one op's schema / execute one op.",
+                },
+                "spec_url": {
+                    "type": "string",
+                    "description": "URL to the OpenAPI/Swagger spec (JSON or YAML).",
+                },
+                "operation_id": {
+                    "type": "string",
+                    "description": "For describe/call: the operation_id from the spec.",
+                },
+                "params": {
+                    "type": "object",
+                    "description": "For call: parameter values keyed by parameter name. Path/query/header params are routed automatically; anything left over for POST/PUT/PATCH becomes the JSON body (or pass `body` explicitly).",
+                },
+                "bearer_token": {
+                    "type": "string",
+                    "description": "Optional: forwarded as `Authorization: Bearer <token>`.",
+                },
+                "headers": {
+                    "type": "object",
+                    "description": "Optional extra request headers (override anything generated automatically).",
+                },
+                "timeout_s": {
+                    "type": "number",
+                    "description": "Override timeout (default 30s, max 120s).",
+                },
+            },
+            "required": ["action", "spec_url"],
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        action = (kwargs.get("action") or "").lower().strip()
+        spec_url = (kwargs.get("spec_url") or "").strip()
+        if not spec_url:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="`spec_url` is required",
+            )
+
+        try:
+            spec = await _load_spec(spec_url)
+        except (httpx.HTTPError, ValueError, RuntimeError) as e:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"failed to load spec: {e}",
+            )
+
+        if action == "browse":
+            return self._browse(spec, spec_url)
+        if action == "describe":
+            return self._describe(spec, kwargs)
+        if action == "call":
+            return await self._call(spec, spec_url, kwargs)
+        return ToolResult(
+            tool_name=self.name, status="error",
+            error=f"unknown action {action!r}; expected browse/describe/call",
+        )
+
+    # -- modes -----------------------------------------------------------
+
+    def _browse(self, spec: dict[str, Any], spec_url: str) -> ToolResult:
+        info = spec.get("info") or {}
+        title = info.get("title") or "(untitled)"
+        version = info.get("version") or "(no version)"
+        base = _server_base_url(spec, spec_url)
+
+        ops: list[dict[str, Any]] = []
+        for op_id, method, path, op in _iter_operations(spec):
+            ops.append({
+                "operation_id": op_id,
+                "method":       method,
+                "path":         path,
+                "summary":      (op.get("summary") or "").strip()[:160],
+                "tags":         op.get("tags") or [],
+            })
+
+        if not ops:
+            return ToolResult(
+                tool_name=self.name, status="success",
+                output=f"{title} ({version}): spec has no operations",
+                metadata={"title": title, "operations": []},
+            )
+
+        lines = [f"{title} ({version}) — {len(ops)} operation(s)",
+                 f"  base url: {base}", ""]
+        for op in ops:
+            tags = f"  [{','.join(op['tags'])}]" if op["tags"] else ""
+            line = f"  {op['method']:6s} {op['path']:50s} → {op['operation_id']}{tags}"
+            lines.append(line)
+            if op["summary"]:
+                lines.append(f"      {op['summary']}")
+
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output="\n".join(lines),
+            metadata={"title": title, "base_url": base, "operations": ops},
+        )
+
+    def _describe(self, spec: dict[str, Any], kwargs: dict) -> ToolResult:
+        op_id = (kwargs.get("operation_id") or "").strip()
+        if not op_id:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="`operation_id` is required for describe",
+            )
+        found = _find_operation(spec, op_id)
+        if not found:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"operation {op_id!r} not in spec",
+            )
+        method, path, op = found
+
+        lines = [
+            f"{method} {path}  →  operation_id={op_id}",
+            f"  summary:     {op.get('summary', '').strip()}",
+            f"  description: {op.get('description', '').strip()[:300]}",
+            f"  tags:        {op.get('tags') or []}",
+        ]
+        params = op.get("parameters") or []
+        if params:
+            lines.append("  parameters:")
+            for pdef in params:
+                req = " (required)" if pdef.get("required") else ""
+                lines.append(
+                    f"    - {pdef.get('name')} (in={pdef.get('in')}, "
+                    f"type={(pdef.get('schema') or {}).get('type', '?')}){req}: "
+                    f"{(pdef.get('description') or '')[:120]}"
+                )
+        rb = op.get("requestBody")
+        if rb:
+            content = (rb.get("content") or {})
+            mime = next(iter(content.keys()), "?")
+            schema = (content.get(mime) or {}).get("schema") or {}
+            lines.append(f"  requestBody ({mime}):")
+            lines.append(f"    schema: {json.dumps(schema, indent=2)[:600]}")
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output="\n".join(lines),
+            metadata={"operation_id": op_id, "method": method, "path": path,
+                      "operation": op},
+        )
+
+    async def _call(self, spec: dict[str, Any], spec_url: str,
+                    kwargs: dict) -> ToolResult:
+        op_id = (kwargs.get("operation_id") or "").strip()
+        params = kwargs.get("params") or {}
+        bearer = (kwargs.get("bearer_token") or "").strip()
+        extra_headers = kwargs.get("headers") or {}
+        timeout = max(1.0, min(120.0, float(kwargs.get("timeout_s") or _DEFAULT_TIMEOUT_S)))
+
+        if not op_id:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="`operation_id` is required for call",
+            )
+        found = _find_operation(spec, op_id)
+        if not found:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"operation {op_id!r} not in spec",
+            )
+        method, path, op = found
+        base = _server_base_url(spec, spec_url)
+        url, query, header_overrides, body = _build_url_and_body(
+            base, path, method, op, params
+        )
+
+        # Merge headers: bearer < spec-derived < user-supplied
+        headers: dict[str, Any] = {}
+        if bearer:
+            headers["Authorization"] = f"Bearer {bearer}"
+        headers.update(header_overrides)
+        headers.update({str(k): str(v) for k, v in extra_headers.items()})
+
+        try:
+            async with httpx.AsyncClient(
+                timeout=timeout, follow_redirects=True
+            ) as client:
+                resp = await client.request(
+                    method, url,
+                    params=query if query else None,
+                    headers=headers if headers else None,
+                    json=body if body is not None else None,
+                )
+        except httpx.TimeoutException:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"timed out after {timeout}s calling {op_id}",
+            )
+        except httpx.RequestError as e:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"network error: {e}",
+            )
+
+        body_bytes = resp.content[:_MAX_BODY_BYTES]
+        ctype = resp.headers.get("content-type", "")
+        if "json" in ctype:
+            try:
+                resp_body = resp.json()
+                body_str = json.dumps(resp_body, indent=2)[:4000]
+            except Exception:
+                body_str = body_bytes.decode("utf-8", errors="replace")[:4000]
+                resp_body = body_str
+        else:
+            body_str = body_bytes.decode("utf-8", errors="replace")[:4000]
+            resp_body = body_str
+
+        out = (
+            f"{method} {url}\n"
+            f"  status: {resp.status_code} {resp.reason_phrase}\n"
+            f"  type:   {ctype}\n"
+            f"\n--- body ---\n{body_str}"
+        )
+        return ToolResult(
+            tool_name=self.name,
+            status="success" if resp.status_code < 400 else "error",
+            output=out,
+            error=None if resp.status_code < 400 else f"HTTP {resp.status_code}",
+            metadata={
+                "operation_id": op_id,
+                "method":       method,
+                "url":          str(resp.url),
+                "status_code":  resp.status_code,
+                "body":         resp_body,
+            },
+        )

execution/tools/plan_mode_tool.py

@@ -0,0 +1,95 @@
+"""Plan Mode tools — toggle the read-only execution mode.
+
+Two tools:
+
+  - **`EnterPlanMode`** — switch ON. Mutating tools (Bash, Write,
+    Edit, NotebookEdit, PythonExec, HttpRequest, Sandbox, etc.)
+    will refuse to run; read-only tools (Read, Grep, Glob,
+    SystemInfo, Calculator, …) keep working. Use when the user
+    wants the agent to *plan* a change and present it before
+    actually applying anything.
+  - **`ExitPlanMode`** — switch OFF. Mutating tools are allowed
+    again. The agent should call this once the user has reviewed
+    and approved the plan.
+
+These are status-flip tools, not blocking prompts — the agent can
+toggle plan mode mid-conversation and the executor's dispatch
+refuses mutators until the next ExitPlanMode.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from core.plan_mode import enter, exit_mode, is_active
+from core.schemas import ToolResult
+from execution.tools.base import BaseTool
+
+
+class EnterPlanModeTool(BaseTool):
+    name = "EnterPlanMode"
+    description = (
+        "Enter plan mode — the executor will refuse any side-effect "
+        "tool (Bash, Write, Edit, NotebookEdit, PythonExec, "
+        "HttpRequest, Sandbox, UpdateMemory, Cron*, Task*, Worktree*, "
+        "Draw, EditImage, Storyboard, Speak, Artifact) until "
+        "ExitPlanMode is called. Read-only tools (Read, Grep, Glob, "
+        "FindAnywhere, SystemInfo, Calculator, DateTime, "
+        "SemanticSearch, DescribeImage, TranscribeAudio, WebSearch, "
+        "WebFetch, CognosCard, Think, AskUserQuestion, "
+        "MCPListServers, TaskList/Get/Output, CronList) keep "
+        "working. Use this when the user wants you to plan first "
+        "and apply changes only after review."
+    )
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {"type": "object", "properties": {}}
+
+    async def execute(self, **_: Any) -> ToolResult:
+        if is_active():
+            return ToolResult(
+                tool_name=self.name, status="success",
+                output="Plan mode is already ON.",
+                metadata={"plan_mode": True, "changed": False},
+            )
+        enter()
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output=(
+                "Plan mode is now ON. Mutating tools are blocked; "
+                "read-only tools still work. Use ExitPlanMode to "
+                "return to normal operation."
+            ),
+            metadata={"plan_mode": True, "changed": True},
+        )
+
+
+class ExitPlanModeTool(BaseTool):
+    name = "ExitPlanMode"
+    description = (
+        "Exit plan mode — re-enable mutating tools. Call this once "
+        "the user has reviewed the planned changes and wants to "
+        "actually apply them."
+    )
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {"type": "object", "properties": {}}
+
+    async def execute(self, **_: Any) -> ToolResult:
+        if not is_active():
+            return ToolResult(
+                tool_name=self.name, status="success",
+                output="Plan mode is already OFF.",
+                metadata={"plan_mode": False, "changed": False},
+            )
+        exit_mode()
+        return ToolResult(
+            tool_name=self.name, status="success",
+            output=(
+                "Plan mode is now OFF. Mutating tools are allowed "
+                "again."
+            ),
+            metadata={"plan_mode": False, "changed": True},
+        )

execution/tools/push_notification_tool.py

@@ -0,0 +1,157 @@
+"""PushNotification — desktop notification when a long job completes.
+
+Sends an OS-level desktop notification so the user sees it even if
+they've alt-tabbed away from the browser/terminal. Tries `notify-send`
+on Linux first (which works under the user's XFCE/GNOME/KDE setup),
+falls back to a terminal bell (BEL char) for headless sessions, and
+returns a clear status either way.
+
+Use cases:
+  - Storyboard finished generating (15-40 min jobs)
+  - Phase-N retrain completed
+  - FLUX-Kontext panel rendered
+  - Anything that takes long enough that the user's attention has
+    drifted elsewhere
+
+Not for chat-turn updates — those go in the response text directly.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import shutil
+import sys
+from typing import Any
+
+from core.schemas import ToolResult
+from execution.tools.base import BaseTool
+
+
+# Urgency mapping to notify-send levels. Same vocabulary FreeDesktop
+# uses, exposed as plain string for clarity.
+_URGENCY_MAP = {
+    "low":      "low",
+    "normal":   "normal",
+    "high":     "critical",   # notify-send calls it "critical"
+    "critical": "critical",
+}
+
+
+class PushNotificationTool(BaseTool):
+    mutates = True
+    name = "PushNotification"
+    description = (
+        "Send a desktop notification to the user. Useful when a "
+        "long-running job (storyboard, FLUX edit, retrain) finishes "
+        "and the user has switched away from the chat. Provide a "
+        "short `title` and optional `message` + `urgency` "
+        "(`low` / `normal` / `high`). Uses `notify-send` on Linux; "
+        "falls back to a terminal bell if no notification daemon is "
+        "available. Don't spam — one notification per completed job."
+    )
+
+    @property
+    def input_schema(self) -> dict[str, Any]:
+        return {
+            "type": "object",
+            "properties": {
+                "title": {
+                    "type": "string",
+                    "description": "Notification headline. Keep under 60 chars.",
+                },
+                "message": {
+                    "type": "string",
+                    "description": (
+                        "Body text. Keep under 200 chars. Optional; "
+                        "if omitted only the title appears."
+                    ),
+                },
+                "urgency": {
+                    "type": "string",
+                    "enum": list(_URGENCY_MAP.keys()),
+                    "description": "low / normal / high (default normal).",
+                    "default": "normal",
+                },
+                "timeout_ms": {
+                    "type": "integer",
+                    "description": (
+                        "Auto-dismiss after N ms. Default 5000. Set "
+                        "0 for sticky."
+                    ),
+                    "default": 5000,
+                },
+            },
+            "required": ["title"],
+        }
+
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        title = (kwargs.get("title") or "").strip()
+        if not title:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error="`title` is required",
+            )
+        message = (kwargs.get("message") or "").strip()
+        urgency = (kwargs.get("urgency") or "normal").lower()
+        urgency = _URGENCY_MAP.get(urgency, "normal")
+        try:
+            timeout_ms = int(kwargs.get("timeout_ms", 5000))
+        except (TypeError, ValueError):
+            timeout_ms = 5000
+
+        # Channel 1: notify-send (Linux desktop)
+        notify = shutil.which("notify-send")
+        if notify is not None:
+            argv = [
+                notify,
+                "--app-name", "Cognos",
+                "--urgency", urgency,
+                "--expire-time", str(max(0, timeout_ms)),
+                title,
+            ]
+            if message:
+                argv.append(message)
+            try:
+                proc = await asyncio.create_subprocess_exec(
+                    *argv,
+                    stdout=asyncio.subprocess.PIPE,
+                    stderr=asyncio.subprocess.PIPE,
+                )
+                _, stderr = await asyncio.wait_for(
+                    proc.communicate(), timeout=5,
+                )
+                if proc.returncode == 0:
+                    return ToolResult(
+                        tool_name=self.name, status="success",
+                        output=f"Notification sent via notify-send: {title!r}",
+                        metadata={
+                            "channel": "notify-send",
+                            "title": title,
+                            "urgency": urgency,
+                        },
+                    )
+                # notify-send returned non-zero — fall through to bell
+            except (asyncio.TimeoutError, OSError):
+                pass
+
+        # Channel 2: terminal bell (works in any TTY)
+        try:
+            sys.stderr.write("\a")
+            sys.stderr.flush()
+            return ToolResult(
+                tool_name=self.name, status="success",
+                output=(
+                    f"Notification sent via terminal bell (no desktop "
+                    f"notifier available): {title!r}"
+                ),
+                metadata={
+                    "channel": "bell",
+                    "title": title,
+                    "fallback_reason": "notify-send unavailable",
+                },
+            )
+        except Exception as e:
+            return ToolResult(
+                tool_name=self.name, status="error",
+                error=f"could not deliver notification: {e}",
+            )