openhands-sdk 1.45.0__tar.gz → 1.47.0__tar.gz

{openhands_sdk-1.45.0 → openhands_sdk-1.47.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-sdk
-Version: 1.45.0
+Version: 1.47.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.45.0 → openhands_sdk-1.47.0}/openhands/sdk/agent/acp_agent.py

@@ -82,6 +82,7 @@ from openhands.sdk.agent.acp_file_credentials import (
 from openhands.sdk.agent.acp_models import ACPModelInfo
 from openhands.sdk.agent.acp_tracing import ACPTurnTrace
 from openhands.sdk.agent.base import AgentBase
+from openhands.sdk.agent.stream_context import StreamContext
 from openhands.sdk.context import AgentContext
 from openhands.sdk.conversation.state import ConversationExecutionStatus
 from openhands.sdk.credential import (
@@ -1926,6 +1927,10 @@ class ACPAgent(AgentBase):
     _suffix_install_state: str = PrivateAttr(default="unused")
     _installed_suffix: str | None = PrivateAttr(default=None)
     _restart_session_on_next_turn: bool = PrivateAttr(default=False)
+    # Stream identity for the turn in flight; see stream_context.py. Held on
+    # the agent rather than threaded through the finalizers because the ACP
+    # turn already resolves through four of them.
+    _stream: StreamContext | None = PrivateAttr(default=None)
     _resumed_existing_session: bool = PrivateAttr(default=False)
     _file_credential_lifecycles: dict[str, ACPFileCredentialLifecycle] = PrivateAttr(
         default_factory=dict
@@ -3688,7 +3693,13 @@ class ACPAgent(AgentBase):
         # completed turn for eval/remote consumers, matching #2190.
         finish_action = FinishAction(message=response_text)
         tc_id = str(uuid.uuid4())
+        # An ACP turn's streamed text lands here, not in a MessageEvent, so
+        # this is the event that retires the stream's slot.
+        minted: dict[str, Any] = {}
+        if self._stream is not None and (item_id := self._stream.claim()):
+            minted["id"] = item_id
         action_event = ActionEvent(
+            **minted,
             source="agent",
             thought=[],
             reasoning_content=thought_text or None,
@@ -3704,6 +3715,8 @@ class ACPAgent(AgentBase):
             llm_response_id=str(uuid.uuid4()),
         )
         on_event(action_event)
+        if self._stream is not None and minted:
+            self._stream.commit()
         on_event(
             ObservationEvent(
                 observation=FinishObservation.from_text(text=response_text),
@@ -3865,6 +3878,19 @@ class ACPAgent(AgentBase):
         (``LocalConversation.arun``) goes through :meth:`astep`, which
         avoids the cross-thread state-lock deadlock described in #3348.
         """
+        with StreamContext.open(conversation, on_token) as stream:
+            self._stream = stream
+            try:
+                self._step(conversation, on_event, stream.token_callback)
+            finally:
+                self._stream = None
+
+    def _step(
+        self,
+        conversation: LocalConversation,
+        on_event: ConversationCallbackType,
+        on_token: ConversationTokenCallbackType | None = None,
+    ) -> None:
         state = conversation.state
 
         if self._restart_session_on_next_turn:
@@ -3933,6 +3959,8 @@ class ACPAgent(AgentBase):
                         )
                         time.sleep(delay)
                         self._cancel_inflight_tool_calls()
+                        if self._stream is not None:
+                            self._stream.new_attempt()
                         self._reset_client_for_turn(
                             on_token,
                             on_event,
@@ -3963,6 +3991,8 @@ class ACPAgent(AgentBase):
                         )
                         time.sleep(delay)
                         self._cancel_inflight_tool_calls()
+                        if self._stream is not None:
+                            self._stream.new_attempt()
                         self._reset_client_for_turn(
                             on_token,
                             on_event,
@@ -4023,6 +4053,22 @@ class ACPAgent(AgentBase):
         supplied by ``LocalConversation.arun`` is responsible for taking
         the state lock around each individual event.
         """
+        with StreamContext.open(conversation, on_token) as stream:
+            self._stream = stream
+            try:
+                await self._astep(
+                    conversation, on_event, stream.token_callback, prompt_message
+                )
+            finally:
+                self._stream = None
+
+    async def _astep(
+        self,
+        conversation: LocalConversation,
+        on_event: ConversationCallbackType,
+        on_token: ConversationTokenCallbackType | None = None,
+        prompt_message: MessageEvent | None = None,
+    ) -> None:
         state = conversation.state
 
         if self._restart_session_on_next_turn:
@@ -4099,6 +4145,8 @@ class ACPAgent(AgentBase):
                         )
                         await asyncio.sleep(delay)
                         self._cancel_inflight_tool_calls()
+                        if self._stream is not None:
+                            self._stream.new_attempt()
                         self._reset_client_for_turn(
                             on_token,
                             on_event,
@@ -4126,6 +4174,8 @@ class ACPAgent(AgentBase):
                         )
                         await asyncio.sleep(delay)
                         self._cancel_inflight_tool_calls()
+                        if self._stream is not None:
+                            self._stream.new_attempt()
                         self._reset_client_for_turn(
                             on_token,
                             on_event,

{openhands_sdk-1.45.0 → openhands_sdk-1.47.0}/openhands/sdk/agent/agent.py

@@ -4,7 +4,7 @@ import json
 import re
 from collections.abc import Callable
 from dataclasses import dataclass, field
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 from pydantic import PrivateAttr, ValidationError, model_validator
 
@@ -18,6 +18,7 @@ from openhands.sdk.agent.response_dispatch import (
     ResponseDispatchMixin,
     classify_response,
 )
+from openhands.sdk.agent.stream_context import StreamContext
 from openhands.sdk.agent.utils import (
     amake_llm_completion,
     aprepare_llm_messages,
@@ -639,6 +640,15 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
         conversation: LocalConversation,
         on_event: ConversationCallbackType,
         on_token: ConversationTokenCallbackType | None = None,
+    ) -> None:
+        with StreamContext.open(conversation, on_token) as stream:
+            self._step(conversation, on_event, stream)
+
+    def _step(
+        self,
+        conversation: LocalConversation,
+        on_event: ConversationCallbackType,
+        stream: StreamContext,
     ) -> None:
         state = conversation.state
         # Check for pending actions (implicit confirmation)
@@ -721,7 +731,7 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
                 self.llm,
                 _messages,
                 tools=list(self.tools_map.values()),
-                on_token=on_token,
+                on_token=stream.token_callback,
                 call_context=call_context,
             )
         except FunctionCallValidationError as e:
@@ -807,11 +817,11 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
         match response_type:
             case LLMResponseType.TOOL_CALLS:
                 self._handle_tool_calls(
-                    message, llm_response, conversation, state, on_event
+                    message, llm_response, conversation, state, on_event, stream
                 )
             case LLMResponseType.CONTENT:
                 self._handle_content_response(
-                    message, llm_response, conversation, state, on_event
+                    message, llm_response, conversation, state, on_event, stream
                 )
             case LLMResponseType.REASONING_ONLY | LLMResponseType.EMPTY:
                 self._handle_no_content_response(
@@ -820,6 +830,7 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
                     conversation,
                     state,
                     on_event,
+                    stream,
                     response_type=response_type,
                 )
 
@@ -839,6 +850,15 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
         parallel calls with :func:`asyncio.gather`, keeping the event
         loop responsive during blocking tool I/O.
         """
+        with StreamContext.open(conversation, on_token) as stream:
+            await self._astep(conversation, on_event, stream)
+
+    async def _astep(
+        self,
+        conversation: LocalConversation,
+        on_event: ConversationCallbackType,
+        stream: StreamContext,
+    ) -> None:
         state = conversation.state
         # Check for pending actions (implicit confirmation)
         pending_actions = ConversationState.get_unmatched_actions(state.active_branch())
@@ -918,7 +938,7 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
                     self.llm,
                     _messages,
                     tools=list(self.tools_map.values()),
-                    on_token=on_token,
+                    on_token=stream.token_callback,
                     call_context=call_context,
                 )
         except FunctionCallValidationError as e:
@@ -1006,11 +1026,11 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
         match response_type:
             case LLMResponseType.TOOL_CALLS:
                 await self._ahandle_tool_calls(
-                    message, llm_response, conversation, state, on_event
+                    message, llm_response, conversation, state, on_event, stream
                 )
             case LLMResponseType.CONTENT:
                 self._handle_content_response(
-                    message, llm_response, conversation, state, on_event
+                    message, llm_response, conversation, state, on_event, stream
                 )
             case LLMResponseType.REASONING_ONLY | LLMResponseType.EMPTY:
                 self._handle_no_content_response(
@@ -1019,6 +1039,7 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
                     conversation,
                     state,
                     on_event,
+                    stream,
                     response_type=response_type,
                 )
 
@@ -1153,6 +1174,7 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
         reasoning_content: str | None = None,
         thinking_blocks: list[ThinkingBlock | RedactedThinkingBlock] | None = None,
         responses_reasoning_item: ReasoningItemModel | None = None,
+        stream: StreamContext | None = None,
     ) -> None:
         try:
             json.loads(tool_call.arguments)
@@ -1168,7 +1190,11 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
                 }
             )
 
+        minted: dict[str, Any] = {}
+        if stream is not None and (item_id := stream.claim()):
+            minted["id"] = item_id
         tc_event = ActionEvent(
+            **minted,
             source="agent",
             thought=thought or [],
             reasoning_content=reasoning_content,
@@ -1181,6 +1207,8 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
             action=None,
         )
         on_event(tc_event)
+        if stream is not None and minted:
+            stream.commit()
         error_event = AgentErrorEvent(
             error=error,
             tool_name=tool_name,
@@ -1207,6 +1235,7 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
         reasoning_content: str | None = None,
         thinking_blocks: list[ThinkingBlock | RedactedThinkingBlock] | None = None,
         responses_reasoning_item: ReasoningItemModel | None = None,
+        stream: StreamContext | None = None,
     ) -> ActionEvent | None:
         """Converts a tool call into an ActionEvent, validating arguments.
 
@@ -1249,6 +1278,7 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
                     reasoning_content=reasoning_content,
                     thinking_blocks=thinking_blocks,
                     responses_reasoning_item=responses_reasoning_item,
+                    stream=stream,
                 )
                 return
 
@@ -1311,11 +1341,19 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
                 reasoning_content=reasoning_content,
                 thinking_blocks=thinking_blocks,
                 responses_reasoning_item=responses_reasoning_item,
+                stream=stream,
             )
             return
 
-        # Create initial action event
+        # Create initial action event. Claimed here rather than at the call
+        # site so an error path, which never builds this event, leaves the slot
+        # open for the abort in StreamContext.__exit__.
+        minted: dict[str, Any] = {}
+        if stream is not None and (item_id := stream.claim()):
+            minted["id"] = item_id
+
         action_event = ActionEvent(
+            **minted,
             action=action,
             thought=thought or [],
             reasoning_content=reasoning_content,
@@ -1339,6 +1377,8 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
                 )
 
         on_event(action_event)
+        if stream is not None and minted:
+            stream.commit()
         return action_event
 
     def _execute_action_event(

{openhands_sdk-1.45.0 → openhands_sdk-1.47.0}/openhands/sdk/agent/response_dispatch.py

@@ -9,8 +9,9 @@ Contains:
 from __future__ import annotations
 
 from enum import StrEnum
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
+from openhands.sdk.agent.stream_context import StreamContext
 from openhands.sdk.conversation.state import ConversationExecutionStatus
 from openhands.sdk.event import MessageEvent
 from openhands.sdk.llm import LLMResponse, Message, TextContent
@@ -106,6 +107,7 @@ class ResponseDispatchMixin:
                 list[ThinkingBlock | RedactedThinkingBlock] | None
             ) = None,
             responses_reasoning_item: ReasoningItemModel | None = None,
+            stream: StreamContext | None = None,
         ) -> ActionEvent | None: ...
 
         def _execute_actions(
@@ -147,6 +149,7 @@ class ResponseDispatchMixin:
         conversation: LocalConversation,
         state: ConversationState,
         on_event: ConversationCallbackType,
+        stream: StreamContext | None = None,
     ) -> None:
         """Handle LLM response containing tool calls."""
         if not all(isinstance(c, TextContent) for c in message.content):
@@ -172,6 +175,9 @@ class ResponseDispatchMixin:
                 responses_reasoning_item=(
                     message.responses_reasoning_item if i == 0 else None
                 ),
+                # The streamed text is this action's thought, so the first
+                # action event is what retires the slot.
+                stream=stream if i == 0 else None,
             )
             if action_event is None:
                 continue
@@ -192,6 +198,7 @@ class ResponseDispatchMixin:
         conversation: LocalConversation,
         state: ConversationState,
         on_event: ConversationCallbackType,
+        stream: StreamContext | None = None,
     ) -> None:
         """Async variant of :meth:`_handle_tool_calls`.
 
@@ -222,6 +229,9 @@ class ResponseDispatchMixin:
                 responses_reasoning_item=(
                     message.responses_reasoning_item if i == 0 else None
                 ),
+                # The streamed text is this action's thought, so the first
+                # action event is what retires the slot.
+                stream=stream if i == 0 else None,
             )
             if action_event is None:
                 continue
@@ -242,9 +252,10 @@ class ResponseDispatchMixin:
         conversation: LocalConversation,
         state: ConversationState,
         on_event: ConversationCallbackType,
+        stream: StreamContext | None = None,
     ) -> None:
         """Handle LLM response with text content — finishes conversation."""
-        self._emit_message_event(message, llm_response, conversation, on_event)
+        self._emit_message_event(message, llm_response, conversation, on_event, stream)
         self._maybe_emit_vllm_tokens(llm_response, on_event)
         logger.debug("LLM produced a message response - awaits user input")
         state.execution_status = ConversationExecutionStatus.FINISHED
@@ -256,6 +267,7 @@ class ResponseDispatchMixin:
         conversation: LocalConversation,
         state: ConversationState,  # noqa: ARG002
         on_event: ConversationCallbackType,
+        stream: StreamContext | None = None,
         *,
         response_type: LLMResponseType,
     ) -> None:
@@ -267,7 +279,7 @@ class ResponseDispatchMixin:
         """
         if response_type is LLMResponseType.EMPTY:
             logger.warning("LLM produced empty response - continuing agent loop")
