openhands-sdk 1.49.6__tar.gz → 1.50.0__tar.gz

{openhands_sdk-1.49.6 → openhands_sdk-1.50.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-sdk
-Version: 1.49.6
+Version: 1.50.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.49.6 → openhands_sdk-1.50.0}/openhands/sdk/agent/agent.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import asyncio
 import json
 import re
 from collections.abc import Callable
@@ -61,6 +62,7 @@ from openhands.sdk.llm import (
     TextContent,
     ThinkingBlock,
 )
+from openhands.sdk.llm.call_context import llm_call_context_scope
 from openhands.sdk.llm.exceptions import (
     FunctionCallValidationError,
     LLMContentPolicyViolationError,
@@ -120,6 +122,18 @@ INIT_STATE_PREFIX_SCAN_WINDOW = 3
 
 
 def _latest_user_message_contains_image(messages: list[Message]) -> bool:
+    """Check if the most recent user message contains image content.
+
+    Scans the message list in reverse order to find the latest user message
+    and checks whether it contains any image attachments.
+
+    Args:
+        messages: List of conversation messages to search.
+
+    Returns:
+        True if the most recent user message contains images, False otherwise.
+        Returns False if no user messages are found.
+    """
     for message in reversed(messages):
         if message.role == "user":
             return message.contains_image
@@ -127,6 +141,18 @@ def _latest_user_message_contains_image(messages: list[Message]) -> bool:
 
 
 def _non_multimodal_image_message(model: str) -> Message:
+    """Create an error message for when images are sent to a non-vision model.
+
+    Constructs a user-friendly assistant message explaining that the current
+    model does not support image understanding and suggesting the user switch
+    to a multimodal model.
+
+    Args:
+        model: The name of the current model that does not support vision.
+
+    Returns:
+        A Message object containing an assistant response with the error explanation.
+    """
     return Message(
         role="assistant",
         content=[
@@ -144,6 +170,20 @@ def _non_multimodal_image_message(model: str) -> Message:
 def _replace_latest_user_images_with_references(
     messages: list[Message],
 ) -> list[Message]:
+    """Replace images in the most recent user message containing images.
+
+    Searches backward, skipping user messages without images. Each image URL
+    becomes a textual reference to the inspect_image_with_vision tool, with a
+    zero-based image index within the selected message.
+
+    Args:
+        messages: List of conversation messages to process.
+
+    Returns:
+        A new list with the selected message copied and its images replaced.
+        Other messages and non-image content are unchanged. If no user message
+        contains images, returns a shallow copy of the original list.
+    """
     rewritten = list(messages)
     for index in range(len(rewritten) - 1, -1, -1):
         message = rewritten[index]
@@ -639,7 +679,11 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
         on_event: ConversationCallbackType,
         on_token: ConversationTokenCallbackType | None = None,
     ) -> None:
-        with StreamContext.open(conversation, on_token) as stream:
+        call_context = conversation.get_llm_call_context()
+        with (
+            llm_call_context_scope(call_context),
+            StreamContext.open(conversation, on_token) as stream,
+        ):
             self._step(conversation, on_event, stream)
 
     def _step(
@@ -849,7 +893,11 @@ 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:
+        call_context = conversation.get_llm_call_context()
+        with (
+            llm_call_context_scope(call_context),
+            StreamContext.open(conversation, on_token) as stream,
+        ):
             await self._astep(conversation, on_event, stream)
 
     async def _astep(
@@ -1022,6 +1070,18 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
 
         message: Message = llm_response.message
         response_type = classify_response(message)
+        if response_type is not LLMResponseType.TOOL_CALLS:
+            # Resolve outside the event loop and state lock. A lookup may call
+            # this server, and update_secrets() may register another source while
+            # we await it. Repeat until the registry is stable under the lock.
+            while True:
+                sources = dict(state.secret_registry.secret_sources)
+                async with conversation._released_state_lock_during_io():
+                    message = await asyncio.to_thread(
+                        self._mask_secrets, message, conversation
+                    )
+                if sources == state.secret_registry.secret_sources:
+                    break
 
         match response_type:
             case LLMResponseType.TOOL_CALLS:
@@ -1030,7 +1090,13 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
                 )
             case LLMResponseType.CONTENT:
                 self._handle_content_response(
-                    message, llm_response, conversation, state, on_event, stream
+                    message,
+                    llm_response,
+                    conversation,
+                    state,
+                    on_event,
+                    stream,
+                    mask_secrets=False,
                 )
             case LLMResponseType.REASONING_ONLY | LLMResponseType.EMPTY:
                 self._handle_no_content_response(
@@ -1041,6 +1107,7 @@ class Agent(CriticMixin, ResponseDispatchMixin, AgentBase):
                     on_event,
                     stream,
                     response_type=response_type,
+                    mask_secrets=False,
                 )
 
     def _requires_user_confirmation(

{openhands_sdk-1.49.6 → openhands_sdk-1.50.0}/openhands/sdk/agent/response_dispatch.py

@@ -253,9 +253,18 @@ class ResponseDispatchMixin:
         state: ConversationState,
         on_event: ConversationCallbackType,
         stream: StreamContext | None = None,
+        *,
+        mask_secrets: bool = True,
     ) -> None:
         """Handle LLM response with text content — finishes conversation."""
-        self._emit_message_event(message, llm_response, conversation, on_event, stream)
+        self._emit_message_event(
+            message,
+            llm_response,
+            conversation,
+            on_event,
+            stream,
+            mask_secrets=mask_secrets,
+        )
         self._maybe_emit_vllm_tokens(llm_response, on_event)
         logger.debug("LLM produced a message response - awaits user input")
         state.execution_status = ConversationExecutionStatus.FINISHED
@@ -270,6 +279,7 @@ class ResponseDispatchMixin:
         stream: StreamContext | None = None,
         *,
         response_type: LLMResponseType,
+        mask_secrets: bool = True,
     ) -> None:
         """Handle LLM response with no user-facing content.
 
@@ -279,7 +289,14 @@ 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, stream)
+        self._emit_message_event(
+            message,
+            llm_response,
+            conversation,
+            on_event,
+            stream,
+            mask_secrets=mask_secrets,
+        )
         self._maybe_emit_vllm_tokens(llm_response, on_event)
         self._send_corrective_nudge(on_event)
 
@@ -290,6 +307,8 @@ class ResponseDispatchMixin:
         conversation: LocalConversation,
         on_event: ConversationCallbackType,
         stream: StreamContext | None = None,
+        *,
+        mask_secrets: bool = True,
     ) -> MessageEvent:
         """Create and emit a MessageEvent, running critic if configured.
 
@@ -302,7 +321,9 @@ class ResponseDispatchMixin:
         msg_event = MessageEvent(
             **minted,
             source="agent",
-            llm_message=self._mask_secrets(message, conversation),
+            llm_message=self._mask_secrets(message, conversation)
+            if mask_secrets
+            else message,
             llm_response_id=llm_response.id,
         )
         if self.critic is not None and self.critic.mode == "finish_and_message":

{openhands_sdk-1.49.6 → openhands_sdk-1.50.0}/openhands/sdk/context/condenser/llm_summarizing_condenser.py

@@ -18,6 +18,7 @@ from openhands.sdk.context.prompts import render_template
 from openhands.sdk.context.view import View
 from openhands.sdk.event.base import LLMConvertibleEvent
 from openhands.sdk.event.condenser import Condensation
+from openhands.sdk.event.llm_convertible import SystemPromptEvent
 from openhands.sdk.llm import LLM, Message, TextContent
 from openhands.sdk.logger import get_logger
 from openhands.sdk.observability.laminar import observe
@@ -27,6 +28,21 @@ from openhands.sdk.utils import maybe_truncate
 logger = get_logger(__name__)
 
 
+def _leading_system_prompt_index(events: Sequence[LLMConvertibleEvent]) -> int | None:
+    """Index of the first ``SystemPromptEvent`` in ``events``, or ``None``.
+
+    The agent loop guarantees the ``SystemPromptEvent`` sits at the head of the
+    view (index 0), so condensation must never forget it -- otherwise the
+    condensed view would open with a non-system message and violate the
+    repo-wide "system before first user" invariant. Returns ``None`` when no
+    system prompt is present (e.g. unit-test views built without one).
+    """
+    for i, event in enumerate(events):
+        if isinstance(event, SystemPromptEvent):
+            return i
+    return None
+
+
 class Reason(Enum):
     """Reasons for condensation."""
 
@@ -186,6 +202,25 @@ class LLMSummarizingCondenser(RollingCondenser):
         if Reason.REQUEST in reasons:
             return CondensationRequirement.HARD
 
+    def _build_summary_messages(self, event_strings: Sequence[str]) -> list[Message]:
+        """Build the messages sent to the summarization LLM.
+
+        The summarization instructions are sent as a ``system`` message and the
+        events to summarize as a ``user`` message. Splitting roles keeps the
+        steering instructions in the provider's ``instructions``/``system`` slot
+        and the event payload in the ``input``/``user`` slot, which is the
+        canonical shape for both the Chat Completions and Responses APIs.
+        """
+        prompt_dir = os.path.join(os.path.dirname(__file__), "prompts")
+        system_prompt = render_template(prompt_dir, "summarizing_system.j2")
+        events_prompt = render_template(
+            prompt_dir, "summarizing_events.j2", events=event_strings
+        )
+        return [
+            Message(role="system", content=[TextContent(text=system_prompt)]),
+            Message(role="user", content=[TextContent(text=events_prompt)]),
+        ]
+
     def _generate_condensation(
         self,
         forgotten_events: Sequence[LLMConvertibleEvent],
@@ -215,13 +250,7 @@ class LLMSummarizingCondenser(RollingCondenser):
             for forgotten_event in forgotten_events
         ]
 
-        prompt = render_template(
-            os.path.join(os.path.dirname(__file__), "prompts"),
-            "summarizing_prompt.j2",
-            events=event_strings,
-        )
-
-        messages = [Message(role="user", content=[TextContent(text=prompt)])]
+        messages = self._build_summary_messages(event_strings)
 
         # Do not pass extra_body explicitly. The LLM handles forwarding
         # litellm_extra_body only when it is non-empty.
@@ -302,8 +331,16 @@ class LLMSummarizingCondenser(RollingCondenser):
         # Calculate naive forgetting end (without considering atomic boundaries)
         naive_end = len(view) - events_from_tail
 
-        # Find actual forgetting_start: smallest manipulation index >= keep_first
-        forgetting_start = view.manipulation_indices.find_next(self.keep_first)
+        # The leading SystemPromptEvent must never be forgotten, otherwise the
+        # condensed view would open with a non-system message. Floor the start
+        # of the forgetting range just past it (this also covers keep_first=0).
+        protected_prefix = self.keep_first
+        system_idx = _leading_system_prompt_index(view.events)
+        if system_idx is not None:
+            protected_prefix = max(protected_prefix, system_idx + 1)
+
+        # Find actual forgetting_start: smallest manipulation index >= protected_prefix
+        forgetting_start = view.manipulation_indices.find_next(protected_prefix)
 
         # Find actual forgetting_end: smallest manipulation index >= naive_end
         forgetting_end = view.manipulation_indices.find_next(naive_end)
@@ -326,14 +363,22 @@ class LLMSummarizingCondenser(RollingCondenser):
         the view is too large for the summarizing LLM to handle). In that case, we keep
         trimming down the contents until a summary can be generated.
         """
+        # Preserve the leading SystemPromptEvent: it must stay at the head of the
+        # view so the request still opens with a system message. Summarize the
+        # events *after* it and insert the summary right behind it.
+        system_idx = _leading_system_prompt_index(view.events)
+        preserve = (system_idx + 1) if system_idx is not None else 0
+        forgotten_events = view.events[preserve:]
+        summary_offset = preserve
+
         max_event_str_length: int | None = None
         attempts_remaining: int = self.hard_context_reset_max_retries
 
         while attempts_remaining > 0:
             try:
                 return self._generate_condensation(
-                    forgotten_events=view.events,
-                    summary_offset=0,
+                    forgotten_events=forgotten_events,
+                    summary_offset=summary_offset,
                     max_event_str_length=max_event_str_length,
                 )
             except Exception as e:
@@ -411,13 +456,7 @@ class LLMSummarizingCondenser(RollingCondenser):
             for fe in forgotten_events
         ]
 
-        prompt = render_template(
-            os.path.join(os.path.dirname(__file__), "prompts"),
-            "summarizing_prompt.j2",
-            events=event_strings,
-        )
-
-        messages = [Message(role="user", content=[TextContent(text=prompt)])]
+        messages = self._build_summary_messages(event_strings)
 
         try:
             llm_response = await self.llm.agenerate(messages=messages, store=False)
@@ -477,14 +516,20 @@ class LLMSummarizingCondenser(RollingCondenser):
         agent_llm: LLM | None = None,  # noqa: ARG002
     ) -> Condensation | None:
         """Async variant of :meth:`hard_context_reset`."""
+        # Preserve the leading SystemPromptEvent (see hard_context_reset).
+        system_idx = _leading_system_prompt_index(view.events)
+        preserve = (system_idx + 1) if system_idx is not None else 0
+        forgotten_events = view.events[preserve:]
+        summary_offset = preserve
+
         max_event_str_length: int | None = None
         attempts_remaining: int = self.hard_context_reset_max_retries
 
         while attempts_remaining > 0:
             try:
                 return await self._agenerate_condensation(
-                    forgotten_events=view.events,
-                    summary_offset=0,
+                    forgotten_events=forgotten_events,
+                    summary_offset=summary_offset,
                     max_event_str_length=max_event_str_length,
                 )
             except Exception as e:

openhands_sdk-1.50.0/openhands/sdk/context/condenser/prompts/summarizing_events.j2

@@ -0,0 +1,7 @@
+{% for event in events %}
+<EVENT>
+{{ event }}
+</EVENT>
+{% endfor %}
+
+Now summarize the events using the rules above.

openhands_sdk-1.49.6/openhands/sdk/context/condenser/prompts/summarizing_prompt.j2 → openhands_sdk-1.50.0/openhands/sdk/context/condenser/prompts/summarizing_system.j2

@@ -45,11 +45,3 @@ USER_CONTEXT: Write 20 haikus based on coin flip results
 COMPLETED: 15 haikus written for results [T,H,T,H,T,H,T,T,H,T,H,T,H,T,H]
 PENDING: 5 more haikus needed
 CURRENT_STATE: Last flip: Heads, Haiku count: 15/20
-
-{% for event in events %}
-<EVENT>
-{{ event }}
-</EVENT>
-{% endfor %}
-
-Now summarize the events using the rules above.

{openhands_sdk-1.49.6 → openhands_sdk-1.50.0}/openhands/sdk/conversation/goal/judge.py

@@ -14,7 +14,10 @@ from typing import Any
 
 from pydantic import BaseModel, Field
 
-from openhands.sdk.conversation.goal.prompts import JUDGE_PROMPT
+from openhands.sdk.conversation.goal.prompts import (
+    JUDGE_SYSTEM_PROMPT,
+    JUDGE_USER_PROMPT,
+)
 from openhands.sdk.event import Event, LLMConvertibleEvent
 from openhands.sdk.llm import LLM, Message, TextContent, content_to_str
 from openhands.sdk.logger import get_logger
@@ -55,15 +58,21 @@ def judge_goal(judge_llm: LLM, objective: str, events: Sequence[Event]) -> GoalV
     """
     convertible = [e for e in events if isinstance(e, LLMConvertibleEvent)]
     transcript = _render_transcript(convertible)
-    prompt = JUDGE_PROMPT.format(objective=objective, transcript=transcript)
+    system_prompt = JUDGE_SYSTEM_PROMPT
+    user_prompt = JUDGE_USER_PROMPT.format(objective=objective, transcript=transcript)
 
     # The judge only needs the verdict text. Force non-streaming so reusing a
     # streaming agent LLM as the judge does not trip completion()'s requirement
     # of an on_token callback when stream=True.
     if judge_llm.stream:
         judge_llm = judge_llm.model_copy(update={"stream": False})
+    # Build a canonical system + user pair: steering/format instructions live in
+    # the system message, the objective + transcript payload in the user message.
     response = judge_llm.completion(
-        messages=[Message(role="user", content=[TextContent(text=prompt)])]
+        messages=[
+            Message(role="system", content=[TextContent(text=system_prompt)]),
+            Message(role="user", content=[TextContent(text=user_prompt)]),
+        ]
     )
     verdict = _parse_verdict(response.message)
     logger.debug("judge_goal verdict: %s", verdict)

{openhands_sdk-1.49.6 → openhands_sdk-1.50.0}/openhands/sdk/conversation/goal/prompts.py

@@ -3,26 +3,44 @@
 from typing import Final
 
 
-JUDGE_PROMPT: Final[str] = """You are auditing whether a long-running GOAL has \
-been COMPLETED by an AI software agent.
-
-<objective>
-{objective}
-</objective>
+JUDGE_SYSTEM_PROMPT: Final[str] = """\
+You are auditing whether a long-running GOAL has been COMPLETED by an AI \
+software agent.
 
 Derive the concrete requirements implied by the objective. For EACH requirement,
-look for authoritative evidence in the transcript below: file contents, command
+look for authoritative evidence in the transcript: file contents, command
 output, or test results produced by the agent. Treat missing, uncertain, or
 merely-claimed-but-unverified evidence as NOT satisfied.
 
+Respond with STRICT JSONand nothing else, in exactly this shape:
+{"score": <float 0.0-1.0, probability the FULL objective is provably done>, \
+"complete": <true|false>, "missing": "<concise description of what remains, or \
+an empty string if complete>"}"""
+
+
+JUDGE_USER_PROMPT: Final[str] = """\
+<objective>
+{objective}
+</objective>
+
 <transcript>
 {transcript}
-</transcript>
-
-Respond with STRICT JSON and nothing else, in exactly this shape:
-{{"score": <float 0.0-1.0, probability the FULL objective is provably done>, \
-"complete": <true|false>, "missing": "<concise description of what remains, or \
-an empty string if complete>"}}"""
+</transcript>"""
+
+
+JUDGE_PROMPT: Final[str] = (
+    JUDGE_SYSTEM_PROMPT.replace("{", "{{").replace("}", "}}")
+    + "\n\n"
+    + JUDGE_USER_PROMPT
+)
+"""Backwards-compatible concatenation of the system steering prompt and the user
+payload template. Kept so external callers that still format a single prompt
+continue to work; new code should use ``JUDGE_SYSTEM_PROMPT`` and
+``JUDGE_USER_PROMPT`` separately to build a ``system + user`` message pair.
+
+JUDGE_SYSTEM_PROMPT carries the raw, un-escaped JSON shape because it is sent
+unformatted ins ``judge_goal``; ``JUDGE_PROMPT`` re-escapes it so the combined
+template survives ``.format(objective=..., transcript=...)``."""
 
 
 FOLLOWUP_PROMPT: Final[str] = """The goal is NOT yet complete (audit iteration \