openhands-sdk 1.29.3__tar.gz → 1.30.0__tar.gz

{openhands_sdk-1.29.3 → openhands_sdk-1.30.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-sdk
-Version: 1.29.3
+Version: 1.30.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

{openhands_sdk-1.29.3 → openhands_sdk-1.30.0}/openhands/sdk/__init__.py

@@ -85,6 +85,7 @@ from openhands.sdk.skills import (
 )
 from openhands.sdk.subagent import (
     agent_definition_to_factory,
+    discover_agents,
     load_agents_from_dir,
     load_project_agents,
     load_user_agents,
@@ -197,6 +198,7 @@ __all__ = [
     "load_project_agents",
     "load_user_agents",
     "load_agents_from_dir",
+    "discover_agents",
     "agent_definition_to_factory",
     "load_project_skills",
     "load_skills_from_dir",

{openhands_sdk-1.29.3 → openhands_sdk-1.30.0}/openhands/sdk/agent/agent.py

@@ -27,7 +27,7 @@ from openhands.sdk.agent.utils import (
     parse_tool_call_arguments,
     prepare_llm_messages,
 )
-from openhands.sdk.context.prompts.presets import create_registry
+from openhands.sdk.context.prompts.presets import PromptPreset, create_registry
 from openhands.sdk.conversation import (
     CancellationToken,
     ConversationCallbackType,
@@ -51,6 +51,7 @@ from openhands.sdk.event.condenser import (
     CondensationRequest,
 )
 from openhands.sdk.llm import (
+    LLM,
     LLMResponse,
     Message,
     MessageToolCall,
@@ -65,6 +66,7 @@ from openhands.sdk.llm.exceptions import (
     LLMContextWindowExceedError,
     LLMMalformedConversationHistoryError,
 )
+from openhands.sdk.llm.router.base import RouterLLM
 from openhands.sdk.logger import get_logger
 from openhands.sdk.observability.laminar import (
     maybe_init_laminar,
@@ -79,6 +81,7 @@ from openhands.sdk.tool import (
 
 
 if TYPE_CHECKING:
+    from openhands.sdk.llm.llm import LLMCallContext
     from openhands.sdk.tool import ToolDefinition
 from openhands.sdk.mcp.tool import MCPToolDefinition
 from openhands.sdk.tool.builtins import (
@@ -113,6 +116,36 @@ def _tool_has_summary_param(tool: ToolDefinition) -> bool:
 INIT_STATE_PREFIX_SCAN_WINDOW = 3
 
 
+def _latest_user_message_contains_image(messages: list[Message]) -> bool:
+    for message in reversed(messages):
+        if message.role == "user":
+            return message.contains_image
+    return False
+
+
+def _non_multimodal_image_message(model: str) -> Message:
+    return Message(
+        role="assistant",
+        content=[
+            TextContent(
+                text=(
+                    "I received your image, but the currently selected model "
+                    f"({model}) does not support image understanding. Please "
+                    "switch to a multimodal model to analyze the image."
+                )
+            )
+        ],
+    )
+
+
+def _should_handle_non_multimodal_image_input(
+    llm: LLM, messages: list[Message]
+) -> bool:
+    if isinstance(llm, RouterLLM):
+        return False
+    return _latest_user_message_contains_image(messages) and not llm.vision_is_active()
+
+
 @dataclass(frozen=True, slots=True)
 class _ActionBatch:
     """Immutable result of preparing a batch of actions for execution.
@@ -474,7 +507,10 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
         secret_infos = state.secret_registry.get_secret_infos()
 
         ctx = self._build_prompt_context(additional_secret_infos=secret_infos)
-        return create_registry().build(ctx).dynamic
+        # The dynamic tier is preset-independent; fall back to the default tier for a
+        # custom Jinja template (preset None), as before.
+        preset = self._prompt_preset or PromptPreset.DEFAULT
+        return create_registry(preset).build(ctx).dynamic
 
     def _execute_actions(
         self,
@@ -572,6 +608,10 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
                 "skipping hook check for legacy conversation state."
             )
 
+        # Build per-conversation context once and thread it through all
+        # LLM calls in this step (avoids shared mutable state on the LLM).
+        call_context: LLMCallContext = conversation.get_llm_call_context()
+
         # Prepare LLM messages from the cached, incrementally-maintained view.
         # See https://github.com/OpenHands/software-agent-sdk/issues/3053.
         _messages_or_condensation = prepare_llm_messages(
@@ -585,6 +625,20 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
 
         _messages = _messages_or_condensation
 
+        if _should_handle_non_multimodal_image_input(self.llm, _messages):
+            logger.info(
+                "Image input received while selected model does not support vision: %s",
+                self.llm.model,
+            )
+            on_event(
+                MessageEvent(
+                    source="agent",
+                    llm_message=_non_multimodal_image_message(self.llm.model),
+                )
+            )
+            state.execution_status = ConversationExecutionStatus.FINISHED
+            return
+
         logger.debug(
             "Sending messages to LLM: "
             f"{json.dumps([m.model_dump() for m in _messages[1:]], indent=2)}"
@@ -596,6 +650,7 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
                 _messages,
                 tools=list(self.tools_map.values()),
                 on_token=on_token,
+                call_context=call_context,
             )
         except FunctionCallValidationError as e:
             logger.warning(f"LLM generated malformed function call: {e}")
@@ -735,6 +790,8 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
                 "skipping hook check for legacy conversation state."
             )
 
+        call_context: LLMCallContext = conversation.get_llm_call_context()
+
         # Prepare LLM messages from the cached, incrementally-maintained view.
         # See https://github.com/OpenHands/software-agent-sdk/issues/3053.
         _messages_or_condensation = await aprepare_llm_messages(
@@ -747,6 +804,20 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
 
         _messages = _messages_or_condensation
 
+        if _should_handle_non_multimodal_image_input(self.llm, _messages):
+            logger.info(
+                "Image input received while selected model does not support vision: %s",
+                self.llm.model,
+            )
+            on_event(
+                MessageEvent(
+                    source="agent",
+                    llm_message=_non_multimodal_image_message(self.llm.model),
+                )
+            )
+            state.execution_status = ConversationExecutionStatus.FINISHED
+            return
+
         logger.debug(
             "Sending messages to LLM: "
             f"{json.dumps([m.model_dump() for m in _messages[1:]], indent=2)}"
@@ -758,6 +829,7 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
                 _messages,
                 tools=list(self.tools_map.values()),
                 on_token=on_token,
+                call_context=call_context,
             )
         except FunctionCallValidationError as e:
             logger.warning(f"LLM generated malformed function call: {e}")

{openhands_sdk-1.29.3 → openhands_sdk-1.30.0}/openhands/sdk/agent/base.py

@@ -26,7 +26,7 @@ from pydantic import (
 
 from openhands.sdk.context.agent_context import AgentContext
 from openhands.sdk.context.condenser import CondenserBase
-from openhands.sdk.context.prompts.presets import create_registry
+from openhands.sdk.context.prompts.presets import PromptPreset, create_registry
 from openhands.sdk.context.prompts.prompt import render_template
 from openhands.sdk.context.prompts.section import Platform, PromptContext
 from openhands.sdk.critic.base import CriticBase
@@ -111,12 +111,21 @@ _DEFAULT_SOUL = (
     " with a computer to solve tasks."
 )
 
-# Built-in prompt dir. The registry only stands in for the default prompt here; a
-# subclass with its own prompts/system_prompt.j2 keeps the Jinja render path.
+# Built-in prompt dir. The registry only stands in for built-in prompts here; a
+# subclass with its own prompts/ keeps the Jinja render path.
 _BUILTIN_PROMPT_DIR = os.path.realpath(
     os.path.join(os.path.dirname(__file__), "prompts")
 )
 
+# Built-in ``system_prompt_filename`` values are back-compat sentinels (the .j2 files
+# were removed) that select a registry preset. ``system_prompt_planning.j2`` keeps its
+# historical name so ``get_planning_agent`` needs no change. Any other filename -- or a
+# subclass's own ``prompt_dir`` -- falls through to the Jinja escape hatch.
+_PRESET_BY_FILENAME: dict[str, PromptPreset] = {
+    "system_prompt.j2": PromptPreset.DEFAULT,
+    "system_prompt_planning.j2": PromptPreset.PLANNING,
+}
+
 
 def _load_soul_md() -> str:
     """Load ``~/.openhands/SOUL.md``, falling back to the built-in default."""
@@ -461,6 +470,18 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
         """Returns the name of the Agent."""
         return self.__class__.__name__
 
+    @property
+    def _prompt_preset(self) -> PromptPreset | None:
+        """The registry preset for this agent's built-in prompt.
+
+        ``None`` means "take the Jinja escape hatch": a subclass with its own
+        ``prompt_dir``, or a ``system_prompt_filename`` that is not a known built-in
+        sentinel (e.g. a custom relative name or an absolute path).
+        """
+        if os.path.realpath(self.prompt_dir) != _BUILTIN_PROMPT_DIR:
+            return None
+        return _PRESET_BY_FILENAME.get(self.system_prompt_filename)
+
     @property
     def static_system_message(self) -> str:
         """Compute the static portion of the system message.
@@ -469,10 +490,11 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
         per-conversation context. This static portion can be cached and reused
         across conversations for better prompt caching efficiency.
 
-        The default prompt is assembled from the typed section registry, which also
-        resolves a custom ``security_policy_filename``. Escape hatches keep the Jinja
-        path: an inline ``system_prompt`` is returned verbatim; a custom
-        ``system_prompt_filename`` or subclass ``prompt_dir`` renders its own template.
+        Built-in prompts (the ``default`` and ``planning`` presets) are assembled from
+        the typed section registry, which also resolves a custom
+        ``security_policy_filename``. Escape hatches keep the Jinja path: an inline
+        ``system_prompt`` is returned verbatim; a custom ``system_prompt_filename`` or
+        subclass ``prompt_dir`` renders its own template.
 
         Returns:
             The static system prompt without dynamic context.
@@ -482,17 +504,15 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
 
         # Escape hatch: a custom filename or a subclass's own prompt_dir renders its
         # own Jinja template; everything else (incl. custom policies) uses the registry.
-        if (
-            self.system_prompt_filename != "system_prompt.j2"
-            or os.path.realpath(self.prompt_dir) != _BUILTIN_PROMPT_DIR
-        ):
+        preset = self._prompt_preset
+        if preset is None:
             return render_template(
                 prompt_dir=self.prompt_dir,
                 template_name=self.system_prompt_filename,
                 **self._resolved_template_kwargs(),
             )
 
-        return create_registry().build(self._build_prompt_context()).static
+        return create_registry(preset).build(self._build_prompt_context()).static
 
     def _resolved_template_kwargs(self) -> dict[str, object]:
         """Resolve the system-prompt template kwargs.
@@ -640,7 +660,10 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
         """
         if not self.agent_context:
             return None
-        return create_registry().build(self._build_prompt_context()).dynamic
+        # The dynamic tier is preset-independent, so a custom Jinja template (preset
+        # None) still gets the default dynamic block, exactly as before.
+        preset = self._prompt_preset or PromptPreset.DEFAULT
+        return create_registry(preset).build(self._build_prompt_context()).dynamic
 
     def init_state(
         self,

{openhands_sdk-1.29.3 → openhands_sdk-1.30.0}/openhands/sdk/agent/utils.py

@@ -31,6 +31,7 @@ from openhands.sdk.tool import Action, ToolDefinition
 
 
 if TYPE_CHECKING:
+    from openhands.sdk.llm.llm import LLMCallContext
     from openhands.sdk.llm.streaming import AnyTokenCallbackType
 
 
@@ -604,6 +605,7 @@ def make_llm_completion(
     messages: list[Message],
     tools: list[ToolDefinition] | None = None,
     on_token: ConversationTokenCallbackType | None = None,
+    call_context: LLMCallContext | None = None,
 ) -> LLMResponse:
     """Make an LLM completion call with the provided messages and tools.
 
@@ -612,6 +614,7 @@ def make_llm_completion(
         messages: The messages to send to the LLM
         tools: Optional list of tools to provide to the LLM
         on_token: Optional callback for streaming token updates
+        call_context: Per-conversation context for cache/session affinity.
 
     Returns:
         LLMResponse from the LLM completion call
@@ -636,6 +639,7 @@ def make_llm_completion(
             store=False,
             add_security_risk_prediction=True,
             on_token=on_token,
+            call_context=call_context,
         )
     else:
         return llm.completion(
@@ -643,6 +647,7 @@ def make_llm_completion(
             tools=tools or [],
             add_security_risk_prediction=True,
             on_token=on_token,
+            call_context=call_context,
         )
 
 
@@ -686,6 +691,7 @@ async def amake_llm_completion(
     messages: list[Message],
     tools: list[ToolDefinition] | None = None,
     on_token: AnyTokenCallbackType | None = None,
+    call_context: LLMCallContext | None = None,
 ) -> LLMResponse:
     """Async variant of :func:`make_llm_completion`."""
     if llm.uses_responses_api():
@@ -696,6 +702,7 @@ async def amake_llm_completion(
             store=False,
             add_security_risk_prediction=True,
             on_token=on_token,
+            call_context=call_context,
         )
     else:
         return await llm.acompletion(
@@ -703,4 +710,5 @@ async def amake_llm_completion(
             tools=tools or [],
             add_security_risk_prediction=True,
             on_token=on_token,
+            call_context=call_context,
         )

{openhands_sdk-1.29.3 → openhands_sdk-1.30.0}/openhands/sdk/context/agent_context.py

@@ -118,7 +118,8 @@ class AgentContext(BaseModel):
         default_factory=list,
         description=(
             "Marketplace registrations for plugin resolution. Registrations with "
-            "auto_load=True are resolved by LocalConversation at startup."
+            "auto_load=True or a list of plugin names are resolved by "
+            "LocalConversation at startup."
         ),
         json_schema_extra={"acp_compatible": True},
     )
@@ -149,8 +150,8 @@ class AgentContext(BaseModel):
         json_schema_extra={"acp_compatible": True},
     )
     current_datetime: datetime | str | None = Field(
-        # Timezone-aware local "now" so the value injected into the system prompt
-        # carries a UTC offset instead of an ambiguous naive local time (#3438).
+        # Timezone-aware local "now"; get_formatted_datetime renders it to the
+        # minute for the prompt.
         default_factory=lambda: datetime.now().astimezone(),
         description=(
             "Current date and time information to provide to the agent. "
@@ -265,13 +266,17 @@ class AgentContext(BaseModel):
 
         Returns:
             Formatted datetime string, or None if current_datetime is not set.
-            If current_datetime is a datetime object, it's formatted as ISO 8601.
+            If current_datetime is a datetime object, it's formatted as
+            "YYYY-MM-DDTHH:MM" (no seconds, microseconds, or UTC offset).
             If current_datetime is already a string, it's returned as-is.
         """
         if self.current_datetime is None:
             return None
         if isinstance(self.current_datetime, datetime):
-            return self.current_datetime.isoformat()
+            # Local wall-clock to the minute: drop seconds, microseconds, offset.
+            return self.current_datetime.replace(tzinfo=None).isoformat(
+                timespec="minutes"
+            )
         return self.current_datetime
 
     def _partition_skills(self) -> tuple[list[Skill], list[Skill]]:

{openhands_sdk-1.29.3 → openhands_sdk-1.30.0}/openhands/sdk/context/condenser/llm_summarizing_condenser.py

@@ -80,6 +80,16 @@ class LLMSummarizingCondenser(RollingCondenser):
             )
         return self
 
+    @model_validator(mode="after")
+    def _disable_streaming_for_summary(self):
+        # Summaries are consumed whole with no on_token callback, which a
+        # streaming LLM requires. Disable streaming once so every summary path
+        # is covered. model_copy is non-mutating and shares usage_id/metrics,
+        # so summary tokens stay attributed to the conversation.
+        if self.llm.stream:
+            self.llm = self.llm.model_copy(update={"stream": False})
+        return self
+
     def handles_condensation_requests(self) -> bool:
         return True
 

openhands_sdk-1.30.0/openhands/sdk/context/prompts/presets.py

@@ -0,0 +1,109 @@
+"""Named :class:`PromptRegistry` presets -- ready-to-use section compositions.
+
+``create_registry()`` selects a section composition over the same engine. The
+``"default"`` preset registers the static-tier sections in the exact order
+``agent/prompts/system_prompt.j2`` emitted them, so ``registry.build(ctx).static``
+reproduces ``AgentBase.static_system_message``. The ``"planning"`` preset is a
+distinct standalone composition (ported from ``system_prompt_planning.j2``) that
+omits the default OpenHands sections. The dynamic-tier sections are **shared** --
+datetime/repo/skills/suffix/secrets are preset-independent -- so a planning agent
+with an ``agent_context`` still gets its dynamic block.
+"""
+
+from enum import StrEnum
+from typing import Final
+
+from openhands.sdk.context.prompts.registry import PromptRegistry
+from openhands.sdk.context.prompts.section import PromptSection
+from openhands.sdk.context.prompts.sections.dynamic import (
+    AvailableSkillsSection,
+    CustomSecretsSection,
+    CustomSuffixSection,
+    DateTimeSection,
+    RepoContextSection,
+)
+from openhands.sdk.context.prompts.sections.planning import PlanningSection
+from openhands.sdk.context.prompts.sections.static import (
+    BrowserSection,
+    CodeQualitySection,
+    EfficiencySection,
+    EnvironmentSetupSection,
+    ExternalServicesSection,
+    FileSystemSection,
+    MemorySection,
+    ModelSpecificSection,
+    ProblemSolvingSection,
+    ProcessManagementSection,
+    PullRequestsSection,
+    RoleSection,
+    SecurityRiskAssessmentSection,
+    SecuritySection,
+    SelfDocumentationSection,
+    SoulSection,
+    TroubleshootingSection,
+    VersionControlSection,
+)
+
+
+__all__ = ["PromptPreset", "create_registry"]
+
+
+class PromptPreset(StrEnum):
+    """Names a :func:`create_registry` section composition."""
+
+    DEFAULT = "default"
+    PLANNING = "planning"
+
+
+_DEFAULT_STATIC_SECTIONS: Final[tuple[PromptSection, ...]] = (
+    SoulSection(),
+    RoleSection(),
+    MemorySection(),
+    EfficiencySection(),
+    FileSystemSection(),
+    CodeQualitySection(),
+    VersionControlSection(),
+    PullRequestsSection(),
+    ProblemSolvingSection(),
+    SelfDocumentationSection(),
+    SecuritySection(),  # guard: security_policy_filename set
+    SecurityRiskAssessmentSection(),  # guard: llm_security_analyzer
+    BrowserSection(),  # guard: ctx.enable_browser
+    ExternalServicesSection(),
+    EnvironmentSetupSection(),
+    TroubleshootingSection(),
+    ProcessManagementSection(),
+    ModelSpecificSection(),  # guard: model_family resolved
+)
+
+_PLANNING_STATIC_SECTIONS: Final[tuple[PromptSection, ...]] = (PlanningSection(),)
+
+_DYNAMIC_SECTIONS: Final[tuple[PromptSection, ...]] = (
+    DateTimeSection(),
+    RepoContextSection(),  # guard: gated repo skills present
+    AvailableSkillsSection(),  # guard: available_skills_prompt
+    CustomSuffixSection(),  # guard: system_message_suffix
+    CustomSecretsSection(),  # guard: secret_infos present
+)
+
+
+def create_registry(preset: PromptPreset = PromptPreset.DEFAULT) -> PromptRegistry:
+    """Build the section registry for ``preset``.
+
+    ``DEFAULT`` is the standard OpenHands composition; ``PLANNING`` is the read-only
+    analysis composition (no ``<SECURITY>``/``<SOUL>``/``<MEMORY>`` ...). Both share
+    the dynamic tier. Sections are stateless, so the per-preset sequences are reused
+    across calls.
+    """
+    match preset:
+        case PromptPreset.PLANNING:
+            static_sections = _PLANNING_STATIC_SECTIONS
+        case PromptPreset.DEFAULT:
+            static_sections = _DEFAULT_STATIC_SECTIONS
+        case _:
+            raise ValueError(f"Unknown prompt preset: {preset!r}")
+
+    r = PromptRegistry()
+    for section in (*static_sections, *_DYNAMIC_SECTIONS):
+        r.register(section)
+    return r

{openhands_sdk-1.29.3 → openhands_sdk-1.30.0}/openhands/sdk/context/prompts/sections/__init__.py

@@ -3,7 +3,8 @@
 Sections are pure, synchronous functions of a :class:`PromptContext` -- no Jinja
 environment, no filesystem loader, no ``render_template`` bootstrap -- so each one
 unit-tests in isolation. The static tier (ported from ``system_prompt.j2``) lives
-in :mod:`.static`.
+in :mod:`.static`; the standalone planning composition (ported from
+``system_prompt_planning.j2``) in :mod:`.planning`.
 """
 
 from openhands.sdk.context.prompts.sections.dynamic import (
@@ -13,6 +14,7 @@ from openhands.sdk.context.prompts.sections.dynamic import (
     DateTimeSection,
     RepoContextSection,
 )
+from openhands.sdk.context.prompts.sections.planning import PlanningSection
 from openhands.sdk.context.prompts.sections.static import (
     BrowserSection,
     CodeQualitySection,
@@ -48,6 +50,7 @@ __all__ = [
     "FileSystemSection",
     "MemorySection",
     "ModelSpecificSection",
+    "PlanningSection",
     "ProblemSolvingSection",
     "ProcessManagementSection",
     "PullRequestsSection",

openhands_sdk-1.29.3/openhands/sdk/agent/prompts/system_prompt_planning.j2 → openhands_sdk-1.30.0/openhands/sdk/context/prompts/sections/planning.py

@@ -1,3 +1,34 @@
+"""The planning system prompt.
+
+Unlike the default composition -- whose blocks each carry a guard and can be overridden
+individually -- the planning prompt is a single standalone STATIC block with no
+per-section guards, so it is one section. The only substitution is ``plan_structure``;
+``tests/sdk/context/prompts/test_planning_registry.py`` pins the output against a golden
+snapshot. No ``_refine``: the text mentions no ``bash``/``terminal`` (its ``<EFFICIENCY>``
+says ``glob and grep``), so the Windows shell substitution is a no-op.
+"""
+
+# The body is verbatim long-form prompt text; wrapping a line would change the rendered
+# bytes, so line-length (E501) is disabled for this whole file.
+# ruff: noqa: E501
+
+from openhands.sdk.context.prompts.section import CacheTier, PromptContext
+
+
+__all__ = ["PlanningSection"]
+
+
+class PlanningSection:
+    """The full planning system prompt as one STATIC block.
+
+    The only substitution is ``plan_structure`` (an empty value reproduces the
+    template's ``<PLAN_STRUCTURE>\\n\\n</PLAN_STRUCTURE>`` output verbatim).
+    """
+
+    name = "planning"
+    cache_tier = CacheTier.STATIC
+
+    _BODY = """\
 You are a Planning Agent that analyzes codebases and helps the user make a detailed plan for their requested changes.
 
 <ROLE>
@@ -92,5 +123,12 @@ Follow this enhanced planning workflow to create well-researched, user-aligned p
 </PLAN_SCOPE>
 
 <PLAN_STRUCTURE>
-{{plan_structure}}
-</PLAN_STRUCTURE>
+{plan_structure}
+</PLAN_STRUCTURE>"""
+
+    def guard(self, ctx: PromptContext) -> bool:  # noqa: ARG002
+        return True
+
+    def render(self, ctx: PromptContext) -> str | None:
+        plan_structure = str(ctx.template_kwargs.get("plan_structure", ""))
+        return self._BODY.replace("{plan_structure}", plan_structure)

{openhands_sdk-1.29.3 → openhands_sdk-1.30.0}/openhands/sdk/conversation/base.py

@@ -18,6 +18,7 @@ from openhands.sdk.observability.laminar import (
     RootSpan,
     end_root_span,
     should_enable_observability,
+    start_child_span,
     start_root_span,
 )
 from openhands.sdk.security.analyzer import SecurityAnalyzerBase
@@ -139,6 +140,7 @@ class BaseConversation(ABC):
     def _start_observability_span(
         self,
         session_id: str,
+        span_name: str = "conversation",
         user_id: str | None = None,
         metadata: dict[str, TraceMetadataValue] | None = None,
         tags: list[str] | None = None,
@@ -148,6 +150,7 @@ class BaseConversation(ABC):
 
         Args:
             session_id: The session ID to associate with the trace
+            span_name: Optional child span name to emit under the conversation root.
             user_id: Optional user ID to associate with the trace
             metadata: Optional trace-level metadata to attach to observability backends
             tags: Optional span tags to attach to the conversation root span
@@ -166,12 +169,15 @@ class BaseConversation(ABC):
             tags=tags,
             attributes=_conversation_tag_attributes(conversation_tags),
         )
+        if span_name != "conversation":
+            start_child_span(self._observability_root_span, span_name, tags=tags)
 
     def _end_observability_span(self) -> None:
         """End the observability span if it hasn't been ended already."""
         if self._span_ended:
             return
-        end_root_span(self._observability_root_span)
+        if self._observability_root_span is not None:
+            end_root_span(self._observability_root_span)
         self._observability_root_span = None
         self._span_ended = True
 
@@ -378,6 +384,19 @@ class BaseConversation(ABC):
         """
         ...
 
+    def load_plugin(self, plugin_ref: str) -> None:
+        """Load a plugin from a registered marketplace.
+
+        Implementations that support marketplace-registered plugins resolve the
+        reference against the conversation agent's registered marketplaces and
+        merge the plugin's skills, hooks, and MCP configuration into the agent.
+
+        Args:
+            plugin_ref: Plugin reference, either ``plugin-name`` or
+                ``plugin-name@marketplace-name``.
+        """
+        raise NotImplementedError("This conversation does not support loading plugins")
+
     @abstractmethod
     def fork(
         self,