openhands-sdk 1.10.0__tar.gz → 1.11.0__tar.gz

{openhands_sdk-1.10.0 → openhands_sdk-1.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openhands-sdk
-Version: 1.10.0
+Version: 1.11.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.10.0 → openhands_sdk-1.11.0}/openhands/sdk/agent/agent.py

@@ -67,6 +67,10 @@ from openhands.sdk.tool.builtins import (
 logger = get_logger(__name__)
 maybe_init_laminar()
 
+# Maximum number of events to scan during init_state defensive checks.
+# SystemPromptEvent must appear within this prefix (at index 0 or 1).
+INIT_STATE_PREFIX_SCAN_WINDOW = 3
+
 
 class Agent(AgentBase):
     """Main agent implementation for OpenHands.
@@ -102,53 +106,82 @@ class Agent(AgentBase):
         state: ConversationState,
         on_event: ConversationCallbackType,
     ) -> None:
+        """Initialize conversation state.
+
+        Invariants enforced by this method:
+        - If a SystemPromptEvent is already present, it must be within the first 3
+          events (index 0 or 1 in practice; index 2 is included in the scan window
+          to detect a user message appearing before the system prompt).
+        - A user MessageEvent should not appear before the SystemPromptEvent.
+
+        These invariants keep event ordering predictable for downstream components
+        (condenser, UI, etc.) and also prevent accidentally materializing the full
+        event history during initialization.
+        """
         super().init_state(state, on_event=on_event)
-        # TODO(openhands): we should add test to test this init_state will actually
-        # modify state in-place
 
         # Defensive check: Analyze state to detect unexpected initialization scenarios
         # These checks help diagnose issues related to lazy loading and event ordering
         # See: https://github.com/OpenHands/software-agent-sdk/issues/1785
-        events = list(state.events)
-        has_system_prompt = any(isinstance(e, SystemPromptEvent) for e in events)
+        #
+        # NOTE: len() is O(1) for EventLog (file-backed implementation).
+        event_count = len(state.events)
+
+        # NOTE: state.events is intentionally an EventsListBase (Sequence-like), not
+        # a plain list. Avoid materializing the full history via list(state.events)
+        # here (conversations can reach 30k+ events).
+        #
+        # Invariant: when init_state is called, SystemPromptEvent (if present) must be
+        # at index 0 or 1.
+        #
+        # Rationale:
+        # - Local conversations start empty and init_state is responsible for adding
+        #   the SystemPromptEvent as the first event.
+        # - Remote conversations may receive an initial ConversationStateUpdateEvent
+        #   from the agent-server immediately after subscription. In a typical remote
+        #   session prefix you may see:
+        #     [ConversationStateUpdateEvent, SystemPromptEvent, MessageEvent, ...]
+        #
+        # We intentionally only inspect the first few events (cheap for both local and
+        # remote) to enforce this invariant.
+        prefix_events = state.events[:INIT_STATE_PREFIX_SCAN_WINDOW]
+
+        has_system_prompt = any(isinstance(e, SystemPromptEvent) for e in prefix_events)
         has_user_message = any(
-            isinstance(e, MessageEvent) and e.source == "user" for e in events
+            isinstance(e, MessageEvent) and e.source == "user" for e in prefix_events
         )
-        has_any_llm_event = any(isinstance(e, LLMConvertibleEvent) for e in events)
-
         # Log state for debugging initialization order issues
         logger.debug(
             f"init_state called: conversation_id={state.id}, "
-            f"event_count={len(events)}, "
+            f"event_count={event_count}, "
             f"has_system_prompt={has_system_prompt}, "
-            f"has_user_message={has_user_message}, "
-            f"has_any_llm_event={has_any_llm_event}"
+            f"has_user_message={has_user_message}"
         )
 
         if has_system_prompt:
-            # SystemPromptEvent already exists - this is unexpected during normal flow
-            # but could happen in persistence/resume scenarios
-            logger.warning(
-                f"init_state called but SystemPromptEvent already exists. "
-                f"conversation_id={state.id}, event_count={len(events)}. "
-                f"This may indicate double initialization or a resume scenario."
+            # Restoring/resuming conversations is normal: a system prompt already
+            # present means this conversation was initialized previously.
+            logger.debug(
+                "init_state: SystemPromptEvent already present; skipping init. "
+                f"conversation_id={state.id}, event_count={event_count}."
             )
             return
 
-        # Assert: If there are user messages but no system prompt, something is wrong
-        # The system prompt should always be added before any user messages
+        # Assert: A user message should never appear before the system prompt.
+        #
+        # NOTE: This is a best-effort check based on the first few events only.
+        # Remote conversations can include a ConversationStateUpdateEvent near the
+        # start, so we scan a small prefix window.
         if has_user_message:
-            event_types = [type(e).__name__ for e in events]
+            event_types = [type(e).__name__ for e in prefix_events]
             logger.error(
-                f"init_state: User message exists without SystemPromptEvent! "
-                f"conversation_id={state.id}, events={event_types}"
+                f"init_state: User message found in prefix before SystemPromptEvent! "
+                f"conversation_id={state.id}, prefix_events={event_types}"
             )
-            assert not has_user_message, (
-                f"Unexpected state: User message exists before SystemPromptEvent. "
-                f"conversation_id={state.id}, event_count={len(events)}, "
-                f"event_types={event_types}. "
-                f"This indicates an initialization order bug - init_state should be "
-                f"called before any user messages are added to the conversation."
+            raise AssertionError(
+                "Unexpected state: user message exists before SystemPromptEvent. "
+                f"conversation_id={state.id}, event_count={event_count}, "
+                f"prefix_event_types={event_types}."
             )
 
         # Prepare system message

{openhands_sdk-1.10.0 → openhands_sdk-1.11.0}/openhands/sdk/agent/base.py

@@ -503,5 +503,5 @@ class AgentBase(DiscriminatedUnionMixin, ABC):
             RuntimeError: If the agent has not been initialized.
         """
         if not self._initialized:
-            raise RuntimeError("Agent not initialized; call initialize() before use")
+            raise RuntimeError("Agent not initialized; call _initialize() before use")
         return self._tools

{openhands_sdk-1.10.0 → openhands_sdk-1.11.0}/openhands/sdk/context/condenser/base.py

@@ -103,6 +103,23 @@ class RollingCondenser(PipelinableCondenserBase, ABC):
     `View` to be passed to the LLM.
     """
 
+    def hard_context_reset(
+        self,
+        view: View,  # noqa: ARG002
+        agent_llm: LLM | None = None,  # noqa: ARG002
+    ) -> Condensation | None:
+        """Perform a hard context reset, if supported by the condenser.
+
+        By default, rolling condensers do not support hard context resets. Override this
+        method to implement hard context reset logic by returning a `Condensation`
+        object.
+
+        This method is invoked when:
+        - A HARD condensation requirement is triggered (e.g., by user request)
+        - But the condenser raises a NoCondensationAvailableException error
+        """
+        return None
+
     @abstractmethod
     def condensation_requirement(
         self, view: View, agent_llm: LLM | None = None
@@ -142,9 +159,25 @@ class RollingCondenser(PipelinableCondenserBase, ABC):
                     # we do so immediately.
                     return view
 
-                # Otherwise re-raise the exception.
-                else:
-                    raise e
+                elif request == CondensationRequirement.HARD:
+                    # The agent has found itself in a situation where it cannot proceed
+                    # without condensation, but the condenser cannot provide one. We'll
+                    # try to recover from this situation by performing a hard context
+                    # reset, if supported by the condenser.
+                    try:
+                        hard_reset_condensation = self.hard_context_reset(
+                            view, agent_llm=agent_llm
+                        )
+                        if hard_reset_condensation is not None:
+                            return hard_reset_condensation
+
+                    # And if something goes wrong with the hard reset make sure we keep
+                    # both errors in the stack
+                    except Exception as hard_reset_exception:
+                        raise hard_reset_exception from e
+
+                # In all other situations re-raise the exception.
+                raise e
 
         # Otherwise we're safe to just return the view.
         else:

{openhands_sdk-1.10.0 → openhands_sdk-1.11.0}/openhands/sdk/context/condenser/llm_summarizing_condenser.py

@@ -18,7 +18,12 @@ from openhands.sdk.context.view import View
 from openhands.sdk.event.base import LLMConvertibleEvent
 from openhands.sdk.event.condenser import Condensation
 from openhands.sdk.llm import LLM, Message, TextContent
+from openhands.sdk.logger import get_logger
 from openhands.sdk.observability.laminar import observe
+from openhands.sdk.utils import maybe_truncate
+
+
+logger = get_logger(__name__)
 
 
 class Reason(Enum):
@@ -47,6 +52,14 @@ class LLMSummarizingCondenser(RollingCondenser):
     `keep_first` events in the conversation will never be condensed or summarized.
     """
 
+    hard_context_reset_max_retries: int = Field(default=5, gt=0)
+    """Number of attempts to perform hard context reset before raising an error."""
+
+    hard_context_reset_context_scaling: float = Field(default=0.8, gt=0.0, lt=1.0)
+    """When performing hard context reset, if the summarization fails, reduce the max
+    size of each event string by this factor and retry.
+    """
+
     @model_validator(mode="after")
     def validate_keep_first_vs_max_size(self):
         events_from_tail = self.max_size // 2 - self.keep_first - 1
@@ -120,6 +133,7 @@ class LLMSummarizingCondenser(RollingCondenser):
         self,
         forgotten_events: Sequence[LLMConvertibleEvent],
         summary_offset: int,
+        max_event_str_length: int | None = None,
     ) -> Condensation:
         """Generate a condensation by using the condenser's LLM to summarize forgotten
         events.
@@ -127,6 +141,8 @@ class LLMSummarizingCondenser(RollingCondenser):
         Args:
             forgotten_events: The list of events to be summarized.
             summary_offset: The index where the summary event should be inserted.
+            max_event_str_length: Optional maximum length for each event string. If
+                provided, event strings longer than this will be truncated.
 
         Returns:
             Condensation: The generated condensation object.
@@ -137,7 +153,10 @@ class LLMSummarizingCondenser(RollingCondenser):
         assert len(forgotten_events) > 0, "No events to condense."
 
         # Convert events to strings for the template
-        event_strings = [str(forgotten_event) for forgotten_event in forgotten_events]
+        event_strings = [
+            maybe_truncate(str(forgotten_event), truncate_after=max_event_str_length)
+            for forgotten_event in forgotten_events
+        ]
 
         prompt = render_template(
             os.path.join(os.path.dirname(__file__), "prompts"),
@@ -232,6 +251,51 @@ class LLMSummarizingCondenser(RollingCondenser):
         # Summary offset is the same as forgetting_start
         return forgotten_events, forgetting_start
 
+    @observe(ignore_inputs=["view", "agent_llm"])
+    def hard_context_reset(
+        self,
+        view: View,
+        agent_llm: LLM | None = None,  # noqa: ARG002
+    ) -> Condensation | None:
+        """Perform a hard context reset by summarizing all events in the view.
+
+        Depending on how the hard context reset is triggered, this may fail (e.g., if
+        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.
+        """
+        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,
+                    max_event_str_length=max_event_str_length,
+                )
+            except Exception as e:
+                # If we haven't set a max_event_str_length yet, set it as the largest
+                # event string length.
+                if max_event_str_length is None:
+                    max_event_str_length = max(len(str(event)) for event in view.events)
+
+                # Since the summarization failed, reduce the max_event_str_length by 20%
+                assert max_event_str_length is not None
+                max_event_str_length = int(
+                    max_event_str_length * self.hard_context_reset_context_scaling
+                )
+
+                # Log the exception so we can track these failures
+                logger.warning(
+                    f"Hard context reset summarization failed with exception: {e}. "
+                    f"Reducing max event size to {max_event_str_length} and retrying."
+                )
+
+            attempts_remaining -= 1
+
+        logger.error("Hard context reset summarization failed after multiple attempts.")
+        return None
+
     @observe(ignore_inputs=["view", "agent_llm"])
     def get_condensation(
         self, view: View, agent_llm: LLM | None = None

{openhands_sdk-1.10.0 → openhands_sdk-1.11.0}/openhands/sdk/context/prompts/templates/system_message_suffix.j2

@@ -27,9 +27,10 @@ You can also directly look up a skill's full content by reading its location pat
 <CUSTOM_SECRETS>
 ### Credential Access
 * Automatic secret injection: When you reference a registered secret key in your bash command, the secret value will be automatically exported as an environment variable before your command executes.
-* How to use secrets: Simply reference the secret key in your command (e.g., `echo ${GITHUB_TOKEN:0:8}` or `curl -H "Authorization: Bearer $API_KEY" https://api.example.com`). The system will detect the key name in your command text and export it as environment variable before it executes your command.
+* How to use secrets: Simply reference the secret key in your command (e.g., `curl -H "Authorization: Bearer $API_KEY" https://api.example.com`). The system will detect the key name in your command text and export it as environment variable before it executes your command.
 * Secret detection: The system performs case-insensitive matching to find secret keys in your command text. If a registered secret key appears anywhere in your command, its value will be made available as an environment variable.
 * Security: Secret values are automatically masked in command output to prevent accidental exposure. You will see `<secret-hidden>` instead of the actual secret value in the output.
+* Avoid exposing raw secrets: Never echo or print the full value of secrets (e.g., avoid `echo $SECRET`). The conversation history may be logged or shared, and exposing raw secret values could compromise security. Instead, use secrets directly in commands where they serve their intended purpose (e.g., in curl headers or git URLs).
 * Refreshing expired secrets: Some secrets (like GITHUB_TOKEN) may be updated periodically or expire over time. If a secret stops working (e.g., authentication failures), try using it again in a new command - the system should automatically use the refreshed value. For example, if GITHUB_TOKEN was used in a git remote URL and later expired, you can update the remote URL with the current token: `git remote set-url origin https://${GITHUB_TOKEN}@github.com/username/repo.git` to pick up the refreshed token value.
 * If it still fails, report it to the user.
 

{openhands_sdk-1.10.0 → openhands_sdk-1.11.0}/openhands/sdk/context/skills/skill.py

@@ -27,15 +27,10 @@ from openhands.sdk.context.skills.utils import (
     validate_skill_name,
 )
 from openhands.sdk.logger import get_logger
-from openhands.sdk.utils import maybe_truncate
 
 
 logger = get_logger(__name__)
 
-# Maximum characters for third-party skill files (e.g., AGENTS.md, CLAUDE.md, GEMINI.md)
-# These files are always active, so we want to keep them reasonably sized
-THIRD_PARTY_SKILL_MAX_CHARS = 10_000
-
 
 class SkillInfo(BaseModel):
     """Lightweight representation of a skill's essential information.
@@ -485,32 +480,14 @@ class Skill(BaseModel):
         """Handle third-party skill files (e.g., .cursorrules, AGENTS.md).
 
         Creates a Skill with None trigger (always active) if the file type
-        is recognized. Truncates content if it exceeds the limit.
+        is recognized.
         """
         skill_name = cls.PATH_TO_THIRD_PARTY_SKILL_NAME.get(path.name.lower())
 
         if skill_name is not None:
-            truncated_content = maybe_truncate(
-                file_content,
-                truncate_after=THIRD_PARTY_SKILL_MAX_CHARS,
-                truncate_notice=(
-                    f"\n\n<TRUNCATED><NOTE>The file {path} exceeded the "
-                    f"maximum length ({THIRD_PARTY_SKILL_MAX_CHARS} "
-                    f"characters) and has been truncated. Only the "
-                    f"beginning and end are shown. You can read the full "
-                    f"file if needed.</NOTE>\n\n"
-                ),
-            )
-
-            if len(file_content) > THIRD_PARTY_SKILL_MAX_CHARS:
-                logger.warning(
-                    f"Third-party skill file {path} ({len(file_content)} chars) "
-                    f"exceeded limit ({THIRD_PARTY_SKILL_MAX_CHARS} chars), truncating"
-                )
-
             return Skill(
                 name=skill_name,
-                content=truncated_content,
+                content=file_content,
                 source=str(path),
                 trigger=None,
             )

{openhands_sdk-1.10.0 → openhands_sdk-1.11.0}/openhands/sdk/conversation/conversation.py

@@ -74,6 +74,7 @@ class Conversation:
             type[ConversationVisualizerBase] | ConversationVisualizerBase | None
         ) = DefaultConversationVisualizer,
         secrets: dict[str, SecretValue] | dict[str, str] | None = None,
+        delete_on_close: bool = False,
     ) -> "LocalConversation": ...
 
     @overload
@@ -96,6 +97,7 @@ class Conversation:
             type[ConversationVisualizerBase] | ConversationVisualizerBase | None
         ) = DefaultConversationVisualizer,
         secrets: dict[str, SecretValue] | dict[str, str] | None = None,
+        delete_on_close: bool = False,
     ) -> "RemoteConversation": ...
 
     def __new__(
@@ -118,6 +120,7 @@ class Conversation:
             type[ConversationVisualizerBase] | ConversationVisualizerBase | None
         ) = DefaultConversationVisualizer,
         secrets: dict[str, SecretValue] | dict[str, str] | None = None,
+        delete_on_close: bool = False,
     ) -> BaseConversation:
         from openhands.sdk.conversation.impl.local_conversation import LocalConversation
         from openhands.sdk.conversation.impl.remote_conversation import (
@@ -143,6 +146,7 @@ class Conversation:
                 visualizer=visualizer,
                 workspace=workspace,
                 secrets=secrets,
+                delete_on_close=delete_on_close,
             )
 
         return LocalConversation(
@@ -159,4 +163,5 @@ class Conversation:
             workspace=workspace,
             persistence_dir=persistence_dir,
             secrets=secrets,
+            delete_on_close=delete_on_close,
         )

{openhands_sdk-1.10.0 → openhands_sdk-1.11.0}/openhands/sdk/conversation/impl/local_conversation.py

@@ -65,6 +65,7 @@ class LocalConversation(BaseConversation):
     llm_registry: LLMRegistry
     _cleanup_initiated: bool
     _hook_processor: HookEventProcessor | None
+    delete_on_close: bool = True
     # Plugin lazy loading state
     _plugin_specs: list[PluginSource] | None
     _resolved_plugins: list[ResolvedPluginSource] | None
@@ -90,6 +91,7 @@ class LocalConversation(BaseConversation):
             type[ConversationVisualizerBase] | ConversationVisualizerBase | None
         ) = DefaultConversationVisualizer,
         secrets: Mapping[str, SecretValue] | None = None,
+        delete_on_close: bool = True,
         cipher: Cipher | None = None,
         **_: object,
     ):
@@ -242,6 +244,7 @@ class LocalConversation(BaseConversation):
 
         atexit.register(self.close)
         self._start_observability_span(str(desired_id))
+        self.delete_on_close = delete_on_close
 
     @property
     def id(self) -> ConversationID:
@@ -708,20 +711,23 @@ class LocalConversation(BaseConversation):
         except AttributeError:
             # Object may be partially constructed; span fields may be missing.
             pass
-        try:
-            tools_map = self.agent.tools_map
-        except (AttributeError, RuntimeError):
-            # Agent not initialized or partially constructed
-            return
-        for tool in tools_map.values():
+        if self.delete_on_close:
             try:
-                executable_tool = tool.as_executable()
-                executable_tool.executor.close()
-            except NotImplementedError:
-                # Tool has no executor, skip it without erroring
-                continue
-            except Exception as e:
-                logger.warning(f"Error closing executor for tool '{tool.name}': {e}")
+                tools_map = self.agent.tools_map
+            except (AttributeError, RuntimeError):
+                # Agent not initialized or partially constructed
+                return
+            for tool in tools_map.values():
+                try:
+                    executable_tool = tool.as_executable()
+                    executable_tool.executor.close()
+                except NotImplementedError:
+                    # Tool has no executor, skip it without erroring
+                    continue
+                except Exception as e:
+                    logger.warning(
+                        f"Error closing executor for tool '{tool.name}': {e}"
+                    )
 
     def ask_agent(self, question: str) -> str:
         """Ask the agent a simple, stateless question and get a direct LLM response.

{openhands_sdk-1.10.0 → openhands_sdk-1.11.0}/openhands/sdk/conversation/impl/remote_conversation.py

@@ -555,6 +555,7 @@ class RemoteConversation(BaseConversation):
     _client: httpx.Client
     _hook_processor: HookEventProcessor | None
     _cleanup_initiated: bool
+    delete_on_close: bool = False
 
     def __init__(
         self,
@@ -573,6 +574,7 @@ class RemoteConversation(BaseConversation):
             type[ConversationVisualizerBase] | ConversationVisualizerBase | None
         ) = DefaultConversationVisualizer,
         secrets: Mapping[str, SecretValue] | None = None,
+        delete_on_close: bool = False,
         **_: object,
     ) -> None:
         """Remote conversation proxy that talks to an agent server.
