mainsequence 9.0.11.dev50__py3-none-any.whl → 9.0.12.dev51__py3-none-any.whl

agent_scaffold/skills/application_surfaces/api_surfaces/SKILL.md

@@ -147,6 +147,13 @@ person, read `User.get_by_uid(uid)`: a workload identity has `identity_type`
 `"workload"`. Caller authentication is not resource authorization; apply the
 endpoint's application policy using the verified user UID.
 
+To list the people, Teams and workloads the caller can see, for example to
+offer sharing candidates, read inside `reads_as_caller()` from
+`mainsequence.server.fastapi`: `User.filter`, `User.get_by_uid`, `Team.filter`
+and `Team.get_by_uid` then answer with the caller's visibility, and workload
+rows carry `managed_by_caller`. Outside a signed HTTP request it raises
+`RequestIdentityError`; it never reads as the application instead.
+
 WebSockets retain the platform's gateway ticket/header contract rather than
 the HTTP Bearer/assertion flow; the getter is available while the authenticated
 connection is active. See the version-matched

mainsequence/_request_identity.py

@@ -2,8 +2,11 @@
 
 from contextlib import contextmanager
 from contextvars import ContextVar
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from typing import Any
+from urllib.parse import urlsplit
+
+CALLER_ASSERTION_HEADER = "X-MainSequence-Caller-Assertion"
 
 
 class RequestIdentityError(RuntimeError):
@@ -14,11 +17,18 @@ class RequestIdentityError(RuntimeError):
 class _RequestScope:
     user: Any = None
     active: bool = True
+    # The verified assertion of a hosted HTTP request, kept only so that
+    # reads_as_caller() can present it (ADR-0036, amended for #198).
+    caller_assertion: str | None = field(default=None, repr=False)
 
 
 _current_scope: ContextVar[_RequestScope | None] = ContextVar(
     "mainsequence_request_identity", default=None
 )
+# The request scope whose caller the directory reads answer as, inside reads_as_caller().
+_caller_reads: ContextVar[_RequestScope | None] = ContextVar(
+    "mainsequence_caller_reads", default=None
+)
 
 
 @contextmanager
@@ -31,6 +41,7 @@ def _request_scope():
         # Copied child-task contexts hold this same frame and must also expire.
         scope.active = False
         scope.user = None
+        scope.caller_assertion = None
         _current_scope.reset(token)
 
 
@@ -42,3 +53,46 @@ def _get_request_identity():
             "once in the application and call User.get_logged_user() inside a request."
         )
     return scope.user
+
+
+@contextmanager
+def _reads_as_caller():
+    scope = _current_scope.get()
+    if scope is None or not scope.active or scope.user is None:
+        raise RequestIdentityError(
+            "Reading as the caller needs an authenticated request. Install request "
+            "identity once in the application and call reads_as_caller() inside a request."
+        )
+    if scope.caller_assertion is None:
+        raise RequestIdentityError(
+            "This request carries no caller assertion. Reading as the caller needs a "
+            "hosted HTTP request in assertion mode, not local mode or a WebSocket."
+        )
+    token = _caller_reads.set(scope)
+    try:
+        yield
+    finally:
+        _caller_reads.reset(token)
+
+
+def _origin(url: str) -> tuple[str, str | None, int | None]:
+    parts = urlsplit(url)
+    scheme = parts.scheme.lower()
+    return scheme, parts.hostname, parts.port or {"http": 80, "https": 443}.get(scheme)
+
+
+def _caller_read_headers(url: str, endpoint_url: str) -> dict[str, str]:
+    """The header a directory read sends to ``url``: none outside reads_as_caller()."""
+    scope = _caller_reads.get()
+    if scope is None:
+        return {}
+    if not scope.active or scope.caller_assertion is None:
+        raise RequestIdentityError(
+            "The request that reads_as_caller() belongs to has ended; its caller "
+            "assertion is no longer available."
+        )
+    if _origin(url) != _origin(endpoint_url):
+        raise RequestIdentityError(
+            "The caller assertion is sent only to the configured platform endpoint."
+        )
+    return {CALLER_ASSERTION_HEADER: scope.caller_assertion}