-        self._emit_message_event(message, llm_response, conversation, on_event)
+        self._emit_message_event(message, llm_response, conversation, on_event, stream)
         self._maybe_emit_vllm_tokens(llm_response, on_event)
         self._send_corrective_nudge(on_event)
 
@@ -277,9 +289,18 @@ class ResponseDispatchMixin:
         llm_response: LLMResponse,
         conversation: LocalConversation,
         on_event: ConversationCallbackType,
+        stream: StreamContext | None = None,
     ) -> MessageEvent:
-        """Create and emit a MessageEvent, running critic if configured."""
+        """Create and emit a MessageEvent, running critic if configured.
+
+        The message carries the id its own stream minted, so a client holding
+        an open slot retires it on ``frame.event.id == slot.item_id``.
+        """
+        minted: dict[str, Any] = {}
+        if stream is not None and (item_id := stream.claim()):
+            minted["id"] = item_id
         msg_event = MessageEvent(
+            **minted,
             source="agent",
             llm_message=self._mask_secrets(message, conversation),
             llm_response_id=llm_response.id,
@@ -291,6 +312,10 @@ class ResponseDispatchMixin:
                     update={"critic_result": critic_result}
                 )
         on_event(msg_event)
+        # Retired only now: on_event can raise while persisting, and a slot
+        # retired before that leaves the client holding it open forever.
+        if stream is not None and minted:
+            stream.commit()
         return msg_event
 
     @staticmethod