@@ -765,6 +767,7 @@ class RemoteConversation(BaseConversation):
             )
             self._hook_processor = HookEventProcessor(hook_manager=hook_manager)
             self._hook_processor.run_session_start()
+        self.delete_on_close = delete_on_close
 
     def _create_llm_completion_log_callback(self) -> ConversationCallbackType:
         """Create a callback that writes LLM completion logs to client filesystem."""
@@ -1134,6 +1137,13 @@ class RemoteConversation(BaseConversation):
             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"/api/conversations/{self.id}")
+            except Exception:
+                pass
 
     def __del__(self) -> None:
         try:

{openhands_sdk-1.10.0 → openhands_sdk-1.11.0}/openhands/sdk/conversation/stuck_detector.py

@@ -15,6 +15,12 @@ from openhands.sdk.logger import get_logger
 logger = get_logger(__name__)
 
 
+# Maximum recent events to scan for stuck detection.
+# This window should be large enough to capture repetitive patterns
+# (4 repeats × 2 events per cycle = 8 events minimum, plus buffer for user messages)
+MAX_EVENTS_TO_SCAN_FOR_STUCK_DETECTION: int = 20
+
+
 class StuckDetector:
     """Detects when an agent is stuck in repetitive or unproductive patterns.
 
@@ -54,8 +60,14 @@ class StuckDetector:
         return self.thresholds.alternating_pattern
 
     def is_stuck(self) -> bool:
-        """Check if the agent is currently stuck."""
-        events = list(self.state.events)
+        """Check if the agent is currently stuck.
+
+        Note: To avoid materializing potentially large file-backed event histories,
+        only the last MAX_EVENTS_TO_SCAN_FOR_STUCK_DETECTION events are analyzed.
+        If a user message exists within this window, only events after it are checked.
+        Otherwise, all events in the window are analyzed.
+        """
+        events = list(self.state.events[-MAX_EVENTS_TO_SCAN_FOR_STUCK_DETECTION:])
 
         # Only look at history after the last user message
         last_user_msg_index = next(
@@ -66,11 +78,8 @@ class StuckDetector:
             ),
             -1,  # Default to -1 if no user message found
         )
-        if last_user_msg_index == -1:
-            logger.warning("No user message found in history, skipping stuck detection")
-            return False
-
-        events = events[last_user_msg_index + 1 :]
+        if last_user_msg_index != -1:
+            events = events[last_user_msg_index + 1 :]
 
         # Determine minimum events needed
         min_threshold = min(
@@ -253,10 +262,10 @@ class StuckDetector:
         return False
 
     def _is_stuck_context_window_error(self, _events: list[Event]) -> bool:
-        """Detects if we're stuck in a loop of context window errors.
+        """Detects if we are stuck in a loop of context window errors.
 
         This happens when we repeatedly get context window errors and try to trim,
-        but the trimming doesn't work, causing us to get more context window errors.
+        but the trimming does not work, causing us to get more context window errors.
         The pattern is repeated AgentCondensationObservation events without any other
         events between them.
         """

