ms-tau-sdk 2.0.3.dev36__tar.gz → 2.0.3.dev37__tar.gz

{ms_tau_sdk-2.0.3.dev36 → ms_tau_sdk-2.0.3.dev37}/CHANGELOG.md

@@ -51,6 +51,19 @@
   `GET /api/chat/model-providers`. The Environment is now sent as the `organization_environment_uid`
   query parameter, as the other list calls send theirs; the call without an Environment is
   unchanged ([issue #68](https://github.com/mainsequence-sdk/ms-tau-sdk/issues/68)).
+- A hosted runtime admits the Agent that delegated to a child session. When Agent A delegates to
+  Agent B through `a2a.send_message`, the platform creates B's child session for the person who
+  owns A's session, and A addresses it with its own credential, so the caller assertion names A's
+  workload User. B's runtime refused every such request with 403. It now also admits that caller
+  when the session's `parent_session_agent_uid` names an Agent and the platform's directory
+  (`GET /api/v1/users/<uid>/`, read with the runtime credential) shows the caller as a workload
+  User whose `agent_uid` is that Agent: Message send and stream, JSON-RPC, and Task continuation,
+  reads, list and cancel. The `X-Caller-*` headers never admit a caller. A session without a
+  parent, another Agent's workload, and a person who is not the owner still get 403, and a lookup
+  that fails refuses the request. One request looks a User up at most once, and nothing is kept
+  after it. The admitted Agent is never a requester: `current_requester()` stays `None` in its
+  turns and in the Task attempts its requests run. See the 2026-10-06 amendment of ADR 0019
+  ([issue #67](https://github.com/mainsequence-sdk/ms-tau-sdk/issues/67)).
 
 ## 2.0.2 — 2026-10-06
 

{ms_tau_sdk-2.0.3.dev36 → ms_tau_sdk-2.0.3.dev37}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ms-tau-sdk
-Version: 2.0.3.dev36
+Version: 2.0.3.dev37
 Summary: Workspace-bound Tau application primitives for Main Sequence projects
 Project-URL: Changelog, https://github.com/mainsequence-sdk/ms-tau-sdk/blob/development/CHANGELOG.md
 Project-URL: Documentation, https://github.com/mainsequence-sdk/ms-tau-sdk/tree/development/docs
@@ -126,7 +126,8 @@ app = create_app()
 
 When Main Sequence hosts the runtime, `create_app()` admits a request only with the platform's
 signed assertion in `X-MainSequence-Caller-Assertion`, never on gateway identity headers, and lets
-only a session's owner or an Organization admin address that session. It declares this request
+only a session's owner, an Organization admin, or the Agent that delegated to it address that
+session. It declares this request
 identity to the platform launcher in `app.state.mainsequence_request_identity`; the launcher serves
 only an application that declares it, so serve the application `create_app()` returns. Outside
 hosting, requests are handled as before. See

{ms_tau_sdk-2.0.3.dev36 → ms_tau_sdk-2.0.3.dev37}/README.md

@@ -93,7 +93,8 @@ app = create_app()
 
 When Main Sequence hosts the runtime, `create_app()` admits a request only with the platform's
 signed assertion in `X-MainSequence-Caller-Assertion`, never on gateway identity headers, and lets
-only a session's owner or an Organization admin address that session. It declares this request
+only a session's owner, an Organization admin, or the Agent that delegated to it address that
+session. It declares this request
 identity to the platform launcher in `app.state.mainsequence_request_identity`; the launcher serves
 only an application that declares it, so serve the application `create_app()` returns. Outside
 hosting, requests are handled as before. See

{ms_tau_sdk-2.0.3.dev36 → ms_tau_sdk-2.0.3.dev37}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ms-tau-sdk"
-version = "2.0.3.dev36"
+version = "2.0.3.dev37"
 description = "Workspace-bound Tau application primitives for Main Sequence projects"
 readme = "README.md"
 requires-python = ">=3.13"

{ms_tau_sdk-2.0.3.dev36 → ms_tau_sdk-2.0.3.dev37}/src/ms_tau_sdk/agent_skills/tau_a2a_runtime_adapter/SKILL.md

@@ -26,8 +26,9 @@ The SDK owns:
 - privately attaching active caller-session proof when a tool advertises
   `mainsequence.ai/requires-caller-session-proof/v1: true`;
 - verifying the platform's signed caller or platform assertion on every inbound request of a
-  hosted runtime, and admitting a request to a session or its Tasks only for the session's owner
-  or an Organization admin;
+  hosted runtime, and admitting a request to a session or its Tasks only for the session's owner,
+  an Organization admin, or the workload User of the Agent that delegated to that child session,
+  which the platform's own records establish, never the `X-Caller-*` headers;
 - presenting the verified caller assertion of the request that starts a chat or A2A Message turn
   only when it marks that turn active, so that the platform can record the turn's requester, and
   giving extension tools that requester and requester-bound calls through `current_requester()`

{ms_tau_sdk-2.0.3.dev36 → ms_tau_sdk-2.0.3.dev37}/src/ms_tau_sdk/agent_skills/tau_repository_integration/SKILL.md

@@ -46,9 +46,9 @@ TAU image, overlay, or SDK-owned deployment.
 
 `create_app()` installs the runtime's request identity. When Main Sequence hosts the runtime, the
 application admits only requests that carry the platform's signed assertion, lets only a session's
-owner or an Organization admin address that session, and declares all this in
-`app.state.mainsequence_request_identity`. The platform launcher serves an application only with
-that declaration, read from the object it serves. Therefore:
+owner, an Organization admin, or the Agent that delegated to it address that session, and declares
+all this in `app.state.mainsequence_request_identity`. The platform launcher serves an application
+only with that declaration, read from the object it serves. Therefore:
 
 - export the object `create_app()` returns as the module's `app`. An application that mounts it
   inside another one declares nothing, and the launcher refuses it;

{ms_tau_sdk-2.0.3.dev36 → ms_tau_sdk-2.0.3.dev37}/src/ms_tau_sdk/api/a2a.py

@@ -930,7 +930,7 @@ def _requester_named_by_task(
     answer must name the same User, as a person, as ``requester_user_uid``.
     """
 
-    if caller_assertion is None:
+    if caller_assertion is None or caller_assertion.caller_is_workload:
         return None
     caller = caller_assertion.caller
     if task.requester_identity_type != "human" or task.requester_user_uid != caller.uid:

{ms_tau_sdk-2.0.3.dev36 → ms_tau_sdk-2.0.3.dev37}/src/ms_tau_sdk/api/request_identity.py

@@ -8,8 +8,9 @@ the kind its route requires: a platform assertion on ``/internal/*``, a caller a
 other route. Handlers read the verified caller with ``current_caller()``, or from
 ``request.state.user`` and ``request.state.user_uid``.
 
-A request that addresses an existing session must also come from the session's owner or from an
-Organization admin; see ``require_session_access()``. Outside hosted mode nothing here changes how
+A request that addresses an existing session must also come from the session's owner, from an
+Organization admin, or, for a delegated child session, from the workload User of the Agent that
+delegated to it; see ``require_session_access()``. Outside hosted mode nothing here changes how
 requests are handled.
 
 The raw caller assertion stays private to the request: ``request_caller_assertion()`` hands it
@@ -18,11 +19,13 @@ only to the turn that request starts, which presents it when it marks the turn a
 
 from __future__ import annotations
 
+import dataclasses
 from collections.abc import Iterable
 from contextvars import ContextVar
 
 import structlog
 from fastapi import FastAPI, HTTPException, Request
+from pydantic import ValidationError
 from starlette.responses import JSONResponse
 from starlette.types import ASGIApp, Receive, Scope, Send
 from starlette.websockets import WebSocketClose
@@ -37,8 +40,8 @@ from ms_tau_sdk.backend.assertions import (
     VerifiedCaller,
 )
 from ms_tau_sdk.backend.client import MainSequenceClient
-from ms_tau_sdk.backend.models import AgentSession
-from ms_tau_sdk.errors import SessionNotFoundError
+from ms_tau_sdk.backend.models import AgentSession, DirectoryUser
+from ms_tau_sdk.errors import SessionNotFoundError, TauSDKError
 from ms_tau_sdk.logging import bind_request_identity_log_fields
 from ms_tau_sdk.runtime.provenance import CallerIdentityError
 from ms_tau_sdk.settings import TauSDKSettings
@@ -66,6 +69,12 @@ _current_caller: ContextVar[VerifiedCaller | None] = ContextVar(
 # The verified raw caller assertion is kept in the request's own scope, not in request.state and
 # not in a context variable, so that only the code that starts the request's turn reads it.
 _CALLER_ASSERTION_SCOPE_KEY = "ms_tau_sdk.caller_assertion"
+# The workload Users that one request looked up, by User UID: the workload, or None for a User
+# that is not a workload or whose lookup failed. It lives only as long as its request.
+_workload_lookups: ContextVar[dict[str, DirectoryUser | None] | None] = ContextVar(
+    "ms_tau_sdk_workload_lookups",
+    default=None,
+)
 
 
 class SessionAccessDeniedError(HTTPException):
@@ -85,15 +94,24 @@ def current_caller() -> VerifiedCaller | None:
 
 
 def request_caller_assertion(request: Request) -> CallerAssertion | None:
-    """Return the verified caller assertion of ``request`` for the turn it starts.
+    """Return the verified caller assertion of ``request`` for the turn or Task it starts.
 
-    It is None outside hosted mode and on the platform's own calls. Only the chat and A2A Message
-    routes read it, to present it when they mark their turn active; it is never logged, persisted,
-    or passed to the model, a tool, a stream, or history.
+    It is None outside hosted mode and on the platform's own calls. Only the chat and A2A routes
+    read it, to present it when they mark their turn active or create or continue a Task; it is
+    never logged, persisted, or passed to the model, a tool, a stream, or history. A caller this
+    request admitted as the Agent that delegated to the session comes back marked as a workload,
+    which is never a requester.
     """
 
     value = request.scope.get(_CALLER_ASSERTION_SCOPE_KEY)
-    return value if isinstance(value, CallerAssertion) else None
+    if not isinstance(value, CallerAssertion):
+        return None
+    lookups = _workload_lookups.get()
+    if lookups is not None and lookups.get(value.caller.uid) is not None:
+        # The request was admitted as the Agent that delegated to the session: its assertion names
+        # a workload, never a requester.
+        return dataclasses.replace(value, caller_is_workload=True)
+    return value
 
 
 def verified_user_uid(settings: TauSDKSettings) -> str | None:
@@ -111,15 +129,63 @@ def verified_user_uid(settings: TauSDKSettings) -> str | None:
     return caller.uid
 
 
+async def _workload_of(client: MainSequenceClient, user_uid: str) -> DirectoryUser | None:
+    """Return the workload User ``user_uid`` names, as the platform's directory shows it, or None.
+
+    A User that is not a workload, and a lookup that fails, give None, so the check fails closed.
+    The answer is kept for the rest of the request only.
+    """
+
+    lookups = _workload_lookups.get()
+    if lookups is not None and user_uid in lookups:
+        return lookups[user_uid]
+    workload: DirectoryUser | None = None
+    try:
+        found = await client.get_user(user_uid)
+    except (TauSDKError, ValidationError) as error:
+        logger.warning(
+            "request_identity.caller_lookup.failed",
+            message="The caller's User could not be looked up; the session is refused",
+            error_type=type(error).__name__,
+        )
+    else:
+        if found.uid == user_uid and found.identity_type == "workload" and found.agent_uid:
+            workload = found
+    if lookups is not None:
+        lookups[user_uid] = workload
+    return workload
+
+
+async def _delegated_to_caller(
+    client: MainSequenceClient,
+    session: AgentSession,
+    caller: VerifiedCaller,
+) -> bool:
+    """Whether ``session`` is a child session that the caller's own Agent delegated to.
+
+    The session must name its parent session's Agent, the caller must be a workload User as the
+    platform's directory shows it, and that workload must serve the same Agent. No request header
+    is read.
+    """
+
+    parent_agent_uid = session.parent_session_agent_uid
+    if not parent_agent_uid:
+        return False
+    workload = await _workload_of(client, caller.uid)
+    return workload is not None and workload.agent_uid == parent_agent_uid
+
+
 async def require_session_access(
     client: MainSequenceClient,
     session_uid: str,
 ) -> AgentSession | None:
-    """Admit the current request to ``session_uid`` only for its owner or an Organization admin.
+    """Admit the current request to ``session_uid`` only for a caller allowed to address it.
 
-    The owner is the User the platform recorded as the session's creator,
-    ``created_by_user_uid``. The check applies in hosted mode only and raises
-    ``SessionAccessDeniedError`` (403). It returns the session when it had to read it.
+    That is the session's owner, the User the platform recorded as its creator
+    (``created_by_user_uid``); an Organization admin; or, for a delegated child session, the
+    workload User of the Agent that delegated to it (``parent_session_agent_uid``). The check
+    applies in hosted mode only and raises ``SessionAccessDeniedError`` (403). It returns the
+    session when it had to read it.
     """
 
     if client.settings.request_identity_mode != "assertion":
@@ -130,16 +196,19 @@ async def require_session_access(
     if caller.is_organization_admin:
         return None
     session = await client.get_session(session_uid)
-    if session.created_by_user_uid != caller.uid:
-        raise SessionAccessDeniedError()
-    return session
+    if session.created_by_user_uid == caller.uid:
+        return session
+    if await _delegated_to_caller(client, session, caller):
+        return session
+    raise SessionAccessDeniedError()
 
 
 async def sessions_the_caller_may_address(
     client: MainSequenceClient,
     session_uids: Iterable[str],
 ) -> set[str] | None:
-    """Return which of ``session_uids`` the current caller may address.
+    """Return which of ``session_uids`` the current caller may address, by the rule of
+    ``require_session_access()``.
 
     None means every session: outside hosted mode, or for an Organization admin. A session that
     no longer exists is left out.
@@ -160,7 +229,9 @@ async def sessions_the_caller_may_address(
             session = await client.get_session(session_uid)
         except SessionNotFoundError:
             continue
-        if session.created_by_user_uid == caller.uid:
+        if session.created_by_user_uid == caller.uid or await _delegated_to_caller(
+            client, session, caller
+        ):
             allowed.add(session_uid)
     return allowed
 
@@ -240,9 +311,11 @@ class RequestIdentityMiddleware:
                 token=token,
             )
         caller_token = _current_caller.set(caller)
+        lookups_token = _workload_lookups.set({})
         try:
             await self.app(scope, receive, send)
         finally:
+            _workload_lookups.reset(lookups_token)
             _current_caller.reset(caller_token)
             scope.pop(_CALLER_ASSERTION_SCOPE_KEY, None)
 

{ms_tau_sdk-2.0.3.dev36 → ms_tau_sdk-2.0.3.dev37}/src/ms_tau_sdk/backend/assertions.py

@@ -113,6 +113,9 @@ class CallerAssertion:
     caller: VerifiedCaller
     expires_at: int
     token: str = field(repr=False)
+    # True when the platform's directory showed the caller to be a workload User. A workload is
+    # never a turn's or a Task's requester.
+    caller_is_workload: bool = False
 
     def unexpired_token(self, *, now: float | None = None) -> str | None:
         """Return the raw assertion while it is valid, and None once it has expired."""

{ms_tau_sdk-2.0.3.dev36 → ms_tau_sdk-2.0.3.dev37}/src/ms_tau_sdk/backend/client.py

@@ -35,6 +35,7 @@ from .models import (
     AgentTaskEventPage,
     AgentTaskExecutionAttempt,
     AgentTaskSnapshot,
+    DirectoryUser,
     LocalChatSessionPage,
     LocalChatTranscript,
     LocalConversationMessagePage,
@@ -77,6 +78,7 @@ from .routes import (
     agent_task_operation,
     model_provider_credentials,
     resource_release_runtime_access,
+    user,
 )
 
 T = TypeVar("T")
@@ -404,6 +406,12 @@ class MainSequenceClient:
                 detail=error.errors(include_input=False),
             ) from error
 
+    async def get_user(self, user_uid: str) -> DirectoryUser:
+        """Look a User of the Organization up, as the platform's directory shows it."""
+
+        data = await self._request("GET", user(user_uid), idempotent=True)
+        return DirectoryUser.model_validate(data)
+
     async def list_model_providers(
         self, *, organization_environment_uid: str | None = None
     ) -> dict[str, Any]:

{ms_tau_sdk-2.0.3.dev36 → ms_tau_sdk-2.0.3.dev37}/src/ms_tau_sdk/backend/models.py

@@ -74,6 +74,9 @@ class AgentSession(BackendModel):
     )
     status: str | None = None
     created_by_user_uid: str | None = None
+    # The Agent of the parent session, or None for a session without a parent. The Agent that
+    # delegated to a child session addresses it with its own workload User.
+    parent_session_agent_uid: str | None = None
     runtime_capabilities: dict[str, str] = Field(default_factory=dict)
 
     @model_validator(mode="after")
@@ -87,6 +90,18 @@ class AgentSession(BackendModel):
         return self
 
 
+class DirectoryUser(BackendModel):
+    """A User of the Organization as the platform's directory shows it to the runtime.
+
+    A workload User's row carries ``identity_type`` ``workload`` and, for the workload of an
+    Agent's release, ``agent_uid``.
+    """
+
+    uid: str
+    identity_type: str | None = None
+    agent_uid: str | None = None
+
+
 class AgentCardEnvelope(BackendModel):
     agent_session_uid: str
     agent_uid: str

{ms_tau_sdk-2.0.3.dev36 → ms_tau_sdk-2.0.3.dev37}/src/ms_tau_sdk/backend/routes.py

@@ -12,6 +12,7 @@ MODEL_PROVIDER_CREDENTIALS = f"{API_V1_PREFIX}/model-provider-credentials/"
 MODEL_PROVIDERS = f"{API_V1_PREFIX}/model-providers/"
 AGENT_TASKS = f"{API_V1_PREFIX}/agent-tasks/"
 RESOURCE_RELEASES = f"{API_V1_PREFIX}/resource-releases/"
+USERS = f"{API_V1_PREFIX}/users/"
 
 type RuntimeLeaseOperation = Literal["acquire", "renew", "release"]
 type ModelProviderCredentialOperation = Literal["hydrate", "status", "flush", "revoke"]
@@ -92,3 +93,7 @@ def agent_task_operation(task_uid: str, operation: AgentTaskOperation) -> str:
 
 def resource_release_runtime_access(release_uid: str) -> str:
     return f"{RESOURCE_RELEASES}{release_uid}/resolve-runtime-access/"
+
+
+def user(user_uid: str) -> str:
+    return f"{USERS}{user_uid}/"

{ms_tau_sdk-2.0.3.dev36 → ms_tau_sdk-2.0.3.dev37}/src/ms_tau_sdk/runtime/manager.py

@@ -1729,7 +1729,7 @@ class SessionRuntimeManager:
             return None
         if task_context is not None:
             return task_context.requester
-        if caller_assertion is None:
+        if caller_assertion is None or caller_assertion.caller_is_workload:
             return None
         caller = caller_assertion.caller
         if runtime.requester_user_uid != caller.uid: