managed-deepagents 0.6.2.dev6__py3-none-win_amd64.whl → 0.6.2.dev7__py3-none-win_amd64.whl

managed_deepagents/__init__.py

@@ -9,12 +9,19 @@ This package provides two things:
 
 Resources use ``define_*`` factories while provider collections use namespaces:
 ``define_sandbox()``, ``channels.slack(...)``, ``connectors.mcp(...)``,
-and ``auth.supabase(...)``. Contributing a *new*
+``credentials.get(...)``, and ``auth.supabase(...)``. Contributing a *new*
 primitive is not part of the public surface.
 """
 
 from __future__ import annotations
 
+from managed_deepagents._credentials import (
+    CredentialAuthorizationRequiredError,
+    CredentialNotFoundError,
+    CredentialOwner,
+    CredentialStoreError,
+    credentials,
+)
 from managed_deepagents._managed_tools import (
     ManagedDeepAgentRuntime,
 )
@@ -31,6 +38,10 @@ from managed_deepagents.sandbox import SandboxDefinition
 from managed_deepagents.schedules import define_schedule
 
 __all__ = [
+    "CredentialAuthorizationRequiredError",
+    "CredentialNotFoundError",
+    "CredentialOwner",
+    "CredentialStoreError",
     "DeepAgentDefinition",
     "ManagedDeepAgentRuntime",
     "MemoryDefinition",
@@ -38,6 +49,7 @@ __all__ = [
     "auth",
     "channels",
     "connectors",
+    "credentials",
     "define_deep_agent",
     "define_identity",
     "define_memory",

managed_deepagents/_agent_auth.py

@@ -0,0 +1,260 @@
+"""Agent Auth client used by ``credentials.get`` and the pre-run credential gate.
+
+Talks to the shipped Agent Auth APIs (credentials + oauth-authorization-sessions),
+not the aspirational ``credentials/mint`` endpoint.
+"""
+
+from __future__ import annotations
+
+import urllib.parse
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Protocol, TypedDict
+
+from managed_deepagents._agent_auth_http import (
+    AGENT_AUTH_TIMEOUT_SECONDS,
+    CredentialStoreError,
+    agent_auth_credential_query,
+    agent_auth_headers,
+    request_agent_auth_json,
+)
+
+AGENT_AUTH_PROVIDER_PAGE_SIZE = 100
+AGENT_AUTH_MAX_PROVIDER_PAGES = 20
+
+_HTTP_BAD_REQUEST = 400
+_HTTP_NOT_FOUND = 404
+_HTTP_CONFLICT = 409
+
+__all__ = [
+    "AGENT_AUTH_TIMEOUT_SECONDS",
+    "AgentAuth",
+    "AgentAuthContext",
+    "AgentAuthUnknownProviderError",
+    "CredentialAuthorizationRequiredError",
+    "PendingAuthorization",
+]
+
+
+@dataclass(frozen=True)
+class AgentAuthContext:
+    base_url: str
+    #: Deployment id, passed to oauth-authorization-sessions as ``agent_id``.
+    agent_id: str
+    #: Authenticated caller, used as ``owner_id`` for user credentials.
+    principal_id: str
+    api_key: str | None = None
+    workspace_id: str | None = None
+
+
+class PendingAuthorization(TypedDict):
+    """One credential slug the caller has not granted, with its connect URL."""
+
+    slug: str
+    connect_url: str
+    auth_id: str
+
+
+class CredentialAuthorizationRequiredError(RuntimeError):
+    def __init__(self, slugs: list[str]) -> None:
+        super().__init__(
+            f"the caller has not connected: {', '.join(slugs)}. Declare the credential "
+            "on a connector so the pre-run gate can request it."
+        )
+        self.slugs = slugs
+
+
+class AgentAuthUnknownProviderError(RuntimeError):
+    def __init__(self, slug: str) -> None:
+        super().__init__(
+            f'Agent Auth has no OAuth provider registered for slug "{slug}". '
+            "Register the provider or fix the credential slug."
+        )
+        self.slug = slug
+
+
+class AgentAuthRequest(Protocol):
+    """HTTP surface bound onto :class:`AgentAuth` (method, path, optional JSON body)."""
+
+    def __call__(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: dict[str, object] | None = None,
+    ) -> tuple[int, dict[str, object]]: ...
+
+
+class AgentAuth:
+    """Bound Agent Auth HTTP client. Headers, origin, and timeout live on the instance."""
+
+    def __init__(
+        self,
+        context: AgentAuthContext,
+        *,
+        request: AgentAuthRequest | None = None,
+        timeout: float = AGENT_AUTH_TIMEOUT_SECONDS,
+    ) -> None:
+        """Bind this client to a caller.
+
+        Args:
+            context: Caller/run identity and Agent Auth origin.
+            request: Testing only. Substitute for the default HTTP transport.
+            timeout: Testing only. Override the request budget in seconds.
+        """
+        self.context = context
+        self._timeout = timeout
+        self._request: AgentAuthRequest = request if request is not None else self._urlopen_json
+
+    def read_user_access_token(self, slug: str) -> str | None:
+        """Read the caller's OAuth access token without starting a session.
+
+        Reads never mint, so a caller can be probed repeatedly — on every replay
+        of an interrupted node, for instance — without leaving authorization
+        sessions behind.
+
+        Returns:
+            The access token, or ``None`` when the caller must connect.
+        """
+        credential_id = self.find_credential_id(
+            owner_type="user",
+            owner_id=self.context.principal_id,
+            kind="oauth2",
+            slug=slug,
+        )
+        if credential_id is None:
+            return None
+        return self._fetch_access_token(credential_id)
+
+    def start_authorization_session(self, slug: str) -> PendingAuthorization:
+        """Start an OAuth session for a slug the caller has not granted."""
+        provider_id = self.resolve_oauth_provider_id(slug)
+        status, body = self._request(
+            "POST",
+            "/v1/agent-auth/oauth-authorization-sessions",
+            body={
+                "provider_id": provider_id,
+                "principal_id": self.context.principal_id,
+                "agent_id": self.context.agent_id,
+            },
+        )
+        if status >= _HTTP_BAD_REQUEST:
+            raise CredentialStoreError(
+                "Agent Auth create oauth-authorization-session failed", status
+            )
+        auth_id = str(body.get("id") or "")
+        connect_url = str(body.get("verification_url") or "")
+        if not auth_id or not connect_url:
+            raise CredentialStoreError(
+                "Agent Auth oauth-authorization-session missing id or verification_url"
+            )
+        return {"slug": slug, "connect_url": connect_url, "auth_id": auth_id}
+
+    def resolve_oauth_provider_id(self, slug: str) -> str:
+        """oauth-providers has no slug filter, so the match is made across pages."""
+        cursor: str | None = None
+        for _ in range(AGENT_AUTH_MAX_PROVIDER_PAGES):
+            query = {"page_size": str(AGENT_AUTH_PROVIDER_PAGE_SIZE)}
+            if cursor:
+                query["cursor"] = cursor
+            status, body = self._request(
+                "GET", f"/v1/agent-auth/oauth-providers?{urllib.parse.urlencode(query)}"
+            )
+            if status >= _HTTP_BAD_REQUEST:
+                raise CredentialStoreError("Agent Auth list oauth-providers failed", status)
+            raw_items = body.get("items")
+            for item in raw_items if isinstance(raw_items, list) else []:
+                if isinstance(item, Mapping) and item.get("slug") == slug and item.get("id"):
+                    return str(item["id"])
+            next_cursor = body.get("next_cursor")
+            if not isinstance(next_cursor, str) or not next_cursor or next_cursor == cursor:
+                raise AgentAuthUnknownProviderError(slug)
+            cursor = next_cursor
+        raise CredentialStoreError("Agent Auth oauth-provider list returned too many pages")
+
+    def find_credential_id(
+        self,
+        *,
+        owner_type: str,
+        owner_id: str,
+        kind: str,
+        slug: str,
+    ) -> str | None:
+        """Find a credential id by slug.
+
+        The credential key is ``credential_id``, never ``id``.
+        """
+        query = agent_auth_credential_query(
+            owner_type=owner_type, owner_id=owner_id, kind=kind, slug=slug
+        )
+        status, body = self._request("GET", f"/v1/agent-auth/credentials?{query}")
+        if status >= _HTTP_BAD_REQUEST:
+            raise CredentialStoreError("Agent Auth list credentials failed", status)
+        items = body.get("items")
+        row = items[0] if isinstance(items, list) and items else None
+        credential_id = row.get("credential_id") if isinstance(row, Mapping) else None
+        return credential_id if isinstance(credential_id, str) else None
+
+    def read_secret(self, credential_id: str) -> str | None:
+        status, body = self._request(
+            "GET",
+            f"/v1/agent-auth/credentials/{_path_segment(credential_id)}/secret",
+        )
+        if status == _HTTP_NOT_FOUND:
+            return None
+        if status >= _HTTP_BAD_REQUEST:
+            raise CredentialStoreError("Agent Auth get secret failed", status)
+        secret = body.get("secret")
+        return secret if isinstance(secret, str) and secret else None
+
+    def _fetch_access_token(self, credential_id: str) -> str | None:
+        status, body = self._request(
+            "GET",
+            f"/v1/agent-auth/credentials/{_path_segment(credential_id)}/oauth2",
+        )
+        if _is_authorization_required(status, body):
+            return None
+        if status >= _HTTP_BAD_REQUEST:
+            raise CredentialStoreError("Agent Auth get oauth2 failed", status)
+        oauth2 = body.get("oauth2") if isinstance(body.get("oauth2"), dict) else body
+        token = oauth2.get("access_token") if isinstance(oauth2, dict) else None
+        return token if isinstance(token, str) and token else None
+
+    def _urlopen_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: dict[str, object] | None = None,
+    ) -> tuple[int, dict[str, object]]:
+        if not self.context.base_url.startswith(("http://", "https://")):
+            raise ValueError("Agent Auth URL must be an http(s) URL")
+        return request_agent_auth_json(
+            method,
+            f"{self.context.base_url}{path}",
+            body=body,
+            headers=self._headers(),
+            timeout=self._timeout,
+        )
+
+    def _headers(self) -> dict[str, str]:
+        return agent_auth_headers(
+            api_key=self.context.api_key,
+            workspace_id=self.context.workspace_id,
+        )
+
+
+def _path_segment(value: str) -> str:
+    return urllib.parse.quote(value, safe="")
+
+
+def _is_authorization_required(status: int, body: dict[str, object]) -> bool:
+    """Agent Auth answers 409 when a stored grant has lapsed and needs re-auth."""
+    if status != _HTTP_CONFLICT:
+        return False
+    detail = str(body.get("detail") or body.get("title") or body.get("error") or "").lower()
+    return (
+        body.get("error") == "authorization_required"
+        or "authorization is required" in detail
+        or "oauth authorization" in detail
+    )

managed_deepagents/_agent_auth_http.py

@@ -0,0 +1,119 @@
+"""Shared Agent Auth HTTP transport and credential-list paging.
+
+Used by ``credentials.get`` and the credential gate so both talk to the same
+API with the same headers, redirect policy, and page walker.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Mapping
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from http.client import HTTPMessage
+    from typing import IO
+
+AGENT_AUTH_TIMEOUT_SECONDS = 10.0
+
+
+class CredentialStoreError(RuntimeError):
+    """Agent Auth could not answer.
+
+    Callers pass a fixed message: a response body can quote secret material, so
+    it never reaches this error, the logs, or the traceback chain.
+    """
+
+    def __init__(self, message: str, status: int | None = None) -> None:
+        self.status = status
+        super().__init__(message if status is None else f"{message} (status {status})")
+
+
+__all__ = [
+    "AGENT_AUTH_TIMEOUT_SECONDS",
+    "CredentialStoreError",
+    "agent_auth_credential_query",
+    "agent_auth_headers",
+    "request_agent_auth_json",
+]
+
+
+def agent_auth_credential_query(
+    *,
+    owner_type: str,
+    owner_id: str,
+    kind: str,
+    slug: str,
+) -> str:
+    """Query string that addresses one credential by its natural key."""
+    return urllib.parse.urlencode(
+        {"owner_type": owner_type, "owner_id": owner_id, "kind": kind, "slug": slug}
+    )
+
+
+def agent_auth_headers(
+    *,
+    api_key: str | None = None,
+    workspace_id: str | None = None,
+) -> dict[str, str]:
+    headers = {
+        "accept": "application/json",
+        "content-type": "application/json",
+        "x-langsmith-product": "mda",
+    }
+    resolved_api_key = (api_key or "").strip()
+    if resolved_api_key:
+        headers["x-api-key"] = resolved_api_key
+    resolved_workspace = (workspace_id or "").strip()
+    if resolved_workspace:
+        headers["x-tenant-id"] = resolved_workspace
+    return headers
+
+
+def _decode_json_object(raw: bytes) -> dict[str, object]:
+    try:
+        payload = json.loads(raw.decode("utf-8") or "{}")
+    except (UnicodeDecodeError, json.JSONDecodeError, ValueError):
+        return {}
+    return payload if isinstance(payload, dict) else {}
+
+
+class _NoRedirectHandler(urllib.request.HTTPRedirectHandler):
+    def redirect_request(
+        self,
+        req: urllib.request.Request,
+        fp: IO[bytes],
+        code: int,
+        msg: str,
+        headers: HTTPMessage,
+        newurl: str,
+    ) -> urllib.request.Request | None:
+        del req, fp, code, msg, headers, newurl
+        return None
+
+
+def request_agent_auth_json(
+    method: str,
+    url: str,
+    *,
+    body: Mapping[str, object] | None = None,
+    headers: Mapping[str, str],
+    timeout: float,
+) -> tuple[int, dict[str, object]]:
+    """Issue one Agent Auth HTTP call: no redirects, bounded timeout, JSON body."""
+    data = None if body is None else json.dumps(dict(body)).encode("utf-8")
+    request = urllib.request.Request(  # noqa: S310
+        url,
+        data=data,
+        headers=dict(headers),
+        method=method,
+    )
+    try:
+        opener = urllib.request.build_opener(_NoRedirectHandler())
+        with opener.open(request, timeout=timeout) as response:
+            return int(response.status), _decode_json_object(response.read())
+    except urllib.error.HTTPError as exc:
+        return int(exc.code), _decode_json_object(exc.read())

