openhands-sdk 1.8.1__py3-none-any.whl → 1.9.0__py3-none-any.whl

openhands/sdk/conversation/state.py

@@ -23,6 +23,7 @@ from openhands.sdk.security.confirmation_policy import (
     ConfirmationPolicyBase,
     NeverConfirm,
 )
+from openhands.sdk.utils.cipher import Cipher
 from openhands.sdk.utils.models import OpenHandsModel
 from openhands.sdk.workspace.base import BaseWorkspace
 
@@ -124,6 +125,7 @@ class ConversationState(OpenHandsModel):
     # ===== Private attrs (NOT Fields) =====
     _fs: FileStore = PrivateAttr()  # filestore for persistence
     _events: EventLog = PrivateAttr()  # now the storage for events
+    _cipher: Cipher | None = PrivateAttr(default=None)  # cipher for secret encryption
     _autosave_enabled: bool = PrivateAttr(
         default=False
     )  # to avoid recursion during init
@@ -166,8 +168,20 @@ class ConversationState(OpenHandsModel):
     def _save_base_state(self, fs: FileStore) -> None:
         """
         Persist base state snapshot (no events; events are file-backed).
+
+        If a cipher is configured, secrets will be encrypted. Otherwise, they
+        will be redacted (serialized as '**********').
         """
-        payload = self.model_dump_json(exclude_none=True)
+        context = {"cipher": self._cipher} if self._cipher else None
+        # Warn if secrets exist but no cipher is configured
+        if not self._cipher and self.secret_registry.secret_sources:
+            logger.warning(
+                f"Saving conversation state without cipher - "
+                f"{len(self.secret_registry.secret_sources)} secret(s) will be "
+                "redacted and lost on restore. Consider providing a cipher to "
+                "preserve secrets."
+            )
+        payload = self.model_dump_json(exclude_none=True, context=context)
         fs.write(BASE_STATE, payload)
 
     # ===== Factory: open-or-create (no load/save methods needed) =====
@@ -180,6 +194,7 @@ class ConversationState(OpenHandsModel):
         persistence_dir: str | None = None,
         max_iterations: int = 500,
         stuck_detection: bool = True,
+        cipher: Cipher | None = None,
     ) -> "ConversationState":
         """Create a new conversation state or resume from persistence.
 
@@ -203,6 +218,10 @@ class ConversationState(OpenHandsModel):
             persistence_dir: Directory for persisting state and events
             max_iterations: Maximum iterations per run
             stuck_detection: Whether to enable stuck detection
+            cipher: Optional cipher for encrypting/decrypting secrets in
+                    persisted state. If provided, secrets are encrypted when
+                    saving and decrypted when loading. If not provided, secrets
+                    are redacted (lost) on serialization.
 
         Returns:
             ConversationState ready for use
@@ -224,7 +243,9 @@ class ConversationState(OpenHandsModel):
 
         # ---- Resume path ----
         if base_text:
-            state = cls.model_validate(json.loads(base_text))
+            # Use cipher context for decrypting secrets if provided
+            context = {"cipher": cipher} if cipher else None
+            state = cls.model_validate(json.loads(base_text), context=context)
 
             # Restore the conversation with the same id
             if state.id != id:
@@ -236,6 +257,7 @@ class ConversationState(OpenHandsModel):
             # Attach event log early so we can read history for tool verification
             state._fs = file_store
             state._events = EventLog(file_store, dir_path=EVENTS_DIR)
+            state._cipher = cipher
 
             # Verify compatibility (agent class + tools)
             agent.verify(state.agent, events=state._events)
@@ -272,6 +294,7 @@ class ConversationState(OpenHandsModel):
         )
         state._fs = file_store
         state._events = EventLog(file_store, dir_path=EVENTS_DIR)
+        state._cipher = cipher
         state.stats = ConversationStats()
 
         state._save_base_state(file_store)  # initial snapshot

openhands/sdk/conversation/visualizer/base.py

@@ -65,3 +65,26 @@ class ConversationVisualizerBase(ABC):
             event: The event to visualize
         """
         pass
+
+    def create_sub_visualizer(
+        self,
+        agent_id: str,  # noqa: ARG002
+    ) -> "ConversationVisualizerBase | None":
+        """Create a visualizer for a sub-agent during delegation.
+
+        Override this method to support sub-agent visualization in multi-agent
+        delegation scenarios. The sub-visualizer will be used to display events
+        from the spawned sub-agent.
+
+        By default, returns None which means sub-agents will not have visualization.
+        Subclasses that support delegation (like DelegationVisualizer) should
+        override this method to create appropriate sub-visualizers.
+
+        Args:
+            agent_id: The identifier of the sub-agent being spawned
+
+        Returns:
+            A visualizer instance for the sub-agent, or None if sub-agent
+            visualization is not supported
+        """
+        return None

