openhands-sdk 1.51.0__tar.gz → 1.53.0__tar.gz

{openhands_sdk-1.51.0 → openhands_sdk-1.53.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-sdk
-Version: 1.51.0
+Version: 1.53.0
 Summary: OpenHands SDK - Core functionality for building AI agents
 Project-URL: Source, https://github.com/OpenHands/software-agent-sdk
 Project-URL: Homepage, https://github.com/OpenHands/software-agent-sdk
@@ -18,7 +18,7 @@ Requires-Dist: joserfc>=1.7.5
 Requires-Dist: litellm>=1.93.0
 Requires-Dist: pillow>=12.3.0
 Requires-Dist: pydantic>=2.13.5
-Requires-Dist: python-frontmatter>=1.1.0
+Requires-Dist: python-frontmatter>=1.3.0
 Requires-Dist: python-json-logger>=3.3.0
 Requires-Dist: tenacity>=9.1.2
 Requires-Dist: websockets>=12

openhands_sdk-1.53.0/openhands/sdk/automation/__init__.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping, Sequence
+from typing import NotRequired, TypedDict
+
+from openhands.sdk.conversation.types import TraceMetadataValue
+from openhands.sdk.logger import get_logger
+from openhands.sdk.observability.laminar import (
+    default_observability_span_name_from_env,
+    observability_metadata_from_env,
+    observability_parent_span_context_from_env,
+    observability_tags_from_env,
+)
+
+
+logger = get_logger(__name__)
+
+_AUTOMATION_ID_KEY = "automation.id"
+_AUTOMATION_NAME_KEY = "automation.name"
+_AUTOMATION_RUN_ID_KEY = "automation.run_id"
+_AUTOMATION_TRIGGER_SOURCE_KEY = "automation.trigger_source"
+_DEFAULT_AUTOMATION_SPAN_NAME = "automation.conversation"
+
+
+class AutomationObservabilityContext(TypedDict):
+    observability_metadata: NotRequired[dict[str, TraceMetadataValue]]
+    observability_tags: NotRequired[list[str]]
+    observability_span_name: NotRequired[str]
+    observability_parent_span_context: NotRequired[str]
+
+
+class AutomationConversationKwargs(AutomationObservabilityContext, total=False):
+    tags: dict[str, str]
+
+
+def _merge_metadata(
+    metadata: Mapping[str, TraceMetadataValue] | None,
+) -> dict[str, TraceMetadataValue]:
+    merged = observability_metadata_from_env()
+    if metadata:
+        merged.update(dict(metadata))
+    return merged
+
+
+def _merge_tags(tags: Sequence[str] | None) -> list[str]:
+    merged: list[str] = []
+    seen: set[str] = set()
+    for tag in [*observability_tags_from_env(), *(tags or [])]:
+        tag = tag.strip()
+        if tag and tag not in seen:
+            seen.add(tag)
+            merged.append(tag)
+    return merged
+
+
+def _metadata_str(metadata: Mapping[str, TraceMetadataValue], key: str) -> str | None:
+    value = metadata.get(key)
+    if value is None or isinstance(value, bool | list):
+        return None
+    return str(value)
+
+
+def automation_observability_context(
+    *,
+    metadata: Mapping[str, TraceMetadataValue] | None = None,
+    tags: Sequence[str] | None = None,
+    span_name: str | None = None,
+    parent_span_context: str | None = None,
+) -> AutomationObservabilityContext:
+    """Collect generic automation observability fields for SDK conversations.
+
+    The automation service owns automation-specific values and supplies them via
+    generic ``OPENHANDS_OBSERVABILITY_*`` environment variables. This helper
+    collects those generic values and merges caller-provided additions, so custom
+    automation scripts do not need to duplicate the boilerplate for every
+    ``Conversation(...)`` call.
+    """
+    context: AutomationObservabilityContext = {}
+
+    merged_metadata = _merge_metadata(metadata)
+    if merged_metadata:
+        context["observability_metadata"] = merged_metadata
+
+    merged_tags = _merge_tags(tags)
+    if merged_tags:
+        context["observability_tags"] = merged_tags
+
+    resolved_span_name = span_name or default_observability_span_name_from_env()
+    if resolved_span_name:
+        context["observability_span_name"] = resolved_span_name
+
+    resolved_parent_context = (
+        parent_span_context or observability_parent_span_context_from_env()
+    )
+    if resolved_parent_context:
+        context["observability_parent_span_context"] = resolved_parent_context
+
+    return context
+
+
+def automation_conversation_tags(
+    metadata: Mapping[str, TraceMetadataValue] | None = None,
+) -> dict[str, str]:
+    """Build product conversation tags from automation observability metadata."""
+    merged_metadata = _merge_metadata(metadata)
+    tags: dict[str, str] = {}
+
+    automation_id = _metadata_str(merged_metadata, _AUTOMATION_ID_KEY)
+    automation_name = _metadata_str(merged_metadata, _AUTOMATION_NAME_KEY)
+    automation_run_id = _metadata_str(merged_metadata, _AUTOMATION_RUN_ID_KEY)
+    trigger_source = _metadata_str(merged_metadata, _AUTOMATION_TRIGGER_SOURCE_KEY)
+
+    if automation_id or automation_name or automation_run_id or trigger_source:
+        tags["automationtrigger"] = "automation"
+    if automation_id:
+        tags["automationid"] = automation_id
+    if automation_name:
+        tags["automationname"] = automation_name
+    if automation_run_id:
+        tags["automationrunid"] = automation_run_id
+
+    return tags
+
+
+def automation_conversation_kwargs(
+    *,
+    metadata: Mapping[str, TraceMetadataValue] | None = None,
+    observability_tags: Sequence[str] | None = None,
+    conversation_tags: Mapping[str, str] | None = None,
+    span_name: str | None = None,
+    parent_span_context: str | None = None,
+    include_conversation_tags: bool = True,
+) -> AutomationConversationKwargs:
+    """Return kwargs to pass into ``Conversation(...)`` from an automation script.
+
+    Example:
+        ``Conversation(..., **automation_conversation_kwargs())``
+    """
+    kwargs: AutomationConversationKwargs = {}
+    resolved_span_name = (
+        span_name
+        or default_observability_span_name_from_env()
+        or _DEFAULT_AUTOMATION_SPAN_NAME
+    )
+    context = automation_observability_context(
+        metadata=metadata,
+        tags=observability_tags,
+        span_name=resolved_span_name,
+        parent_span_context=parent_span_context,
+    )
+    if context_metadata := context.get("observability_metadata"):
+        kwargs["observability_metadata"] = context_metadata
+    if context_tags := context.get("observability_tags"):
+        kwargs["observability_tags"] = context_tags
+    if context_span_name := context.get("observability_span_name"):
+        kwargs["observability_span_name"] = context_span_name
+    if context_parent := context.get("observability_parent_span_context"):
+        kwargs["observability_parent_span_context"] = context_parent
+
+    if include_conversation_tags:
+        merged_conversation_tags = automation_conversation_tags(metadata)
+        if conversation_tags:
+            merged_conversation_tags.update(dict(conversation_tags))
+        if merged_conversation_tags:
+            kwargs["tags"] = merged_conversation_tags
+
+    return kwargs
+
+
+def automation_observability_headers(
+    *,
+    metadata: Mapping[str, TraceMetadataValue] | None = None,
+    tags: Sequence[str] | None = None,
+    span_name: str | None = None,
+    parent_span_context: str | None = None,
+) -> dict[str, str]:
+    """Return observability headers for direct agent-server API calls."""
+    context = automation_observability_context(
+        metadata=metadata,
+        tags=tags,
+        span_name=span_name,
+        parent_span_context=parent_span_context,
+    )
+    headers: dict[str, str] = {}
+    if context_metadata := context.get("observability_metadata"):
+        headers["X-OpenHands-Observability-Metadata"] = json.dumps(
+            context_metadata, separators=(",", ":")
+        )
+    if context_tags := context.get("observability_tags"):
+        headers["X-OpenHands-Observability-Tags"] = ",".join(context_tags)
+    if context_span_name := context.get("observability_span_name"):
+        headers["X-OpenHands-Observability-Span-Name"] = context_span_name
+    if context_parent := context.get("observability_parent_span_context"):
+        headers["X-OpenHands-Observability-Parent-Span-Context"] = context_parent
+
+    try:
+        from opentelemetry.propagate import inject
+
+        inject(headers)
+    except Exception:
+        logger.debug(
+            "Failed to inject OpenTelemetry propagation headers", exc_info=True
+        )
+    return headers
+
+
+__all__ = [
+    "AutomationConversationKwargs",
+    "AutomationObservabilityContext",
+    "automation_conversation_kwargs",
+    "automation_conversation_tags",
+    "automation_observability_context",
+    "automation_observability_headers",
+]

{openhands_sdk-1.51.0 → openhands_sdk-1.53.0}/openhands/sdk/conversation/base.py

@@ -18,7 +18,10 @@ from openhands.sdk.llm.llm import LLM
 from openhands.sdk.llm.message import Message
 from openhands.sdk.observability.laminar import (
     RootSpan,
+    default_observability_span_name_from_env,
     end_root_span,
+    merge_observability_metadata,
+    observability_parent_span_context_from_env,
     should_enable_observability,
     start_child_span,
     start_root_span,
@@ -147,6 +150,7 @@ class BaseConversation(ABC):
         metadata: dict[str, TraceMetadataValue] | None = None,
         tags: list[str] | None = None,
         conversation_tags: Mapping[str, str] | None = None,
+        parent_span_context: str | None = None,
     ) -> None:
         """Start a per-conversation observability root span.
 
@@ -163,13 +167,24 @@ class BaseConversation(ABC):
         if self._observability_root_span is not None:
             # Idempotent: never start two roots for one conversation.
             return
+        default_span_name = default_observability_span_name_from_env()
+        if default_span_name and span_name == "conversation":
+            span_name = default_span_name
+
+        metadata = merge_observability_metadata(metadata)
+        attributes: dict[str, TraceMetadataValue] = dict(metadata)
+        tag_attributes = _conversation_tag_attributes(conversation_tags)
+        if tag_attributes:
+            attributes.update(tag_attributes)
         self._observability_root_span = start_root_span(
             "conversation",
             session_id=session_id,
             user_id=user_id,
             metadata=metadata,
             tags=tags,
-            attributes=_conversation_tag_attributes(conversation_tags),
+            attributes=attributes,
+            parent_span_context=parent_span_context
+            or observability_parent_span_context_from_env(),
         )
         if span_name != "conversation":
             start_child_span(self._observability_root_span, span_name, tags=tags)

{openhands_sdk-1.51.0 → openhands_sdk-1.53.0}/openhands/sdk/conversation/conversation.py

@@ -88,6 +88,7 @@ class Conversation:
         observability_metadata: dict[str, TraceMetadataValue] | None = None,
         observability_tags: list[str] | None = None,
         observability_span_name: str = "conversation",
+        observability_parent_span_context: str | None = None,
     ) -> "LocalConversation": ...
 
     @overload
@@ -117,6 +118,7 @@ class Conversation:
         observability_metadata: dict[str, TraceMetadataValue] | None = None,
         observability_tags: list[str] | None = None,
         observability_span_name: str = "conversation",
+        observability_parent_span_context: str | None = None,
     ) -> "RemoteConversation": ...
 
     def __new__(
@@ -146,6 +148,7 @@ class Conversation:
         observability_metadata: dict[str, TraceMetadataValue] | None = None,
         observability_tags: list[str] | None = None,
         observability_span_name: str = "conversation",
+        observability_parent_span_context: str | None = None,
     ) -> BaseConversation:
         from openhands.sdk.conversation.impl.local_conversation import LocalConversation
         from openhands.sdk.conversation.impl.remote_conversation import (
@@ -209,6 +212,7 @@ class Conversation:
                 observability_metadata=observability_metadata,
                 observability_tags=observability_tags,
                 observability_span_name=observability_span_name,
+                observability_parent_span_context=observability_parent_span_context,
             )
 
         return LocalConversation(
@@ -232,4 +236,5 @@ class Conversation:
             observability_metadata=observability_metadata,
             observability_tags=observability_tags,
             observability_span_name=observability_span_name,
+            observability_parent_span_context=observability_parent_span_context,
         )

{openhands_sdk-1.51.0 → openhands_sdk-1.53.0}/openhands/sdk/conversation/impl/local_conversation.py

@@ -236,6 +236,7 @@ class LocalConversation(BaseConversation):
         # positional argument.
         max_budget_per_run: float | None = None,
         observability_span_name: str = "conversation",
+        observability_parent_span_context: str | None = None,
         prompt_cache_key: str | None = None,
         file_store: FileStore | None = None,
         mcp_tool_provider: MCPToolProvider | None = None,
@@ -552,6 +553,7 @@ class LocalConversation(BaseConversation):
             metadata=observability_metadata,
             tags=observability_tags,
             conversation_tags=tags,
+            parent_span_context=observability_parent_span_context,
         )
         self.delete_on_close = delete_on_close
 

{openhands_sdk-1.51.0 → openhands_sdk-1.53.0}/openhands/sdk/conversation/impl/remote_conversation.py

@@ -53,7 +53,13 @@ from openhands.sdk.event.types import EventID
 from openhands.sdk.hooks import HookConfig
 from openhands.sdk.llm import LLM, Message, TextContent
 from openhands.sdk.logger import DEBUG, get_logger
-from openhands.sdk.observability.laminar import OPERATION_METADATA_KEY, observe
+from openhands.sdk.observability.laminar import (
+    OPERATION_METADATA_KEY,
+    default_observability_span_name_from_env,
+    merge_observability_metadata,
+    observability_parent_span_context_from_env,
+    observe,
+)
 from openhands.sdk.security.analyzer import SecurityAnalyzerBase
 from openhands.sdk.security.confirmation_policy import (
     ConfirmationPolicyBase,
@@ -739,6 +745,7 @@ class RemoteConversation(BaseConversation):
         observability_metadata: dict[str, TraceMetadataValue] | None = None,
         observability_tags: list[str] | None = None,
         observability_span_name: str = "conversation",
+        observability_parent_span_context: str | None = None,
         **_: object,
     ) -> None:
         """Remote conversation proxy that talks to an agent server.
@@ -777,6 +784,15 @@ class RemoteConversation(BaseConversation):
             observability_span_name: Optional child span name for observability
                       backends. The root span remains named "conversation".
         """
+        observability_metadata = merge_observability_metadata(observability_metadata)
+        observability_parent_span_context = (
+            observability_parent_span_context
+            or observability_parent_span_context_from_env()
+        )
+        default_span_name = default_observability_span_name_from_env()
+        if default_span_name and observability_span_name == "conversation":
+            observability_span_name = default_span_name
+
         # Client tool specs the server already has persisted for this
         # conversation (populated when re-attaching to an existing one). These
         # must be registered locally before the initial event sync so that
@@ -860,6 +876,7 @@ class RemoteConversation(BaseConversation):
                 if observability_tags is not None
                 else [],
                 "observability_span_name": observability_span_name,
+                "observability_parent_span_context": observability_parent_span_context,
                 "user_id": user_id,
             }
             if user_id:
@@ -921,6 +938,7 @@ class RemoteConversation(BaseConversation):
             metadata=observability_metadata,
             tags=observability_tags,
             conversation_tags=tags,
+            parent_span_context=observability_parent_span_context,
         )
         # All hooks (including SessionStart/SessionEnd) are executed server-side.
         # hook_config is sent in the creation payload.
@@ -944,6 +962,22 @@ class RemoteConversation(BaseConversation):
         conversation ID follows the server's idempotency contract; this method
         does not probe for an existing conversation.
         """
+        updates: dict[str, object] = {
+            "observability_metadata": merge_observability_metadata(
+                request.observability_metadata
+            ),
+        }
+        default_span_name = default_observability_span_name_from_env()
+        if default_span_name and request.observability_span_name == "conversation":
+            updates["observability_span_name"] = default_span_name
+        parent_span_context = (
+            request.observability_parent_span_context
+            or observability_parent_span_context_from_env()
+        )
+        if parent_span_context:
+            updates["observability_parent_span_context"] = parent_span_context
+        request = request.model_copy(update=updates)
+
         response = _send_request(
             workspace.client,
             "POST",
@@ -962,6 +996,7 @@ class RemoteConversation(BaseConversation):
             metadata=request.observability_metadata,
             tags=request.observability_tags,
             conversation_tags=request.tags,
+            parent_span_context=request.observability_parent_span_context,
         )
         return conversation
 

{openhands_sdk-1.51.0 → openhands_sdk-1.53.0}/openhands/sdk/conversation/request.py

@@ -258,6 +258,14 @@ class ConversationConfig(BaseModel):
             "span names for grouping or signal routing."
         ),
     )