managed_deepagents/_channels/schedule_delivery.py

@@ -2,31 +2,30 @@
 
 from __future__ import annotations
 
+import logging
 import os
-import uuid
 from collections.abc import Awaitable, Callable, Mapping
 from importlib import import_module
 from typing import TYPE_CHECKING, Any, Literal, TypedDict, cast
 
 from managed_deepagents._channels.assistant_text import extract_assistant_text
 from managed_deepagents._channels.binding import SLACK_BOT_TOKEN_ENV
-from managed_deepagents._channels.trigger.client import create_trigger_client
 from managed_deepagents._identity_runtime import (
     _ambient_configurable,
     _configurable_from_runtime,
 )
-from managed_deepagents._log import logger
 from managed_deepagents._memory.async_util import await_if_needed
 
 if TYPE_CHECKING:
     from langchain.agents.middleware.types import AgentMiddleware
 
-    from managed_deepagents._channels.trigger.types import TriggerChannelActionRequest
     from managed_deepagents._channels.types import ChannelAddress
 else:
     # Authoring-light installs may lack langchain; annotations stay deferred.
     AgentMiddleware = object
 
+_LOG = logging.getLogger("mda")
+
 _schedule_metadata_for_tests: Callable[[], Mapping[str, object] | None] | None = None
 
 
