openhands-sdk 1.46.0__tar.gz → 1.48.0__tar.gz

{openhands_sdk-1.46.0 → openhands_sdk-1.48.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-sdk
-Version: 1.46.0
+Version: 1.48.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.46.0 → openhands_sdk-1.48.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
@@ -1957,7 +1962,7 @@ class ACPAgent(AgentBase):
             self._file_credential_bindings[secret_name] = binding
 
     def restart_for_updated_credentials(self, secret_names: Collection[str]) -> None:
-        configured = {spec.secret_name for spec in self.acp_file_secrets}
+        configured = {spec.secret_name for spec in self._active_file_secrets()}
         with self._file_credential_lock:
             self._replace_file_credentials_on_next_materialisation.update(
                 configured.intersection(secret_names)
@@ -2452,7 +2457,7 @@ class ACPAgent(AgentBase):
         (their values are file blobs, not env vars the subprocess can reference
         by name).
         """
-        configured = {spec.secret_name for spec in self.acp_file_secrets}
+        configured = {spec.secret_name for spec in self._active_file_secrets()}
         if not configured:
             return set()
         return set(state.secret_registry.secret_sources) & configured
@@ -2587,6 +2592,42 @@ class ACPAgent(AgentBase):
             self.acp_server or ""
         ) or detect_acp_provider_by_command(self.acp_command)
 
+    def _active_file_secrets(self) -> list[ACPFileSecretSpec]:
+        """The file-secret specs that apply to the provider this agent runs.
+
+        Drops the specs that are *another registered provider's* reserved
+        credential and keeps everything else, so a harness added upstream cannot
+        change how this provider's conversation treats a secret carrying the new
+        reserved name (see #4923). A name several providers share stays: it is
+        this provider's too.
+
+        Deliberately no provenance test. :attr:`acp_file_secrets` defaults to the
+        union across the registry, but a persisted conversation carries whatever
+        that union was when it was written, so comparing against today's default
+        would read an older list as a caller override and silently stop scoping
+        after an upgrade. Filtering by ownership needs no such distinction, and a
+        spec for a CLI outside the registry is owned by nobody and always applies.
+
+        An unrecognised server keeps every spec, matching
+        :meth:`_strip_conflicting_env`: without an identity we cannot tell whose
+        credential a reserved name belongs to.
+        """
+        provider = self._resolved_provider()
+        if provider is None:
+            return list(self.acp_file_secrets)
+        own = {spec.secret_name for spec in provider.file_secrets}
+        owned_elsewhere = {
+            spec.secret_name
+            for key, info in ACP_PROVIDERS.items()
+            if key != provider.key
+            for spec in info.file_secrets
+        } - own
+        return [
+            spec
+            for spec in self.acp_file_secrets
+            if spec.secret_name not in owned_elsewhere
+        ]
+
     def _strip_conflicting_env(self, env: dict[str, str]) -> None:
         """Remove env vars that would defeat this provider's own credential.
 
@@ -2615,7 +2656,7 @@ class ACPAgent(AgentBase):
     def _materialise_file_secrets(
         self, state: ConversationState, env: dict[str, str]
     ) -> None:
-        for spec in self.acp_file_secrets:
+        for spec in self._active_file_secrets():
             name = spec.secret_name
             with self._file_credential_lock:
                 replace_existing = (
@@ -3091,7 +3132,7 @@ class ACPAgent(AgentBase):
                         or detect_acp_provider_by_agent_name(agent_name)
                     )
                     configured = _preconfigured_credentials(
-                        auth_provider, self.acp_file_secrets, env
+                        auth_provider, self._active_file_secrets(), env
                     )
                     if configured:
                         logger.info(
@@ -3688,7 +3729,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 +3751,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 +3914,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 +3995,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 +4027,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 +4089,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 +4181,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 +4210,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.46.0 → openhands_sdk-1.48.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,11 +18,10 @@ 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,
     fix_malformed_tool_arguments,
-    make_llm_completion,
     normalize_tool_call,
     parse_tool_call_arguments,
     prepare_llm_messages,
@@ -535,7 +534,7 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
             system_prompt=TextContent(text=self.static_system_message),
             # 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.
+            # Agent calls always expose security risk prediction in tool schemas.
             tools=list(self.tools_map.values()),
             dynamic_context=TextContent(text=dynamic_context)
             if dynamic_context
@@ -639,6 +638,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)
@@ -717,11 +725,12 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
         )
 
         try:
-            llm_response = make_llm_completion(
-                self.llm,
-                _messages,
+            llm_response = self.llm.generate(
+                messages=_messages,
                 tools=list(self.tools_map.values()),
-                on_token=on_token,
+                store=False,
+                add_security_risk_prediction=True,
+                on_token=stream.token_callback,
                 call_context=call_context,
             )
         except FunctionCallValidationError as e:
@@ -807,11 +816,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 +829,7 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
                     conversation,
                     state,
                     on_event,
+                    stream,
                     response_type=response_type,
                 )
 
@@ -833,12 +843,21 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
         """Async variant of :meth:`step`.
 
         The LLM completion is performed asynchronously via
-        :func:`amake_llm_completion`.  Tool dispatch uses
+        :meth:`LLM.agenerate`.  Tool dispatch uses
         :meth:`_aexecute_actions` which runs each tool call in its own
         thread via :func:`asyncio.loop.run_in_executor` and schedules
         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())
@@ -914,11 +933,12 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
             # and state snapshots aren't blocked for the whole response. No-op
             # unless the run loop holds the lock (e.g. direct astep() in tests).
             async with conversation._released_state_lock_during_io():
-                llm_response = await amake_llm_completion(
-                    self.llm,
-                    _messages,
+                llm_response = await self.llm.agenerate(
+                    messages=_messages,
                     tools=list(self.tools_map.values()),
-                    on_token=on_token,
+                    store=False,
+                    add_security_risk_prediction=True,
+                    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.46.0 → openhands_sdk-1.48.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