π OpenHands: AI-Driven Development
Use user email as Laminar trace user_id when available (#14504)
Juan Michelini3515cb085834
diff --git a/enterprise/integrations/resolver_context.py b/enterprise/integrations/resolver_context.pyindex 22b79de030..807bb41c00 100644--- a/enterprise/integrations/resolver_context.py+++ b/enterprise/integrations/resolver_context.py@@ -26,6 +26,9 @@ class ResolverUserContext(UserContext):async def get_user_id(self) -> str | None:return await self.saas_user_auth.get_user_id()+ async def get_user_email(self) -> str | None:+ return await self.saas_user_auth.get_user_email()+async def get_user_info(self) -> UserInfo:user_settings = await self.saas_user_auth.get_user_settings()user_id = await self.saas_user_auth.get_user_id()diff --git a/openhands/app_server/app_conversation/live_status_app_conversation_service.py b/openhands/app_server/app_conversation/live_status_app_conversation_service.pyindex 3ab7909a1e..cba9318854 100644--- a/openhands/app_server/app_conversation/live_status_app_conversation_service.py+++ b/openhands/app_server/app_conversation/live_status_app_conversation_service.py@@ -243,6 +243,11 @@ class LiveStatusAppConversationService(AppConversationServiceBase):) -> AsyncGenerator[AppConversationStartTask, None]:# Create and yield the start taskuser_id = await self.user_context.get_user_id()+ # Prefer the user's email as the Laminar trace user id so traces are+ # immediately attributable in the Laminar UI instead of showing only+ # a pseudo-anonymous internal id. Falls back to ``user_id`` when no+ # email is available (e.g. OSS mode).+ laminar_user_id = await self.user_context.get_user_email() or user_id# Validate and inherit from parent conversation if providedif request.parent_conversation_id:@@ -334,14 +339,14 @@ class LiveStatusAppConversationService(AppConversationServiceBase):# traces with the authenticated user. The currently pinned# ``openhands-sdk`` release does not yet expose ``user_id`` on# ``StartConversationRequest`` (added in software-agent-sdk#3242),- # so passing ``user_id=user.id`` to ``create_request(...)`` is- # silently dropped by pydantic. The agent-server reads the field- # directly from the request body, so injecting it here works- # regardless of whether the local SDK model knows about it.- # Remove this once OpenHands pins to an SDK release that exposes- # ``user_id`` on ``StartConversationRequest``.- if user_id:- body_json['user_id'] = user_id+ # so passing it to ``create_request(...)`` is silently dropped by+ # pydantic. The agent-server reads the field directly from the+ # request body, so injecting it here works regardless of whether+ # the local SDK model knows about it. Remove this once OpenHands+ # pins to an SDK release that exposes ``user_id`` on+ # ``StartConversationRequest``.+ if laminar_user_id:+ body_json['user_id'] = laminar_user_idheaders = ({'X-Session-API-Key': sandbox.session_api_key}if sandbox.session_api_key@@ -1411,12 +1416,16 @@ class LiveStatusAppConversationService(AppConversationServiceBase):# Pass agent explicitly β it has server-only overrides (system# prompts, LLM metadata, skills) applied after create_agent().# ``user_id`` is forwarded so the agent-server can attach it to- # observability spans (see software-agent-sdk#3242). It is dropped- # silently by pydantic on SDK versions that don't yet expose the- # field; the start-conversation POST also injects it directly into- # the JSON body as a forward-compatible fallback.+ # observability spans (see software-agent-sdk#3242). We prefer the+ # user's email so Laminar traces are immediately attributable, and+ # fall back to the internal user id when no email is available.+ # The kwarg is dropped silently by pydantic on SDK versions that+ # don't yet expose the field; the start-conversation POST also+ # injects it directly into the JSON body as a forward-compatible+ # fallback.+ laminar_user_id = await self.user_context.get_user_email() or user.idrequest = conv_settings.create_request(- StartConversationRequest, agent=agent, user_id=user.id+ StartConversationRequest, agent=agent, user_id=laminar_user_id)# --- skills (require remote workspace) ------------------------------@@ -1556,9 +1565,12 @@ class LiveStatusAppConversationService(AppConversationServiceBase):})# ``user_id`` is forwarded for observability; see the LLM path above- # for behavior on SDK versions that don't yet expose the field.+ # for behavior on SDK versions that don't yet expose the field. We+ # prefer email over the internal id so Laminar traces are immediately+ # attributable, falling back to ``user.id`` when no email is available.+ laminar_user_id = await self.user_context.get_user_email() or user.idreturn conv_settings.create_request(- StartConversationRequest, agent=acp_agent, user_id=user.id+ StartConversationRequest, agent=acp_agent, user_id=laminar_user_id)async def _process_pending_messages(diff --git a/openhands/app_server/user/auth_user_context.py b/openhands/app_server/user/auth_user_context.pyindex ec5960c2f5..2936b09a9c 100644--- a/openhands/app_server/user/auth_user_context.py+++ b/openhands/app_server/user/auth_user_context.py@@ -36,6 +36,9 @@ class AuthUserContext(UserContext):user_id = await self.user_auth.get_user_id()return user_id+ async def get_user_email(self) -> str | None:+ return await self.user_auth.get_user_email()+async def get_user_info(self) -> UserInfo:user_info = self._user_infoif user_info is None:diff --git a/openhands/app_server/user/specifiy_user_context.py b/openhands/app_server/user/specifiy_user_context.pyindex e275f99adc..af36e3940a 100644--- a/openhands/app_server/user/specifiy_user_context.py+++ b/openhands/app_server/user/specifiy_user_context.py@@ -19,6 +19,9 @@ class SpecifyUserContext(UserContext):async def get_user_id(self) -> str | None:return self.user_id+ async def get_user_email(self) -> str | None:+ return None+async def get_user_info(self) -> UserInfo:raise NotImplementedError()diff --git a/openhands/app_server/user/user_context.py b/openhands/app_server/user/user_context.pyindex 82c4e4cb71..55c2fd84f4 100644--- a/openhands/app_server/user/user_context.py+++ b/openhands/app_server/user/user_context.py@@ -19,6 +19,20 @@ class UserContext(ABC):async def get_user_id(self) -> str | None:"""Get the user id"""+ @abstractmethod+ async def get_user_email(self) -> str | None:+ """Get the email for the current user, if available.++ Returns the user's email address for attribution in observability+ traces (e.g. Laminar). In SaaS/enterprise mode this is typically+ the Keycloak email; in OSS mode or for admin-scoped contexts this+ returns ``None`` so callers can fall back to the internal user id.++ Note: this value is considered PII and may be forwarded to+ third-party observability services. Treat it accordingly when+ adding new callers.+ """+@abstractmethodasync def get_user_info(self) -> UserInfo:"""Get the user info."""diff --git a/tests/unit/app_server/test_user_context_email.py b/tests/unit/app_server/test_user_context_email.pynew file mode 100644index 0000000000..1d0586de74--- /dev/null+++ b/tests/unit/app_server/test_user_context_email.py@@ -0,0 +1,103 @@+"""Unit tests for ``UserContext.get_user_email()`` implementations.++These tests cover the change that uses the user's email (when available) as+the Laminar trace ``user_id`` so traces are immediately attributable in the+Laminar UI, while still falling back to the internal user id (e.g. in OSS+mode or for admin-scoped contexts).+"""++from unittest.mock import AsyncMock++import pytest++from openhands.app_server.user.auth_user_context import AuthUserContext+from openhands.app_server.user.specifiy_user_context import (+ ADMIN,+ SpecifyUserContext,+)+++class TestAuthUserContextEmail:+ """``AuthUserContext.get_user_email()`` delegates to ``UserAuth``."""++ @pytest.mark.asyncio+ async def test_returns_email_when_user_auth_has_one(self):+ """SaaS mode: Keycloak-backed UserAuth returns the user's email."""+ user_auth = AsyncMock()+ user_auth.get_user_email = AsyncMock(return_value='[email protected]')+ ctx = AuthUserContext(user_auth=user_auth)++ email = await ctx.get_user_email()++ assert email == '[email protected]'+ user_auth.get_user_email.assert_awaited_once()++ @pytest.mark.asyncio+ async def test_returns_none_when_user_auth_has_no_email(self):+ """OSS mode: DefaultUserAuth returns None and we propagate that."""+ user_auth = AsyncMock()+ user_auth.get_user_email = AsyncMock(return_value=None)+ ctx = AuthUserContext(user_auth=user_auth)++ email = await ctx.get_user_email()++ assert email is None+ user_auth.get_user_email.assert_awaited_once()+++class TestSpecifyUserContextEmail:+ """Admin contexts have no associated end-user email."""++ @pytest.mark.asyncio+ async def test_returns_none_for_admin_context(self):+ assert await ADMIN.get_user_email() is None++ @pytest.mark.asyncio+ async def test_returns_none_for_arbitrary_user_id(self):+ ctx = SpecifyUserContext(user_id='some-uuid')+ assert await ctx.get_user_email() is None+++class TestLaminarUserIdFallback:+ """The exact ``email or user_id`` expression used at the three callsites+ inside ``LiveStatusAppConversationService``. We verify the semantics here+ rather than reach into the large async _start_app_conversation flow.+ """++ @pytest.mark.asyncio+ async def test_prefers_email_when_available(self):+ ctx = AuthUserContext(user_auth=AsyncMock())+ ctx.user_auth.get_user_email = AsyncMock(return_value='[email protected]')+ user_id = 'internal-uuid-123'++ laminar_user_id = await ctx.get_user_email() or user_id++ assert laminar_user_id == '[email protected]'++ @pytest.mark.asyncio+ async def test_falls_back_to_user_id_when_email_is_none(self):+ ctx = AuthUserContext(user_auth=AsyncMock())+ ctx.user_auth.get_user_email = AsyncMock(return_value=None)+ user_id = 'internal-uuid-123'++ laminar_user_id = await ctx.get_user_email() or user_id++ assert laminar_user_id == 'internal-uuid-123'++ @pytest.mark.asyncio+ async def test_falls_back_to_user_id_when_email_is_empty_string(self):+ """``or`` also treats '' as falsy, which is the desired behavior:+ an empty email is not useful as a Laminar trace id."""+ ctx = AuthUserContext(user_auth=AsyncMock())+ ctx.user_auth.get_user_email = AsyncMock(return_value='')+ user_id = 'internal-uuid-123'++ laminar_user_id = await ctx.get_user_email() or user_id++ assert laminar_user_id == 'internal-uuid-123'++ @pytest.mark.asyncio+ async def test_admin_context_always_falls_back_to_user_id(self):+ user_id = 'admin-target-user-id'+ laminar_user_id = await ADMIN.get_user_email() or user_id+ assert laminar_user_id == 'admin-target-user-id'