+    observability_parent_span_context: str | None = Field(
+        default=None,
+        description=(
+            "Serialized parent span context used to attach this conversation to "
+            "an upstream automation or integration trace."
+        ),
+    )
+
     autotitle: bool = Field(
         default=True,
         description=(

{openhands_sdk-1.51.0 → openhands_sdk-1.53.0}/openhands/sdk/observability/laminar.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import contextlib
 import functools
 import inspect
+import json
 import sys
 from collections.abc import Callable, Iterator, Mapping
 from typing import TYPE_CHECKING, Any, Final, Literal, cast
@@ -35,6 +36,109 @@ _OBSERVABILITY_ENV_KEYS: Final[tuple[str, ...]] = (
 OPERATION_METADATA_KEY: Final[str] = "openhands.operation"
 """Metadata key naming the side-utility operation a span subtree belongs to."""
 
+_OBSERVABILITY_METADATA_ENV: Final[str] = "OPENHANDS_OBSERVABILITY_METADATA"
+_OBSERVABILITY_TAGS_ENV: Final[str] = "OPENHANDS_OBSERVABILITY_TAGS"
+_OBSERVABILITY_SPAN_NAME_ENV: Final[str] = "OPENHANDS_OBSERVABILITY_SPAN_NAME"
+_OBSERVABILITY_PARENT_CONTEXT_ENV: Final[str] = (
+    "OPENHANDS_OBSERVABILITY_PARENT_SPAN_CONTEXT"
+)
+_LAMINAR_PARENT_CONTEXT_ENV: Final[str] = "LMNR_SPAN_CONTEXT"
+
+
+def _is_trace_metadata_value(value: Any) -> bool:
+    if isinstance(value, str | bool | int | float):
+        return True
+    if isinstance(value, list):
+        return (
+            all(isinstance(item, str) for item in value)
+            or all(isinstance(item, bool) for item in value)
+            or all(
+                isinstance(item, int) and not isinstance(item, bool) for item in value
+            )
+            or all(isinstance(item, float) for item in value)
+        )
+    return False
+
+
+def _clean_trace_metadata(value: Any) -> dict[str, TraceMetadataValue]:
+    if not isinstance(value, dict):
+        return {}
+    cleaned: dict[str, TraceMetadataValue] = {}
+    for key, item in value.items():
+        if isinstance(key, str) and key and _is_trace_metadata_value(item):
+            cleaned[key] = item
+    return cleaned
+
+
+def observability_metadata_from_env() -> dict[str, TraceMetadataValue]:
+    """Return generic observability metadata supplied by the process env."""
+    raw_metadata = get_env(_OBSERVABILITY_METADATA_ENV)
+    if not raw_metadata:
+        return {}
+    try:
+        return _clean_trace_metadata(json.loads(raw_metadata))
+    except json.JSONDecodeError:
+        logger.debug("Ignoring invalid %s", _OBSERVABILITY_METADATA_ENV)
+        return {}
+
+
+def merge_observability_metadata(
+    metadata: Mapping[str, TraceMetadataValue] | None,
+) -> dict[str, TraceMetadataValue]:
+    """Merge generic env defaults with caller-supplied metadata."""
+    merged = observability_metadata_from_env()
+    if metadata:
+        merged.update(metadata)
+    return merged
+
+
+def observability_parent_span_context_from_env() -> str | None:
+    """Return serialized parent span context propagated by the host process."""
+    return get_env(_OBSERVABILITY_PARENT_CONTEXT_ENV) or get_env(
+        _LAMINAR_PARENT_CONTEXT_ENV
+    )
+
+
+def default_observability_span_name_from_env() -> str | None:
+    """Return the default conversation child span name from generic env."""
+    return get_env(_OBSERVABILITY_SPAN_NAME_ENV)
+
+
+def observability_tags_from_env() -> list[str]:
+    """Return comma-separated observability tags supplied by generic env."""
+    raw_tags = get_env(_OBSERVABILITY_TAGS_ENV)
+    if not raw_tags:
+        return []
+    return [tag.strip() for tag in raw_tags.split(",") if tag.strip()]
+
+
+def observability_headers_from_env() -> dict[str, str]:
+    """Build generic observability headers for agent-server API calls."""
+    headers: dict[str, str] = {}
+    metadata = observability_metadata_from_env()
+    if metadata:
+        headers["X-OpenHands-Observability-Metadata"] = json.dumps(
+            metadata, separators=(",", ":")
+        )
+    tags = observability_tags_from_env()
+    if tags:
+        headers["X-OpenHands-Observability-Tags"] = ",".join(tags)
+    span_name = default_observability_span_name_from_env()
+    if span_name:
+        headers["X-OpenHands-Observability-Span-Name"] = span_name
+    parent_context = observability_parent_span_context_from_env()
+    if parent_context:
+        headers["X-OpenHands-Observability-Parent-Span-Context"] = parent_context
+    try:
+        from opentelemetry.propagate import inject
+
+        inject(headers)
+    except Exception:
+        logger.debug(
+            "Failed to inject OpenTelemetry propagation headers", exc_info=True
+        )
+    return headers
+
 
 def _get_int_env(key: str) -> int | None:
     """Read an environment variable as an optional int."""
@@ -48,18 +152,6 @@ def _get_int_env(key: str) -> int | None:
     return None
 
 
-def _get_bool_env(key: str) -> bool:
-    """Read an environment variable as a boolean.
-
-    Returns True if the value is 'true', '1', 'yes', 'on' (case-insensitive).
-    Returns False otherwise.
-    """
-    val = get_env(key)
-    if val is None:
-        return False
-    return val.lower() in ("true", "1", "yes", "on")
-
-
 def maybe_init_laminar():
     """Initialize Laminar if the environment variables are set.
 
@@ -101,7 +193,12 @@ def maybe_init_laminar():
         return
 
     base_url = get_env("LMNR_BASE_URL") or None
-    force_http = _get_bool_env("LMNR_FORCE_HTTP")
+    force_http = (get_env("LMNR_FORCE_HTTP") or "").lower() in (
+        "true",
+        "1",
+        "yes",
+        "on",
+    )
     instruments_env = get_env("LMNR_INSTRUMENTS")
     instruments = None
     if instruments_env is not None:
@@ -300,15 +397,24 @@ class RootSpan:
         name: str,
         session_id: str | None = None,
         user_id: str | None = None,
-        attributes: Mapping[str, str] | None = None,
+        attributes: Mapping[str, TraceMetadataValue] | None = None,
         metadata: dict[str, TraceMetadataValue] | None = None,
         tags: list[str] | None = None,
+        parent_span_context: str | None = None,
     ) -> None:
         from lmnr import Laminar
 
+        parent = None
+        if parent_span_context:
+            with contextlib.suppress(Exception):
+                parent = Laminar.deserialize_span_context(parent_span_context)
+
         # ``start_span`` returns a span without attaching it as the current
         # OTel context; we'll restore it on every entry point via ``use_span``.
-        self.span = Laminar.start_span(name)
+        if parent is not None:
+            self.span = Laminar.start_span(name, parent_span_context=parent)
+        else:
+            self.span = Laminar.start_span(name)
         if attributes:
             with contextlib.suppress(Exception):
                 for key, value in attributes.items():
@@ -350,9 +456,10 @@ def start_root_span(
     name: str,
     session_id: str | None = None,
     user_id: str | None = None,
-    attributes: Mapping[str, str] | None = None,
+    attributes: Mapping[str, TraceMetadataValue] | None = None,
     metadata: dict[str, TraceMetadataValue] | None = None,
     tags: list[str] | None = None,
+    parent_span_context: str | None = None,
 ) -> RootSpan | None:
     """Create a long-lived root span for an owning object.
 
@@ -368,6 +475,7 @@ def start_root_span(
             attributes=attributes,
             metadata=metadata,
             tags=tags,
+            parent_span_context=parent_span_context,
         )
     except Exception:
         logger.debug("Failed to create observability root span", exc_info=True)