openhands-sdk 1.55.1__tar.gz → 1.57.0__tar.gz

{openhands_sdk-1.55.1 → openhands_sdk-1.57.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-sdk
-Version: 1.55.1
+Version: 1.57.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
@@ -15,7 +15,7 @@ Requires-Dist: filelock>=3.20.1
 Requires-Dist: httpx[socks]>=0.28.1
 Requires-Dist: jsonschema>=4.23.0
 Requires-Dist: joserfc>=1.7.5
-Requires-Dist: litellm>=1.93.0
+Requires-Dist: litellm<1.106,>=1.93.0
 Requires-Dist: pillow>=12.3.0
 Requires-Dist: pydantic>=2.13.5
 Requires-Dist: python-frontmatter>=1.3.0

{openhands_sdk-1.55.1 → openhands_sdk-1.57.0}/openhands/sdk/agent/agent.py

@@ -625,6 +625,10 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
         preset = self._prompt_preset or PromptPreset.DEFAULT
         return create_registry(preset).build(ctx).dynamic
 
+    @staticmethod
+    def _mark_conversation_finished(state: ConversationState) -> None:
+        state.execution_status = ConversationExecutionStatus.FINISHED
+
     def _execute_actions(
         self,
         conversation: LocalConversation,
@@ -648,11 +652,7 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
             check_iterative_refinement=lambda ae: (
                 self._check_iterative_refinement(conversation, ae)
             ),
-            mark_finished=lambda: setattr(
-                state,
-                "execution_status",
-                ConversationExecutionStatus.FINISHED,
-            ),
+            mark_finished=lambda: self._mark_conversation_finished(state),
         )
 
     async def _aexecute_actions(
@@ -683,11 +683,7 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
             check_iterative_refinement=lambda ae: (
                 self._check_iterative_refinement(conversation, ae)
             ),
-            mark_finished=lambda: setattr(
-                state,
-                "execution_status",
-                ConversationExecutionStatus.FINISHED,
-            ),
+            mark_finished=lambda: self._mark_conversation_finished(state),
         )
 
     @observe(name="agent.step", ignore_inputs=["state", "on_event"])
@@ -1594,7 +1590,7 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
             condenser_config = self.condenser.model_dump(
                 exclude={"llm"}, exclude_none=True
             )
-            condenser_llm_obj = getattr(self.condenser, "llm", None)
+            condenser_llm_obj = self.condenser.get_llm()
             condenser_llm = (
                 condenser_llm_obj.model if condenser_llm_obj is not None else "N/A"
             )

{openhands_sdk-1.55.1 → openhands_sdk-1.57.0}/openhands/sdk/agent/base.py

@@ -33,7 +33,6 @@ from openhands.sdk.mcp.client import MCPClient
 from openhands.sdk.mcp.config import MCPServer
 from openhands.sdk.mcp.tool import MCPToolDefinition, MCPToolExecutor
 from openhands.sdk.tool import (
-    BROWSER_TOOL_NAME,
     BUILT_IN_TOOL_CLASSES,
     BUILT_IN_TOOLS,
     Tool,
@@ -45,7 +44,6 @@ from openhands.sdk.tool.builtins.vision_inspect import (
     VisionInspectTool,
     has_vision_profile_available,
 )
-from openhands.sdk.utils.deprecation import warn_deprecated
 from openhands.sdk.utils.models import DiscriminatedUnionMixin
 from openhands.sdk.utils.path import get_user_persistence_dir
 
@@ -268,21 +266,11 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
 
     @field_validator("system_prompt_kwargs")
     @classmethod
-    def _warn_deprecated_enable_browser(
+    def _drop_retired_enable_browser(
         cls, value: dict[str, object]
     ) -> dict[str, object]:
-        if "enable_browser" in value:
-            warn_deprecated(
-                "system_prompt_kwargs['enable_browser']",
-                deprecated_in="1.51.0",
-                removed_in="1.56.0",
-                details=(
-                    "Browser guidance now comes from the loaded browser tools; "
-                    "only custom Jinja templates still read this kwarg."
-                ),
-                stacklevel=5,
-            )
-        return value
+        """Old saved conversations may still carry this retired prompt flag."""
+        return {key: item for key, item in value.items() if key != "enable_browser"}
 
     condenser: CondenserBase | None = Field(
         default=None,
@@ -378,15 +366,10 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
         # own Jinja template; everything else (incl. custom policies) uses the registry.
         preset = self._prompt_preset
         if preset is None:
-            # Deprecated kwarg, kept until 1.56.0 for templates that branch on it.
-            template_kwargs = {
-                "enable_browser": any(t.name == BROWSER_TOOL_NAME for t in self.tools),
-                **self._resolved_template_kwargs(),
-            }
             return render_template(
                 prompt_dir=self.prompt_dir,
                 template_name=self.system_prompt_filename,
-                **template_kwargs,
+                **self._resolved_template_kwargs(),
             )
 
         return create_registry(preset).build(self._build_prompt_context()).static
@@ -421,9 +404,7 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
             "model_family" not in template_kwargs
             or "model_variant" not in template_kwargs
         ):
-            spec = get_model_prompt_spec(
-                self.llm.model, getattr(self.llm, "model_canonical_name", None)
-            )
+            spec = get_model_prompt_spec(self.llm.model, self.llm.model_canonical_name)
             if "model_family" not in template_kwargs and spec.family:
                 template_kwargs["model_family"] = spec.family
             if "model_variant" not in template_kwargs and spec.variant:

{openhands_sdk-1.55.1 → openhands_sdk-1.57.0}/openhands/sdk/context/condenser/base.py

@@ -29,6 +29,10 @@ class CondenserBase(DiscriminatedUnionMixin, ABC):
     step the condenser will use that condensation event to produce a new `View`.
     """
 
+    def get_llm(self) -> LLM | None:
+        """The LLM used by the condenser, if any."""
+        return None
+
     @abstractmethod
     def condense(self, view: View, agent_llm: LLM | None = None) -> View | Condensation:
         """Condense a sequence of events into a potentially smaller list.

{openhands_sdk-1.55.1 → openhands_sdk-1.57.0}/openhands/sdk/context/condenser/llm_summarizing_condenser.py

@@ -112,6 +112,10 @@ class LLMSummarizingCondenser(RollingCondenser):
     def handles_condensation_requests(self) -> bool:
         return True
 
+    def get_llm(self) -> LLM | None:
+        """The LLM used by the condenser, if any."""
+        return self.llm
+
     def _effective_max_tokens(self, agent_llm: LLM | None) -> int | None:
         """Return the effective token cap that triggers token-based condensation.
 

{openhands_sdk-1.55.1 → openhands_sdk-1.57.0}/openhands/sdk/conversation/base.py

@@ -2,7 +2,7 @@ import contextlib
 from abc import ABC, abstractmethod
 from collections.abc import AsyncIterator, Iterable, Mapping
 from pathlib import Path
-from typing import TYPE_CHECKING, Protocol, TypeVar, cast
+from typing import TYPE_CHECKING, Any, Protocol, TypeVar, cast
 
 from openhands.sdk.conversation.conversation_stats import ConversationStats
 from openhands.sdk.conversation.events_list_base import EventsListBase
@@ -45,6 +45,7 @@ def _conversation_tag_attributes(
 
 if TYPE_CHECKING:
     from openhands.sdk.agent.base import AgentBase
+    from openhands.sdk.conversation.secret_registry import SecretRegistry
     from openhands.sdk.conversation.state import ConversationExecutionStatus
     from openhands.sdk.hooks import HookConfig
 
@@ -122,6 +123,11 @@ class ConversationStateProtocol(Protocol):
         """The hook configuration for this conversation."""
         ...
 
+    @property
+    def secret_registry(self) -> "SecretRegistry":
+        """The secret registry for this conversation."""
+        ...
+
 
 class BaseConversation(ABC):
     """Abstract base class for conversation implementations.
@@ -131,9 +137,16 @@ class BaseConversation(ABC):
     exchange, execution control, and state management.
     """
 
+    _cleanup_initiated: bool = False
+    _cleanup_complete: bool = False
+    _hook_processor: Any = None
+
     def __init__(self) -> None:
         """Initialize the base conversation with span tracking."""
         self._span_ended = False
+        self._cleanup_initiated = False
+        self._cleanup_complete = False
+        self._hook_processor = None
         # Owned root span. The ``observe`` decorator looks up this attribute
         # (by name ``_observability_root_span``) on ``self`` at every entry
         # point and re-attaches it via ``Laminar.use_span`` so that nested
@@ -142,6 +155,21 @@ class BaseConversation(ABC):
         # that constructed the conversation.
         self._observability_root_span: RootSpan | None = None
 
+    @property
+    def cleanup_initiated(self) -> bool:
+        """Whether conversation cleanup has started."""
+        return self._cleanup_initiated
+
+    @property
+    def cleanup_complete(self) -> bool:
+        """Whether conversation cleanup has finished."""
+        return self._cleanup_complete
+
+    @property
+    def hook_processor(self) -> Any:
+        """The active hook processor for the conversation, if configured."""
+        return self._hook_processor
+
     def _start_observability_span(
         self,
         session_id: str,

{openhands_sdk-1.55.1 → openhands_sdk-1.57.0}/openhands/sdk/conversation/impl/local_conversation.py

@@ -177,6 +177,16 @@ def _copy_event_for_fork(event: Event) -> Event:
     return Event.model_validate_json(event.model_dump_json(exclude_none=True))
 
 
+def _same_llm_config(a: LLM, b: LLM) -> bool:
+    """Return whether two LLMs serialize to the same config, secrets included."""
+    if a is b:
+        return True
+    context = {"expose_secrets": True}
+    return a.model_dump(mode="json", context=context) == b.model_dump(
+        mode="json", context=context
+    )
+
+
 class LocalConversation(BaseConversation):
     agent: AgentBase
     workspace: LocalWorkspace
@@ -528,8 +538,8 @@ class LocalConversation(BaseConversation):
         # Idempotent with the create_request() lift; lower priority than
         # request.secrets (below). On resume, fill-if-absent so a persisted
         # value is never downgraded (or lost to redacted/no-cipher serialization).
-        if (ctx := getattr(self.agent, "agent_context", None)) is not None:
-            ctx_secrets = getattr(ctx, "secrets", None)
+        if self.agent is not None and self.agent.agent_context is not None:
+            ctx_secrets = self.agent.agent_context.secrets
             if ctx_secrets:
                 existing_sources = self._state.secret_registry.secret_sources
                 fill_secrets: dict[str, SecretValue] = {}
@@ -1664,18 +1674,31 @@ class LocalConversation(BaseConversation):
         """Swap the agent's LLM to the given object.
 
         The caller owns ``llm.usage_id``; it is the registry key. If an
-        entry with that key already exists, the cached LLM is reused and
-        the passed ``llm`` is dropped — matching the rest of the
-        registry's "first-write-wins" contract.
+        entry with that key already exists and has the same config, the
+        cached LLM is reused. If its config differs (e.g. ``default``, which
+        agent initialization registers, posted with another model), the
+        passed ``llm`` replaces the entry and takes over the metrics already
+        recorded under that ``usage_id``.
 
         Args:
             llm: LLM to install on the agent.
         """
+        usage_id = llm.usage_id
         try:
-            new_llm = self.llm_registry.get(llm.usage_id)
+            registered = self.llm_registry.get(usage_id)
         except KeyError:
+            registered = None
+        if registered is not None and _same_llm_config(registered, llm):
+            new_llm = registered
+        else:
             new_llm = create_subscription_llm_from_config(llm)
+            if registered is not None:
+                self.llm_registry.remove(usage_id)
             self.llm_registry.add(new_llm)
+            if registered is not None:
+                # Keep one metrics object per usage_id: ConversationStats
+                # tracks the registered LLM's, so accrued usage is retained.
+                new_llm.restore_metrics(registered.metrics)
         # A switch_llm tool runs on a worker thread while run()/arun() holds the
         # state lock across the agent step on another thread, blocked awaiting
         # this very tool. Re-acquiring _state here would deadlock, so skip it:
@@ -1760,7 +1783,8 @@ class LocalConversation(BaseConversation):
 
         Raises:
             ValueError: If the conversation's agent is not an :class:`ACPAgent`,
-                or (for a live switch) the provider does not support runtime
+                if ``model`` is empty or whitespace-only (live or not), or
+                (for a live switch) the provider does not support runtime
                 model switching, or the ACP server rejects the switch.
             TimeoutError: If a live switch's ``session/set_model`` round-trip
                 exceeds ``acp_prompt_timeout`` seconds.
@@ -1769,6 +1793,10 @@ class LocalConversation(BaseConversation):
             raise ValueError(
                 "switch_acp_model is only supported for ACP conversations."
             )
+        # Check here, not only in set_acp_model: the pre-run path below skips
+        # that call and would persist a blank model unchecked.
+        if not model or not model.strip():
+            raise ValueError("model must be a non-empty string")
         with self._state:
             # With a live session, perform the protocol switch first; if it
             # fails we leave the persisted state untouched. Without one (pre
@@ -2818,9 +2846,9 @@ class LocalConversation(BaseConversation):
 
     def close(self) -> None:
         """Close the conversation and clean up all tool executors."""
-        if getattr(self, "_cleanup_complete", False):
+        if self._cleanup_complete:
             return
-        first_attempt = not getattr(self, "_cleanup_initiated", False)
+        first_attempt = not self._cleanup_initiated
         if first_attempt:
             self._cleanup_initiated = True
 
@@ -2835,7 +2863,7 @@ class LocalConversation(BaseConversation):
                 logger.debug(f"Could not register accumulated cost: {e}")
 
             logger.debug("Closing conversation and cleaning up tool executors")
-            hook_processor = getattr(self, "_hook_processor", None)
+            hook_processor = self._hook_processor
             if hook_processor is not None:
                 hook_processor.run_session_end()
             try:

{openhands_sdk-1.55.1 → openhands_sdk-1.57.0}/openhands/sdk/conversation/impl/remote_conversation.py

@@ -13,6 +13,7 @@ from urllib.parse import urlparse
 
 import httpx
 import websockets
+from litellm.types.utils import Delta, ModelResponseStream, StreamingChoices
 from websockets.exceptions import ConnectionClosed
 
 from openhands.sdk.agent.base import AgentBase
@@ -28,12 +29,16 @@ from openhands.sdk.conversation.exceptions import (
     ConversationRunError,
     WebSocketConnectionError,
 )
-from openhands.sdk.conversation.secret_registry import SecretValue
+from openhands.sdk.conversation.secret_registry import (
+    SecretRegistry,
+    SecretValue,
+)
 from openhands.sdk.conversation.state import ConversationExecutionStatus
 from openhands.sdk.conversation.title_utils import generate_conversation_title
 from openhands.sdk.conversation.types import (
     ConversationCallbackType,
     ConversationID,
+    ConversationTokenCallbackType,
     StuckDetectionThresholds,
     TraceMetadataValue,
 )
@@ -49,6 +54,7 @@ from openhands.sdk.event.conversation_state import (
     ConversationStateUpdateEvent,
 )
 from openhands.sdk.event.llm_completion_log import LLMCompletionLogEvent
+from openhands.sdk.event.streaming_delta import StreamingDeltaEvent
 from openhands.sdk.event.types import EventID
 from openhands.sdk.hooks import HookConfig
 from openhands.sdk.llm import LLM, Message, TextContent
@@ -92,6 +98,26 @@ def _validate_remote_agent(agent_data: dict) -> AgentBase:
     return AgentBase.model_validate(agent_data)
 
 
+def _token_delta_callback(
+    token_callbacks: list[ConversationTokenCallbackType],
+) -> ConversationCallbackType:
+    """Hand each streamed delta from the events socket to the token callbacks."""
+    on_token = BaseConversation.compose_callbacks(token_callbacks)
+
+    def callback(event: Event) -> None:
+        if isinstance(event, StreamingDeltaEvent):
+            delta = Delta(
+                content=event.content, reasoning_content=event.reasoning_content
+            )
+            on_token(
+                ModelResponseStream(
+                    id=event.id, choices=[StreamingChoices(index=0, delta=delta)]
+                )
+            )
+
+    return callback
+
+
 def _restore_tool_registrations(tool_module_qualnames: Mapping[str, str]) -> None:
     """Import the tool modules persisted with a remote conversation."""
     for tool_name, module_qualname in tool_module_qualnames.items():
@@ -493,9 +519,16 @@ class RemoteEventsList(EventsListBase):
         return len(self._cached_events) - 1
 
     def create_default_callback(self) -> ConversationCallbackType:
-        """Create a default callback that adds events to this list."""
+        """Create a default callback that adds events to this list.
+
+        Streamed ``StreamingDeltaEvent`` frames are transient: the server never
+        stores them, so they reach the other callbacks but stay out of this
+        list, which keeps matching the server's event log.
+        """
 
         def callback(event: Event) -> None:
+            if isinstance(event, StreamingDeltaEvent):
+                return
             self.add_event(event)
 
         return callback
@@ -689,6 +722,15 @@ class RemoteState(ConversationStateProtocol):
             return HookConfig.model_validate(hook_config_data)
         return None
 
+    @property
+    def secret_registry(self) -> SecretRegistry:
+        """The secret registry for this conversation."""
+        info = self._get_conversation_info()
+        secret_registry_data = info.get("secret_registry")
+        if secret_registry_data is not None:
+            return SecretRegistry.model_validate(secret_registry_data)
+        return SecretRegistry()
+
     def model_dump(self, **_kwargs):
         """Get a dictionary representation of the remote state."""
         info = self._get_conversation_info()
@@ -746,6 +788,7 @@ class RemoteConversation(BaseConversation):
         observability_tags: list[str] | None = None,
         observability_span_name: str = "conversation",
         observability_parent_span_context: str | None = None,
+        token_callbacks: list[ConversationTokenCallbackType] | None = None,
         **_: object,
     ) -> None:
         """Remote conversation proxy that talks to an agent server.
@@ -783,7 +826,10 @@ class RemoteConversation(BaseConversation):
             observability_tags: Optional root span tags for observability backends.
             observability_span_name: Optional child span name for observability
                       backends. The root span remains named "conversation".
+            token_callbacks: Optional callbacks invoked with each streamed token
+                      delta the server sends (agent LLM with ``stream=True``).
         """
+        super().__init__()
         observability_metadata = merge_observability_metadata(observability_metadata)
         observability_parent_span_context = (
             observability_parent_span_context
@@ -920,6 +966,7 @@ class RemoteConversation(BaseConversation):
             workspace=workspace,
             conversation_id=conversation_id,
             callbacks=callbacks,
+            token_callbacks=token_callbacks,
             max_iteration_per_run=max_iteration_per_run,
             client_tools=[*(client_tools or []), *attached_client_tools],
             visualizer=visualizer,
@@ -1060,10 +1107,13 @@ class RemoteConversation(BaseConversation):
         visualizer: (
             type[ConversationVisualizerBase] | ConversationVisualizerBase | None
         ),
+        token_callbacks: list[ConversationTokenCallbackType] | None = None,
     ) -> None:
         super().__init__()  # Initialize base class with span tracking
         self.agent = agent
         self._callbacks = callbacks or []
+        if token_callbacks:
+            self._callbacks.append(_token_delta_callback(token_callbacks))
         self.max_iteration_per_run = max_iteration_per_run
         self.workspace = workspace
         self._client = workspace.client
@@ -1166,13 +1216,40 @@ class RemoteConversation(BaseConversation):
         all_callbacks = self._callbacks + [run_complete_callback]
         composed_callback = BaseConversation.compose_callbacks(all_callbacks)
 
+        # Track which events the callbacks have seen, so that events the
+        # server recorded while the socket was reconnecting (and that only
+        # reached the cache through REST reconciliation) can be replayed to
+        # them once, without the live socket delivering them a second time.
+        delivered_ids: set[str] = set()
+        replayed_ids: set[str] = set()
+
+        def socket_callback(event: Event) -> None:
+            if event.id in replayed_ids:
+                replayed_ids.discard(event.id)
+                return
+            delivered_ids.add(event.id)
+            composed_callback(event)
+
+        def replay_missed_events() -> None:
+            self._state.events.reconcile()
+            replayed_ids.clear()
+            for event in self._state.events[:]:
+                if event.id in delivered_ids:
+                    continue
+                delivered_ids.add(event.id)
+                replayed_ids.add(event.id)
+                try:
+                    composed_callback(event)
+                except Exception:
+                    logger.exception("ws_replay_callback_error", stack_info=True)
+
         # Initialize WebSocket client for callbacks
         self._ws_client = WebSocketCallbackClient(
             host=self.workspace.host,
             conversation_id=str(self._id),
-            callback=composed_callback,
+            callback=socket_callback,
             api_key=self.workspace.api_key,
-            on_reconnect=self._state.events.reconcile,
+            on_reconnect=replay_missed_events,
         )
         self._ws_client.start()
 
@@ -1210,6 +1287,9 @@ class RemoteConversation(BaseConversation):
         # were emitted between the initial REST sync and WebSocket subscription.
         # This is the "reconciliation" part of the subscription handshake.
         self._state.events.reconcile()
+        # Callbacks are not replayed history: only events recorded after this
+        # point and missed by the socket are replayed on reconnect.
+        delivered_ids.update(event.id for event in self._state.events[:])
 
     def _create_llm_completion_log_callback(self) -> ConversationCallbackType:
         """Create a callback that writes LLM completion logs to client filesystem."""
@@ -1850,52 +1930,55 @@ class RemoteConversation(BaseConversation):
         The workspace owns the client and will close it during its own cleanup.
         Closing it here would prevent the workspace from making cleanup API calls.
         """
-        if self._cleanup_initiated:
+        if self._cleanup_complete:
             return
-        self._cleanup_initiated = True
-
-        # Best-effort: hand the accumulated LLM cost to the workspace so it can
-        # be included in the automation completion callback. Only read cached
-        # state — close() also runs on the failure path, where a live fetch
-        # could block until timeout against an agent server that is already gone.
-        # The cache tracks this run: the agent server streams a "stats" update
-        # after every LLM response (EventService._setup_stats_streaming), so it
-        # holds the run's spend even on the failure path, which wakes run() from
-        # a per-field ERROR/STUCK update before the post-run full-state snapshot.
-        try:
-            cached = self._state._cached_state
-            # Require an actual "stats" entry: a cache built only from partial
-            # field updates — e.g. the subscribe-time push for a service with no
-            # live conversation — would otherwise yield 0.0 and record a run as
-            # free when its cost is really just unknown.
-            if cached is not None and "stats" in cached:
-                cost = self._state.stats.get_combined_metrics().accumulated_cost
-                self.workspace.register_cost(cost)
-        except Exception as e:
-            logger.debug(f"Could not register accumulated cost: {e}")
-
-        # SessionEnd hooks are executed server-side (via hook_config in payload).
-        try:
-            # Stop WebSocket client if it exists
-            if self._ws_client:
-                self._ws_client.stop()
-                self._ws_client = None
-        except Exception:
-            pass
+        first_attempt = not self._cleanup_initiated
+        if first_attempt:
+            self._cleanup_initiated = True
+
+            # Best-effort: hand the accumulated LLM cost to the workspace so it can
+            # be included in the automation completion callback. Only read cached
+            # state — close() also runs on the failure path, where a live fetch
+            # could block until timeout against an agent server that is already gone.
+            # The cache tracks this run: the agent server streams a "stats" update
+            # after every LLM response (EventService._setup_stats_streaming), so it
+            # holds the run's spend even on the failure path, which wakes run() from
+            # a per-field ERROR/STUCK update before the post-run full-state snapshot.
+            try:
+                cached = self._state._cached_state
+                # Require an actual "stats" entry: a cache built only from partial
+                # field updates — e.g. the subscribe-time push for a service with no
+                # live conversation — would otherwise yield 0.0 and record a run as
+                # free when its cost is really just unknown.
+                if cached is not None and "stats" in cached:
+                    cost = self._state.stats.get_combined_metrics().accumulated_cost
+                    self.workspace.register_cost(cost)
+            except Exception as e:
+                logger.debug(f"Could not register accumulated cost: {e}")
 
-        self._end_observability_span()
-        if self.delete_on_close:
+            # SessionEnd hooks are executed server-side (via hook_config in payload).
             try:
-                # trigger server-side delete_conversation to release resources
-                # like tmux sessions
-                _send_request(
-                    self._client,
-                    "DELETE",
-                    f"{CONVERSATIONS_PATH}/{self.id}",
-                )
+                # Stop WebSocket client if it exists
+                if self._ws_client:
+                    self._ws_client.stop()
+                    self._ws_client = None
             except Exception:
                 pass
 
+            self._end_observability_span()
+            if self.delete_on_close:
+                try:
+                    # trigger server-side delete_conversation to release resources
+                    # like tmux sessions
+                    _send_request(
+                        self._client,
+                        "DELETE",
+                        f"{CONVERSATIONS_PATH}/{self.id}",
+                    )
+                except Exception:
+                    pass
+        self._cleanup_complete = True
+
     def __del__(self) -> None:
         try:
             self.close()