openhands/sdk/critic/__init__.py

@@ -1,15 +1,18 @@
-from openhands.sdk.critic.base import CriticBase, CriticResult
+from openhands.sdk.critic.base import CriticBase
 from openhands.sdk.critic.impl import (
     AgentFinishedCritic,
+    APIBasedCritic,
     EmptyPatchCritic,
     PassCritic,
 )
+from openhands.sdk.critic.result import CriticResult
 
 
 __all__ = [
     "CriticBase",
     "CriticResult",
     "AgentFinishedCritic",
+    "APIBasedCritic",
     "EmptyPatchCritic",
     "PassCritic",
 ]

openhands/sdk/critic/base.py

@@ -1,29 +1,15 @@
 import abc
 from collections.abc import Sequence
-from typing import ClassVar
+from typing import TYPE_CHECKING, Literal
 
-from pydantic import BaseModel, Field
+from pydantic import Field
 
-from openhands.sdk.event import LLMConvertibleEvent
+from openhands.sdk.critic.result import CriticResult
 from openhands.sdk.utils.models import DiscriminatedUnionMixin
 
 
-class CriticResult(BaseModel):
-    """A critic result is a score and a message."""
-
-    THRESHOLD: ClassVar[float] = 0.5
-
-    score: float = Field(
-        description="A predicted probability of success between 0 and 1.",
-        ge=0.0,
-        le=1.0,
-    )
-    message: str | None = Field(description="An optional message explaining the score.")
-
-    @property
-    def success(self) -> bool:
-        """Whether the agent is successful."""
-        return self.score >= CriticResult.THRESHOLD
+if TYPE_CHECKING:
+    from openhands.sdk.event.base import LLMConvertibleEvent
 
 
 class CriticBase(DiscriminatedUnionMixin, abc.ABC):
@@ -31,8 +17,19 @@ class CriticBase(DiscriminatedUnionMixin, abc.ABC):
     optional git patch, and returns a score about the quality of agent's action.
     """
 
+    mode: Literal["finish_and_message", "all_actions"] = Field(
+        default="finish_and_message",
+        description=(
+            "When to run critic evaluation:\n"
+            "- 'finish_and_message': Evaluate on FinishAction and agent"
+            " MessageEvent (default, minimal performance impact)\n"
+            "- 'all_actions': Evaluate after every agent action (WARNING: "
+            "significantly slower due to API calls on each action)"
+        ),
+    )
+
     @abc.abstractmethod
     def evaluate(
-        self, events: Sequence[LLMConvertibleEvent], git_patch: str | None = None
+        self, events: Sequence["LLMConvertibleEvent"], git_patch: str | None = None
     ) -> CriticResult:
         pass

openhands/sdk/critic/impl/__init__.py

@@ -1,12 +1,14 @@
 """Critic implementations module."""
 
 from openhands.sdk.critic.impl.agent_finished import AgentFinishedCritic
+from openhands.sdk.critic.impl.api import APIBasedCritic
 from openhands.sdk.critic.impl.empty_patch import EmptyPatchCritic
 from openhands.sdk.critic.impl.pass_critic import PassCritic
 
 
 __all__ = [
     "AgentFinishedCritic",
+    "APIBasedCritic",
     "EmptyPatchCritic",
     "PassCritic",
 ]

openhands/sdk/critic/impl/agent_finished.py

@@ -7,13 +7,17 @@ This critic evaluates whether an agent properly finished a task by checking:
 """
 
 from collections.abc import Sequence
+from typing import TYPE_CHECKING
 
 from openhands.sdk.critic.base import CriticBase, CriticResult
-from openhands.sdk.event import ActionEvent, LLMConvertibleEvent
 from openhands.sdk.logger import get_logger
 from openhands.sdk.tool.builtins.finish import FinishAction
 
 
+if TYPE_CHECKING:
+    from openhands.sdk.event.base import LLMConvertibleEvent
+
+
 logger = get_logger(__name__)
 
 
@@ -27,7 +31,7 @@ class AgentFinishedCritic(CriticBase):
     """
 
     def evaluate(
-        self, events: Sequence[LLMConvertibleEvent], git_patch: str | None = None
+        self, events: Sequence["LLMConvertibleEvent"], git_patch: str | None = None
     ) -> CriticResult:
         """
         Evaluate if an agent properly finished with a non-empty git patch.
