readyagentsdev 0.8.2__py3-none-any.whl

readyagents/mcp/server.py

@@ -0,0 +1,246 @@
+"""Expose ReadyAgents builtin tools (and run-workflow) as an MCP server."""
+
+from __future__ import annotations
+
+import inspect
+from pathlib import Path
+from typing import Any
+
+from readyagents.config import MAX_HTTP_BODY_BYTES, get_settings
+from readyagents.errors import MCPError
+from readyagents.mcp.builtin import builtin_tools
+
+
+def mcp_available() -> bool:
+    try:
+        import mcp  # noqa: F401
+
+        return True
+    except ImportError:
+        return False
+
+
+def _create_server(name: str) -> Any:
+    try:
+        from mcp.server import MCPServer
+
+        return MCPServer(name)
+    except ImportError:
+        pass
+    try:
+        from mcp.server.fastmcp import FastMCP
+
+        return FastMCP(name)
+    except ImportError as exc:
+        raise MCPError(
+            "This version of the mcp package does not provide MCPServer or FastMCP."
+        ) from exc
+
+
+def construct_server(*, allow_http: bool | None = None, workspace: Path | None = None) -> Any:
+    """Build an MCP server that exposes builtin tools. Does not start a transport."""
+    if not mcp_available():
+        raise MCPError('MCP extra is not installed. Run: pip install -e ".[mcp]"')
+
+    settings = get_settings()
+    allow = settings.allow_http if allow_http is None else allow_http
+    root = workspace or settings.workspace_path()
+    tools = {t.name: t for t in builtin_tools(allow_http=allow, workspace=root)}
+    server = _create_server("readyagents")
+    _register_server_tools(server, tools, workspace=Path(root))
+    return server
+
+
+def serve_stdio(*, allow_http: bool | None = None, workspace: Path | None = None) -> None:
+    """Run a stdio MCP server exposing builtin tools."""
+    construct_server(allow_http=allow_http, workspace=workspace).run(transport="stdio")
+
+
+def streamable_http_app(
+    server: Any,
+    *,
+    host: str,
+    port: int,
+    max_body_bytes: int = MAX_HTTP_BODY_BYTES,
+) -> Any:
+    """Return the SDK Streamable HTTP Starlette app mounted at /mcp. Feature-detect."""
+    method = getattr(server, "streamable_http_app", None)
+    if method is None:
+        raise MCPError(
+            "This mcp package does not support Streamable HTTP. "
+            "Upgrade with: pip install 'mcp>=2' or pip install -e '.[mcp]'"
+        )
+    kwargs: dict[str, Any] = {
+        "streamable_http_path": "/mcp",
+        "host": host,
+        "max_request_body_size": max_body_bytes,
+    }
+    security = _transport_security_settings(host, port)
+    if security is not None:
+        kwargs["transport_security"] = security
+    # Keep SDK default response mode so Accept can negotiate JSON vs SSE.
+    kwargs.pop("json_response", None)
+    if not callable(method):
+        return method
+    return _call_supported_kwargs(method, kwargs)
+
+
+def _transport_security_settings(host: str, port: int) -> Any | None:
+    try:
+        from mcp.server.transport_security import TransportSecuritySettings
+    except ImportError:
+        return None
+    try:
+        return TransportSecuritySettings(
+            enable_dns_rebinding_protection=True,
+            allowed_hosts=_dns_allowed_hosts(host, port),
+            allowed_origins=_dns_allowed_origins(host, port),
+        )
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def _dns_bind_names(host: str) -> list[str]:
+    names: list[str] = []
+    for item in (host, "127.0.0.1", "localhost", "::1"):
+        if item and item not in names:
+            names.append(item)
+    return names
+
+
+def _host_header_variants(name: str, port: int) -> list[str]:
+    variants: list[str] = []
+
+    def add(value: str) -> None:
+        if value not in variants:
+            variants.append(value)
+
+    ipv6 = ":" in name and not name.startswith("[")
+    bracketed = f"[{name}]" if ipv6 else name
+    add(name)
+    add(bracketed)
+    add(f"{bracketed}:{port}")
+    if not ipv6:
+        add(f"{name}:{port}")
+    add(f"{name}:*")
+    add(f"{bracketed}:*")
+    return variants
+
+
+def _dns_allowed_hosts(host: str, port: int) -> list[str]:
+    hosts: list[str] = []
+    for name in _dns_bind_names(host):
+        for variant in _host_header_variants(name, port):
+            if variant not in hosts:
+                hosts.append(variant)
+    return hosts
+
+
+def _dns_allowed_origins(host: str, port: int) -> list[str]:
+    origins: list[str] = []
+    for name in _dns_bind_names(host):
+        ipv6 = ":" in name and not name.startswith("[")
+        shown = f"[{name}]" if ipv6 else name
+        for value in (f"http://{shown}:{port}", f"http://{shown}:*"):
+            if value not in origins:
+                origins.append(value)
+    return origins
+
+
+def _call_supported_kwargs(method: Any, kwargs: dict[str, Any]) -> Any:
+    try:
+        signature = inspect.signature(method)
+        params = signature.parameters
+    except (TypeError, ValueError):
+        return method()
+    if any(param.kind is inspect.Parameter.VAR_KEYWORD for param in params.values()):
+        accepted = dict(kwargs)
+    else:
+        accepted = {key: value for key, value in kwargs.items() if key in params}
+    accepted.pop("json_response", None)
+    try:
+        return method(**accepted) if accepted else method()
+    except TypeError:
+        return method()
+
+
+def _register_server_tools(server: Any, tools: dict[str, Any], *, workspace: Path) -> None:
+    root = Path(workspace).resolve()
+
+    @server.tool(name="now", description=tools["now"].description)
+    def now() -> str:
+        return str(tools["now"].run())
+
+    @server.tool(name="calc", description=tools["calc"].description)
+    def calc(expression: str) -> str:
+        return str(tools["calc"].run(expression=expression))
+
+    @server.tool(name="json_get", description=tools["json_get"].description)
+    def json_get(data: str, path: str) -> str:
+        import json
+
+        result = tools["json_get"].run(data=data, path=path)
+        if isinstance(result, (dict, list)):
+            return json.dumps(result)
+        return str(result)
+
+    @server.tool(name="json_set", description=tools["json_set"].description)
+    def json_set(data: str, path: str, value: str) -> str:
+        import json
+
+        result = tools["json_set"].run(data=data, path=path, value=value)
+        if isinstance(result, (dict, list)):
+            return json.dumps(result)
+        return str(result)
+
+    @server.tool(name="json_merge", description=tools["json_merge"].description)
+    def json_merge(data: str, path: str, value: str) -> str:
+        import json
+
+        result = tools["json_merge"].run(data=data, path=path, value=value)
+        if isinstance(result, (dict, list)):
+            return json.dumps(result)
+        return str(result)
+
+    @server.tool(name="http_get", description=tools["http_get"].description)
+    def http_get(url: str) -> str:
+        return str(tools["http_get"].run(url=url))
+
+    @server.tool(name="list_dir", description=tools["list_dir"].description)
+    def list_dir(path: str = ".", include_hidden: bool = False, max_entries: int = 200) -> str:
+        import json
+
+        result = tools["list_dir"].run(
+            path=path, include_hidden=include_hidden, max_entries=max_entries
+        )
+        if isinstance(result, (dict, list)):
+            return json.dumps(result)
+        return str(result)
+
+    @server.tool(name="read_file", description=tools["read_file"].description)
+    def read_file(path: str) -> str:
+        return str(tools["read_file"].run(path=path))
+
+    @server.tool(name="write_file", description=tools["write_file"].description)
+    def write_file(path: str, content: str) -> str:
+        return str(tools["write_file"].run(path=path, content=content))
+
+    @server.tool()
+    def run_workflow(path: str, inputs_json: str = "{}") -> str:
+        """Run a ReadyAgents workflow file under the server workspace."""
+        import json
+
+        from readyagents.config import get_settings
+        from readyagents.errors import ConfigError
+        from readyagents.workflow.runner import confine_under, run_workflow_file
+
+        data = json.loads(inputs_json) if inputs_json else {}
+        if not isinstance(data, dict):
+            raise ValueError("inputs_json must be a JSON object")
+        try:
+            wf_path = confine_under(path, root, what="workflow")
+        except ConfigError as exc:
+            raise MCPError(str(exc)) from exc
+        bound = get_settings().model_copy(update={"workspace": Path(root)})
+        state = run_workflow_file(wf_path, inputs=data, settings=bound)
+        return json.dumps(state.to_record(), ensure_ascii=False)

