managed-deepagents 0.6.2.dev51__py3-none-win_amd64.whl → 0.6.2.dev52__py3-none-win_amd64.whl

managed_deepagents/__init__.py

@@ -8,7 +8,7 @@ This package provides two things:
   ``mda`` console script.
 
 Resources use ``define_*`` factories while provider collections use namespaces:
-``define_sandbox()``, ``define_mcp()``, ``channels.slack(...)``,
+``define_sandbox()``, ``channels.slack(...)``, ``connectors.mcp(...)``,
 ``connections.get(...)``, and ``auth.supabase(...)``. Contributing a *new*
 primitive is not part of the public surface.
 """
@@ -32,7 +32,6 @@ from managed_deepagents.namespaces import (
     auth,
     channels,
     connectors,
-    define_mcp,
     define_sandbox,
 )
 from managed_deepagents.sandbox import SandboxDefinition
@@ -54,7 +53,6 @@ __all__ = [
     "connectors",
     "define_deep_agent",
     "define_identity",
-    "define_mcp",
     "define_memory",
     "define_sandbox",
     "define_schedule",

managed_deepagents/_agent_auth.py

@@ -16,6 +16,7 @@ from managed_deepagents._agent_auth_http import (
     CredentialStoreError,
     agent_auth_credential_query,
     agent_auth_headers,
+    missing_workspace_connection_error,
     request_agent_auth_json,
 )
 
@@ -23,6 +24,7 @@ AGENT_AUTH_PROVIDER_PAGE_SIZE = 100
 AGENT_AUTH_MAX_PROVIDER_PAGES = 20
 
 _HTTP_BAD_REQUEST = 400
+_HTTP_FORBIDDEN = 403
 _HTTP_NOT_FOUND = 404
 _HTTP_CONFLICT = 409
 
@@ -33,21 +35,46 @@ __all__ = [
     "AgentAuthUnknownProviderError",
     "CredentialAuthorizationRequiredError",
     "PendingAuthorization",
+    "ResolvePrincipalIdentity",
     "WorkspaceConnection",
+    "clear_principal_resolve_cache_for_tests",
 ]
 
 
 @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
+    #: Deployment id when present. Required for agent-owned lookups; optional for user OAuth.
+    agent_id: str | None = None
     api_key: str | None = None
     workspace_id: str | None = None
-    #: Agent Builder service JWT for workspace-owned credential material.
-    service_key: str | None = None
+
+
+class ResolvePrincipalIdentity(TypedDict):
+    provider: str
+    issuer: str
+    subject: str
+
+
+_principal_resolve_cache: dict[str, str] = {}
+
+
+def clear_principal_resolve_cache_for_tests() -> None:
+    """Drop cached principal resolutions. Test-only."""
+    _principal_resolve_cache.clear()
+
+
+def _principal_resolve_cache_key(
+    context: AgentAuthContext, identity: ResolvePrincipalIdentity
+) -> str:
+    origin = context.base_url.rstrip("/")
+    workspace = (context.workspace_id or "").strip()
+    return (
+        f"{origin}\0{workspace}\0"
+        f"{identity['provider']}\0{identity['issuer']}\0{identity['subject']}"
+    )
 
 
 class PendingAuthorization(TypedDict):
@@ -116,6 +143,49 @@ class AgentAuth:
         self._timeout = timeout
         self._request: AgentAuthRequest = request if request is not None else self._urlopen_json
 
+    def resolve_principal(self, identity: ResolvePrincipalIdentity) -> str:
+        """Resolve a verified external identity to an Agent Auth principal UUID."""
+        provider = identity["provider"].strip()
+        issuer = identity["issuer"].strip()
+        subject = identity["subject"].strip()
+        if not provider or not issuer or not subject:
+            raise CredentialStoreError(
+                "Agent Auth principal resolve requires provider, issuer, and subject"
+            )
+        key = _principal_resolve_cache_key(
+            self.context, {"provider": provider, "issuer": issuer, "subject": subject}
+        )
+        cached = _principal_resolve_cache.get(key)
+        if cached is not None:
+            return cached
+        principal_id = self._resolve_principal_uncached(
+            {"provider": provider, "issuer": issuer, "subject": subject}
+        )
+        _principal_resolve_cache[key] = principal_id
+        return principal_id
+
+    def _resolve_principal_uncached(self, identity: ResolvePrincipalIdentity) -> str:
+        status, body = self._request(
+            "POST",
+            "/v1/agent-auth/principals",
+            body={
+                "provider": identity["provider"],
+                "issuer": identity["issuer"],
+                "subject": identity["subject"],
+            },
+        )
+        if status >= _HTTP_BAD_REQUEST:
+            raise CredentialStoreError("Agent Auth resolve principal failed", status, body)
+        principal = body.get("principal")
+        principal_id = ""
+        if isinstance(principal, Mapping):
+            raw = principal.get("id")
+            if isinstance(raw, str):
+                principal_id = raw.strip()
+        if not principal_id:
+            raise CredentialStoreError("Agent Auth resolve principal returned no principal id")
+        return principal_id
+
     def find_workspace_connection(self, slug: str) -> WorkspaceConnection | None:
         """List workspace connections and return the row for ``slug``, if any."""
         if not (self.context.workspace_id or "").strip():
@@ -134,7 +204,7 @@ class AgentAuth:
                 f"/v1/agent-auth/connections?{urllib.parse.urlencode(query)}",
             )
             if status >= _HTTP_BAD_REQUEST:
-                raise CredentialStoreError("Agent Auth list connections failed", status)
+                raise CredentialStoreError("Agent Auth list connections failed", status, body)
             raw_items = body.get("items")
             items = raw_items if isinstance(raw_items, list) else []
             for item in items:
@@ -170,31 +240,23 @@ class AgentAuth:
     def find_secret_credential_id(self, connection: WorkspaceConnection, slug: str) -> str | None:
         """Resolve the credential id for a secret connection row.
 
