openhands-sdk 1.6.0__tar.gz → 1.7.0__tar.gz

{openhands_sdk-1.6.0 → openhands_sdk-1.7.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: openhands-sdk
-Version: 1.6.0
+Version: 1.7.0
 Summary: OpenHands SDK - Core functionality for building AI agents
 Requires-Python: >=3.12
 Requires-Dist: deprecation>=2.1.0
 Requires-Dist: fastmcp>=2.11.3
 Requires-Dist: httpx>=0.27.0
-Requires-Dist: litellm>=1.80.7
+Requires-Dist: litellm>=1.80.10
 Requires-Dist: pydantic>=2.11.7
 Requires-Dist: python-frontmatter>=1.1.0
 Requires-Dist: python-json-logger>=3.3.0

{openhands_sdk-1.6.0 → openhands_sdk-1.7.0}/openhands/sdk/__init__.py

@@ -1,7 +1,12 @@
 from importlib.metadata import PackageNotFoundError, version
 
 from openhands.sdk.agent import Agent, AgentBase
-from openhands.sdk.context import AgentContext
+from openhands.sdk.context import (
+    AgentContext,
+    load_project_skills,
+    load_skills_from_dir,
+    load_user_skills,
+)
 from openhands.sdk.context.condenser import (
     LLMSummarizingCondenser,
 )
@@ -99,5 +104,8 @@ __all__ = [
     "Workspace",
     "LocalWorkspace",
     "RemoteWorkspace",
+    "load_project_skills",
+    "load_skills_from_dir",
+    "load_user_skills",
     "__version__",
 ]

{openhands_sdk-1.6.0 → openhands_sdk-1.7.0}/openhands/sdk/agent/agent.py

@@ -109,17 +109,10 @@ class Agent(AgentBase):
             event = SystemPromptEvent(
                 source="agent",
                 system_prompt=TextContent(text=self.system_message),
-                # Always expose a 'security_risk' parameter in tool schemas.
-                # This ensures the schema remains consistent, even if the
-                # security analyzer is disabled. Validation of this field
-                # happens dynamically at runtime depending on the analyzer
-                # configured. This allows weaker models to omit risk field
-                # and bypass validation requirements when analyzer is disabled.
-                # For detailed logic, see `_extract_security_risk` method.
-                tools=[
-                    t.to_openai_tool(add_security_risk_prediction=True)
-                    for t in self.tools_map.values()
-                ],
+                # Tools are stored as ToolDefinition objects and converted to
+                # OpenAI format with security_risk parameter during LLM completion.
+                # See make_llm_completion() in agent/utils.py for details.
+                tools=list(self.tools_map.values()),
             )
             on_event(event)
 

{openhands_sdk-1.6.0 → openhands_sdk-1.7.0}/openhands/sdk/agent/base.py

@@ -121,6 +121,15 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
             "- An absolute path (e.g., '/path/to/custom_prompt.j2')"
         ),
     )
