agentvalet 0.1.0__py3-none-any.whl

agentvalet/__init__.py

@@ -0,0 +1,55 @@
+"""agentvalet — call approved SaaS platforms from any Python agent.
+
+Your agent never holds the downstream credential. This client signs a
+short-lived RS256 identity assertion; the AgentValet broker checks it against
+the owner's grants and policy, injects the credential at call time, and writes
+an audit record.
+
+    from agentvalet import AgentValet
+
+    av = AgentValet.from_env()
+    av.call(
+        platform="slack",
+        endpoint="/api/chat.postMessage",
+        method="POST",
+        scope="chat:write",
+        data={"channel": "#general", "text": "Deploy finished."},
+    )
+
+Use :class:`agentvalet.aio.AsyncAgentValet` for the async equivalent.
+"""
+
+from __future__ import annotations
+
+from ._constants import DEFAULT_PROXY_URL
+from .aio import AsyncAgentValet
+from .client import AgentValet
+from .errors import (
+    AccessDeniedError,
+    AgentValetError,
+    ApprovalDeniedError,
+    ApprovalExpiredError,
+    ApprovalTimeoutError,
+    ConfigError,
+    NetworkError,
+    ProxyError,
+    UpstreamError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DEFAULT_PROXY_URL",
+    "AccessDeniedError",
+    "AgentValet",
+    "AgentValetError",
+    "ApprovalDeniedError",
+    "ApprovalExpiredError",
+    "ApprovalTimeoutError",
+    "AsyncAgentValet",
+    "ConfigError",
+    "NetworkError",
+    "ProxyError",
+    "UpstreamError",
+    "__version__",
+]

agentvalet/_constants.py

@@ -0,0 +1,31 @@
+"""Behavioural contract with the AgentValet proxy.
+
+These are NOT preferences. Each value is matched by
+``packages/client/src/client.ts`` (TypeScript) and ``apps/mcp-server``. If one
+of them changes here and not there, an operator debugging the Python SDK is no
+longer debugging the same system as the Node one.
+
+``tests/test_constants.py`` asserts every value, so changing one is a
+deliberate, reviewed act rather than a drive-by edit.
+
+Note the unit: the TypeScript client uses milliseconds; Python uses **seconds**,
+matching the httpx/requests convention. The underlying values are the same.
+"""
+
+DEFAULT_PROXY_URL = "https://api.agentvalet.ai"
+
+#: Approval long-poll budget. Sits under Claude Desktop's hardcoded 60s tool
+#: timeout so the MCP path and the SDK path give up at the same moment.
+APPROVAL_TIMEOUT_S = 50.0
+
+#: How often we ask the proxy whether the owner has decided.
+APPROVAL_POLL_S = 2.0
+
+#: Per-request network timeout.
+REQUEST_TIMEOUT_S = 15.0
+
+#: Agent assertions are deliberately short-lived; the proxy rejects long-dated
+#: ones. Seconds.
+JWT_LIFETIME_S = 60
+
+JWT_ALGORITHM = "RS256"

agentvalet/_protocol.py