-        With an Agent Builder service key, prefer GET-for-owner / workspace list.
-        Personal API keys may only list agent-owned credentials.
+        Agent-owned connection declarations scope the credential to this
+        deployment. Workspace-owned credentials are deliberately not visible
+        to deployments.
         """
         if connection.kind != "secret":
             return None
-        workspace_id = (self.context.workspace_id or "").strip()
-        if not workspace_id:
+        agent_id = (self.context.agent_id or "").strip()
+        if not agent_id:
             raise CredentialStoreError(
-                "connections are not configured: LANGSMITH_WORKSPACE_ID is not set"
-            )
-        if (self.context.service_key or "").strip():
-            from_owner = self._credential_id_for_owner(
-                connection.connection_id, "workspace", workspace_id
-            )
-            if from_owner is not None:
-                return from_owner
-            return self.find_credential_id(
-                owner_type="workspace",
-                owner_id=workspace_id,
-                kind="secret",
-                slug=slug,
+                "connections are not configured: LANGSMITH_HOST_PROJECT_ID is not set"
             )
+        from_agent = self._credential_id_for_owner(connection.connection_id, "agent", agent_id)
+        if from_agent is not None:
+            return from_agent
         return self.find_credential_id(
             owner_type="agent",
-            owner_id=self.context.agent_id,
+            owner_id=agent_id,
             kind="secret",
             slug=slug,
         )
@@ -202,6 +264,12 @@ class AgentAuth:
     def _credential_id_for_owner(
         self, connection_id: str, owner_type: str, owner_id: str
     ) -> str | None:
+        """Read credential_id from GET /connections/{id}?credential_owner_*.
+
+        Deployments authenticate with ``LANGSMITH_API_KEY`` (the minted
+        service-account key). User and workspace owners additionally require
+        workspace management permission.
+        """
         query = urllib.parse.urlencode(
             {
                 "credential_owner_type": owner_type,
@@ -215,16 +283,27 @@ class AgentAuth:
         if status == _HTTP_NOT_FOUND:
             return None
         if status >= _HTTP_BAD_REQUEST:
-            raise CredentialStoreError("Agent Auth get connection for owner failed", status)
+            raise CredentialStoreError(
+                "Agent Auth get connection for owner failed"
+                + (" (forbidden)" if status == _HTTP_FORBIDDEN else ""),
+                status,
+                body,
+            )
         return _connection_credential_id(body)
 
     def read_user_secret(self, slug: str) -> str | None:
         """Read a caller-owned opaque secret grant for a workspace connection slug."""
-        credential_id = self.find_credential_id(
-            owner_type="user",
-            owner_id=self.context.principal_id,
-            kind="secret",
-            slug=slug,
+        connection = self.find_workspace_connection(slug)
+        if connection is None:
+            return None
+        return self.read_user_secret_for_connection(connection)
+
+    def read_user_secret_for_connection(self, connection: WorkspaceConnection) -> str | None:
+        """Read a caller-owned opaque secret when the connection row is already loaded."""
+        if connection.kind != "secret":
+            return None
+        credential_id = self._credential_id_for_owner(
+            connection.connection_id, "user", self.context.principal_id
         )
         if credential_id is None:
             return None
@@ -244,11 +323,17 @@ class AgentAuth:
         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,
+        connection = self.find_workspace_connection(slug)
+        if connection is None:
+            return None
+        return self.read_user_access_token_for_connection(connection)
+
+    def read_user_access_token_for_connection(self, connection: WorkspaceConnection) -> str | None:
+        """Read a caller OAuth token when the connection row is already loaded."""
+        if connection.kind != "oauth2":
+            return None
+        credential_id = self._credential_id_for_owner(
+            connection.connection_id, "user", self.context.principal_id
         )
         if credential_id is None:
             return None
@@ -258,7 +343,7 @@ class AgentAuth:
         """Start an OAuth session for a slug the caller has not granted."""
         connection = self.find_workspace_connection(slug)
         if connection is None:
-            raise CredentialStoreError(f"workspace connection {slug!r} is not configured")
+            raise missing_workspace_connection_error(slug)
         if connection.kind != "oauth2":
             raise CredentialStoreError(f"connection {slug!r} is not an OAuth connection")
         status, body = self._request(
@@ -266,13 +351,13 @@ class AgentAuth:
             "/v1/agent-auth/oauth-authorization-sessions",
             body={
                 "connection_id": connection.connection_id,
-                "principal_id": self.context.principal_id,
-                "agent_id": self.context.agent_id,
+                "owner_type": "user",
+                "owner_id": self.context.principal_id,
             },
         )
         if status >= _HTTP_BAD_REQUEST:
             raise CredentialStoreError(
-                "Agent Auth create oauth-authorization-session failed", status
+                "Agent Auth create oauth-authorization-session failed", status, body
             )
         auth_id = str(body.get("id") or "")
         connect_url = str(body.get("verification_url") or "")
@@ -293,7 +378,7 @@ class AgentAuth:
                 "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)
+                raise CredentialStoreError("Agent Auth list oauth-providers failed", status, body)
             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"):
@@ -329,7 +414,7 @@ class AgentAuth:
             )
             status, body = self._request("GET", f"/v1/agent-auth/credentials?{query}")
             if status >= _HTTP_BAD_REQUEST:
-                raise CredentialStoreError("Agent Auth list credentials failed", status)
+                raise CredentialStoreError("Agent Auth list credentials failed", status, body)
             raw_items = body.get("items")
             items = raw_items if isinstance(raw_items, list) else []
             for item in items:
@@ -352,7 +437,7 @@ class AgentAuth:
         if status == _HTTP_NOT_FOUND:
             return None
         if status >= _HTTP_BAD_REQUEST:
-            raise CredentialStoreError("Agent Auth get secret failed", status)
+            raise CredentialStoreError("Agent Auth get secret failed", status, body)
         secret = body.get("secret")
         return secret if isinstance(secret, str) and secret else None
 
@@ -364,7 +449,7 @@ class AgentAuth:
         if _is_authorization_required(status, body):
             return None
         if status >= _HTTP_BAD_REQUEST:
-            raise CredentialStoreError("Agent Auth get oauth2 failed", status)
+            raise CredentialStoreError("Agent Auth get oauth2 failed", status, body)
         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
@@ -390,7 +475,6 @@ class AgentAuth:
         return agent_auth_headers(
             api_key=self.context.api_key,
             workspace_id=self.context.workspace_id,
-            service_key=self.context.service_key,
         )
 
 

managed_deepagents/_agent_auth_http.py

@@ -7,36 +7,96 @@ API with the same headers, redirect policy, and page walker.
 from __future__ import annotations
 
 import json
+import re
 import urllib.error
 import urllib.parse
 import urllib.request
 from collections.abc import Mapping
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Final
 
 if TYPE_CHECKING:
     from http.client import HTTPMessage
     from typing import IO
 
 AGENT_AUTH_TIMEOUT_SECONDS = 10.0
+AGENT_AUTH_PROBLEM_HINT_MAX_CHARS = 200
+_PROBLEM_HINT_FIELDS: Final = ("detail", "remedy")
+
+
+def agent_auth_problem_hint(body: Mapping[str, object] | None) -> str | None:
+    """Return the caller-facing part of an Agent Auth problem+json body.
+
+    ``detail`` names the failure and ``remedy`` names the fix. Nothing else
+    from a response body is read, because the rest can quote secret material.
+    Both are collapsed to one line and truncated so a long or multi-line body
+    cannot reshape an error message.
+    """
+    seen: dict[str, None] = {}
+    for field in _PROBLEM_HINT_FIELDS:
+        value = None if body is None else body.get(field)
+        if not isinstance(value, str):
+            continue
+        text = " ".join(value.split())
+        if text:
+            seen[text] = None
+    if not seen:
+        return None
+    hint = " ".join(seen)
+    if len(hint) > AGENT_AUTH_PROBLEM_HINT_MAX_CHARS:
+        return hint[:AGENT_AUTH_PROBLEM_HINT_MAX_CHARS] + "..."
+    return hint
 
 
 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.
+    Callers pass a fixed message; the only part of a response body that reaches
+    this error, the logs, or the traceback chain is the allow-listed
+    problem+json hint, since an arbitrary body can quote secret material.
     """
 
