runeward 0.2.0__py3-none-any.whl

runeward/__init__.py

@@ -0,0 +1,28 @@
+"""runeward — Python client and agent-framework adapters for the Runeward
+agent governance harness.
+
+The core :class:`RunewardClient` depends only on the standard library. The
+framework helpers live in :mod:`runeward.langchain_tools`,
+:mod:`runeward.crewai_tools`, :mod:`runeward.llamaindex_tools`,
+:mod:`runeward.openai_agents_tools`, and :mod:`runeward.strands_tools`; each
+imports its framework lazily, so importing this package never requires those
+extras to be installed.
+"""
+
+from __future__ import annotations
+
+from .client import (
+    RunewardApprovalRequired,
+    RunewardClient,
+    RunewardDenied,
+    RunewardError,
+)
+
+__all__ = [
+    "RunewardClient",
+    "RunewardError",
+    "RunewardDenied",
+    "RunewardApprovalRequired",
+]
+
+__version__ = "0.2.0"

runeward/client.py

@@ -0,0 +1,297 @@
+"""A dependency-light Python client for the runeward control plane.
+
+Uses only the Python standard library (``urllib``) so it can be dropped into any
+environment without pulling in ``requests`` or an async HTTP stack. The client
+mirrors the runeward REST contract 1:1 and translates the two governance
+outcomes into exceptions:
+
+* HTTP ``403`` -> :class:`RunewardDenied`
+* HTTP ``202`` -> :class:`RunewardApprovalRequired` (carries the ``approval_id``)
+
+Everything else that isn't a 2xx becomes a :class:`RunewardError`.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.parse
+import urllib.request
+import warnings
+from typing import Any, Dict, List, Optional
+
+__all__ = [
+    "RunewardClient",
+    "RunewardError",
+    "RunewardDenied",
+    "RunewardApprovalRequired",
+]
+
+
+class RunewardError(Exception):
+    """Base error for any non-success response from the control plane."""
+
+    def __init__(self, message: str, *, status: Optional[int] = None,
+                 payload: Optional[Dict[str, Any]] = None) -> None:
+        super().__init__(message)
+        self.status = status
+        self.payload = payload or {}
+
+
+class RunewardDenied(RunewardError):
+    """Raised when policy denies an action (HTTP 403).
+
+    ``reason`` explains *why* it was blocked. A denial is a policy decision, not
+    a transient failure: do not retry the identical action.
+    """
+
+    def __init__(self, reason: str, *, payload: Optional[Dict[str, Any]] = None) -> None:
+        super().__init__(f"runeward denied action: {reason}", status=403, payload=payload)
+        self.reason = reason
+
+
+class RunewardApprovalRequired(RunewardError):
+    """Raised when an action needs human approval (HTTP 202).
+
+    ``approval_id`` identifies the pending request in the approvals inbox. The
+    caller should pause and surface this to a human rather than working around
+    the gate.
+    """
+
+    def __init__(self, approval_id: str, *, reason: str = "",
+                 payload: Optional[Dict[str, Any]] = None) -> None:
+        super().__init__(
+            f"runeward requires approval (id={approval_id}): {reason}".rstrip(": "),
+            status=202,
+            payload=payload,
+        )
+        self.approval_id = approval_id
+        self.reason = reason
+
+
+class RunewardClient:
+    """Thin, synchronous client over the runeward REST control plane.
+
+    Example
+    -------
+    >>> rw = RunewardClient("http://localhost:8080")
+    >>> sbx = rw.create_sandbox("dev")
+    >>> rw.shell(sbx["id"], ["echo", "hello"])["stdout"]
+    'hello\\n'
+    >>> rw.kill_sandbox(sbx["id"])
+    """
+
+    def __init__(self, base_url: str = "http://localhost:8080", *,
+                 timeout: float = 60.0, token: Optional[str] = None,
+                 allow_insecure: bool = False) -> None:
+        # Normalize so we can safely join paths without doubling slashes.
+        self.base_url = self._normalize_base_url(base_url)
+        self._validate_transport(self.base_url, allow_insecure)
+        self.timeout = timeout
+        self.token = token
+
+    # -- low-level request plumbing ---------------------------------------
+
+    def _request(self, method: str, path: str,
+                 body: Optional[Dict[str, Any]] = None) -> Any:
+        """Perform an HTTP request and decode the JSON response.
+
+        Maps governance status codes to typed exceptions before returning.
+        """
+        url = f"{self.base_url}{path}"
+        data = None
+        headers = {"Accept": "application/json"}
+        if body is not None:
+            data = json.dumps(body).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return self._decode(resp.status, resp.read())
+        except urllib.error.HTTPError as exc:  # 4xx / 5xx arrive here
+            payload = self._safe_json(exc.read())
+            self._raise_for_status(exc.code, payload)
+            # _raise_for_status always raises for non-2xx; keep the type checker happy.
+            raise
+        except urllib.error.URLError as exc:  # connection refused, DNS, timeout
+            raise RunewardError(f"could not reach runeward at {url}: {exc.reason}") from exc
+
+    def _decode(self, status: int, raw: bytes) -> Any:
+        """Handle a response the stdlib treated as success (2xx)."""
+        payload = self._safe_json(raw)
+        # 202 is "success" to urllib but means an approval gate to runeward.
+        if status == 202:
+            self._raise_for_status(status, payload)
+        return payload
+
+    @staticmethod
+    def _safe_json(raw: bytes) -> Dict[str, Any]:
+        if not raw:
+            return {}
+        try:
+            return json.loads(raw.decode("utf-8"))
+        except (ValueError, UnicodeDecodeError):
+            return {"raw": raw.decode("utf-8", "replace")}
+
+    @staticmethod
+    def _normalize_base_url(base_url: str) -> str:
+        base_url = base_url.strip()
+        parsed = urllib.parse.urlsplit(base_url)
+        if not parsed.scheme:
+            base_url = f"https://{base_url}"
+        return base_url.rstrip("/")
+
+    @staticmethod
+    def _is_loopback_host(hostname: Optional[str]) -> bool:
+        if not hostname:
+            return False
+        host = hostname.lower().strip("[]")
+        return host in {"localhost", "127.0.0.1", "::1"}
+
+    @staticmethod
+    def _env_allows_insecure() -> bool:
+        value = os.environ.get("RUNEWARD_ALLOW_INSECURE_HTTP", "").strip().lower()
+        return value in {"1", "true", "yes", "on"}
+
+    @classmethod
+    def _validate_transport(cls, base_url: str, allow_insecure: bool) -> None:
+        parsed = urllib.parse.urlsplit(base_url)
+        if parsed.scheme != "http":
+            return
+        if cls._is_loopback_host(parsed.hostname):
+            return
+        if allow_insecure or cls._env_allows_insecure():
+            warnings.warn(
+                f"runeward client using insecure HTTP transport to non-loopback host: {base_url}",
+                RuntimeWarning,
+                stacklevel=3,
+            )
+            return
+        raise ValueError(
+            "refusing insecure http:// base URL to non-loopback host; "
+            "use https://, set allow_insecure=True, or set RUNEWARD_ALLOW_INSECURE_HTTP=1"
+        )
+
+    @staticmethod
+    def _segment(value: str) -> str:
+        return urllib.parse.quote(value, safe="")
+
+    @staticmethod
+    def _raise_for_status(status: int, payload: Dict[str, Any]) -> None:
+        if status == 403 or payload.get("verdict") == "deny":
+            raise RunewardDenied(payload.get("reason", "denied by policy"), payload=payload)
+        if status == 202 or payload.get("verdict") == "require-approval":
+            raise RunewardApprovalRequired(
+                payload.get("approval_id", ""),
+                reason=payload.get("reason", ""),
+                payload=payload,
+            )
+        raise RunewardError(
+            f"runeward returned HTTP {status}: {payload}", status=status, payload=payload
+        )
+
+    # -- health & discovery -----------------------------------------------
+
+    def healthz(self) -> Any:
+        """``GET /healthz`` — liveness check."""
+        return self._request("GET", "/healthz")
+
+    def list_profiles(self) -> List[Dict[str, Any]]:
+        """``GET /v1/charters`` — reachable profiles."""
+        return self._request("GET", "/v1/charters").get("profiles", [])
+
+    # -- sandbox lifecycle -------------------------------------------------
+
+    def create_sandbox(self, profile: str) -> Dict[str, Any]:
+        """``POST /v1/citadels`` — provision a sandbox from ``profile``."""
+        return self._request("POST", "/v1/citadels", {"profile": profile})
+
+    def list_sandboxes(self) -> List[Dict[str, Any]]:
+        """``GET /v1/citadels``."""
+        return self._request("GET", "/v1/citadels").get("sandboxes", [])
+
+    def get_sandbox(self, sandbox: str) -> Dict[str, Any]:
+        """``GET /v1/citadels/{id}``."""
+        return self._request("GET", f"/v1/citadels/{self._segment(sandbox)}")
+
+    def kill_sandbox(self, sandbox: str) -> Any:
+        """``DELETE /v1/citadels/{id}`` — tear the sandbox down."""
+        return self._request("DELETE", f"/v1/citadels/{self._segment(sandbox)}")
+
+    # -- execution ---------------------------------------------------------
+
+    def shell(self, sandbox: str, command: List[str], workdir: str = "") -> Dict[str, Any]:
+        """``POST .../shell/exec`` — run ``command`` (an argv list) in the sandbox.
+
+        Returns ``{"verdict","exit_code","stdout","stderr","duration_ms"}``. An
+        ``allow`` verdict with a non-zero ``exit_code`` is a normal program
+        error, not a policy denial.
+        """
+        return self._request(
+            "POST", f"/v1/citadels/{self._segment(sandbox)}/shell/exec",
+            {"command": list(command), "workdir": workdir},
+        )
+
+    def python(self, sandbox: str, code: str) -> Dict[str, Any]:
+        """``POST .../code/python`` — run a Python snippet in the sandbox."""
+        return self._request("POST", f"/v1/citadels/{self._segment(sandbox)}/code/python", {"code": code})
+
+    def node(self, sandbox: str, code: str) -> Dict[str, Any]:
+        """``POST .../code/node`` — run a Node.js snippet in the sandbox."""
+        return self._request("POST", f"/v1/citadels/{self._segment(sandbox)}/code/node", {"code": code})
+
+    # -- files -------------------------------------------------------------
+
+    def read_file(self, sandbox: str, path: str) -> str:
+        """``POST .../file/read`` — return the file's ``content``."""
+        return self._request(
+            "POST", f"/v1/citadels/{self._segment(sandbox)}/file/read", {"path": path}
+        ).get("content", "")
+
+    def write_file(self, sandbox: str, path: str, content: str) -> int:
+        """``POST .../file/write`` — write ``content``; return ``bytes`` written."""
+        return self._request(
+            "POST", f"/v1/citadels/{self._segment(sandbox)}/file/write",
+            {"path": path, "content": content},
+        ).get("bytes", 0)
+
+    def list_files(self, sandbox: str, path: str) -> str:
+        """``POST .../file/list`` — list a directory; return the raw ``output``."""
+        return self._request(
+            "POST", f"/v1/citadels/{self._segment(sandbox)}/file/list", {"path": path}
+        ).get("output", "")
+
+    def search_files(self, sandbox: str, query: str, path: str) -> str:
+        """``POST .../file/search`` — search for ``query`` under ``path``."""
+        return self._request(
+            "POST", f"/v1/citadels/{self._segment(sandbox)}/file/search",
+            {"query": query, "path": path},
+        ).get("output", "")
+
+    # -- audit -------------------------------------------------------------
+
+    def audit(self, sandbox: str) -> List[Dict[str, Any]]:
+        """``GET .../chronicle`` — this sandbox's ledger events."""
+        return self._request("GET", f"/v1/citadels/{self._segment(sandbox)}/chronicle").get("events", [])
+
+    def verify_audit(self) -> bool:
+        """``GET /v1/chronicle/verify`` — verify the ledger hash chain."""
+        return bool(self._request("GET", "/v1/chronicle/verify").get("ok", False))
+
+    # -- approvals ---------------------------------------------------------
+
+    def list_approvals(self) -> List[Dict[str, Any]]:
+        """``GET /v1/conclave`` — pending human-in-the-loop requests."""
+        return self._request("GET", "/v1/conclave").get("approvals", [])
+
+    def approve(self, approval_id: str) -> Any:
+        """``POST /v1/conclave/{id}/approve``."""
+        return self._request("POST", f"/v1/conclave/{self._segment(approval_id)}/approve")
+
+    def deny(self, approval_id: str) -> Any:
+        """``POST /v1/conclave/{id}/deny``."""
+        return self._request("POST", f"/v1/conclave/{self._segment(approval_id)}/deny")