@@ -0,0 +1,168 @@
+"""Pure protocol logic — no I/O, no awaits.
+
+Everything that decides *what* to send and *what a response means* lives here,
+so the sync and async clients can share it verbatim. Only transport differs
+between them. If you find yourself adding a branch to one client and not the
+other, it belongs in this module instead.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import Any
+
+from .errors import (
+    AccessDeniedError,
+    ApprovalDeniedError,
+    ApprovalExpiredError,
+    ProxyError,
+    UpstreamError,
+)
+
+
+def build_action_body(
+    platform: str,
+    endpoint: str,
+    scope: str,
+    method: str = "GET",
+    data: Any = None,
+    connection_id: str | None = None,
+    reason: str | None = None,
+) -> dict[str, Any]:
+    """Wire body for ``POST /v1/actions``.
+
+    Optional fields are omitted entirely rather than sent as null — the proxy
+    distinguishes absent from null for ``data``.
+    """
+    body: dict[str, Any] = {
+        "platform": platform,
+        "endpoint": endpoint,
+        "method": method,
+        "scope": scope,
+    }
+    if data is not None:
+        body["data"] = data
+    if connection_id:
+        body["connection_id"] = connection_id
+    if reason:
+        body["reason"] = reason
+    return body
+
+
+def authzen_body(agent_id: str, platform: str, scope: str) -> dict[str, Any]:
+    return {
+        "subject": {"type": "agent", "id": agent_id},
+        "action": {"name": "tool_call"},
+        "resource": {"type": "platform_scope", "id": f"{platform}:{scope}"},
+    }
+
+
+def try_parse_json(text: str) -> Any:
+    """Parse only if it looks structured; otherwise hand back the raw text.
+
+    Mirrors the Node client so a non-JSON upstream body (a plain-text error,
+    an empty 204) surfaces identically in both SDKs.
+    """
+    trimmed = text.strip()
+    if not (trimmed.startswith("{") or trimmed.startswith("[")):
+        return text
+    try:
+        return json.loads(trimmed)
+    except ValueError:
+        return text
+
+
+def approval_id_from_202(text: str) -> str | None:
+    parsed = try_parse_json(text)
+    if isinstance(parsed, dict):
+        value = parsed.get("approval_id")
+        if isinstance(value, str):
+            return value
+    return None
+
+
+def interpret_action_response(
+    status: int, text: str, platform: str, scope: str
+) -> Any:
+    """Turn a ``/v1/actions`` reply into a value or the right exception.
+
+    Callers must handle the 202 branch *before* this — an approval is a
+    continuation, not a result.
+    """
+    if status == 403:
+        # The proxy's authorize pipeline denies with 403 for both "no grant"
+        # and "policy blocked". Its own type so callers can branch into
+        # request_access() instead of dead-ending on a generic failure.
+        raise AccessDeniedError(status, text, platform, scope)
+    if not 200 <= status < 300:
+        raise ProxyError(status, text)
+    return try_parse_json(text)
+
+
+def interpret_approval_status(payload: Mapping[str, Any], approval_id: str) -> tuple[bool, Any]:
+    """Interpret one poll of ``GET /v1/approvals/:id``.
+
+    Returns ``(done, value)``. ``done=False`` means keep polling. Terminal
+    failures raise.
+    """
+    status = payload.get("status")
+
+    if status == "denied":
+        raise ApprovalDeniedError(approval_id, _as_str(payload.get("execution_error")))
+    if status == "expired":
+        raise ApprovalExpiredError(approval_id)
+
+    execution_error = payload.get("execution_error")
+    if execution_error:
+        # Approved, but re-execution failed (upstream down, agent revoked
+        # between approval and execution).
+        raise ProxyError(502, f"Approved but re-execution failed: {execution_error}")
+
+    if status == "approved" and payload.get("executed_at") and payload.get("result"):
+        result = payload["result"]
+        upstream_status = int(result.get("status", 0))
+        if not 200 <= upstream_status < 300:
+            raise UpstreamError(upstream_status, result.get("data"))
+        return True, result.get("data")
+
+    return False, None
+
+
+def diagnose_network_error(err: BaseException, proxy_url: str) -> str:
+    """Turn a transport failure into something a developer can act on.
+
+    httpx's bare "Connection error" says nothing about whether it's DNS, a
+    corporate MITM proxy, or the broker being down.
+    """
+    raw = str(err)
+    lower = raw.lower()
+
+    if "getaddrinfo" in lower or "name or service not known" in lower or "nodename" in lower:
+        return (
+            f"Cannot resolve {proxy_url}. Check DNS / corporate proxy / VPN, or confirm "
+            f"proxy_url is correct. Raw: {raw}"
+        )
+    if "refused" in lower or "reset" in lower:
+        return (
+            f"Connection to {proxy_url} was refused or reset. The broker may be down — check "
+            f"https://status.agentvalet.ai — or a firewall is blocking it. Raw: {raw}"
+        )
+    if "timeout" in lower or "timed out" in lower:
+        return (
+            f"Request to {proxy_url} timed out. Likely VPN routing, corporate proxy buffering, "
+            f"or a slow network. Raw: {raw}"
+        )
+    if "certificate" in lower or "ssl" in lower or "tls" in lower:
+        return (
+            f"TLS / certificate problem talking to {proxy_url}. A corporate MITM proxy may be "
+            f"intercepting traffic. Raw: {raw}"
+        )
+    return (
+        f"Network error reaching {proxy_url}: {raw}. Check VPN, corporate proxy, and firewall "
+        f"rules for api.agentvalet.ai."
+    )
+
+
+def _as_str(value: Any) -> str | None:
+    return value if isinstance(value, str) else None

agentvalet/_signing.py

@@ -0,0 +1,33 @@
+"""RS256 agent assertion minting.
+
+Split out so both clients share it and so the failure mode is one place: a
+malformed PEM must surface as :class:`ConfigError`, never as a raw PyJWT or
+cryptography traceback that sends the reader looking in the wrong library.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import jwt
+
+from ._constants import JWT_ALGORITHM, JWT_LIFETIME_S
+from .errors import ConfigError
+
+
+def sign_jwt(agent_id: str, owner_id: str, private_key_pem: str) -> str:
+    now = int(time.time())
+    claims: dict[str, Any] = {
+        "agent_id": agent_id,
+        "owner_id": owner_id,
+        "iat": now,
+        "exp": now + JWT_LIFETIME_S,
+    }
+    try:
+        return jwt.encode(claims, private_key_pem, algorithm=JWT_ALGORITHM)
+    except Exception as err:
+        raise ConfigError(
+            f"Private key is not a valid RS256 PEM: {err}. Expected a PKCS#8 private key — "
+            "run `agentvalet register` to generate one."
+        ) from err