mainsequence/client/base.py

@@ -180,6 +180,11 @@ class BaseObjectOrm:
     def _sdk_owned_query_context(cls, operation: str) -> dict[str, Any]:
         return {}
 
+    @classmethod
+    def _read_request_headers(cls, url: str) -> dict[str, str]:
+        """Headers a filter or detail read adds to its own request to ``url``."""
+        return {}
+
     @classmethod
     def _sdk_owned_create_context(cls, operation: str) -> dict[str, Any]:
         return {}
@@ -540,12 +545,13 @@ class BaseObjectOrm:
 
         while next_url:
             req_payload = {"params": params} if params else {}
+            headers = cls._read_request_headers(next_url)
             r = make_request(
                 s=cls.build_session(),
                 loaders=cls.LOADERS,
                 r_type="GET",
                 url=next_url,
-                payload=req_payload,
+                payload={**req_payload, "headers": headers} if headers else req_payload,
                 time_out=timeout,
             )
             raise_for_response(r, payload=req_payload)
@@ -610,12 +616,16 @@ class BaseObjectOrm:
                 **cls._sdk_owned_query_context(operation),
             }
 
+            payload = {"params": params}  # neede to pass special serializer
+            headers = cls._read_request_headers(detail_url)
+            if headers:
+                payload["headers"] = headers
             r = make_request(
                 s=cls.build_session(),
                 loaders=cls.LOADERS,
                 r_type="GET",
                 url=detail_url,
-                payload={"params": params},  # neede to pass special serializer
+                payload=payload,
                 time_out=timeout,
             )
             raise_for_response(r)

mainsequence/client/models_user.py

@@ -6,7 +6,11 @@ from uuid import UUID
 
 from pydantic import BaseModel, ConfigDict, Field, StrictBool, field_validator, model_validator
 
-from mainsequence._request_identity import RequestIdentityError, _get_request_identity
+from mainsequence._request_identity import (
+    RequestIdentityError,
+    _caller_read_headers,
+    _get_request_identity,
+)
 from mainsequence.defaults import STANDARD_BACKEND_URL
 
 from .base import (
@@ -336,7 +340,18 @@ class TeamMembershipUpdateResult(BasePydanticModel):
     )
 
 
-class Team(PermissionManagedObjectMixin, BasePydanticModel, UserApiBaseObjectOrm):
+class _CallerDirectoryReadMixin:
+    """Inside ``reads_as_caller()``, ``filter`` and ``get`` reads answer as the
+    request's caller (ADR-0036, amended for #198)."""
+
+    @classmethod
+    def _read_request_headers(cls, url: str) -> dict[str, str]:
+        return _caller_read_headers(url, cls.get_object_url())
+
+
+class Team(
+    _CallerDirectoryReadMixin, PermissionManagedObjectMixin, BasePydanticModel, UserApiBaseObjectOrm
+):
     ENDPOINT: ClassVar[str] = "teams"
     FILTERSET_FIELDS: ClassVar[dict[str, list[str]] | None] = {
         "uid": ["exact", "in"],
@@ -960,7 +975,7 @@ class ShareableAccessState(BasePydanticModel):
     )
 
 
-class User(UserApiBaseObjectOrm, BasePydanticModel):
+class User(_CallerDirectoryReadMixin, UserApiBaseObjectOrm, BasePydanticModel):
     """A platform User: a person, or the workload identity a deployed Job,
     FastAPI release or Agent runs as.
 
@@ -974,6 +989,10 @@ class User(UserApiBaseObjectOrm, BasePydanticModel):
     The reverse direction is ``workload_user_uid`` on ``Job``,
     ``ResourceRelease`` and ``Agent``: the UID of the User that workload runs
     as, to pass to ``User.get_by_uid`` and to sharing calls.
+
+    Inside ``mainsequence.server.fastapi.reads_as_caller()``, ``User.filter``
+    and ``User.get_by_uid`` answer with what the request's caller may see, and
+    workload rows carry ``managed_by_caller``.
     """
 
     # Platform facts, not application authorization policy. None means the
