aynigma 0.3.1__py3-none-any.whl

aynigma/__init__.py

@@ -0,0 +1,61 @@
+from .client import (
+    APIError,
+    AsyncAynigma,
+    AuthenticationError,
+    Aynigma,
+    AynigmaError,
+    BlockedError,
+    QuotaExceededError,
+    ValidationResult,
+    aguard_openai_chat,
+    aguard_openai_chat_v2,
+    guard_openai_chat,
+    guard_openai_chat_v2,
+)
+from .agent_errors import MCPError, TokenError
+from .agent_tokens import AgentTokenProvider, DelegatedToken
+from .agents import AgentAuthorizer, ApprovalRequired, RunKilled, ClaudeAgentApprovalBridge, ExecutionReceipt, RemoteTool, ToolDenied, ToolExecutor, OpenAIAgentsApprovalBridge, SemanticKernelApprovalBridge, acting_for_user, as_langchain_tool, build_langgraph_approval_workflow, build_crewai_approval_flow, as_openai_agents_tool, as_crewai_tool, as_claude_agent_tool, as_google_adk_tool, as_google_adk_approval_tool, as_semantic_kernel_function
+from .approval_checkpoints import PostgresApprovalCheckpointStore
+
+async_guard_openai_chat = aguard_openai_chat
+
+__all__ = [
+    "APIError",
+    "AgentAuthorizer",
+    "AgentTokenProvider",
+    "DelegatedToken",
+    "RunKilled",
+    "TokenError",
+    "MCPError",
+    "ApprovalRequired",
+    "ClaudeAgentApprovalBridge",
+    "AsyncAynigma",
+    "AuthenticationError",
+    "Aynigma",
+    "AynigmaError",
+    "BlockedError",
+    "ExecutionReceipt",
+    "OpenAIAgentsApprovalBridge",
+    "PostgresApprovalCheckpointStore",
+    "SemanticKernelApprovalBridge",
+    "QuotaExceededError",
+    "RemoteTool",
+    "ToolDenied",
+    "ToolExecutor",
+    "acting_for_user",
+    "as_langchain_tool",
+    "build_langgraph_approval_workflow",
+    "build_crewai_approval_flow",
+    "as_openai_agents_tool",
+    "as_crewai_tool",
+    "as_claude_agent_tool",
+    "as_google_adk_tool",
+    "as_google_adk_approval_tool",
+    "as_semantic_kernel_function",
+    "ValidationResult",
+    "aguard_openai_chat",
+    "aguard_openai_chat_v2",
+    "async_guard_openai_chat",
+    "guard_openai_chat",
+    "guard_openai_chat_v2",
+]

aynigma/agent_errors.py

