feat(sdk/io): add PostgreSQLFileStore for persistent EventLog

examples/02_remote_agent_server/06_custom_tool/custom_tools/log_data.py

@@ -8,7 +8,7 @@
 import json
 from collections.abc import Sequence
 from datetime import UTC, datetime
-from enum import Enum
+from enum import StrEnum
 from pathlib import Path
 from typing import Any
 
@@ -27,7 +27,7 @@
 # --- Enums and Models ---
 
 
-class LogLevel(str, Enum):
+class LogLevel(StrEnum):
     """Log level for entries."""
 
     DEBUG = "debug"

openhands-agent-server/openhands/agent_server/agent-server.spec

@@ -68,6 +68,7 @@ a = Analysis(
         *collect_data_files("fastmcp"),
         *collect_data_files("mcp"),
         *collect_data_files("fakeredis"),  # Required for commands.json used by fakeredis ACL
+        *collect_data_files("binaryornot"),  # Required for binaryornot.data signatures at runtime
         *get_fakeredis_data(),  # Ensure fakeredis/model/ directory structure exists
 
         # OpenHands SDK prompt templates (adjusted for shallow namespace layout)

openhands-agent-server/openhands/agent_server/models.py

@@ -1,6 +1,6 @@
 from abc import ABC
 from datetime import datetime
-from enum import Enum
+from enum import Enum, StrEnum
 from typing import Any
 from uuid import UUID, uuid4
 
@@ -51,7 +51,7 @@ class ServerErrorEvent(Event):
     detail: str = Field(description="Details about the error")
 
 
-class ConversationSortOrder(str, Enum):
+class ConversationSortOrder(StrEnum):
     """Enum for conversation sorting options."""
 
     CREATED_AT = "CREATED_AT"
@@ -60,7 +60,7 @@ class ConversationSortOrder(str, Enum):
     UPDATED_AT_DESC = "UPDATED_AT_DESC"
 
 
-class EventSortOrder(str, Enum):
+class EventSortOrder(StrEnum):
     """Enum for event sorting options."""
 
     TIMESTAMP = "TIMESTAMP"

openhands-sdk/openhands/sdk/agent/agent.py

@@ -462,8 +462,8 @@ def _execute_actions(
         batch.emit(on_event)
         batch.finalize(
             on_event=on_event,
-            check_iterative_refinement=lambda ae: (
-                self._check_iterative_refinement(conversation, ae)
+            check_iterative_refinement=lambda ae: self._check_iterative_refinement(
+                conversation, ae
             ),
             mark_finished=lambda: setattr(
                 state,

openhands-sdk/openhands/sdk/conversation/impl/local_conversation.py

@@ -37,7 +37,7 @@
 )
 from openhands.sdk.event.conversation_error import ConversationErrorEvent
 from openhands.sdk.hooks import HookConfig, HookEventProcessor, create_hook_callback
-from openhands.sdk.io import LocalFileStore
+from openhands.sdk.io import FileStore, LocalFileStore
 from openhands.sdk.llm import LLM, Message, TextContent
 from openhands.sdk.llm.llm_profile_store import LLMProfileStore
 from openhands.sdk.llm.llm_registry import LLMRegistry
@@ -108,6 +108,7 @@ def __init__(
         delete_on_close: bool = True,
         cipher: Cipher | None = None,
         tags: dict[str, str] | None = None,
+        file_store: FileStore | None = None,
         **_: object,
     ):
         """Initialize the conversation.
@@ -188,6 +189,7 @@ def __init__(
             stuck_detection=stuck_detection,
             cipher=cipher,
             tags=tags,
+            file_store=file_store,
         )
 
         self._pin_prompt_cache_key()

openhands-sdk/openhands/sdk/conversation/state.py

@@ -2,7 +2,7 @@
 import json
 from collections.abc import Callable, Sequence
 from contextlib import AbstractContextManager
-from enum import Enum
+from enum import StrEnum
 from pathlib import Path
 from typing import Any, Self
 
@@ -43,7 +43,7 @@
 logger = get_logger(__name__)
 
 
-class ConversationExecutionStatus(str, Enum):
+class ConversationExecutionStatus(StrEnum):
     """Enum representing the current execution state of the conversation."""
 
     IDLE = "idle"  # Conversation is ready to receive tasks
@@ -282,6 +282,7 @@ def create(
         stuck_detection: bool = True,
         cipher: Cipher | None = None,
         tags: dict[str, str] | None = None,
+        file_store: FileStore | None = None,
     ) -> "ConversationState":
         """Create a new conversation state or resume from persistence.
 
@@ -311,6 +312,12 @@ def create(
                     are redacted (lost) on serialization.
             tags: Optional key-value tags for the conversation. Keys must be
                   lowercase alphanumeric, values up to 256 characters.
+            file_store: Optional pre-configured FileStore for event
+                    persistence. When provided, ``persistence_dir`` is **not**
+                    used for EventLog storage (the supplied store takes
+                    precedence). Note that ``persistence_dir`` is still read
+                    for ``env_observation_persistence_dir`` — pass both if you
+                    need observation persistence alongside a custom store.
 
         Returns:
             ConversationState ready for use
@@ -319,16 +326,17 @@ def create(
             ValueError: If conversation ID or tools mismatch on restore
             ValidationError: If agent or other fields fail Pydantic validation
         """
-        if persistence_dir:
-            file_store = LocalFileStore(
-                persistence_dir, cache_limit_size=max_iterations
-            )
-        else:
-            logger.warning(
-                "No persistence_dir provided; falling back to InMemoryFileStore. "
-                "EventLog data will not persist across requests."
-            )
-            file_store = InMemoryFileStore()
+        if file_store is None:
+            if persistence_dir:
+                file_store = LocalFileStore(
+                    persistence_dir, cache_limit_size=max_iterations
+                )
+            else:
+                logger.warning(
+                    "No persistence_dir provided; falling back to InMemoryFileStore. "
+                    "EventLog data will not persist across requests."
+                )
+                file_store = InMemoryFileStore()
 
         try:
             base_text = file_store.read(BASE_STATE)

openhands-sdk/openhands/sdk/hooks/config.py

@@ -3,7 +3,7 @@
 import json
 import logging
 import re
-from enum import Enum
+from enum import StrEnum
 from pathlib import Path
 from typing import Any
 
@@ -36,7 +36,7 @@ def _pascal_to_snake(name: str) -> str:
 )
 
 
-class HookType(str, Enum):
+class HookType(StrEnum):
     """Types of hooks that can be executed."""
 
     COMMAND = "command"  # Shell command executed via subprocess

openhands-sdk/openhands/sdk/hooks/types.py

@@ -1,12 +1,12 @@
 """Hook event types and data structures."""
 
-from enum import Enum
+from enum import StrEnum
 from typing import Any
 
 from pydantic import BaseModel, Field
 
 
-class HookEventType(str, Enum):
+class HookEventType(StrEnum):
     """Types of hook events that can trigger hooks."""
 
     PRE_TOOL_USE = "PreToolUse"
@@ -32,7 +32,7 @@ class HookEvent(BaseModel):
     model_config = {"use_enum_values": True}
 
 
-class HookDecision(str, Enum):
+class HookDecision(StrEnum):
     """Decisions a hook can make about an operation."""
 
     ALLOW = "allow"

openhands-sdk/openhands/sdk/io/__init__.py

@@ -3,4 +3,14 @@
 from .memory import InMemoryFileStore
 
 
-__all__ = ["LocalFileStore", "FileStore", "InMemoryFileStore"]
+try:
+    from .postgresql import PostgreSQLFileStore
+
+    __all__ = [
+        "LocalFileStore",
+        "FileStore",
+        "InMemoryFileStore",
+        "PostgreSQLFileStore",
+    ]
+except ImportError:
+    __all__ = ["LocalFileStore", "FileStore", "InMemoryFileStore"]