@@ -66,18 +70,18 @@ class AgentFinishedCritic(CriticBase):
             message="Agent completed with FinishAction and non-empty patch",
         )
 
-    def _has_finish_action(self, events: Sequence[LLMConvertibleEvent]) -> bool:
+    def _has_finish_action(self, events: Sequence["LLMConvertibleEvent"]) -> bool:
         """Check if the last action was a FinishAction."""
         if not events:
             return False
 
         # Look for the last ActionEvent in the history
+        from openhands.sdk.event.llm_convertible.action import ActionEvent
+
         for event in reversed(events):
             if isinstance(event, ActionEvent):
-                # Check if this is a FinishAction
                 if event.action and isinstance(event.action, FinishAction):
                     return True
-                # If we find any other action type, the agent didn't finish
                 return False
 
         return False

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

@@ -0,0 +1,18 @@
+from openhands.sdk.critic.impl.api.client import (
+    ClassificationItem,
+    ClassificationResponse,
+    CriticClient,
+    LabelProbMap,
+    UsageTokens,
+)
+from openhands.sdk.critic.impl.api.critic import APIBasedCritic
+
+
+__all__ = [
+    "APIBasedCritic",
+    "CriticClient",
+    "ClassificationItem",
+    "ClassificationResponse",
+    "LabelProbMap",
+    "UsageTokens",
+]

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