runeward/crewai_tools.py

@@ -0,0 +1,222 @@
+"""CrewAI tool wrappers around :class:`RunewardClient`.
+
+CrewAI (and its ``pydantic`` dependency) are imported *lazily* inside
+:func:`make_runeward_tools` so the base ``runeward`` client works without the
+extra. Install with ``pip install runeward[crewai]``.
+
+Each tool is a ``crewai.tools.BaseTool`` subclass with a typed pydantic
+args-schema. Governance verdicts are surfaced as descriptive strings so the crew
+can reason about a denial or an approval gate instead of raising.
+"""
+
+from __future__ import annotations
+
+from typing import Any, List
+
+from .client import RunewardApprovalRequired, RunewardClient, RunewardDenied
+
+
+def _format_denied(exc: RunewardDenied) -> str:
+    return (
+        f"DENIED by policy: {exc.reason}. Do not retry this action; choose a "
+        "different, allowed approach or report the block to the human."
+    )
+
+
+def _format_approval(exc: RunewardApprovalRequired) -> str:
+    return (
+        f"APPROVAL REQUIRED (approval_id={exc.approval_id}): "
+        f"{exc.reason or 'a human must sign off before this runs'}. "
+        "Pause the task and ask the human to approve or deny."
+    )
+
+
+def make_runeward_tools(client: RunewardClient) -> List[Any]:
+    """Build a list of CrewAI ``BaseTool`` instances bound to ``client``.
+
+    Returns one tool per runeward capability. Requires ``crewai`` to be
+    installed (``pip install runeward[crewai]``).
+    """
+    # Lazy import so crewai stays an optional extra.
+    try:
+        from crewai.tools import BaseTool
+        from pydantic import BaseModel, Field
+    except ImportError as exc:  # pragma: no cover - depends on optional extra
+        raise ImportError(
+            "CrewAI is required for make_runeward_tools(). "
+            "Install it with: pip install runeward[crewai]"
+        ) from exc
+
+    # --- argument schemas -------------------------------------------------
+
+    class CreateCitadelArgs(BaseModel):
+        profile: str = Field(..., description="Charter name, e.g. 'dev' or 'governed'.")
+
+    class ShellArgs(BaseModel):
+        sandbox: str = Field(..., description="Citadel id from create_citadel.")
+        command: List[str] = Field(..., description="argv list, e.g. ['ls','-la'].")
+        workdir: str = Field("", description="Optional working directory.")
+
+    class CodeArgs(BaseModel):
+        sandbox: str = Field(..., description="Citadel id.")
+        code: str = Field(..., description="Source code to execute.")
+
+    class ReadArgs(BaseModel):
+        sandbox: str = Field(..., description="Citadel id.")
+        path: str = Field(..., description="File path to read.")
+
+    class WriteArgs(BaseModel):
+        sandbox: str = Field(..., description="Citadel id.")
+        path: str = Field(..., description="File path to write.")
+        content: str = Field(..., description="Content to write.")
+
+    class ListArgs(BaseModel):
+        sandbox: str = Field(..., description="Citadel id.")
+        path: str = Field(..., description="Directory path to list.")
+
+    class SearchArgs(BaseModel):
+        sandbox: str = Field(..., description="Citadel id.")
+        query: str = Field(..., description="Search query.")
+        path: str = Field(..., description="Path to search under.")
+
+    class CitadelArgs(BaseModel):
+        sandbox: str = Field(..., description="Citadel id.")
+
+    class NoArgs(BaseModel):
+        pass
+
+    # --- tool definitions -------------------------------------------------
+
+    class CreateCitadelTool(BaseTool):
+        name: str = "runeward_create_citadel"
+        description: str = "Provision a governed Citadel from a runeward Charter. Returns Citadel metadata including its id."
+        args_schema: type = CreateCitadelArgs
+
+        def _run(self, profile: str) -> str:
+            try:
+                return str(client.create_sandbox(profile))
+            except RunewardDenied as e:
+                return _format_denied(e)
+            except RunewardApprovalRequired as e:
+                return _format_approval(e)
+
+    class ShellTool(BaseTool):
+        name: str = "runeward_shell"
+        description: str = "Run a shell command (argv list) in a Citadel. Returns verdict, exit_code, stdout, stderr."
+        args_schema: type = ShellArgs
+
+        def _run(self, sandbox: str, command: List[str], workdir: str = "") -> str:
+            try:
+                return str(client.shell(sandbox, command, workdir))
+            except RunewardDenied as e:
+                return _format_denied(e)
+            except RunewardApprovalRequired as e:
+                return _format_approval(e)
+
+    class PythonTool(BaseTool):
+        name: str = "runeward_python"
+        description: str = "Run a Python code snippet inside the Citadel."
+        args_schema: type = CodeArgs
+
+        def _run(self, sandbox: str, code: str) -> str:
+            try:
+                return str(client.python(sandbox, code))
+            except RunewardDenied as e:
+                return _format_denied(e)
+            except RunewardApprovalRequired as e:
+                return _format_approval(e)
+
+    class NodeTool(BaseTool):
+        name: str = "runeward_node"
+        description: str = "Run a Node.js code snippet inside the Citadel."
+        args_schema: type = CodeArgs
+
+        def _run(self, sandbox: str, code: str) -> str:
+            try:
+                return str(client.node(sandbox, code))
+            except RunewardDenied as e:
+                return _format_denied(e)
+            except RunewardApprovalRequired as e:
+                return _format_approval(e)
+
+    class ReadFileTool(BaseTool):
+        name: str = "runeward_read_file"
+        description: str = "Read a file's contents from the Citadel."
+        args_schema: type = ReadArgs
+
+        def _run(self, sandbox: str, path: str) -> str:
+            try:
+                return client.read_file(sandbox, path)
+            except RunewardDenied as e:
+                return _format_denied(e)
+            except RunewardApprovalRequired as e:
+                return _format_approval(e)
+
+    class WriteFileTool(BaseTool):
+        name: str = "runeward_write_file"
+        description: str = "Write content to a file in the Citadel."
+        args_schema: type = WriteArgs
+
+        def _run(self, sandbox: str, path: str, content: str) -> str:
+            try:
+                return f"wrote {client.write_file(sandbox, path, content)} bytes to {path}"
+            except RunewardDenied as e:
+                return _format_denied(e)
+            except RunewardApprovalRequired as e:
+                return _format_approval(e)
+
+    class ListFilesTool(BaseTool):
+        name: str = "runeward_list_files"
+        description: str = "List a directory in the Citadel."
+        args_schema: type = ListArgs
+
+        def _run(self, sandbox: str, path: str) -> str:
+            try:
+                return client.list_files(sandbox, path)
+            except RunewardDenied as e:
+                return _format_denied(e)
+            except RunewardApprovalRequired as e:
+                return _format_approval(e)
+
+    class SearchFilesTool(BaseTool):
+        name: str = "runeward_search_files"
+        description: str = "Search for a query string under a path in the Citadel."
+        args_schema: type = SearchArgs
+
+        def _run(self, sandbox: str, query: str, path: str) -> str:
+            try:
+                return client.search_files(sandbox, query, path)
+            except RunewardDenied as e:
+                return _format_denied(e)
+            except RunewardApprovalRequired as e:
+                return _format_approval(e)
+
+    class ListConclaveTool(BaseTool):
+        name: str = "runeward_list_conclave"
+        description: str = "List pending human-in-the-loop Conclave requests."
+        args_schema: type = NoArgs
+
+        def _run(self) -> str:
+            return str(client.list_approvals())
+
+    class KillCitadelTool(BaseTool):
+        name: str = "runeward_kill_citadel"
+        description: str = "Tear down a Citadel when the task is finished."
+        args_schema: type = CitadelArgs
+
+        def _run(self, sandbox: str) -> str:
+            client.kill_sandbox(sandbox)
+            return f"Citadel {sandbox} terminated"
+
+    return [
+        CreateCitadelTool(),
+        ShellTool(),
+        PythonTool(),
+        NodeTool(),
+        ReadFileTool(),
+        WriteFileTool(),
+        ListFilesTool(),
+        SearchFilesTool(),
+        ListConclaveTool(),
+        KillCitadelTool(),
+    ]