+    security_policy_filename: str = Field(
+        default="security_policy.j2",
+        description=(
+            "Security policy template filename. Can be either:\n"
+            "- A relative filename (e.g., 'security_policy.j2') loaded from the "
+            "agent's prompts directory\n"
+            "- An absolute path (e.g., '/path/to/custom_security_policy.j2')"
+        ),
+    )
     system_prompt_kwargs: dict[str, object] = Field(
         default_factory=dict,
         description="Optional kwargs to pass to the system prompt Jinja2 template.",
@@ -165,6 +174,8 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
     def system_message(self) -> str:
         """Compute system message on-demand to maintain statelessness."""
         template_kwargs = dict(self.system_prompt_kwargs)
+        # Add security_policy_filename to template kwargs
+        template_kwargs["security_policy_filename"] = self.security_policy_filename
         template_kwargs.setdefault("model_name", self.llm.model)
         if (
             "model_family" not in template_kwargs

{openhands_sdk-1.6.0 → openhands_sdk-1.7.0}/openhands/sdk/agent/prompts/system_prompt.j2

@@ -74,7 +74,7 @@ You are OpenHands agent, a helpful AI assistant that can interact with a compute
 </SELF_DOCUMENTATION>
 
 <SECURITY>
-{% include 'security_policy.j2' %}
+{% include security_policy_filename %}
 </SECURITY>
 
 {% if llm_security_analyzer %}

{openhands_sdk-1.6.0 → openhands_sdk-1.7.0}/openhands/sdk/agent/utils.py

@@ -195,6 +195,15 @@ def make_llm_completion(
 
     Returns:
         LLMResponse from the LLM completion call
+
+    Note:
+        Always exposes a 'security_risk' parameter in tool schemas via
+        add_security_risk_prediction=True. This ensures the schema remains
+        consistent, even if the security analyzer is disabled. Validation of
+        this field happens dynamically at runtime depending on the analyzer
+        configured. This allows weaker models to omit risk field and bypass
+        validation requirements when analyzer is disabled. For detailed logic,
+        see `_extract_security_risk` method in agent.py.
     """
     if llm.uses_responses_api():
         return llm.responses(

{openhands_sdk-1.6.0 → openhands_sdk-1.7.0}/openhands/sdk/context/__init__.py

@@ -7,6 +7,7 @@ from openhands.sdk.context.skills import (
     SkillKnowledge,
     SkillValidationError,
     TaskTrigger,
+    load_project_skills,
     load_skills_from_dir,
     load_user_skills,
 )
@@ -21,6 +22,7 @@ __all__ = [
     "SkillKnowledge",
     "load_skills_from_dir",
     "load_user_skills",
+    "load_project_skills",
     "render_template",
     "SkillValidationError",
 ]

{openhands_sdk-1.6.0 → openhands_sdk-1.7.0}/openhands/sdk/context/agent_context.py

@@ -14,7 +14,7 @@ from openhands.sdk.context.skills import (
 )
 from openhands.sdk.llm import Message, TextContent
 from openhands.sdk.logger import get_logger
-from openhands.sdk.secret import SecretValue
+from openhands.sdk.secret import SecretSource, SecretValue
 
 
 logger = get_logger(__name__)
@@ -136,15 +136,23 @@ class AgentContext(BaseModel):
             logger.warning(f"Failed to load public skills: {str(e)}")
         return self
 
-    def get_secret_names(self) -> list[str]:
-        """Get the list of secret names from the secrets field.
+    def get_secret_infos(self) -> list[dict[str, str]]:
+        """Get secret information (name and description) from the secrets field.
 
         Returns:
-            List of secret names. Returns an empty list if no secrets are configured.
+            List of dictionaries with 'name' and 'description' keys.
+            Returns an empty list if no secrets are configured.
+            Description will be None if not available.
         """
         if not self.secrets:
             return []
-        return list(self.secrets.keys())
+        secret_infos = []
+        for name, secret_value in self.secrets.items():
+            description = None
+            if isinstance(secret_value, SecretSource):
+                description = secret_value.description
+            secret_infos.append({"name": name, "description": description})
+        return secret_infos
 
     def get_system_message_suffix(self) -> str | None:
         """Get the system message with repo skill content and custom suffix.
@@ -158,15 +166,15 @@ class AgentContext(BaseModel):
         repo_skills = [s for s in self.skills if s.trigger is None]
         logger.debug(f"Triggered {len(repo_skills)} repository skills: {repo_skills}")
         # Build the workspace context information
-        secret_names = self.get_secret_names()
-        if repo_skills or self.system_message_suffix or secret_names:
+        secret_infos = self.get_secret_infos()
+        if repo_skills or self.system_message_suffix or secret_infos:
             # TODO(test): add a test for this rendering to make sure they work
             formatted_text = render_template(
                 prompt_dir=str(PROMPT_DIR),
                 template_name="system_message_suffix.j2",
                 repo_skills=repo_skills,
                 system_message_suffix=self.system_message_suffix or "",
-                secret_names=secret_names,
+                secret_infos=secret_infos,
             ).strip()
             return formatted_text
         elif self.system_message_suffix and self.system_message_suffix.strip():

{openhands_sdk-1.6.0 → openhands_sdk-1.7.0}/openhands/sdk/context/prompts/prompt.py

@@ -4,7 +4,45 @@ import re
 import sys
 from functools import lru_cache
 
-from jinja2 import Environment, FileSystemBytecodeCache, FileSystemLoader, Template
+from jinja2 import (
+    BaseLoader,
+    Environment,
+    FileSystemBytecodeCache,
+    Template,
+    TemplateNotFound,
+)
+
+
+class FlexibleFileSystemLoader(BaseLoader):
+    """A Jinja2 loader that supports both relative paths (within a base directory)
+    and absolute paths anywhere on the filesystem.
+    """
+
+    def __init__(self, searchpath: str):
+        self.searchpath = os.path.abspath(searchpath)
+
+    def get_source(self, environment, template):  # noqa: ARG002
+        # If template is an absolute path, use it directly
+        if os.path.isabs(template):
+            path = template
+        else:
+            # Otherwise, look for it in the searchpath
+            path = os.path.join(self.searchpath, template)
+
+        if not os.path.exists(path):
+            raise TemplateNotFound(template)
+
+        mtime = os.path.getmtime(path)
+        with open(path, encoding="utf-8") as f:
+            source = f.read()
+
+        def uptodate():
+            try:
+                return os.path.getmtime(path) == mtime
+            except OSError:
+                return False
+
+        return source, path, uptodate
 
 
 def refine(text: str) -> str:
@@ -27,7 +65,7 @@ def _get_env(prompt_dir: str) -> Environment:
     os.makedirs(cache_folder, exist_ok=True)
     bcc = FileSystemBytecodeCache(directory=cache_folder)
     env = Environment(
-        loader=FileSystemLoader(prompt_dir),
+        loader=FlexibleFileSystemLoader(prompt_dir),
         bytecode_cache=bcc,
         autoescape=False,
     )

{openhands_sdk-1.6.0 → openhands_sdk-1.7.0}/openhands/sdk/context/prompts/templates/system_message_suffix.j2

@@ -14,7 +14,7 @@ Please follow them while working.
 
 {{ system_message_suffix }}
 {% endif %}
-{% if secret_names %}
+{% if secret_infos %}
 <CUSTOM_SECRETS>
 ### Credential Access
 * Automatic secret injection: When you reference a registered secret key in your bash command, the secret value will be automatically exported as an environment variable before your command executes.
@@ -25,8 +25,8 @@ Please follow them while working.
 * If it still fails, report it to the user.
 
 You have access to the following environment variables
-{% for secret_name in secret_names %}
-* **${{ secret_name }}**
+{% for secret_info in secret_infos %}
+* **${{ secret_info.name }}**{% if secret_info.description %} - {{ secret_info.description }}{% endif %}
 {% endfor %}
 </CUSTOM_SECRETS>
 {% endif %}

{openhands_sdk-1.6.0 → openhands_sdk-1.7.0}/openhands/sdk/context/skills/__init__.py

@@ -1,6 +1,7 @@
 from openhands.sdk.context.skills.exceptions import SkillValidationError
 from openhands.sdk.context.skills.skill import (
     Skill,
+    load_project_skills,
     load_public_skills,
     load_skills_from_dir,
     load_user_skills,
@@ -21,6 +22,7 @@ __all__ = [
     "SkillKnowledge",
     "load_skills_from_dir",
     "load_user_skills",
+    "load_project_skills",
     "load_public_skills",
     "SkillValidationError",
 ]

{openhands_sdk-1.6.0 → openhands_sdk-1.7.0}/openhands/sdk/context/skills/skill.py

@@ -398,6 +398,67 @@ def load_user_skills() -> list[Skill]:
     return all_skills
 
 
+def load_project_skills(work_dir: str | Path) -> list[Skill]:
+    """Load skills from project-specific directories.
+
+    Searches for skills in {work_dir}/.openhands/skills/ and
+    {work_dir}/.openhands/microagents/ (legacy). Skills from both
+    directories are merged, with skills/ taking precedence for
+    duplicate names.
+
+    Args:
+        work_dir: Path to the project/working directory.
+
+    Returns:
+        List of Skill objects loaded from project directories.
+        Returns empty list if no skills found or loading fails.
+    """
+    if isinstance(work_dir, str):
+        work_dir = Path(work_dir)
+
+    all_skills = []
+    seen_names = set()
+
+    # Load project-specific skills from .openhands/skills and legacy microagents
+    project_skills_dirs = [
+        work_dir / ".openhands" / "skills",
+        work_dir / ".openhands" / "microagents",  # Legacy support
+    ]
+
+    for project_skills_dir in project_skills_dirs:
+        if not project_skills_dir.exists():
+            logger.debug(
+                f"Project skills directory does not exist: {project_skills_dir}"
+            )
+            continue
+
+        try:
+            logger.debug(f"Loading project skills from {project_skills_dir}")
+            repo_skills, knowledge_skills = load_skills_from_dir(project_skills_dir)
+
+            # Merge repo and knowledge skills
+            for skills_dict in [repo_skills, knowledge_skills]:
+                for name, skill in skills_dict.items():
+                    if name not in seen_names:
+                        all_skills.append(skill)
+                        seen_names.add(name)
+                    else:
+                        logger.warning(
+                            f"Skipping duplicate skill '{name}' from "
+                            f"{project_skills_dir}"
+                        )
+
+        except Exception as e:
+            logger.warning(
+                f"Failed to load project skills from {project_skills_dir}: {str(e)}"
+            )
+
+    logger.debug(
+        f"Loaded {len(all_skills)} project skills: {[s.name for s in all_skills]}"
+    )
+    return all_skills
+
+
 # Public skills repository configuration
 PUBLIC_SKILLS_REPO = "https://github.com/OpenHands/skills"
 PUBLIC_SKILLS_BRANCH = "main"

{openhands_sdk-1.6.0 → openhands_sdk-1.7.0}/openhands/sdk/context/view.py

@@ -89,38 +89,72 @@ class View(BaseModel):
             raise ValueError(f"Invalid key type: {type(key)}")
 
     @staticmethod
-    def _enforce_batch_atomicity(
+    def _build_action_batches(
         events: Sequence[Event],
-        forgotten_event_ids: set[EventID],
-    ) -> set[EventID]:
-        """Ensure that if any event in a batch is forgotten, all events in that
-        batch are forgotten.
-
-        This prevents partial batches from being sent to the LLM, which can cause
-        API errors when thinking blocks are separated from their tool calls.
+    ) -> tuple[
+        dict[EventID, list[EventID]], dict[EventID, EventID], dict[EventID, ToolCallID]
+    ]:
+        """Build a map of llm_response_id -> list of ActionEvent IDs.
+
+        Returns:
+            A tuple of:
+            - batches: dict mapping llm_response_id to list of ActionEvent IDs
+            - action_id_to_response_id: dict mapping ActionEvent ID to llm_response_id
+            - action_id_to_tool_call_id: dict mapping ActionEvent ID to tool_call_id
         """
         batches: dict[EventID, list[EventID]] = {}
+        action_id_to_response_id: dict[EventID, EventID] = {}
+        action_id_to_tool_call_id: dict[EventID, ToolCallID] = {}
+
         for event in events:
             if isinstance(event, ActionEvent):
                 llm_response_id = event.llm_response_id
                 if llm_response_id not in batches:
                     batches[llm_response_id] = []
                 batches[llm_response_id].append(event.id)
+                action_id_to_response_id[event.id] = llm_response_id
+                action_id_to_tool_call_id[event.id] = event.tool_call_id
+
+        return batches, action_id_to_response_id, action_id_to_tool_call_id
+
+    @staticmethod
+    def _enforce_batch_atomicity(
+        events: Sequence[Event],
+        removed_event_ids: set[EventID],
+    ) -> set[EventID]:
+        """Ensure that if any ActionEvent in a batch is removed, all ActionEvents
+        in that batch are removed.
+
+        This prevents partial batches from being sent to the LLM, which can cause
+        API errors when thinking blocks are separated from their tool calls.
 
-        updated_forgotten_ids = set(forgotten_event_ids)
+        Args:
+            events: The original list of events
+            removed_event_ids: Set of event IDs that are being removed
+
+        Returns:
+            Updated set of event IDs that should be removed (including all
+            ActionEvents in batches where any ActionEvent was removed)
+        """
+        batches, action_id_to_response_id, _ = View._build_action_batches(events)
+
+        if not batches:
+            return removed_event_ids
+
+        updated_removed_ids = set(removed_event_ids)
 
         for llm_response_id, batch_event_ids in batches.items():
-            # Check if any event in this batch is being forgotten
-            if any(event_id in forgotten_event_ids for event_id in batch_event_ids):
-                # If so, forget all events in this batch
-                updated_forgotten_ids.update(batch_event_ids)
+            # Check if any ActionEvent in this batch is being removed
+            if any(event_id in removed_event_ids for event_id in batch_event_ids):
+                # If so, remove all ActionEvents in this batch
+                updated_removed_ids.update(batch_event_ids)
                 logger.debug(
-                    f"Enforcing batch atomicity: forgetting entire batch "
+                    f"Enforcing batch atomicity: removing entire batch "
                     f"with llm_response_id={llm_response_id} "
                     f"({len(batch_event_ids)} events)"
                 )
 
-        return updated_forgotten_ids
+        return updated_removed_ids
 
     @staticmethod
     def filter_unmatched_tool_calls(
@@ -129,18 +163,47 @@ class View(BaseModel):
         """Filter out unmatched tool call events.
 
         Removes ActionEvents and ObservationEvents that have tool_call_ids
-        but don't have matching pairs.
+        but don't have matching pairs. Also enforces batch atomicity - if any
+        ActionEvent in a batch is filtered out, all ActionEvents in that batch
+        are also filtered out.
         """
         action_tool_call_ids = View._get_action_tool_call_ids(events)
         observation_tool_call_ids = View._get_observation_tool_call_ids(events)
 
-        return [
-            event
-            for event in events
-            if View._should_keep_event(
+        # Build batch info for batch atomicity enforcement
+        _, _, action_id_to_tool_call_id = View._build_action_batches(events)
+
+        # First pass: identify which events would NOT be kept based on matching
+        removed_event_ids: set[EventID] = set()
+        for event in events:
+            if not View._should_keep_event(
                 event, action_tool_call_ids, observation_tool_call_ids
-            )
-        ]
+            ):
+                removed_event_ids.add(event.id)
+
+        # Second pass: enforce batch atomicity for ActionEvents
+        # If any ActionEvent in a batch is removed, all ActionEvents in that
+        # batch should also be removed
+        removed_event_ids = View._enforce_batch_atomicity(events, removed_event_ids)
+
+        # Third pass: also remove ObservationEvents whose ActionEvents were removed
+        # due to batch atomicity
+        tool_call_ids_to_remove: set[ToolCallID] = set()
+        for action_id in removed_event_ids:
+            if action_id in action_id_to_tool_call_id:
+                tool_call_ids_to_remove.add(action_id_to_tool_call_id[action_id])
+
+        # Filter out removed events
+        result = []
+        for event in events:
+            if event.id in removed_event_ids:
+                continue
+            if isinstance(event, ObservationBaseEvent):
+                if event.tool_call_id in tool_call_ids_to_remove:
+                    continue
+            result.append(event)
+
+        return result
 
     @staticmethod
     def _get_action_tool_call_ids(events: list[LLMConvertibleEvent]) -> set[ToolCallID]:

{openhands_sdk-1.6.0 → openhands_sdk-1.7.0}/openhands/sdk/conversation/conversation.py

@@ -1,3 +1,4 @@
+from collections.abc import Mapping
 from pathlib import Path
 from typing import TYPE_CHECKING, Self, overload
 
@@ -7,6 +8,7 @@ from openhands.sdk.conversation.types import (
     ConversationCallbackType,
     ConversationID,
     ConversationTokenCallbackType,
+    StuckDetectionThresholds,
 )
 from openhands.sdk.conversation.visualizer import (
     ConversationVisualizerBase,
@@ -56,6 +58,9 @@ class Conversation:
         token_callbacks: list[ConversationTokenCallbackType] | None = None,
         max_iteration_per_run: int = 500,
         stuck_detection: bool = True,
+        stuck_detection_thresholds: (
+            StuckDetectionThresholds | Mapping[str, int] | None
+        ) = None,
         visualizer: (
             type[ConversationVisualizerBase] | ConversationVisualizerBase | None
         ) = DefaultConversationVisualizer,
@@ -73,6 +78,9 @@ class Conversation:
         token_callbacks: list[ConversationTokenCallbackType] | None = None,
         max_iteration_per_run: int = 500,
         stuck_detection: bool = True,
+        stuck_detection_thresholds: (
+            StuckDetectionThresholds | Mapping[str, int] | None
+        ) = None,
         visualizer: (
             type[ConversationVisualizerBase] | ConversationVisualizerBase | None
         ) = DefaultConversationVisualizer,
@@ -90,6 +98,9 @@ class Conversation:
         token_callbacks: list[ConversationTokenCallbackType] | None = None,
         max_iteration_per_run: int = 500,
         stuck_detection: bool = True,
+        stuck_detection_thresholds: (
+            StuckDetectionThresholds | Mapping[str, int] | None
+        ) = None,
         visualizer: (
             type[ConversationVisualizerBase] | ConversationVisualizerBase | None
         ) = DefaultConversationVisualizer,
@@ -114,6 +125,7 @@ class Conversation:
                 token_callbacks=token_callbacks,
                 max_iteration_per_run=max_iteration_per_run,
                 stuck_detection=stuck_detection,
+                stuck_detection_thresholds=stuck_detection_thresholds,
                 visualizer=visualizer,
                 workspace=workspace,
                 secrets=secrets,
@@ -126,6 +138,7 @@ class Conversation:
             token_callbacks=token_callbacks,
             max_iteration_per_run=max_iteration_per_run,
             stuck_detection=stuck_detection,
+            stuck_detection_thresholds=stuck_detection_thresholds,
             visualizer=visualizer,
             workspace=workspace,
             persistence_dir=persistence_dir,

openhands_sdk-1.7.0/openhands/sdk/conversation/exceptions.py

@@ -0,0 +1,50 @@
+from openhands.sdk.conversation.types import ConversationID
+
+
+ISSUE_URL = "https://github.com/OpenHands/software-agent-sdk/issues/new"
+
+
+class ConversationRunError(RuntimeError):
+    """Raised when a conversation run fails.
+
+    Carries the conversation_id and persistence_dir to make resuming/debugging
+    easier while preserving the original exception via exception chaining.
+    """
+
+    conversation_id: ConversationID
+    persistence_dir: str | None
+    original_exception: BaseException
+
+    def __init__(
+        self,
+        conversation_id: ConversationID,
+        original_exception: BaseException,
+        persistence_dir: str | None = None,
+        message: str | None = None,
+    ) -> None:
+        self.conversation_id = conversation_id
+        self.persistence_dir = persistence_dir
+        self.original_exception = original_exception
+        default_msg = self._build_error_message(
+            conversation_id, original_exception, persistence_dir
+        )
+        super().__init__(message or default_msg)
+
+    @staticmethod
+    def _build_error_message(
+        conversation_id: ConversationID,
+        original_exception: BaseException,
+        persistence_dir: str | None,
+    ) -> str:
+        """Build a detailed error message with debugging information."""
+        lines = [
+            f"Conversation run failed for id={conversation_id}: {original_exception}",
+        ]
+
+        if persistence_dir:
+            lines.append(f"\nConversation logs are stored at: {persistence_dir}")
+            lines.append("\nTo help debug this issue, please file a bug report at:")
+            lines.append(f"  {ISSUE_URL}")
+            lines.append("and attach the conversation logs from the directory above.")
+
+        return "\n".join(lines)

{openhands_sdk-1.6.0 → openhands_sdk-1.7.0}/openhands/sdk/conversation/impl/local_conversation.py

@@ -18,6 +18,7 @@ from openhands.sdk.conversation.types import (
     ConversationCallbackType,
     ConversationID,
     ConversationTokenCallbackType,
+    StuckDetectionThresholds,
 )
 from openhands.sdk.conversation.visualizer import (
     ConversationVisualizerBase,
@@ -66,6 +67,9 @@ class LocalConversation(BaseConversation):
         token_callbacks: list[ConversationTokenCallbackType] | None = None,
         max_iteration_per_run: int = 500,
         stuck_detection: bool = True,
+        stuck_detection_thresholds: (
+            StuckDetectionThresholds | Mapping[str, int] | None
+        ) = None,
         visualizer: (
             type[ConversationVisualizerBase] | ConversationVisualizerBase | None
         ) = DefaultConversationVisualizer,
@@ -92,6 +96,11 @@ class LocalConversation(BaseConversation):
                        - ConversationVisualizerBase instance: Use custom visualizer
                        - None: No visualization
             stuck_detection: Whether to enable stuck detection
+            stuck_detection_thresholds: Optional configuration for stuck detection
+                      thresholds. Can be a StuckDetectionThresholds instance or
+                      a dict with keys: 'action_observation', 'action_error',
+                      'monologue', 'alternating_pattern'. Values are integers
+                      representing the number of repetitions before triggering.
         """
         super().__init__()  # Initialize with span tracking
         # Mark cleanup as initiated as early as possible to avoid races or partially
@@ -159,7 +168,20 @@ class LocalConversation(BaseConversation):
         self.max_iteration_per_run = max_iteration_per_run
 
         # Initialize stuck detector
-        self._stuck_detector = StuckDetector(self._state) if stuck_detection else None
+        if stuck_detection:
+            # Convert dict to StuckDetectionThresholds if needed
+            if isinstance(stuck_detection_thresholds, Mapping):
+                threshold_config = StuckDetectionThresholds(
+                    **stuck_detection_thresholds
+                )
+            else:
+                threshold_config = stuck_detection_thresholds
+            self._stuck_detector = StuckDetector(
+                self._state,
+                thresholds=threshold_config,
+            )
+        else:
+            self._stuck_detector = None
 
         with self._state:
             self.agent.init_state(self._state, on_event=self._on_event)
@@ -349,10 +371,10 @@ class LocalConversation(BaseConversation):
                 )
             )
 
-            # Re-raise with conversation id for better UX; include original traceback
-            raise ConversationRunError(self._state.id, e) from e
-        finally:
-            self._end_observability_span()
+            # Re-raise with conversation id and persistence dir for better UX
+            raise ConversationRunError(
+                self._state.id, e, persistence_dir=self._state.persistence_dir
+            ) from e
 
     def set_confirmation_policy(self, policy: ConfirmationPolicyBase) -> None:
         """Set the confirmation policy and store it in conversation state."""