@@ -986,6 +1005,7 @@ class User(UserApiBaseObjectOrm, BasePydanticModel):
         "uid": ["exact", "in"],
         "email": ["exact", "contains", "in"],
         "identity_type": ["exact"],
+        "search": ["exact"],
     }
     FILTER_VALUE_NORMALIZERS: ClassVar[dict[str, str]] = {
         "uid": "uid",
@@ -994,6 +1014,7 @@ class User(UserApiBaseObjectOrm, BasePydanticModel):
         "email__contains": "str",
         "email__in": "str",
         "identity_type": "str",
+        "search": "str",
     }
 
     id: int | None = Field(
@@ -1038,6 +1059,15 @@ class User(UserApiBaseObjectOrm, BasePydanticModel):
         description="UID of the Agent a workload identity belongs to; None otherwise.",
         examples=[None],
     )
+    managed_by_caller: bool | None = Field(
+        None,
+        title="Managed By Caller",
+        description=(
+            "On a workload identity read inside `reads_as_caller()`: whether the "
+            "request's caller manages that workload. None when the row does not carry it."
+        ),
+        examples=[True],
+    )
     profile_picture: str | None = Field(
         None,
         title="Profile Picture URL",

mainsequence/server/caller_assertions.py

@@ -16,7 +16,8 @@ import requests
 from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
 from jwt import InvalidKeyError, InvalidTokenError
 
-ASSERTION_HEADER = "X-MainSequence-Caller-Assertion"
+from mainsequence._request_identity import CALLER_ASSERTION_HEADER as ASSERTION_HEADER
+
 ASSERTION_TYPE = "mainsequence-caller-assertion+jwt"
 ASSERTION_ALGORITHM = "EdDSA"
 MAX_ASSERTION_SECONDS = 300

mainsequence/server/fastapi.py

@@ -6,11 +6,12 @@ import asyncio
 import json
 import os
 import re
+from contextlib import contextmanager
 from uuid import UUID
 
 import requests
 
-from mainsequence._request_identity import _request_scope
+from mainsequence._request_identity import _reads_as_caller, _request_scope
 from mainsequence.client.models_user import RequestUserIdentity
 
 from .caller_assertions import (
@@ -220,6 +221,7 @@ class _RequestIdentityMiddleware:
                         )
                         state["resource_release_uid"] = caller.release_uid
                         state["organization_environment_uid"] = caller.environment_uid
+                        context.caller_assertion = assertion
                     else:
                         user = await asyncio.to_thread(_local_user, scope)
                     context.user = user
@@ -267,4 +269,19 @@ def install_request_identity(app):
     )
 
 
-__all__ = ["install_request_identity"]
+@contextmanager
+def reads_as_caller():
+    """Read the directory as the request's caller instead of as the application.
+
+    Inside the block, ``User.filter``, ``User.get_by_uid``, ``Team.filter`` and
+    ``Team.get_by_uid`` present the caller assertion the request arrived with,
+    and the platform answers with what the caller may see. No other call sends
+    it. Raises ``RequestIdentityError`` outside an authenticated request or when
+    the request carries no assertion (local mode, WebSockets); it never reads as
+    the application instead. See ADR-0036.
+    """
+    with _reads_as_caller():
+        yield
+
+
+__all__ = ["install_request_identity", "reads_as_caller"]

