openhands-sdk 1.9.1__py3-none-any.whl → 1.11.0__py3-none-any.whl

openhands/sdk/critic/impl/api/critic.py

@@ -49,13 +49,16 @@ class APIBasedCritic(CriticBase, CriticClient):
         messages = LLMConvertibleEvent.events_to_messages(llm_convertible_events)
 
         # Serialize messages to dicts for API
-        for message in messages:
-            message.cache_enabled = False
-            message.vision_enabled = False  # Critic does not support vision currently
-            message.function_calling_enabled = True
-            message.force_string_serializer = False
-            message.send_reasoning_content = False
-        formatted_messages = [message.to_chat_dict() for message in messages]
+        formatted_messages = [
+            message.to_chat_dict(
+                cache_enabled=False,
+                vision_enabled=False,  # Critic does not support vision currently
+                function_calling_enabled=True,
+                force_string_serializer=False,
+                send_reasoning_content=False,
+            )
+            for message in messages
+        ]
 
         # Convert ToolDefinition objects to ChatCompletionToolParam format
         tools_for_api = [tool.to_openai_tool() for tool in tools]

openhands/sdk/event/condenser.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from pydantic import Field
 from rich.text import Text
 
@@ -22,8 +24,9 @@ class Condensation(Event):
     summary_offset: int | None = Field(
         default=None,
         ge=0,
-        description="An optional offset to the start of the resulting view"
-        " indicating where the summary should be inserted.",
+        description="An optional offset to the start of the resulting view (after"
+        " forgotten events have been removed) indicating where the summary should be"
+        " inserted. If not provided, the summary will not be inserted into the view.",
     )
     llm_response_id: EventID = Field(
         description=(
@@ -45,6 +48,53 @@ class Condensation(Event):
             text.append(f"{self.summary}\n")
         return text
 
+    @property
+    def summary_event(self) -> CondensationSummaryEvent:
+        """Generates a CondensationSummaryEvent.
+
+        Since summary events are not part of the main event store and are generated
+        dynamically, this property ensures the created event has a unique and consistent
+        ID based on the condensation event's ID.
+
+        Raises:
+            ValueError: If no summary is present.
+        """
+        if self.summary is None:
+            raise ValueError("No summary present to generate CondensationSummaryEvent.")
+
+        # Create a deterministic ID for the summary event.
+        # This ID will be unique amongst all auto-generated IDs (by virtue of the
+        # "-summary" suffix).
+        # These events are not intended to be stored alongside regular events, but the
+        # ID is still compatible with the file-based event store.
+        summary_id = f"{self.id}-summary"
+
+        return CondensationSummaryEvent(
+            id=summary_id,
+            summary=self.summary,
+            source=self.source,
+        )
+
+    @property
+    def has_summary_metadata(self) -> bool:
+        """Checks if both summary and summary_offset are present."""
+        return self.summary is not None and self.summary_offset is not None
+
+    def apply(self, events: list[LLMConvertibleEvent]) -> list[LLMConvertibleEvent]:
+        """Applies the condensation to a list of events.
+
+        This method removes events that are marked to be forgotten and returns a new
+        list of events. If the summary metadata is present (both summary and offset),
+        the corresponding CondensationSummaryEvent will be inserted at the specified
+        offset _after_ the forgotten events have been removed.
+        """
+        output = [event for event in events if event.id not in self.forgotten_event_ids]
+        if self.has_summary_metadata:
+            assert self.summary_offset is not None
+            summary_event = self.summary_event
+            output.insert(self.summary_offset, summary_event)
+        return output
+
 
 class CondensationRequest(Event):
     """This action is used to request a condensation of the conversation history.

openhands/sdk/git/cached_repo.py

@@ -170,6 +170,25 @@ class GitHelper:
             # origin/HEAD may not be set (e.g., bare clone, or never configured)
             return None
 
+    def get_head_commit(self, repo_path: Path, timeout: int = 10) -> str:
+        """Get the current HEAD commit SHA.
+
+        Args:
+            repo_path: Path to the repository.
+            timeout: Timeout in seconds.
+
+        Returns:
+            Full 40-character commit SHA of HEAD.
+
+        Raises:
+            GitCommandError: If command fails.
+        """
+        return run_git_command(
+            ["git", "rev-parse", "HEAD"],
+            cwd=repo_path,
+            timeout=timeout,
+        )
+
 
 def try_cached_clone_or_update(
     url: str,

openhands/sdk/hooks/__init__.py

@@ -6,6 +6,7 @@ during agent execution, enabling deterministic control over agent behavior.
 """
 
 from openhands.sdk.hooks.config import (
+    HOOK_EVENT_FIELDS,
     HookConfig,
     HookDefinition,
     HookMatcher,
@@ -21,6 +22,7 @@ from openhands.sdk.hooks.types import HookDecision, HookEvent, HookEventType
 
 
 __all__ = [
+    "HOOK_EVENT_FIELDS",
     "HookConfig",
     "HookDefinition",
     "HookMatcher",

openhands/sdk/hooks/config.py

@@ -22,8 +22,9 @@ def _pascal_to_snake(name: str) -> str:
     return result
 
 
-# Valid snake_case field names for hook events
-_VALID_HOOK_FIELDS: frozenset[str] = frozenset(
+# Valid snake_case field names for hook events.
+# This is the single source of truth for hook event types.
+HOOK_EVENT_FIELDS: frozenset[str] = frozenset(
     {
         "pre_tool_use",
         "post_tool_use",
@@ -188,8 +189,8 @@ class HookConfig(BaseModel):
 
             if is_pascal_case:
                 # Validate that PascalCase key maps to a known field
-                if snake_key not in _VALID_HOOK_FIELDS:
-                    valid_types = ", ".join(sorted(_VALID_HOOK_FIELDS))
+                if snake_key not in HOOK_EVENT_FIELDS:
+                    valid_types = ", ".join(sorted(HOOK_EVENT_FIELDS))
                     raise ValueError(
                         f"Unknown event type '{key}'. Valid types: {valid_types}"
                     )
@@ -287,3 +288,42 @@ class HookConfig(BaseModel):
 
         with open(path, "w") as f:
             json.dump(self.model_dump(mode="json", exclude_defaults=True), f, indent=2)
+
+    @classmethod
+    def merge(cls, configs: list["HookConfig"]) -> "HookConfig | None":
+        """Merge multiple hook configs by concatenating handlers per event type.
+
+        Each hook config may have multiple event types (pre_tool_use,
+        post_tool_use, etc.). This method combines all matchers from all
+        configs for each event type.
+
+        Args:
+            configs: List of HookConfig objects to merge.
+
+        Returns:
+            A merged HookConfig with all matchers concatenated, or None if no configs
+            or if the result is empty.
+
+        Example:
+            >>> config1 = HookConfig(pre_tool_use=[HookMatcher(matcher="*")])
+            >>> config2 = HookConfig(pre_tool_use=[HookMatcher(matcher="terminal")])
+            >>> merged = HookConfig.merge([config1, config2])
+            >>> len(merged.pre_tool_use)  # Both matchers combined
+            2
+        """
+        if not configs:
+            return None
+
+        # Collect all matchers by event type using the canonical field list
+        collected: dict[str, list] = {field: [] for field in HOOK_EVENT_FIELDS}
+        for config in configs:
+            for field in HOOK_EVENT_FIELDS:
+                collected[field].extend(getattr(config, field))
+
+        merged = cls(**collected)
+
+        # Return None if the merged config is empty
+        if merged.is_empty():
+            return None
+
+        return merged

openhands/sdk/hooks/executor.py

@@ -8,6 +8,7 @@ from pydantic import BaseModel
 
 from openhands.sdk.hooks.config import HookDefinition
 from openhands.sdk.hooks.types import HookDecision, HookEvent
+from openhands.sdk.utils import sanitized_env
 
 
 class HookResult(BaseModel):
@@ -50,7 +51,7 @@ class HookExecutor:
     ) -> HookResult:
         """Execute a single hook."""
         # Prepare environment
-        hook_env = os.environ.copy()
+        hook_env = sanitized_env()
         hook_env["OPENHANDS_PROJECT_DIR"] = self.working_dir
         hook_env["OPENHANDS_SESSION_ID"] = event.session_id or ""
         hook_env["OPENHANDS_EVENT_TYPE"] = event.event_type

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/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",
+]

openhands/sdk/llm/auth/credentials.py

@@ -0,0 +1,157 @@
+"""Credential storage and retrieval for OAuth-based LLM authentication."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import warnings
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from openhands.sdk.logger import get_logger
+
+
+logger = get_logger(__name__)
+
+
+def get_credentials_dir() -> Path:
+    """Get the directory for storing credentials.
+
+    Uses XDG_DATA_HOME if set, otherwise defaults to ~/.local/share/openhands.
+    """
+    return Path.home() / ".openhands" / "auth"
+
+
+class OAuthCredentials(BaseModel):
+    """OAuth credentials for subscription-based LLM access."""
+
+    type: Literal["oauth"] = "oauth"
+    vendor: str = Field(description="The vendor/provider (e.g., 'openai')")
+    access_token: str = Field(description="The OAuth access token")
+    refresh_token: str = Field(description="The OAuth refresh token")
+    expires_at: int = Field(
+        description="Unix timestamp (ms) when the access token expires"
+    )
+
+    def is_expired(self) -> bool:
+        """Check if the access token is expired."""
+        # Add 60 second buffer to avoid edge cases
+        # Add 60 second buffer to avoid edge cases where token expires during request
+        return self.expires_at < (int(time.time() * 1000) + 60_000)
+
+
+class CredentialStore:
+    """Store and retrieve OAuth credentials for LLM providers."""
+
+    def __init__(self, credentials_dir: Path | None = None):
+        """Initialize the credential store.
+
+        Args:
+            credentials_dir: Optional custom directory for storing credentials.
+                           Defaults to ~/.local/share/openhands/auth/
+        """
+        self._credentials_dir = credentials_dir or get_credentials_dir()
+        logger.info(f"Using credentials directory: {self._credentials_dir}")
+
+    @property
+    def credentials_dir(self) -> Path:
+        """Get the credentials directory, creating it if necessary."""
+        self._credentials_dir.mkdir(parents=True, exist_ok=True)
+        # Set directory permissions to owner-only (rwx------)
+        if os.name != "nt":
+            self._credentials_dir.chmod(0o700)
+        return self._credentials_dir
+
+    def _get_credentials_file(self, vendor: str) -> Path:
+        """Get the path to the credentials file for a vendor."""
+        return self.credentials_dir / f"{vendor}_oauth.json"
+
+    def get(self, vendor: str) -> OAuthCredentials | None:
+        """Get stored credentials for a vendor.
+
+        Args:
+            vendor: The vendor/provider name (e.g., 'openai')
+
+        Returns:
+            OAuthCredentials if found and valid, None otherwise
+        """
+        creds_file = self._get_credentials_file(vendor)
+        if not creds_file.exists():
+            return None
+
+        try:
+            with open(creds_file) as f:
+                data = json.load(f)
+            return OAuthCredentials.model_validate(data)
+        except (json.JSONDecodeError, ValueError):
+            # Invalid credentials file, remove it
+            creds_file.unlink(missing_ok=True)
+            return None
+
+    def save(self, credentials: OAuthCredentials) -> None:
+        """Save credentials for a vendor.
+
+        Args:
+            credentials: The OAuth credentials to save
+        """
+        creds_file = self._get_credentials_file(credentials.vendor)
+        with open(creds_file, "w") as f:
+            json.dump(credentials.model_dump(), f, indent=2)
+        # Set restrictive permissions (owner read/write only)
+        # Note: On Windows, NTFS ACLs should be used instead
+        if os.name != "nt":  # Not Windows
+            creds_file.chmod(0o600)
+        else:
+            warnings.warn(
+                "File permissions on Windows should be manually restricted",
+                stacklevel=2,
+            )
+
+    def delete(self, vendor: str) -> bool:
+        """Delete stored credentials for a vendor.
+
+        Args:
+            vendor: The vendor/provider name
+
+        Returns:
+            True if credentials were deleted, False if they didn't exist
+        """
+        creds_file = self._get_credentials_file(vendor)
+        if creds_file.exists():
+            creds_file.unlink()
+            return True
+        return False
+
+    def update_tokens(
+        self,
+        vendor: str,
+        access_token: str,
+        refresh_token: str | None,
+        expires_in: int,
+    ) -> OAuthCredentials | None:
+        """Update tokens for an existing credential.
+
+        Args:
+            vendor: The vendor/provider name
+            access_token: New access token
+            refresh_token: New refresh token (if provided)
+            expires_in: Token expiry in seconds
+
+        Returns:
+            Updated credentials, or None if no existing credentials found
+        """
+        existing = self.get(vendor)
+        if existing is None:
+            return None
+
+        updated = OAuthCredentials(
+            vendor=vendor,
+            access_token=access_token,
+            refresh_token=refresh_token or existing.refresh_token,
+            expires_at=int(time.time() * 1000) + (expires_in * 1000),
+        )
+        self.save(updated)
+        return updated