agentapprovalprotocol 0.1.0__py3-none-any.whl

agentapprovalprotocol/__init__.py

@@ -0,0 +1,33 @@
+"""Agent Approval Protocol SDK.
+
+Put an agent's tool calls behind an AAP approval provider. ``Gate`` and
+``AsyncGate`` decide whether one call may run; framework integrations build
+on them. See https://agentapprovalprotocol.io.
+"""
+
+from ._client import AAPError, AsyncClient, Client, ConflictError, CredentialRefused, NotFound
+from ._gate import Allow, AsyncGate, Call, Deny, Gate, Pending, Verdict
+from ._wire import Consumption, Decision, Outcome, ProtocolError, Request
+from .receiver import Receiver
+
+__all__ = [
+    "AAPError",
+    "Allow",
+    "AsyncClient",
+    "AsyncGate",
+    "Call",
+    "Client",
+    "ConflictError",
+    "Consumption",
+    "CredentialRefused",
+    "Decision",
+    "Deny",
+    "Gate",
+    "NotFound",
+    "Outcome",
+    "Pending",
+    "ProtocolError",
+    "Receiver",
+    "Request",
+    "Verdict",
+]

agentapprovalprotocol/_client.py

@@ -0,0 +1,201 @@
+"""AAP HTTP client, in synchronous and asynchronous forms.
+
+Both forms share the response rules below; only the transport differs.
+Transport failures, 429 and 5xx responses are retried with the same
+idempotency key until the retry budget runs out.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from email.utils import parsedate_to_datetime
+from typing import Any, Mapping
+from urllib.parse import urlsplit
+
+import httpx
+
+from ._wire import ProtocolError, Request, dumps, loads, parse_request
+
+USER_AGENT = "agentapprovalprotocol-python"
+MAX_RESPONSE = 8 << 20
+
+
+class AAPError(Exception):
+    """The operation did not produce a usable result."""
+
+
+class CredentialRefused(AAPError):
+    """The provider refused the instance credential (HTTP 401 or 403)."""
+
+
+class ConflictError(AAPError):
+    """A 409 answer, identified by the provider's error code."""
+
+    def __init__(self, code: str, message: str = ""):
+        super().__init__(f"AAP conflict: {code}")
+        self.code = code
+        self.message = message
+
+
+class NotFound(AAPError):
+    """The request is unknown or unavailable to this instance."""
+
+
+def validate_base_url(base_url: str) -> str:
+    parts = urlsplit(base_url)
+    if not parts.netloc or parts.username or parts.password or parts.query or parts.fragment:
+        raise ValueError("base URL must be an absolute AAP URL without credentials, query or fragment")
+    local = parts.hostname in ("localhost", "127.0.0.1", "::1")
+    if parts.scheme != "https" and not (parts.scheme == "http" and local):
+        raise ValueError("base URL requires HTTPS, except on localhost")
+    return base_url.rstrip("/")
+
+
+def _retry_after(response: httpx.Response) -> float | None:
+    value = response.headers.get("retry-after")
+    if value is None:
+        return None
+    if value.isdigit():
+        return float(value)
+    try:
+        return max(0.0, parsedate_to_datetime(value).timestamp() - time.time())
+    except (TypeError, ValueError):
+        return None
+
+
+def _result(response: httpx.Response, raw: bytes) -> Request | None:
+    """Turn a final response into a request, raise, or return None to retry."""
+    code = response.status_code
+    if code == 429 or code >= 500:
+        return None
+    if code in (401, 403):
+        raise CredentialRefused(f"the provider refused the instance credential (HTTP {code})")
+    if code == 404:
+        raise NotFound("the request is unavailable")
+    if code == 409:
+        try:
+            error = loads(raw)["error"]
+            raise ConflictError(str(error["code"]), str(error.get("message", "")))
+        except (ProtocolError, KeyError, TypeError) as err:
+            raise AAPError("AAP request failed (HTTP 409)") from err
+    if code not in (200, 201):
+        raise AAPError(f"AAP request failed (HTTP {code})")
+    if len(raw) > MAX_RESPONSE:
+        raise ProtocolError("AAP response too large")
+    return parse_request(loads(raw))
+
+
+class _Base:
+    def __init__(self, base_url: str, token: str, *, retry_budget: float = 30.0):
+        if not token or "\n" in token or "\r" in token:
+            raise ValueError("instance token is required and must not contain newlines")
+        self.base_url = validate_base_url(base_url)
+        self.retry_budget = retry_budget
+        self._headers = {"Authorization": f"Bearer {token}", "User-Agent": USER_AGENT}
+
+    def _request(self, method: str, path: str, body: Mapping[str, Any] | None, key: str | None) -> tuple[dict[str, str], bytes | None]:
+        headers = dict(self._headers)
+        content = None
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+            content = dumps(body)
+        if key is not None:
+            headers["Idempotency-Key"] = key
+        return headers, content
+
+
+class Client(_Base):
+    """Synchronous AAP client for one instance credential."""
+
+    def __init__(self, base_url: str, token: str, *, http: httpx.Client | None = None, retry_budget: float = 30.0):
+        super().__init__(base_url, token, retry_budget=retry_budget)
+        self._http = http or httpx.Client(timeout=40.0, follow_redirects=False)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def _send(self, method: str, path: str, body: Mapping[str, Any] | None = None, key: str | None = None, *, timeout: float | None = None) -> Request:
+        headers, content = self._request(method, path, body, key)
+        deadline = time.monotonic() + self.retry_budget
+        delay = 0.1
+        while True:
+            wait = delay
+            try:
+                response = self._http.request(method, self.base_url + path, headers=headers, content=content, timeout=timeout or 40.0)
+                raw = response.read()
+                result = _result(response, raw)
+                if result is not None:
+                    return result
+                wait = max(delay, _retry_after(response) or 0.0)
+            except httpx.TransportError:
+                pass
+            if time.monotonic() + wait > deadline:
+                raise AAPError("the provider could not be reached")
+            time.sleep(wait)
+            delay = min(delay * 2, 2.0)
+
+    def create(self, submission: Mapping[str, Any], key: str) -> Request:
+        return self._send("POST", "/v1/requests", submission, key)
+
+    def get(self, request_id: str, *, wait: int | None = None) -> Request:
+        query = f"?wait={wait}s" if wait else ""
+        return self._send("GET", f"/v1/requests/{request_id}{query}", timeout=(wait or 0) + 10.0)
+
+    def cancel(self, request_id: str) -> Request:
+        return self._send("DELETE", f"/v1/requests/{request_id}")
+
+    def consume(self, request_id: str, key: str) -> Request:
+        return self._send("POST", f"/v1/requests/{request_id}/consume", None, key)
+
+    def report_outcome(self, request_id: str, status: str, note: str | None = None) -> Request:
+        body = {"status": status, **({"note": note} if note else {})}
+        return self._send("POST", f"/v1/requests/{request_id}/outcome", body)
+
+
+class AsyncClient(_Base):
+    """Asynchronous AAP client for one instance credential."""
+
+    def __init__(self, base_url: str, token: str, *, http: httpx.AsyncClient | None = None, retry_budget: float = 30.0):
+        super().__init__(base_url, token, retry_budget=retry_budget)
+        self._http = http or httpx.AsyncClient(timeout=40.0, follow_redirects=False)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def _send(self, method: str, path: str, body: Mapping[str, Any] | None = None, key: str | None = None, *, timeout: float | None = None) -> Request:
+        headers, content = self._request(method, path, body, key)
+        deadline = time.monotonic() + self.retry_budget
+        delay = 0.1
+        while True:
+            wait = delay
+            try:
+                response = await self._http.request(method, self.base_url + path, headers=headers, content=content, timeout=timeout or 40.0)
+                raw = await response.aread()
+                result = _result(response, raw)
+                if result is not None:
+                    return result
+                wait = max(delay, _retry_after(response) or 0.0)
+            except httpx.TransportError:
+                pass
+            if time.monotonic() + wait > deadline:
+                raise AAPError("the provider could not be reached")
+            await asyncio.sleep(wait)
+            delay = min(delay * 2, 2.0)
+
+    async def create(self, submission: Mapping[str, Any], key: str) -> Request:
+        return await self._send("POST", "/v1/requests", submission, key)
+
+    async def get(self, request_id: str, *, wait: int | None = None) -> Request:
+        query = f"?wait={wait}s" if wait else ""
+        return await self._send("GET", f"/v1/requests/{request_id}{query}", timeout=(wait or 0) + 10.0)
+
+    async def cancel(self, request_id: str) -> Request:
+        return await self._send("DELETE", f"/v1/requests/{request_id}")
+
+    async def consume(self, request_id: str, key: str) -> Request:
+        return await self._send("POST", f"/v1/requests/{request_id}/consume", None, key)
+
+    async def report_outcome(self, request_id: str, status: str, note: str | None = None) -> Request:
+        body = {"status": status, **({"note": note} if note else {})}
+        return await self._send("POST", f"/v1/requests/{request_id}/outcome", body)