readyagents/notify.py

@@ -0,0 +1,63 @@
+"""Outbound pause notify. Core never listens; packs may receive the webhook."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from urllib.parse import urljoin
+
+from readyagents import __version__
+from readyagents.mcp.builtin import (
+    _MAX_HTTP_REDIRECTS,
+    _assert_public_http_url,
+    _http_exchange,
+    _resolve_public_ips,
+)
+
+_KIND = "notify"
+
+
+def post_json(url: str, payload: dict[str, Any], *, timeout: float = 5.0) -> None:
+    data = json.dumps(payload, ensure_ascii=False, default=str).encode("utf-8")
+    current = url.strip() if isinstance(url, str) else ""
+    headers = {
+        "Content-Type": "application/json",
+        "User-Agent": f"readyagents/{__version__}",
+    }
+    for _ in range(_MAX_HTTP_REDIRECTS + 1):
+        parsed = _assert_public_http_url(current, kind=_KIND)
+        assert parsed.hostname is not None
+        ips = _resolve_public_ips(parsed.hostname, kind=_KIND)
+        port = parsed.port or (443 if parsed.scheme == "https" else 80)
+        path = parsed.path or "/"
+        if parsed.query:
+            path = f"{path}?{parsed.query}"
+        last_err: Exception | None = None
+        status = 0
+        location: str | None = None
+        for ip in ips:
+            try:
+                status, _body, location = _http_exchange(
+                    parsed.scheme,
+                    parsed.hostname,
+                    ip,
+                    port,
+                    path,
+                    method="POST",
+                    body=data,
+                    headers=headers,
+                    timeout=timeout,
+                )
+                last_err = None
+                break
+            except (TimeoutError, OSError) as exc:
+                last_err = exc
+        if last_err is not None:
+            raise last_err
+        if status in {301, 302, 303, 307, 308} and location:
+            current = urljoin(current, location)
+            continue
+        if status >= 400:
+            raise OSError(f"HTTP Error {status}")
+        return
+    raise OSError("too many redirects")

readyagents/packs/__init__.py

@@ -0,0 +1,26 @@
+from readyagents.packs.loader import (
+    collect_pack_authorizers,
+    collect_pack_nodes,
+    collect_pack_secrets,
+    collect_pack_specs,
+    collect_pack_tools,
+    confine_pack_path,
+    discover_packs,
+    load_local_packs,
+    load_pack_file,
+)
+from readyagents.packs.protocol import BasePack, Pack
+
+__all__ = [
+    "BasePack",
+    "Pack",
+    "collect_pack_authorizers",
+    "collect_pack_nodes",
+    "collect_pack_secrets",
+    "collect_pack_specs",
+    "collect_pack_tools",
+    "confine_pack_path",
+    "discover_packs",
+    "load_local_packs",
+    "load_pack_file",
+]

readyagents/packs/loader.py

@@ -0,0 +1,157 @@
+"""Load installed packs via importlib.metadata entry points and local files."""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import sys
+from collections.abc import Sequence
+from importlib.metadata import entry_points
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+from readyagents.errors import ConfigError
+from readyagents.logging import get_logger
+from readyagents.packs.protocol import Pack
+from readyagents.tools import ToolRegistry
+
+log = get_logger("packs")
+
+ENTRY_POINT_GROUP = "readyagents.packs"
+
+
+def discover_packs() -> list[Pack]:
+    """Load every installed pack. Core runs fine with an empty list."""
+    packs: list[Pack] = []
+    selected = entry_points().select(group=ENTRY_POINT_GROUP)
+    for ep in selected:
+        try:
+            loaded = ep.load()
+            pack = loaded() if callable(loaded) and not _is_pack_instance(loaded) else loaded
+            if not _is_pack_instance(pack):
+                raise ConfigError(
+                    f"Entry point '{ep.name}' did not return a Pack (name/version/register_*)"
+                )
+            packs.append(pack)
+            log.debug("Loaded pack %s %s", pack.name, pack.version)
+        except ConfigError:
+            raise
+        except Exception as exc:  # noqa: BLE001
+            raise ConfigError(f"Failed to load pack '{ep.name}': {exc}") from exc
+    return packs
+
+
+def _is_pack_instance(obj: Any) -> bool:
+    return (
+        hasattr(obj, "name")
+        and hasattr(obj, "version")
+        and callable(getattr(obj, "register_nodes", None))
+        and callable(getattr(obj, "register_tools", None))
+        and callable(getattr(obj, "register_workflows", None))
+    )
+
+
+def collect_pack_tools(packs: list[Pack] | None = None) -> ToolRegistry:
+    registry = ToolRegistry()
+    for pack in packs if packs is not None else discover_packs():
+        for tool in pack.register_tools() or []:
+            registry.register(tool)
+    return registry
+
+
+def collect_pack_nodes(packs: list[Pack] | None = None) -> dict[str, Any]:
+    handlers: dict[str, Any] = {}
+    for pack in packs if packs is not None else discover_packs():
+        for type_name, handler in (pack.register_nodes() or {}).items():
+            handlers[type_name] = handler
+    return handlers
+
+
+def collect_pack_secrets(packs: list[Pack] | None = None) -> list[Any]:
+    backends: list[Any] = []
+    for pack in packs if packs is not None else discover_packs():
+        fn = getattr(pack, "register_secrets", None)
+        if not callable(fn):
+            continue
+        backends.extend(list(fn() or []))
+    return backends
+
+
+def collect_pack_authorizers(packs: list[Pack] | None = None) -> list[Any]:
+    authorizers: list[Any] = []
+    for pack in packs if packs is not None else discover_packs():
+        fn = getattr(pack, "register_authorizers", None)
+        if not callable(fn):
+            continue
+        authorizers.extend(list(fn() or []))
+    return authorizers
+
+
+def collect_pack_specs(flags: Sequence[str] | None = None, *, env: str | None = None) -> list[str]:
+    """Combine READYAGENTS_PACK (pathsep or comma) with repeatable --pack flags."""
+    out: list[str] = []
+    raw_env = os.environ.get("READYAGENTS_PACK") if env is None else env
+    if raw_env:
+        normalized = raw_env.replace(",", os.pathsep)
+        for part in normalized.split(os.pathsep):
+            piece = part.strip()
+            if piece:
+                out.append(piece)
+    for flag in flags or ():
+        text = str(flag).strip()
+        if text:
+            out.append(text)
+    return out
+
+
+def confine_pack_path(raw: str | Path, root: Path) -> Path:
+    """Resolve ``raw`` and refuse anything outside ``root`` (symlink-aware)."""
+    root = Path(root).resolve()
+    text = str(raw).strip()
+    if not text or "\x00" in text:
+        raise ConfigError(f"Pack path must be a Python file under {root}")
+    candidate = Path(text)
+    if not candidate.is_absolute():
+        candidate = root / candidate
+    resolved = candidate.resolve()
+    if not resolved.is_relative_to(root):
+        raise ConfigError(
+            f"Pack path is outside the workspace: {raw} "
+            f"(resolved to {resolved}, must stay under {root})"
+        )
+    if not resolved.is_file():
+        raise ConfigError(f"Pack file not found: {raw}")
+    if resolved.suffix.lower() != ".py":
+        raise ConfigError(f"Pack path must be a Python file: {raw}")
+    return resolved
+
+
+def load_pack_file(raw: str | Path, *, root: Path) -> Pack:
+    """Import a local pack module confined under ``root``."""
+    path = confine_pack_path(raw, root)
+    mod_name = f"_readyagents_pack_{path.stem}_{uuid4().hex[:8]}"
+    spec = importlib.util.spec_from_file_location(mod_name, path)
+    if spec is None or spec.loader is None:
+        raise ConfigError(f"Could not load pack {path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[mod_name] = module
+    try:
+        spec.loader.exec_module(module)
+    except Exception as extra:
+        sys.modules.pop(mod_name, None)
+        raise ConfigError(f"Failed to load pack '{path}': {extra}") from extra
+    getter = getattr(module, "get_pack", None)
+    if callable(getter):
+        loaded = getter()
+        if _is_pack_instance(loaded):
+            log.debug("Loaded local pack %s %s from %s", loaded.name, loaded.version, path)
+            return loaded
+        raise ConfigError(f"get_pack() in {path} did not return a Pack")
+    if _is_pack_instance(module):
+        return module  # type: ignore[return-value]
+    raise ConfigError(f"Pack {path} needs get_pack() or a Pack instance")
+
+
+def load_local_packs(specs: Sequence[str], *, root: Path) -> list[Pack]:
+    return [load_pack_file(spec, root=root) for spec in specs]

readyagents/packs/protocol.py

@@ -0,0 +1,55 @@
+"""Pack protocol — commercial / extra capability layers sit on top of core."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any, Protocol, runtime_checkable
+
+from readyagents.tools import Tool
+
+
+@runtime_checkable
+class NodeHandler(Protocol):
+    """Optional custom node type: `execute(node, state, context) -> output`."""
+
+    type_name: str
+
+    def execute(self, node: Any, state: Any, context: Any) -> Any: ...
+
+
+@runtime_checkable
+class Pack(Protocol):
+    """A ReadyAgents pack discovered via entry points `readyagents.packs`."""
+
+    name: str
+    version: str
+
+    def register_nodes(self) -> Mapping[str, NodeHandler]: ...
+
+    def register_tools(self) -> Sequence[Tool]: ...
+
+    def register_workflows(self) -> Sequence[Any]: ...
+
+
+class BasePack:
+    """Convenient base class for packs (not required)."""
+
+    name = "unnamed"
+    version = "0.0.0"
+
+    def register_nodes(self) -> Mapping[str, NodeHandler]:
+        return {}
+
+    def register_tools(self) -> Sequence[Tool]:
+        return []
+
+    def register_workflows(self) -> Sequence[Any]:
+        return []
+
+    def register_secrets(self) -> Sequence[Any]:
+        """Optional secrets-manager backends (Vault/AWS live in packs, not core)."""
+        return []
+
+    def register_authorizers(self) -> Sequence[Any]:
+        """Optional RBAC hooks. Default in core is allow-all."""
+        return []