@@ -59,16 +58,6 @@ class NormalizedScheduleDeliverTo(TypedDict):
     auto_post: bool
 
 
-def get_deployment_id(env: Mapping[str, str] | None = None) -> str | None:
-    """Return the deployment ID supplied by the managed runtime."""
-    resolved_env = os.environ if env is None else env
-    for key in ("LANGSMITH_HOST_PROJECT_ID", "LANGGRAPH_CLOUD_ID"):
-        value = (resolved_env.get(key) or "").strip()
-        if value:
-            return value
-    return None
-
-
 def read_schedule_deliver_to(  # noqa: PLR0911 - validation short-circuits
     configurable: Mapping[str, object] | None,
 ) -> NormalizedScheduleDeliverTo | None:
@@ -133,7 +122,7 @@ def address_from_deliver_to(to: _ProviderConversation | _ProviderThread) -> Chan
     return {"conversation_id": to["conversation_id"]}
 
 
-async def deliver_schedule_result(  # noqa: C901, PLR0911 - soft-fail outcomes
+async def deliver_schedule_result(  # noqa: PLR0911 - soft-fail outcomes
     *,
     deliver_to: NormalizedScheduleDeliverTo,
     reply_text: str,
@@ -145,9 +134,9 @@ async def deliver_schedule_result(  # noqa: C901, PLR0911 - soft-fail outcomes
     if not text or not deliver_to["auto_post"]:
         return "skipped"
     if deliver_to["channel"] != "slack":
-        logger.error(
-            'schedule deliver_to channel "%s" is not supported yet',
-            logger.log_identifier(deliver_to["channel"]),
+        _LOG.error(
+            "schedule deliver_to channel %r is not supported yet",
+            deliver_to["channel"],
         )
         return "failed"
 
@@ -162,47 +151,15 @@ async def deliver_schedule_result(  # noqa: C901, PLR0911 - soft-fail outcomes
             if hasattr(result, "__await__"):
                 await cast("Awaitable[object]", result)
             return "posted"
-        except Exception as error:  # noqa: BLE001 - soft-fail schedule delivery
-            logger.error(
-                "schedule Slack delivery failed (%s)",
-                logger.safe_error_label(error),
-            )
-            return "failed"
-
-    deployment_id = get_deployment_id()
-    try:
-        client = create_trigger_client()
-    except ValueError:
-        client = None
-    if client is not None and deployment_id:
-        action: TriggerChannelActionRequest = {
-            "type": "post",
-            "action_id": str(uuid.uuid4()),
-            "address": dict(address),
-            "message": {"text": text},
-        }
-        try:
-            await client.post_deployment_action(
-                deployment_id,
-                deliver_to["channel"],
-                action,
-            )
-            return "posted"
-        except Exception as error:  # noqa: BLE001 - soft-fail schedule delivery
-            logger.error(
-                "schedule Trigger channel delivery failed (%s)",
-                logger.safe_error_label(error),
-            )
+        except Exception:  # noqa: BLE001 - soft-fail schedule delivery
+            _LOG.exception("schedule Slack delivery failed")
             return "failed"
 
     token = (
         bot_token if bot_token is not None else os.environ.get(SLACK_BOT_TOKEN_ENV) or ""
     ).strip()
     if not token:
-        logger.error(
-            "schedule deliver_to requires Trigger channel configuration or "
-            "SLACK_BOT_TOKEN; skipping auto-post"
-        )
+        _LOG.error("schedule deliver_to requires SLACK_BOT_TOKEN; skipping auto-post")
         return "failed"
 
     try:
@@ -219,11 +176,8 @@ async def deliver_schedule_result(  # noqa: C901, PLR0911 - soft-fail outcomes
         if hasattr(posted, "__await__"):
             await cast("Awaitable[object]", posted)
         return "posted"
-    except Exception as error:  # noqa: BLE001 - soft-fail schedule delivery
-        logger.error(
-            "schedule Slack delivery failed (%s)",
-            logger.safe_error_label(error),
-        )
+    except Exception:  # noqa: BLE001 - soft-fail schedule delivery
+        _LOG.exception("schedule Slack delivery failed")
         return "failed"
 
 
@@ -343,7 +297,6 @@ __all__ = [
     "address_from_deliver_to",
     "create_schedule_delivery_middleware",
     "deliver_schedule_result",
-    "get_deployment_id",
     "is_trusted_schedule_delivery_run",
     "read_schedule_deliver_to",
 ]

managed_deepagents/_channels/trigger/client.py

@@ -93,41 +93,18 @@ class TriggerClient(TriggerClientLike):
         channel_id: str,
         body: TriggerChannelActionRequest,
     ) -> TriggerChannelActionResponse:
-        encoded_channel_id = urllib.parse.quote(channel_id, safe="")
-        response = await self._post(
-            "actions",
-            f"{self._api_base}/channels/{encoded_channel_id}/actions",
-            body,
-        )
-        return _parse_action_response(response)
-
-    async def post_deployment_action(
-        self,
-        deployment_id: str,
-        channel_name: str,
-        body: TriggerChannelActionRequest,
-    ) -> TriggerChannelActionResponse:
-        query = urllib.parse.urlencode(
-            {"deployment_id": deployment_id, "channel_name": channel_name}
-        )
-        response = await self._post(
-            "actions",
-            f"{self._api_base}/channels/actions?{query}",
-            body,
-        )
-        return _parse_action_response(response)
+        response = await self._post("actions", channel_id, body)
+        response_id = response.get("id") if isinstance(response, dict) else None
+        if not isinstance(response_id, str) or not response_id.strip():
+            raise TriggerClientError("actions")
+        return {"id": response_id}
 
     async def post_runtime_event(
         self,
         channel_id: str,
         body: TriggerChannelRuntimeEventRequest,
     ) -> TriggerChannelRuntimeEventResponse:
-        encoded_channel_id = urllib.parse.quote(channel_id, safe="")
-        response = await self._post(
-            "events",
-            f"{self._api_base}/channels/{encoded_channel_id}/events",
-            body,
-        )
+        response = await self._post("events", channel_id, body)
         status = response.get("status") if isinstance(response, dict) else None
         if not isinstance(status, str):
             raise TriggerClientError("events")
@@ -136,9 +113,11 @@ class TriggerClient(TriggerClientLike):
     async def _post(
         self,
         operation: TriggerClientOperation,
-        url: str,
+        channel_id: str,
         body: TriggerChannelActionRequest | TriggerChannelRuntimeEventRequest,
     ) -> object:
+        encoded_channel_id = urllib.parse.quote(channel_id, safe="")
+        url = f"{self._api_base}/channels/{encoded_channel_id}/{operation}"
         headers = {
             "content-type": "application/json",
             "x-api-key": self._api_key,
@@ -165,13 +144,6 @@ class TriggerClient(TriggerClientLike):
             raise TriggerClientError(operation) from None
 
 
-def _parse_action_response(response: object) -> TriggerChannelActionResponse:
-    response_id = response.get("id") if isinstance(response, dict) else None
-    if not isinstance(response_id, str) or not response_id.strip():
-        raise TriggerClientError("actions")
-    return {"id": response_id}
-
-
 def create_trigger_client(
     *,
     user_id: str | None = None,

managed_deepagents/_channels/trigger/types.py

@@ -66,15 +66,12 @@ class TriggerChannelActionMessage(TypedDict):
     text: str
 
 
-class TriggerChannelActionRequestRequired(TypedDict):
+class TriggerChannelActionRequest(TypedDict):
     type: Literal["post"]
     action_id: str
     address: TriggerChannelAddress
-    message: TriggerChannelActionMessage
-
-
-class TriggerChannelActionRequest(TriggerChannelActionRequestRequired, total=False):
     source_thread_key: str
+    message: TriggerChannelActionMessage
 
 
 class TriggerChannelActionResponse(TypedDict):