@@ -0,0 +1,89 @@
+"""Exceptions shared by the agent authorizer and the token provider."""
+from __future__ import annotations
+
+from typing import Optional
+
+from .client import APIError, AuthenticationError
+
+
+# Short next steps for the denial codes a developer meets most. The code stays first in the message so
+# anything that parses "Agent tool call denied: <code>" keeps working.
+DENIAL_HINTS = {
+    "no_policy": "No rule allows this tool for this agent. Add one on the agent page.",
+    "run_mismatch": "This approval belongs to another run. Resume with "
+                    "AgentAuthorizer(..., run_id=<the run_id from ApprovalRequired>).",
+    "payload_mismatch": "The arguments differ from the ones that were approved.",
+    "approval_already_used": "This approval was already used. Each approval works once, so ask for a new one.",
+    "approval_expired": "This approval expired before it was used. Call the tool again to request a new one.",
+    "approval_not_approved": "A reviewer has not approved this call yet.",
+    "policy_version_changed": "The policy changed after this approval was requested. "
+                              "Call the tool again to request a new one.",
+    "environment": "The matching rule is limited to other environments. "
+                   "Check the rule's environments and the agent's environment on the agent page.",
+    "rate_limited": "The hourly limit on the matching rule is used up. Wait, or raise the limit on the agent page.",
+}
+
+
+class ToolDenied(Exception):
+    """A tool call was refused. ``reason`` is the backend's reason code; ``hint`` is a short next step or None."""
+
+    def __init__(self, reason: str):
+        hint = DENIAL_HINTS.get(reason)
+        super().__init__(f"Agent tool call denied: {reason}" + (f". {hint}" if hint else ""))
+        self.reason = reason
+        self.hint = hint
+
+
+class RunKilled(ToolDenied):
+    """The agent run was stopped by an administrator or an incident.
+
+    Cached tokens are dropped when this is raised. The next call starts a new
+    run, so catch this to stop the current task, not to retry it blindly.
+    """
+
+    def __init__(self, reason: str = "run_killed"):
+        super().__init__(reason)
+
+
+class ApprovalRequired(Exception):
+    """The call needs a human reviewer. Save ``approval_id`` and ``run_id``, then call ``run_tool`` again with
+    ``approval_id`` from an authorizer that continues the same run (``AgentAuthorizer(..., run_id=run_id)``).
+
+    ``run_id`` is the run the approval was raised in (None with the legacy ``X-AGENT-KEY`` header, which has no
+    runs). ``tool_name`` is the tool that was refused, when known.
+    """
+
+    def __init__(self, approval_id: int, call_id: str, run_id: Optional[str] = None,
+                 tool_name: Optional[str] = None):
+        subject = f"Tool call '{tool_name}'" if tool_name else "Tool call"
+        message = (f"{subject} needs human approval (approval {approval_id}). "
+                   f"A reviewer can approve it in Agent IAM > Activity. "
+                   f"Then call run_tool again with approval_id={approval_id}")
+        if run_id:
+            message += f", from a worker started with run_id='{run_id}'"
+        super().__init__(message + ".")
+        self.approval_id = approval_id
+        self.call_id = call_id
+        self.run_id = run_id
+        self.tool_name = tool_name
+
+
+class TokenError(AuthenticationError):
+    """The token endpoint refused a request (RFC 6749 error shape)."""
+
+    def __init__(self, error: str, description: str = "", status_code: Optional[int] = None):
+        super().__init__(f"Agent token request failed: {error}" + (f" ({description})" if description else ""))
+        self.error = error
+        self.error_description = description
+        self.status_code = status_code
+
+
+class MCPError(APIError):
+    """The MCP gateway refused a request (HTTP 400); ``payload`` is the JSON-RPC error body."""
+
+    def __init__(self, payload: dict, status_code: Optional[int] = 400):
+        error = payload.get("error") if isinstance(payload, dict) else None
+        message = error.get("message") if isinstance(error, dict) else None
+        super().__init__(f"MCP request rejected: {message}" if message else "MCP request rejected", status_code)
+        self.payload = payload
+        self.error = error

aynigma/agent_tokens.py