{openhands_sdk-1.10.0 → openhands_sdk-1.11.0}/openhands/sdk/llm/__init__.py

@@ -1,3 +1,9 @@
+from openhands.sdk.llm.auth import (
+    OPENAI_CODEX_MODELS,
+    CredentialStore,
+    OAuthCredentials,
+    OpenAISubscriptionAuth,
+)
 from openhands.sdk.llm.llm import LLM
 from openhands.sdk.llm.llm_registry import LLMRegistry, RegistryEvent
 from openhands.sdk.llm.llm_response import LLMResponse
@@ -22,11 +28,18 @@ from openhands.sdk.llm.utils.verified_models import VERIFIED_MODELS
 
 
 __all__ = [
+    # Auth
+    "CredentialStore",
+    "OAuthCredentials",
+    "OpenAISubscriptionAuth",
+    "OPENAI_CODEX_MODELS",
+    # Core
     "LLMResponse",
     "LLM",
     "LLMRegistry",
     "RouterLLM",
     "RegistryEvent",
+    # Messages
     "Message",
     "MessageToolCall",
     "TextContent",
@@ -35,10 +48,13 @@ __all__ = [
     "RedactedThinkingBlock",
     "ReasoningItemModel",
     "content_to_str",
+    # Streaming
     "LLMStreamChunk",
     "TokenCallbackType",
+    # Metrics
     "Metrics",
     "MetricsSnapshot",
+    # Models
     "VERIFIED_MODELS",
     "UNVERIFIED_MODELS_EXCLUDING_BEDROCK",
     "get_unverified_models",

openhands_sdk-1.11.0/openhands/sdk/llm/auth/__init__.py

@@ -0,0 +1,28 @@
+"""Authentication module for LLM subscription-based access.
+
+This module provides OAuth-based authentication for LLM providers that support
+subscription-based access (e.g., ChatGPT Plus/Pro for OpenAI Codex models).
+"""
+
+from openhands.sdk.llm.auth.credentials import (
+    CredentialStore,
+    OAuthCredentials,
+)
+from openhands.sdk.llm.auth.openai import (
+    OPENAI_CODEX_MODELS,
+    OpenAISubscriptionAuth,
+    SupportedVendor,
+    inject_system_prefix,
+    transform_for_subscription,
+)
+
+
+__all__ = [
+    "CredentialStore",
+    "OAuthCredentials",
+    "OpenAISubscriptionAuth",
+    "OPENAI_CODEX_MODELS",
+    "SupportedVendor",
+    "inject_system_prefix",
+    "transform_for_subscription",
+]