{mainsequence-9.0.11.dev50.dist-info → mainsequence-9.0.12.dev51.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 9.0.11.dev50
+Version: 9.0.12.dev51
 Summary: Main Sequence SDK
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License-Expression: MIT

{mainsequence-9.0.11.dev50.dist-info → mainsequence-9.0.12.dev51.dist-info}/RECORD

@@ -1,6 +1,6 @@
 agent_scaffold/AGENTS.md,sha256=W91rpnyQuoQIa-3dsebIYyuwnbGLvkmuq_8X5k2hTAw,6399
 agent_scaffold/skills/a2a_sdk_execution/SKILL.md,sha256=NKtcXibE8TxZzKzz1KzJ2cVZ_EeuJJkb660U6wLvZ3s,11809
-agent_scaffold/skills/application_surfaces/api_surfaces/SKILL.md,sha256=BUaqO3MkZ-d5sdh2xNPNQ904aO3RIJZfQW54FhDRxkc,16225
+agent_scaffold/skills/application_surfaces/api_surfaces/SKILL.md,sha256=jYuZvxtfKh9MpWPxmT1EqPnkW_i4BbZfvDnWRiJHqRk,16659
 agent_scaffold/skills/mainsequence-inference/SKILL.md,sha256=yv8aAHLQ2FBBSWPIFadY7pGNTwtR-yiR_-UzaGRN9-g,12502
 agent_scaffold/skills/maintenance/bug_auditor/SKILL.md,sha256=CCKs7edyZ9RK-WtAgXJXucokJFXZxk8sRUe0_imFtu8,8610
 agent_scaffold/skills/maintenance/code_repository_maintenance/SKILL.md,sha256=pPsZaERlfokSJ6b6vLjpA5U0KuKxbOFzzcxOVW_ikiI,17935
@@ -10,7 +10,7 @@ agent_scaffold/skills/platform_operations/orchestration_and_releases/SKILL.md,sh
 agent_scaffold/skills/sdk_code_repository_execution/SKILL.md,sha256=zly7MheB-Sjd0x6l_oPCOTBqkL2E4SSXwTlfSwdIPfQ,10196
 mainsequence/__init__.py,sha256=70CbIo7ZG1mzi5uwkqDtVESunBE0RanHjeFg4ptfsA0,385
 mainsequence/__main__.py,sha256=KuAP69uduS2ImrPIgNMzbGBRepZzjqvUONu5vFh4v4A,176
-mainsequence/_request_identity.py,sha256=jiroPFVDM8vphEf9VXuggQJKUOGohfk7-pDwJSOILEw,1211
+mainsequence/_request_identity.py,sha256=BZVboogZPnRoka9vNYa3DOzex1qYDNOCiJ-2be9Jzqw,3406
 mainsequence/bootstrap.py,sha256=AvG55Y46RcshVqJZsyqvUDN62CJg4CDbHu0Bvsbwfzs,2910
 mainsequence/code_repository_context.py,sha256=JRrWjwpnUy8I-OjSd9hHlrcq8-Ow3Zeh_N6cYvmtA3o,28545
 mainsequence/code_repository_skills.py,sha256=AyC1HFAxQXHXNBGbarVUJS2cHd4X5HwDx6u8XBophbE,23611
@@ -37,7 +37,7 @@ mainsequence/cli/ui.py,sha256=memd6pmjALfGj8zndGCx_z80ztQeqTcOvcofU0un34U,2277
 mainsequence/client/__init__.py,sha256=lsr9JWxeVqOG0KRoHErW5M40ACPSR7SAEE508dTN5XM,672
 mainsequence/client/_transport.py,sha256=l2xkbJ21SbrJhzgOf58Yikxg-uzOQPyo-H5hENdCBo8,5374
 mainsequence/client/agent_runtime_models.py,sha256=8H4VEZWgnlYx3r7XY9eQq4D7hfzLRyhrIRyy2ZVae2Y,67718
-mainsequence/client/base.py,sha256=T3k3xptM09TreiVogrxAPWoIy8zM6Dtn3Cbwsnb33ag,42678
+mainsequence/client/base.py,sha256=ZxuwUIscBNQGvByd7NGbn03VtNU9nazqkEouyKfVLk0,43129
 mainsequence/client/client.py,sha256=Jaw9RYObdVDS5J2O0pln99-XpuW9e4vW-SsbJRNldfw,3866
 mainsequence/client/compute_validation.py,sha256=ByeX0CkIE7qq06ggZFfN92U3Qp2e9cvo2RTIGWa5_Vw,6662
 mainsequence/client/exceptions.py,sha256=xx2L4l3OMNsTybbYkiTKK398ahnutEascM0It35tGr0,3815
@@ -45,18 +45,18 @@ mainsequence/client/github_issues.py,sha256=pSTUw3UPrmE6wqnpoJctartTaNSq6iu6PQRr
 mainsequence/client/inference.py,sha256=tYKHRxLR6mA5iLmgd3qURwweWc2OPQuw0__tD3LQgSI,7748
 mainsequence/client/models_foundry.py,sha256=JwQdPLDSO4dZI-KC0SUdmN6izmNIKMb9IzZlYXy0Mig,36488
 mainsequence/client/models_helpers.py,sha256=nlbHuQAylTOHAZOq4ltJQp6QvC3NW_kw7tZFosGc5rM,47311
-mainsequence/client/models_user.py,sha256=vpnzwemq9SVXHndlIhS731veJz9yzQ8rz5b0mP42KVQ,41166
+mainsequence/client/models_user.py,sha256=YFEClKcKZpWLCy8Gmg8tZXIHmJbkdQHkeOBJXmp0HG0,42169
 mainsequence/client/observability.py,sha256=_WrDKCaNk_TXmKElKCXC1inork6Exxxe8FRY4m1GI9s,16008
 mainsequence/client/utils.py,sha256=d6lXJPAOe683gb-ph9x0GJcvK5c5Pg9gr90ihDgQGug,32484
 mainsequence/client/value_sets.py,sha256=7TA-mpuAd3hOduNgO1WTQQTuNOGaFgue-VqCsDWKaC8,6181
 mainsequence/instrumentation/__init__.py,sha256=J_9XmfjprElvz0u2t9rTyJT0kFdyKpxdbkdQiaw28_U,316
 mainsequence/instrumentation/utils.py,sha256=b-ihjSioAepeLfMpudM2SqCtvnxMqIXileHx3klBCQU,3377
 mainsequence/server/__init__.py,sha256=BHUAhtdWPDRdxX07NYO_6wrBv5mf0GsXflecO52PmUc,73
-mainsequence/server/caller_assertions.py,sha256=f9jHhVeoFK1ScDCmW8h3lEIU5V7zKw70SUSVV2P7wUI,10975
-mainsequence/server/fastapi.py,sha256=Y5QB51CRVbuUVRUcWh5GKQ5b5vMPjbs9scioTt684oQ,10712
-mainsequence-9.0.11.dev50.dist-info/licenses/LICENSE,sha256=b6Ecsk8wjsEby3lbSzdljR6hHiFGHBizt9iWV2p1c_I,1074
-mainsequence-9.0.11.dev50.dist-info/METADATA,sha256=fIx_7NHIGCF8alTSS09AH7RLc0Hj3jEs_vZIeWbq84s,7403
-mainsequence-9.0.11.dev50.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-mainsequence-9.0.11.dev50.dist-info/entry_points.txt,sha256=XGAOq3-mF2lWWpeRJvoaWyMarRcK167mH1g124aGdUs,88
-mainsequence-9.0.11.dev50.dist-info/top_level.txt,sha256=BFeblM_Q9q0cUWBvTxnfWcWQEHtf5XZi9nOS-Gdfwus,28
-mainsequence-9.0.11.dev50.dist-info/RECORD,,
+mainsequence/server/caller_assertions.py,sha256=Me8of2Ku8in-97LWU2oY-0oD1OW6zF-xOVVpEQ0eoe4,11010
+mainsequence/server/fastapi.py,sha256=zclo7ARHKUKSTmOc0KdxUSwfsxlx6SJuaiAe-19nzWg,11465
+mainsequence-9.0.12.dev51.dist-info/licenses/LICENSE,sha256=b6Ecsk8wjsEby3lbSzdljR6hHiFGHBizt9iWV2p1c_I,1074
+mainsequence-9.0.12.dev51.dist-info/METADATA,sha256=F7sYdFmk6Ni6QFEbA2jMXCaoD6wxb_w4WSSUsZ9dPk4,7403
+mainsequence-9.0.12.dev51.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+mainsequence-9.0.12.dev51.dist-info/entry_points.txt,sha256=XGAOq3-mF2lWWpeRJvoaWyMarRcK167mH1g124aGdUs,88
+mainsequence-9.0.12.dev51.dist-info/top_level.txt,sha256=BFeblM_Q9q0cUWBvTxnfWcWQEHtf5XZi9nOS-Gdfwus,28
+mainsequence-9.0.12.dev51.dist-info/RECORD,,