@@ -0,0 +1,404 @@
+"""Short-lived agent tokens: client credentials, caching, refresh and delegation.
+
+``AgentTokenProvider`` trades an agent key for a 15 minute bearer token and keeps
+it fresh. ``exchange`` turns a human's token (or an already delegated token) into
+a delegated token for this agent (RFC 8693). The key is sent only to the token
+endpoint, never to the tool-call, receipt or MCP endpoints.
+"""
+from __future__ import annotations
+
+import argparse
+import base64
+import json
+import logging
+import os
+import re
+import sys
+import threading
+import time
+from concurrent.futures import Future
+from typing import Any, Callable, Dict, Optional, TypeVar, Union
+
+import httpx
+
+from .agent_errors import RunKilled, TokenError
+from .client import APIError
+
+log = logging.getLogger("aynigma.agents")
+DEFAULT_BASE_URL = "https://api.aynigma.ai/api/v1"
+JWT_TYPE = "urn:ietf:params:oauth:token-type:jwt"
+EXCHANGE_GRANT = "urn:ietf:params:oauth:grant-type:token-exchange"
+
+TokenLike = Union[str, "DelegatedToken", "AgentTokenProvider"]
+
+
+def resolve_base_url(base_url: Optional[str] = None) -> str:
+    return (base_url or os.getenv("AYNIGMA_API_URL") or DEFAULT_BASE_URL).rstrip("/")
+
+
+def decode_claims(token: str) -> Dict[str, Any]:
+    """Decode a JWT payload WITHOUT verifying it. For display and debugging only."""
+    try:
+        payload = token.split(".")[1]
+        payload += "=" * (-len(payload) % 4)
+        claims = json.loads(base64.urlsafe_b64decode(payload.encode("ascii")))
+    except (IndexError, ValueError, UnicodeError):
+        raise ValueError("Not a decodable JWT") from None
+    if not isinstance(claims, dict):
+        raise ValueError("Not a decodable JWT")
+    return claims
+
+
+def _token_value(value: TokenLike) -> str:
+    return value if isinstance(value, str) else value.token()
+
+
+T = TypeVar("T")
+
+
+class _SingleFlight:
+    """Run one network call for many concurrent callers; the lock is never held during the call."""
+
+    def __init__(self, lock: "threading.RLock"):
+        self._lock = lock
+        self._future: Optional[Future] = None
+
+    def run(self, fresh: Callable[[], Optional[T]], fn: Callable[[], T]) -> T:
+        """``fresh`` runs under the lock and returns a usable cached value, or None."""
+        with self._lock:
+            hit = fresh()
+            if hit is not None:
+                return hit
+            future = self._future
+            if future is None:
+                future = Future()
+                self._future = future
+                leader = True
+            else:
+                leader = False
+        if not leader:
+            return future.result()
+        try:
+            result = fn()
+        except BaseException as exc:
+            future.set_exception(exc)
+            raise
+        else:
+            future.set_result(result)
+            return result
+        finally:
+            with self._lock:
+                self._future = None
+
+
+class _Issued:
+    """One issued token and the moment it should be replaced."""
+
+    def __init__(self, response: Dict[str, Any], now: float, leeway: float):
+        token = response.get("access_token")
+        if not isinstance(token, str) or not token:
+            raise APIError("Malformed token response")
+        try:
+            expires_in = float(response.get("expires_in") or 0)
+        except (TypeError, ValueError):
+            raise APIError("Malformed token response") from None
+        if expires_in <= 0:
+            try:
+                expires_in = max(float(decode_claims(token)["exp"]) - now, 1.0)
+            except (KeyError, TypeError, ValueError):
+                raise APIError("Malformed token response") from None
+        self.token = token
+        self.scope = str(response.get("scope") or "")
+        self.run_id = response.get("run_id") if isinstance(response.get("run_id"), str) else None
+        self.expires_at = now + expires_in
+        self.refresh_at = now + expires_in * (1.0 - leeway)
+
+
+class DelegatedToken:
+    """A human's authority delegated to one agent. Re-exchanges itself near expiry."""
+
+    def __init__(self, provider: "AgentTokenProvider", subject: TokenLike, scope: Optional[str],
+                 issued: _Issued):
+        self._provider = provider
+        self._subject = subject
+        self._requested_scope = scope
+        self._issued = issued
+        self._lock = threading.RLock()
+        self._flight = _SingleFlight(self._lock)
+
+    def __repr__(self) -> str:  # never show the token
+        return "DelegatedToken(scope=%r)" % self._issued.scope
+
+    def token(self) -> str:
+        def fresh() -> Optional[str]:
+            issued = self._issued
+            return issued.token if self._provider._clock() < issued.refresh_at else None
+
+        def exchange() -> str:
+            issued = self._provider._exchange(self._subject, self._requested_scope)
+            with self._lock:
+                self._issued = issued
+            return issued.token
+        return self._flight.run(fresh, exchange)
+
+    def invalidate(self, failed_token: Optional[str] = None) -> None:
+        """Force the next ``token()`` to exchange again (after a 401).
+
+        With ``failed_token``, only if that is still the current token.
+        """
+        with self._lock:
+            if failed_token is None or self._issued.token == failed_token:
+                self._issued.refresh_at = 0.0
+
+    @property
+    def expires_at(self) -> float:
+        return self._issued.expires_at
+
+    @property
+    def scope(self) -> str:
+        return self._issued.scope
+
+    @property
+    def expired(self) -> bool:
+        return self._provider._clock() >= self._issued.expires_at
+
+    @property
+    def provider(self) -> "AgentTokenProvider":
+        return self._provider
+
+    def claims(self) -> Dict[str, Any]:
+        return decode_claims(self._issued.token)
+
+
+_ACTOR_OR_RUN = re.compile(r"\b(actor|run)")
+
+
+class AgentTokenProvider:
+    """Fetch, cache and refresh a client credentials token for one agent.
+
+    The token is fetched on first use, reused, and replaced once ``leeway`` (a
+    fraction, default 0.2) of its lifetime is left. Thread safe: concurrent
+    callers share one fetch, and no lock is held during network calls.
+
+    A run that ended (idle) is replaced by a new one transparently (logged at
+    INFO). A run that was killed raises ``RunKilled``.
+    """
+
+    def __init__(self, agent_id: str, agent_key: str, base_url: Optional[str] = None,
+                 http_client: Optional[httpx.Client] = None, run_id: Optional[str] = None,
+                 leeway: float = 0.2, timeout: float = 10.0,
+                 clock: Callable[[], float] = time.time):
+        if not agent_id or not agent_key:
+            raise ValueError("agent_id and agent_key are required")
+        if not 0 <= leeway < 1:
+            raise ValueError("leeway must be at least 0 and below 1")
+        self.agent_id = str(agent_id)
+        self._key = agent_key
+        self.base_url = resolve_base_url(base_url)
+        self._http = http_client or httpx.Client(timeout=timeout)
+        self._owns_http = http_client is None
+        self._leeway = leeway
+        self._clock = clock
+        self._run_id = run_id
+        self._issued: Optional[_Issued] = None
+        self._lock = threading.RLock()
+        self._flight = _SingleFlight(self._lock)
+
+    def __repr__(self) -> str:  # never show the key
+        return f"AgentTokenProvider(agent_id={self.agent_id!r})"
+
+    # -- token endpoint -------------------------------------------------
+
+    def _post_token(self, form: Dict[str, str]) -> Dict[str, Any]:
+        try:
+            response = self._http.post(f"{self.base_url}/agents/oauth/token", data=form,
+                                       headers={"Accept": "application/json"})
+        except httpx.HTTPError:
+            raise APIError("Agent token service unavailable") from None
+        try:
+            payload = response.json()
+        except (ValueError, UnicodeDecodeError):
+            raise APIError("Malformed token response", response.status_code) from None
+        if not isinstance(payload, dict):
+            raise APIError("Malformed token response", response.status_code)
+        if response.status_code != 200:
+            error = payload.get("error")
+            if isinstance(error, str) and error:
+                raise TokenError(error, str(payload.get("error_description") or ""), response.status_code)
+            raise APIError("Agent token request failed", response.status_code)
+        return payload
+
+    def _forget_run(self) -> None:
+        with self._lock:
+            self._run_id = None
+            self._issued = None
+
+    def _fetch(self, continue_run: bool = True) -> _Issued:
+        with self._lock:
+            previous = self._run_id
+        run_id = previous if continue_run else None
+        form = {"grant_type": "client_credentials", "client_id": self.agent_id,
+                "client_secret": self._key}
+        if run_id:
+            form["run_id"] = run_id
+        try:
+            payload = self._post_token(form)
+        except TokenError as exc:
+            if exc.error != "invalid_grant" or not run_id:
+                raise
+            self._forget_run()
+            if "run_killed" in exc.error_description:
+                raise RunKilled("run_killed") from None
+            # The run is over for another reason: start a new one.
+            del form["run_id"]
+            payload = self._post_token(form)
+        issued = _Issued(payload, self._clock(), self._leeway)
+        if previous and issued.run_id and issued.run_id != previous:
+            log.info("Agent run %s ended; continuing in new run %s", previous, issued.run_id)
+        with self._lock:
+            if issued.run_id:
+                self._run_id = issued.run_id
+            self._issued = issued
+        return issued
+
+    def _refresh(self, failed_token: Optional[str], continue_run: bool = True) -> _Issued:
+        def fresh() -> Optional[_Issued]:
+            issued = self._issued
+            if issued is None:
+                return None
+            if failed_token is None:
+                return issued if self._clock() < issued.refresh_at else None
+            return issued if issued.token != failed_token else None
+        return self._flight.run(fresh, lambda: self._fetch(continue_run))
+
+    def _current(self) -> _Issued:
+        return self._refresh(None)
+
+    # -- public API -----------------------------------------------------
+
+    def token(self) -> str:
+        return self._current().token
+
+    def cached_token(self) -> Optional[str]:
+        """The cached token, or None. Never touches the network."""
+        issued = self._issued
+        return issued.token if issued is not None else None
+
+    @property
+    def run_id(self) -> Optional[str]:
+        """Run of the current token, or the run being continued. Never touches the network."""
+        issued = self._issued
+        return (issued.run_id if issued is not None else None) or self._run_id
+
+    @property
+    def scope(self) -> Optional[str]:
+        """Scope of the current token, or None before the first fetch. Never touches the network."""
+        issued = self._issued
+        return issued.scope if issued is not None else None
+
+    @property
+    def expires_at(self) -> Optional[float]:
+        issued = self._issued
+        return issued.expires_at if issued is not None else None
+
+    def claims(self) -> Dict[str, Any]:
+        """Decoded claims of the current token. Not verified; do not trust for decisions."""
+        return decode_claims(self.token())
+
+    def invalidate(self, run_killed: bool = False) -> None:
+        """Drop the cached token. After a kill, also forget the run so the next token starts a new one."""
+        with self._lock:
+            self._issued = None
+            if run_killed:
+                self._run_id = None
+
+    def refresh_after_unauthorized(self, failed_token: Optional[str] = None,
+                                   new_run: bool = False) -> str:
+        """Replace the token after the API answered 401.
+
+        Does nothing if ``failed_token`` is no longer the cached token (another
+        caller already refreshed), and concurrent callers share one fetch.
+        Continues the same run; if that run was killed, raises ``RunKilled``.
+        ``new_run=True`` starts a new run (the old one ended).
+        """
+        return self._refresh(failed_token if failed_token is not None else self.cached_token(),
+                             continue_run=not new_run).token
+
+    def _exchange(self, subject: TokenLike, scope: Optional[str]) -> _Issued:
+        def attempt() -> Dict[str, Any]:
+            actor = self.token()
+            form = {
+                "grant_type": EXCHANGE_GRANT,
+                "subject_token": _token_value(subject), "subject_token_type": JWT_TYPE,
+                "actor_token": actor, "actor_token_type": JWT_TYPE,
+            }
+            if scope:
+                form["scope"] = scope
+            try:
+                return self._post_token(form)
+            except TokenError as exc:
+                exc.actor_token = actor  # type: ignore[attr-defined]
+                raise
+        try:
+            payload = attempt()
+        except TokenError as exc:
+            description = exc.error_description.lower()
+            if exc.error != "invalid_grant":
+                raise
+            if "run_killed" in description:
+                self.invalidate(run_killed=True)
+                raise RunKilled("run_killed") from None
+            if not _ACTOR_OR_RUN.search(description):
+                raise  # the user's token was refused: a new actor token would not help
+            self.refresh_after_unauthorized(getattr(exc, "actor_token", None))
+            payload = attempt()
+        return _Issued(payload, self._clock(), self._leeway)
+
+    def exchange(self, subject_token: TokenLike, scope: Optional[str] = None) -> DelegatedToken:
+        """Delegate a user JWT (or another delegated token) to this agent.
+
+        ``scope`` can only narrow what the user and the agent already share.
+        """
+        if isinstance(subject_token, str) and not subject_token:
+            raise ValueError("subject_token is required")
+        return DelegatedToken(self, subject_token, scope, self._exchange(subject_token, scope))
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+
+def _truthy(value: Optional[str]) -> bool:
+    return (value or "").strip().lower() in ("1", "true", "yes", "on")
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="aynigma-agents-token",
+        description="Print an agent token for debugging. Prefer the AYNIGMA_AGENT_KEY variable over --key, "
+                    "which is visible in the process list.")
+    parser.add_argument("--agent-id", default=os.getenv("AYNIGMA_AGENT_ID"))
+    parser.add_argument("--key", default=os.getenv("AYNIGMA_AGENT_KEY"))
+    parser.add_argument("--base-url", default=os.getenv("AYNIGMA_API_URL") or DEFAULT_BASE_URL)
+    parser.add_argument("--claims", action="store_true", help="print the decoded claims instead of the token")
+    args = parser.parse_args(argv)
+    if not args.agent_id:
+        parser.error("--agent-id (or AYNIGMA_AGENT_ID) is required")
+    if not args.key:
+        parser.error("--key (or AYNIGMA_AGENT_KEY) is required")
+    provider = AgentTokenProvider(args.agent_id, args.key, args.base_url)
+    try:
+        if args.claims:
+            print(json.dumps(provider.claims(), indent=2, sort_keys=True))
+        else:
+            print(provider.token())
+    except (TokenError, APIError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    finally:
+        provider.close()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())