agentvalet/aio.py

@@ -0,0 +1,267 @@
+"""Asynchronous AgentValet client.
+
+A method-for-method mirror of :class:`agentvalet.client.AgentValet`. All the
+decision logic lives in :mod:`agentvalet._protocol`, which both clients share,
+so the only thing that differs here is the transport and the awaits. The test
+suite runs the same behaviour table against both classes to keep it that way.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Awaitable
+from typing import Any, Callable, Union
+
+import httpx
+
+from ._constants import (
+    APPROVAL_POLL_S,
+    APPROVAL_TIMEOUT_S,
+    DEFAULT_PROXY_URL,
+    REQUEST_TIMEOUT_S,
+)
+from ._protocol import (
+    approval_id_from_202,
+    authzen_body,
+    build_action_body,
+    diagnose_network_error,
+    interpret_action_response,
+    interpret_approval_status,
+    try_parse_json,
+)
+from ._signing import sign_jwt
+from .env import agent_id_from_env, owner_id_from_env, private_key_from_env, proxy_url_from_env
+from .errors import ApprovalTimeoutError, ConfigError, NetworkError, ProxyError
+
+__all__ = ["AsyncAgentValet"]
+
+AsyncProgressCallback = Callable[[dict[str, Any]], Union[Awaitable[None], None]]
+
+
+class AsyncAgentValet:
+    """Async twin of :class:`agentvalet.client.AgentValet`."""
+
+    def __init__(
+        self,
+        agent_id: str,
+        owner_id: str,
+        private_key: str,
+        proxy_url: str = DEFAULT_PROXY_URL,
+        timeout_s: float = REQUEST_TIMEOUT_S,
+        approval_timeout_s: float = APPROVAL_TIMEOUT_S,
+        approval_poll_s: float = APPROVAL_POLL_S,
+        on_approval_pending: AsyncProgressCallback | None = None,
+        transport: httpx.AsyncClient | None = None,
+    ) -> None:
+        if not agent_id:
+            raise ConfigError("agent_id is required")
+        if not owner_id:
+            raise ConfigError("owner_id is required")
+        if not private_key:
+            raise ConfigError("private_key is required")
+
+        self.agent_id = agent_id
+        self.owner_id = owner_id
+        self.proxy_url = proxy_url.rstrip("/")
+        self._private_key = private_key
+        self._timeout_s = timeout_s
+        self._approval_timeout_s = approval_timeout_s
+        self._approval_poll_s = approval_poll_s
+        self._on_approval_pending = on_approval_pending
+        self._owns_client = transport is None
+        self._http = transport or httpx.AsyncClient(timeout=timeout_s)
+
+    @classmethod
+    def from_env(cls, **overrides: Any) -> AsyncAgentValet:
+        agent_id = overrides.pop("agent_id", None) or agent_id_from_env()
+        owner_id = overrides.pop("owner_id", None) or owner_id_from_env()
+        if not agent_id or not owner_id:
+            raise ConfigError(
+                "AgentValet identity not found in the environment. Set AGENTVALET_AGENT_ID and "
+                "AGENTVALET_OWNER_ID (or AGENT_ID / OWNER_ID), or run `agentvalet register`."
+            )
+        return cls(
+            agent_id=agent_id,
+            owner_id=owner_id,
+            private_key=overrides.pop("private_key", None) or private_key_from_env(),
+            proxy_url=overrides.pop("proxy_url", None) or proxy_url_from_env(),
+            **overrides,
+        )
+
+    async def __aenter__(self) -> AsyncAgentValet:
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._http.aclose()
+
+    # -- core --------------------------------------------------------------
+
+    async def call(
+        self,
+        platform: str,
+        endpoint: str,
+        scope: str,
+        method: str = "GET",
+        data: Any = None,
+        connection_id: str | None = None,
+        reason: str | None = None,
+        approval_timeout_s: float | None = None,
+    ) -> Any:
+        """See :meth:`agentvalet.client.AgentValet.call`."""
+        body = build_action_body(
+            platform=platform,
+            endpoint=endpoint,
+            scope=scope,
+            method=method,
+            data=data,
+            connection_id=connection_id,
+            reason=reason,
+        )
+        response = await self._authed_request("POST", "/v1/actions", json=body)
+        text = response.text
+
+        if response.status_code == 202:
+            approval_id = approval_id_from_202(text)
+            if approval_id:
+                return await self.wait_for_approval(
+                    approval_id,
+                    platform=platform,
+                    scope=scope,
+                    endpoint=endpoint,
+                    timeout_s=approval_timeout_s,
+                )
+
+        return interpret_action_response(response.status_code, text, platform, scope)
+
+    async def wait_for_approval(
+        self,
+        approval_id: str,
+        platform: str = "",
+        scope: str = "",
+        endpoint: str = "",
+        timeout_s: float | None = None,
+    ) -> Any:
+        """See :meth:`agentvalet.client.AgentValet.wait_for_approval`."""
+        budget = self._approval_timeout_s if timeout_s is None else timeout_s
+        started = time.monotonic()
+
+        while time.monotonic() - started < budget:
+            await asyncio.sleep(self._approval_poll_s)
+            elapsed = time.monotonic() - started
+
+            try:
+                response = await self._authed_request("GET", f"/v1/approvals/{approval_id}")
+            except NetworkError:
+                continue
+
+            if response.status_code >= 400:
+                raise ProxyError(response.status_code, response.text)
+
+            done, value = interpret_approval_status(response.json(), approval_id)
+            if done:
+                return value
+
+            if self._on_approval_pending:
+                maybe = self._on_approval_pending(
+                    {
+                        "approval_id": approval_id,
+                        "elapsed_s": elapsed,
+                        "platform": platform,
+                        "scope": scope,
+                        "endpoint": endpoint,
+                    }
+                )
+                # Accept either a plain callback or a coroutine function.
+                if asyncio.iscoroutine(maybe):
+                    await maybe
+
+        raise ApprovalTimeoutError(approval_id, budget)
+
+    # -- discovery / governance -------------------------------------------
+
+    async def list_platforms(self) -> Any:
+        return await self._get_json("/v1/agent/permissions")
+
+    async def pending_actions(self) -> Any:
+        return await self._get_json("/v1/agents/me/pending-actions")
+
+    async def evaluate(self, platform: str, scope: str) -> Any:
+        response = await self._authed_request(
+            "POST", "/v1/authzen/access", json=authzen_body(self.agent_id, platform, scope)
+        )
+        if response.status_code >= 400:
+            raise ProxyError(response.status_code, response.text)
+        return try_parse_json(response.text)
+
+    async def request_access(
+        self,
+        platform: str,
+        scope: str | None = None,
+        reason: str | None = None,
+        timeout_s: float | None = None,
+    ) -> dict[str, str]:
+        submit = await self._authed_request(
+            "POST",
+            "/v1/access-request",
+            json={"platform": platform, "scope": scope, "reason": reason},
+        )
+        if submit.status_code >= 400:
+            raise ProxyError(submit.status_code, submit.text)
+
+        token = submit.json().get("request_token")
+        if not token:
+            raise ProxyError(submit.status_code, "Access request did not return a request_token.")
+
+        budget = self._approval_timeout_s if timeout_s is None else timeout_s
+        deadline = time.monotonic() + budget
+        while time.monotonic() < deadline:
+            await asyncio.sleep(self._approval_poll_s)
+            try:
+                status_res = await self._authed_request("GET", f"/v1/access-request/status/{token}")
+            except NetworkError:
+                continue
+            if status_res.status_code >= 400:
+                continue
+            status = status_res.json().get("status")
+            if status in ("approved", "denied"):
+                return {"status": status, "request_token": token}
+
+        return {"status": "pending", "request_token": token}
+
+    # -- transport ---------------------------------------------------------
+
+    def sign_jwt(self) -> str:
+        return sign_jwt(self.agent_id, self.owner_id, self._private_key)
+
+    async def _authed_request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        url = f"{self.proxy_url}{path}"
+
+        async def once() -> httpx.Response:
+            token = self.sign_jwt()
+            try:
+                return await self._http.request(
+                    method,
+                    url,
+                    headers={
+                        "Authorization": f"Bearer {token}",
+                        "Content-Type": "application/json",
+                    },
+                    timeout=self._timeout_s,
+                    **kwargs,
+                )
+            except httpx.HTTPError as err:
+                raise NetworkError(diagnose_network_error(err, self.proxy_url), err) from err
+
+        response = await once()
+        return await once() if response.status_code == 401 else response
+
+    async def _get_json(self, path: str) -> Any:
+        response = await self._authed_request("GET", path)
+        if response.status_code >= 400:
+            raise ProxyError(response.status_code, response.text)
+        return try_parse_json(response.text)