readyagents/policy.py

@@ -0,0 +1,127 @@
+"""RBAC hooks and PII redaction. No control plane — local policy only."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Sequence
+from typing import Any, Protocol, runtime_checkable
+
+from readyagents.errors import AuthorizationError
+
+_EMAIL = re.compile(r"(?i)\b[A-Z0-9._%+\-]+@[A-Z0-9.\-]+\.[A-Z]{2,}\b")
+_SK_KEY = re.compile(r"sk-[A-Za-z0-9]{8,}")
+_ASSIGNED_SECRET = re.compile(r"(?i)\b(api[_-]?key|secret|token|password|passwd)\s*[=:]\s*\S+")
+
+DEFAULT_REDACT_PATTERNS: tuple[re.Pattern[str], ...] = (_EMAIL, _SK_KEY, _ASSIGNED_SECRET)
+REDACTED = "[redacted]"
+
+
+@runtime_checkable
+class Authorizer(Protocol):
+    """Allow or deny an action. Raise ``AuthorizationError`` to deny."""
+
+    def check(self, actor: str | None, action: str, resource: str) -> None: ...
+
+
+class AllowAll:
+    """Default authorizer — core stays open unless a pack/hook is installed."""
+
+    def check(self, actor: str | None, action: str, resource: str) -> None:
+        return None
+
+
+class CallbackAuthorizer:
+    """Wrap a ``(actor, action, resource) -> bool`` callback."""
+
+    def __init__(
+        self,
+        allowed: Callable[[str | None, str, str], bool],
+        *,
+        name: str = "callback",
+    ) -> None:
+        self._allowed = allowed
+        self.name = name
+
+    def check(self, actor: str | None, action: str, resource: str) -> None:
+        if not self._allowed(actor, action, resource):
+            raise AuthorizationError(actor, action, resource)
+
+
+class CompositeAuthorizer:
+    """Every registered authorizer must allow (AND)."""
+
+    def __init__(self, parts: Sequence[Authorizer]) -> None:
+        self.parts = [p for p in parts if p is not None]
+
+    def check(self, actor: str | None, action: str, resource: str) -> None:
+        for part in self.parts:
+            part.check(actor, action, resource)
+
+
+def resolve_authorizer(raw: Any) -> Authorizer:
+    if raw is None:
+        return AllowAll()
+    if isinstance(raw, CompositeAuthorizer):
+        return raw
+    if hasattr(raw, "check") and callable(raw.check):
+        return raw
+    if isinstance(raw, Sequence) and not isinstance(raw, (str, bytes)):
+        return CompositeAuthorizer(list(raw))
+    return AllowAll()
+
+
+class Redactor:
+    """Mask emails, vendor-style keys, assignment secrets, and extra literals."""
+
+    def __init__(
+        self,
+        *,
+        patterns: Sequence[str] | None = None,
+        literals: Sequence[str] | None = None,
+        replacement: str = REDACTED,
+    ) -> None:
+        compiled: list[re.Pattern[str]] = list(DEFAULT_REDACT_PATTERNS)
+        for raw in patterns or []:
+            text = str(raw).strip()
+            if not text:
+                continue
+            compiled.append(re.compile(text))
+        self._patterns = compiled
+        self._literals = [str(item) for item in (literals or []) if str(item)]
+        self.replacement = replacement
+
+    def redact_text(self, text: str) -> str:
+        out = text
+        for lit in self._literals:
+            if lit:
+                out = out.replace(lit, self.replacement)
+        for pat in self._patterns:
+            out = pat.sub(self.replacement, out)
+        return out
+
+    def redact(self, value: Any) -> Any:
+        if value is None or isinstance(value, (int, float, bool)):
+            return value
+        if isinstance(value, str):
+            return self.redact_text(value)
+        if isinstance(value, dict):
+            return {str(k): self.redact(v) for k, v in value.items()}
+        if isinstance(value, (list, tuple)):
+            return [self.redact(v) for v in value]
+        if isinstance(value, bytes):
+            try:
+                return self.redact_text(value.decode("utf-8"))
+            except UnicodeDecodeError:
+                return self.replacement
+        return value
+
+
+def redactor_from_settings(
+    *,
+    enabled: bool,
+    patterns: Sequence[str] | None = None,
+    literals: Sequence[str] | None = None,
+) -> Redactor | None:
+    if not enabled:
+        return None
+    return Redactor(patterns=patterns, literals=literals)

readyagents/py.typed

@@ -0,0 +1 @@
+