@@ -0,0 +1,232 @@
+"""
+Standalone chat template implementation using Jinja2.
+
+This module provides a lightweight implementation of chat template rendering
+that is compatible with HuggingFace transformers but removes the dependency
+on the full transformers library.
+
+The implementation follows the same approach as transformers:
+- Uses Jinja2 for template rendering
+- Loads templates dynamically from tokenizer_config.json
+- Supports caching of compiled templates and fetched configs
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Sequence
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+from urllib.error import URLError
+from urllib.request import Request, urlopen
+
+import jinja2
+from jinja2.ext import loopcontrols
+from jinja2.sandbox import ImmutableSandboxedEnvironment
+
+
+# Cache directory for downloaded tokenizer configs
+CACHE_DIR = Path.home() / ".cache" / "chat_templates"
+
+
+def _get_cache_path(tokenizer_name: str) -> Path:
+    """Get the cache path for a tokenizer config."""
+    # Create a safe filename from the tokenizer name
+    safe_name = hashlib.md5(tokenizer_name.encode()).hexdigest()
+    return CACHE_DIR / f"{safe_name}_tokenizer_config.json"
+
+
+def _fetch_tokenizer_config(
+    tokenizer_name: str, use_cache: bool = True
+) -> dict[str, Any]:
+    """
+    Fetch tokenizer_config.json from HuggingFace Hub.
+
+    Args:
+        tokenizer_name: The HuggingFace model/tokenizer name
+            (e.g., "Qwen/Qwen3-4B-Instruct-2507")
+        use_cache: Whether to use cached config if available
+
+    Returns:
+        The parsed tokenizer config dictionary
+    """
+    cache_path = _get_cache_path(tokenizer_name)
+
+    # Try to load from cache
+    if use_cache and cache_path.exists():
+        with open(cache_path, encoding="utf-8") as f:
+            return json.load(f)
+
+    # Fetch from HuggingFace Hub
+    url = f"https://huggingface.co/{tokenizer_name}/raw/main/tokenizer_config.json"
+
+    try:
+        request = Request(url, headers={"User-Agent": "chat_template/1.0"})
+        with urlopen(request, timeout=30) as response:
+            config = json.loads(response.read().decode("utf-8"))
+    except URLError as e:
+        raise RuntimeError(f"Failed to fetch tokenizer config from {url}: {e}")
+
+    # Cache the config
+    if use_cache:
+        CACHE_DIR.mkdir(parents=True, exist_ok=True)
+        with open(cache_path, "w", encoding="utf-8") as f:
+            json.dump(config, f)
+
+    return config
+
+
+@lru_cache(maxsize=16)
+def _compile_jinja_template(chat_template: str) -> jinja2.Template:
+    """
+    Compile a Jinja2 chat template.
+
+    This matches the transformers implementation with custom tojson filter
+    and other utilities.
+    """
+
+    def raise_exception(message: str) -> None:
+        raise jinja2.exceptions.TemplateError(message)
+
+    def tojson(
+        x: Any,
+        ensure_ascii: bool = False,
+        indent: int | None = None,
+        separators: tuple[str, str] | None = None,
+        sort_keys: bool = False,
+    ) -> str:
+        # Match the transformers implementation - no HTML escaping
+        return json.dumps(
+            x,
+            ensure_ascii=ensure_ascii,
+            indent=indent,
+            separators=separators,
+            sort_keys=sort_keys,
+        )
+
+    jinja_env = ImmutableSandboxedEnvironment(
+        trim_blocks=True,
+        lstrip_blocks=True,
+        extensions=[loopcontrols],
+    )
+    jinja_env.filters["tojson"] = tojson
+    jinja_env.globals["raise_exception"] = raise_exception
+
+    return jinja_env.from_string(chat_template)
+
+
+class ChatTemplateRenderer:
+    """
+    A lightweight chat template renderer compatible with HuggingFace transformers.
+
+    This class can dynamically load templates from HuggingFace Hub or use
+    provided templates directly.
+    """
+
+    def __init__(
+        self,
+        tokenizer_name: str | None = None,
+        chat_template: str | None = None,
+        use_cache: bool = True,
+    ):
+        """
+        Initialize the renderer.
+
+        Args:
+            tokenizer_name: HuggingFace tokenizer name to load template from.
+                If provided, will fetch tokenizer_config.json from
+                HuggingFace Hub.
+            chat_template: Direct Jinja2 template string.
+                If provided, tokenizer_name is ignored.
+            use_cache: Whether to cache fetched tokenizer configs.
+        """
+        if chat_template is not None:
+            self._chat_template = chat_template
+        elif tokenizer_name is not None:
+            config = _fetch_tokenizer_config(tokenizer_name, use_cache=use_cache)
+            self._chat_template = config.get("chat_template")
+            if self._chat_template is None:
+                raise ValueError(
+                    f"No chat_template found in tokenizer config for {tokenizer_name}"
+                )
+        else:
+            raise ValueError("Either tokenizer_name or chat_template must be provided")
+
+        self._compiled_template = _compile_jinja_template(self._chat_template)
+
+    @property
+    def chat_template(self) -> str:
+        """The raw Jinja2 chat template string."""
+        assert self._chat_template is not None
+        return self._chat_template
+
+    def apply_chat_template(
+        self,
+        messages: Sequence[dict[str, Any]],
+        tools: Sequence[dict[str, Any]] | None = None,
+        add_generation_prompt: bool = False,
+        **kwargs: Any,
+    ) -> str:
+        """
+        Apply the chat template to format messages.
+
+        Args:
+            messages: List of message dicts with 'role' and 'content' keys.
+            tools: Optional list of tool definitions for function calling.
+            add_generation_prompt: If True, append assistant prompt at the end.
+            **kwargs: Additional template variables.
+
+        Returns:
+            Formatted string ready for tokenization.
+        """
+        return self._compiled_template.render(
+            messages=messages,
+            tools=tools,
+            add_generation_prompt=add_generation_prompt,
+            **kwargs,
+        )
+
+
+# Convenience function for simple use cases
+def apply_chat_template(
+    messages: Sequence[dict[str, Any]],
+    tokenizer_name: str | None = None,
+    chat_template: str | None = None,
+    tools: Sequence[dict[str, Any]] | None = None,
+    add_generation_prompt: bool = False,
+    use_cache: bool = True,
+    **kwargs: Any,
+) -> str:
+    """
+    Apply a chat template to format messages.
+
+    This is a convenience function that creates a renderer and applies the
+    template. For repeated use with the same tokenizer, prefer using
+    ChatTemplateRenderer directly.
+
+    Args:
+        messages: List of message dicts with 'role' and 'content' keys.
+        tokenizer_name: HuggingFace tokenizer name to load template from.
+        chat_template: Direct Jinja2 template string.
+            If provided, tokenizer_name is ignored.
+        tools: Optional list of tool definitions for function calling.
+        add_generation_prompt: If True, append assistant prompt at the end.
+        use_cache: Whether to cache fetched tokenizer configs.
+        **kwargs: Additional template variables.
+
+    Returns:
+        Formatted string ready for tokenization.
+    """
+    renderer = ChatTemplateRenderer(
+        tokenizer_name=tokenizer_name,
+        chat_template=chat_template,
+        use_cache=use_cache,
+    )
+    return renderer.apply_chat_template(
+        messages=messages,
+        tools=tools,
+        add_generation_prompt=add_generation_prompt,
+        **kwargs,
+    )