agentapprovalprotocol/_gate.py

@@ -0,0 +1,310 @@
+"""The gate: whether one tool call may run now.
+
+Every check runs the same steps, whether the call is new or seen again
+after a resume: create the request with the call's idempotency key (a
+replay returns the existing request), wait or report pending, check the
+decision, consume it, allow. A value a framework passes back on resume is
+never read, so only the provider can approve. Any failure denies.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import hashlib
+import logging
+import time
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, AsyncIterator, Awaitable, Callable, Iterator, Literal, Mapping
+
+from ._client import AAPError, AsyncClient, Client, ConflictError, CredentialRefused
+from ._wire import APPROVED, CANCELLED, DENIED, EXPIRED, PENDING, ProtocolError, Request, dumps, loads, matches
+
+log = logging.getLogger("agentapprovalprotocol")
+
+FAIL_CLOSED = "The approval adapter could not obtain a valid AAP decision. The call was not run."
+REFUSED = "The approval provider refused this agent's credential, so no tool call can run. Ask whoever manages the agent. The call was not run."
+EXPIRED_TEXT = "The approval window or permission to start this call expired. The call was not run."
+CANCELLED_TEXT = "The call was cancelled before execution."
+CONSUMED_TEXT = "This approved call was already attempted, so it was not run again. Request approval again if it still needs to happen."
+TIMED_OUT = "Approval was not obtained in time. The call was not run."
+
+Mode = Literal["sync", "async"]
+
+
+@dataclass(frozen=True)
+class Call:
+    """One tool call the gate is asked about.
+
+    ``key`` must identify this tool call within its run and stay the same
+    when the call is seen again after a resume or replay. ``resume`` is how
+    a receiver wakes the run later, in async mode.
+    """
+
+    key: str
+    tool: str
+    arguments: Mapping[str, Any]
+    server: str | None = None
+    reasoning: str | None = None
+    context: Mapping[str, Any] | None = None
+    resume: Mapping[str, Any] | None = None
+
+
+@dataclass(frozen=True)
+class Allow:
+    """The approval was checked and consumed. Run the tool now."""
+
+    request_id: str
+    _report: Callable[[str, str | None], Any] = field(repr=False)
+
+    def __bool__(self) -> bool:
+        return True
+
+    def report(self, status: Literal["succeeded", "failed"], note: str | None = None) -> Any:
+        """Report the outcome. Best effort: failures are logged, never raised."""
+        return self._report(status, note)
+
+
+@dataclass(frozen=True)
+class Deny:
+    """The call must not run. ``reason`` is written for the model."""
+
+    reason: str
+    status: str
+    request_id: str | None = None
+
+    def __bool__(self) -> bool:
+        return False
+
+
+@dataclass(frozen=True)
+class Pending:
+    """Async mode: no decision yet. Pause the run; a receiver wakes it."""
+
+    request_id: str
+
+    def __bool__(self) -> bool:
+        return False
+
+
+Verdict = Allow | Deny | Pending
+
+
+def submission(call: Call, timeout: str, defaults: Mapping[str, Any]) -> dict[str, Any]:
+    context = {**defaults, **(call.context or {}), "call_id": call.key}
+    if call.resume is not None:
+        context["resume"] = dict(call.resume)
+    body: dict[str, Any] = {"tool": call.tool, "arguments": dict(call.arguments), "timeout": timeout, "context": context}
+    if call.server:
+        body["server"] = call.server
+    if call.reasoning:
+        body["agent_reasoning"] = call.reasoning
+    return body
+
+
+def idempotency_key(call: Call, body: Mapping[str, Any]) -> str:
+    """Stable for the same call and submission; any change asks again."""
+    return hashlib.sha256(call.key.encode() + b"\x00" + dumps(body)).hexdigest()
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _settled(request: Request) -> Deny | None:
+    """The deny for a terminal request, or None when it may be consumed."""
+    if request.status == DENIED:
+        note = request.decision.note if request.decision else None
+        return Deny(f"The provider denied this call: {note}" if note else "The provider denied this call.", DENIED, request.id)
+    if request.status == CANCELLED:
+        return Deny(CANCELLED_TEXT, CANCELLED, request.id)
+    if request.status == EXPIRED:
+        return Deny(EXPIRED_TEXT, EXPIRED, request.id)
+    assert request.status == APPROVED and request.decision and request.decision.expires_at
+    if request.consumption is not None:
+        return Deny(CONSUMED_TEXT, "consumed", request.id)
+    if _now() >= request.decision.expires_at:
+        return Deny(EXPIRED_TEXT, EXPIRED, request.id)
+    return None
+
+
+def _consumed(request: Request, consumed: Request, body: Mapping[str, Any]) -> bool:
+    return consumed.status == APPROVED and consumed.consumption is not None and matches(consumed, body, request)
+
+
+def _conflict(err: ConflictError, request_id: str) -> Deny:
+    if err.code == "already_consumed":
+        return Deny(CONSUMED_TEXT, "consumed", request_id)
+    if err.code == "approval_expired":
+        return Deny(EXPIRED_TEXT, EXPIRED, request_id)
+    return Deny(FAIL_CLOSED, "error", request_id)
+
+
+def _failure(err: BaseException, request_id: str | None) -> Deny:
+    if isinstance(err, CredentialRefused):
+        return Deny(REFUSED, "error", request_id)
+    if not isinstance(err, (AAPError, ProtocolError)):
+        log.exception("approval gate failed", exc_info=err)
+    return Deny(FAIL_CLOSED, "error", request_id)
+
+
+class _GateConfig:
+    def __init__(self, mode: Mode, timeout: str | None, wait_limit: float, context: Mapping[str, Any] | None, report_outcomes: bool):
+        if mode not in ("sync", "async"):
+            raise ValueError("mode must be sync or async")
+        self.mode = mode
+        self.timeout = timeout or ("24h" if mode == "async" else "10m")
+        self.wait_limit = wait_limit
+        self.context = dict(context or {})
+        self.report_outcomes = report_outcomes
+
+    def _poll_until(self, request: Request, started: float) -> float:
+        remaining = (request.deadline_at - _now()).total_seconds() + 10
+        return started + min(self.wait_limit, max(0.0, remaining))
+
+
+class Gate(_GateConfig):
+    """Synchronous gate.
+
+    In sync mode ``check`` waits for the decision. In async mode it returns
+    ``Pending`` when there is none yet, unless the caller says this call
+    cannot be paused, in which case it waits.
+    """
+
+    def __init__(self, client: Client, *, mode: Mode = "sync", timeout: str | None = None, wait_limit: float = 540.0, context: Mapping[str, Any] | None = None, report_outcomes: bool = True):
+        super().__init__(mode, timeout, wait_limit, context, report_outcomes)
+        self.client = client
+
+    def check(self, call: Call, *, can_pause: bool = True) -> Verdict:
+        body = submission(call, self.timeout, self.context)
+        request: Request | None = None
+        try:
+            request = self.client.create(body, idempotency_key(call, body))
+            body = loads(dumps(body))  # compare responses with what was sent, exactly
+            if not matches(request, body):
+                raise ProtocolError("the provider returned a different request")
+            started = time.monotonic()
+            while request.status == PENDING:
+                if self.mode == "async" and can_pause:
+                    return Pending(request.id)
+                left = self._poll_until(request, started) - time.monotonic()
+                if left <= 0:
+                    self._abandon(request.id)
+                    return Deny(TIMED_OUT, EXPIRED, request.id)
+                previous, polled = request, time.monotonic()
+                request = self.client.get(request.id, wait=max(1, min(25, int(left))))
+                if not matches(request, body, previous):
+                    raise ProtocolError("the provider returned a different request")
+                if request.status == PENDING and time.monotonic() - polled < 0.1:
+                    time.sleep(0.1)  # the provider answered without waiting
+            if (deny := _settled(request)) is not None:
+                return deny
+            try:
+                consumed = self.client.consume(request.id, str(uuid.uuid4()))
+            except ConflictError as err:
+                return _conflict(err, request.id)
+            if not _consumed(request, consumed, body):
+                raise ProtocolError("invalid consumption")
+            return Allow(request.id, self._reporter(request.id))
+        except Exception as err:  # noqa: BLE001 - every failure denies
+            return _failure(err, request.id if request else None)
+
+    def _abandon(self, request_id: str) -> None:
+        with contextlib.suppress(Exception):
+            self.client.cancel(request_id)
+
+    def _reporter(self, request_id: str) -> Callable[[str, str | None], bool]:
+        def report(status: str, note: str | None) -> bool:
+            try:
+                self.client.report_outcome(request_id, status, note)
+                return True
+            except Exception:  # noqa: BLE001
+                log.warning("could not report the outcome of %s", request_id, exc_info=True)
+                return False
+
+        return report
+
+    @contextlib.contextmanager
+    def guard(self, call: Call, *, can_pause: bool = True) -> Iterator[Verdict]:
+        """Check the call; on an allow, report the outcome when the block exits."""
+        verdict = self.check(call, can_pause=can_pause)
+        try:
+            yield verdict
+        except BaseException:
+            if isinstance(verdict, Allow) and self.report_outcomes:
+                verdict.report("failed")
+            raise
+        if isinstance(verdict, Allow) and self.report_outcomes:
+            verdict.report("succeeded")
+
+
+class AsyncGate(_GateConfig):
+    """Asynchronous gate, the same rules as ``Gate`` on an ``AsyncClient``."""
+
+    def __init__(self, client: AsyncClient, *, mode: Mode = "sync", timeout: str | None = None, wait_limit: float = 540.0, context: Mapping[str, Any] | None = None, report_outcomes: bool = True):
+        super().__init__(mode, timeout, wait_limit, context, report_outcomes)
+        self.client = client
+
+    async def check(self, call: Call, *, can_pause: bool = True) -> Verdict:
+        body = submission(call, self.timeout, self.context)
+        request: Request | None = None
+        try:
+            request = await self.client.create(body, idempotency_key(call, body))
+            body = loads(dumps(body))  # compare responses with what was sent, exactly
+            if not matches(request, body):
+                raise ProtocolError("the provider returned a different request")
+            started = time.monotonic()
+            while request.status == PENDING:
+                if self.mode == "async" and can_pause:
+                    return Pending(request.id)
+                left = self._poll_until(request, started) - time.monotonic()
+                if left <= 0:
+                    await self._abandon(request.id)
+                    return Deny(TIMED_OUT, EXPIRED, request.id)
+                previous, polled = request, time.monotonic()
+                request = await self.client.get(request.id, wait=max(1, min(25, int(left))))
+                if not matches(request, body, previous):
+                    raise ProtocolError("the provider returned a different request")
+                if request.status == PENDING and time.monotonic() - polled < 0.1:
+                    await asyncio.sleep(0.1)  # the provider answered without waiting
+            if (deny := _settled(request)) is not None:
+                return deny
+            try:
+                consumed = await self.client.consume(request.id, str(uuid.uuid4()))
+            except ConflictError as err:
+                return _conflict(err, request.id)
+            if not _consumed(request, consumed, body):
+                raise ProtocolError("invalid consumption")
+            return Allow(request.id, self._reporter(request.id))
+        except Exception as err:  # noqa: BLE001 - every failure denies
+            return _failure(err, request.id if request else None)
+
+    async def _abandon(self, request_id: str) -> None:
+        with contextlib.suppress(Exception):
+            await self.client.cancel(request_id)
+
+    def _reporter(self, request_id: str) -> Callable[[str, str | None], Awaitable[bool]]:
+        async def report(status: str, note: str | None) -> bool:
+            try:
+                await self.client.report_outcome(request_id, status, note)
+                return True
+            except Exception:  # noqa: BLE001
+                log.warning("could not report the outcome of %s", request_id, exc_info=True)
+                return False
+
+        return report
+
+    @contextlib.asynccontextmanager
+    async def guard(self, call: Call, *, can_pause: bool = True) -> AsyncIterator[Verdict]:
+        """Check the call; on an allow, report the outcome when the block exits."""
+        verdict = await self.check(call, can_pause=can_pause)
+        try:
+            yield verdict
+        except BaseException:
+            if isinstance(verdict, Allow) and self.report_outcomes:
+                await verdict.report("failed")
+            raise
+        if isinstance(verdict, Allow) and self.report_outcomes:
+            await verdict.report("succeeded")