-    def __init__(self, message: str, status: int | None = None) -> None:
+    def __init__(
+        self,
+        message: str,
+        status: int | None = None,
+        problem: Mapping[str, object] | None = None,
+    ) -> None:
         self.status = status
-        super().__init__(message if status is None else f"{message} (status {status})")
+        with_status = message if status is None else f"{message} (status {status})"
+        hint = agent_auth_problem_hint(problem)
+        super().__init__(with_status if hint is None else f"{with_status}: {hint}")
+
+
+# Each runtime quotes the slug its own way: repr() here, JSON.stringify in npm.
+_MISSING_WORKSPACE_CONNECTION = re.compile(
+    r"""workspace connection ['"]([A-Za-z0-9][A-Za-z0-9._-]*)['"] is not configured"""
+)
+
+
+def missing_workspace_connection_error(slug: str) -> CredentialStoreError:
+    """Return the error for a declared slug that has no workspace connection row."""
+    return CredentialStoreError(f"workspace connection {slug!r} is not configured")
+
+
+def missing_workspace_connection_slug(text: str) -> str | None:
+    """Read the slug back out of a missing-connection message.
+
+    A run that fails in the gate reaches a channel as a plain string, so this is
+    the only way back to the slug. It must move with the message it parses.
+    """
+    match = _MISSING_WORKSPACE_CONNECTION.search(text)
+    return None if match is None else match.group(1)
 
 
 __all__ = [
+    "AGENT_AUTH_PROBLEM_HINT_MAX_CHARS",
     "AGENT_AUTH_TIMEOUT_SECONDS",
     "CredentialStoreError",
     "agent_auth_credential_query",
     "agent_auth_headers",
+    "agent_auth_problem_hint",
+    "missing_workspace_connection_error",
+    "missing_workspace_connection_slug",
     "request_agent_auth_json",
 ]
 
@@ -70,16 +130,12 @@ def agent_auth_headers(
     *,
     api_key: str | None = None,
     workspace_id: str | None = None,
-    service_key: str | None = None,
 ) -> dict[str, str]:
     headers = {
         "accept": "application/json",
         "content-type": "application/json",
         "x-langsmith-product": "mda",
     }
-    resolved_service_key = (service_key or "").strip()
-    if resolved_service_key:
-        headers["x-service-key"] = resolved_service_key
     resolved_api_key = (api_key or "").strip()
     if resolved_api_key:
         headers["x-api-key"] = resolved_api_key