openhands-sdk 1.5.0__py3-none-any.whl → 1.7.2__py3-none-any.whl

openhands/sdk/conversation/conversation.py

@@ -1,3 +1,4 @@
+from collections.abc import Mapping
 from pathlib import Path
 from typing import TYPE_CHECKING, Self, overload
 
@@ -7,11 +8,13 @@ from openhands.sdk.conversation.types import (
     ConversationCallbackType,
     ConversationID,
     ConversationTokenCallbackType,
+    StuckDetectionThresholds,
 )
 from openhands.sdk.conversation.visualizer import (
     ConversationVisualizerBase,
     DefaultConversationVisualizer,
 )
+from openhands.sdk.hooks import HookConfig
 from openhands.sdk.logger import get_logger
 from openhands.sdk.secret import SecretValue
 from openhands.sdk.workspace import LocalWorkspace, RemoteWorkspace
@@ -54,8 +57,12 @@ class Conversation:
         conversation_id: ConversationID | None = None,
         callbacks: list[ConversationCallbackType] | None = None,
         token_callbacks: list[ConversationTokenCallbackType] | None = None,
+        hook_config: HookConfig | None = None,
         max_iteration_per_run: int = 500,
         stuck_detection: bool = True,
+        stuck_detection_thresholds: (
+            StuckDetectionThresholds | Mapping[str, int] | None
+        ) = None,
         visualizer: (
             type[ConversationVisualizerBase] | ConversationVisualizerBase | None
         ) = DefaultConversationVisualizer,
@@ -71,8 +78,12 @@ class Conversation:
         conversation_id: ConversationID | None = None,
         callbacks: list[ConversationCallbackType] | None = None,
         token_callbacks: list[ConversationTokenCallbackType] | None = None,
+        hook_config: HookConfig | None = None,
         max_iteration_per_run: int = 500,
         stuck_detection: bool = True,
+        stuck_detection_thresholds: (
+            StuckDetectionThresholds | Mapping[str, int] | None
+        ) = None,
         visualizer: (
             type[ConversationVisualizerBase] | ConversationVisualizerBase | None
         ) = DefaultConversationVisualizer,
@@ -88,8 +99,12 @@ class Conversation:
         conversation_id: ConversationID | None = None,
         callbacks: list[ConversationCallbackType] | None = None,
         token_callbacks: list[ConversationTokenCallbackType] | None = None,
+        hook_config: HookConfig | None = None,
         max_iteration_per_run: int = 500,
         stuck_detection: bool = True,
+        stuck_detection_thresholds: (
+            StuckDetectionThresholds | Mapping[str, int] | None
+        ) = None,
         visualizer: (
             type[ConversationVisualizerBase] | ConversationVisualizerBase | None
         ) = DefaultConversationVisualizer,
@@ -112,8 +127,10 @@ class Conversation:
                 conversation_id=conversation_id,
                 callbacks=callbacks,
                 token_callbacks=token_callbacks,
+                hook_config=hook_config,
                 max_iteration_per_run=max_iteration_per_run,
                 stuck_detection=stuck_detection,
+                stuck_detection_thresholds=stuck_detection_thresholds,
                 visualizer=visualizer,
                 workspace=workspace,
                 secrets=secrets,
@@ -124,8 +141,10 @@ class Conversation:
             conversation_id=conversation_id,
             callbacks=callbacks,
             token_callbacks=token_callbacks,
+            hook_config=hook_config,
             max_iteration_per_run=max_iteration_per_run,
             stuck_detection=stuck_detection,
+            stuck_detection_thresholds=stuck_detection_thresholds,
             visualizer=visualizer,
             workspace=workspace,
             persistence_dir=persistence_dir,

openhands/sdk/conversation/exceptions.py

@@ -1,25 +1,50 @@
 from openhands.sdk.conversation.types import ConversationID
 
 
+ISSUE_URL = "https://github.com/OpenHands/software-agent-sdk/issues/new"
+
+
 class ConversationRunError(RuntimeError):
     """Raised when a conversation run fails.
 
-    Carries the conversation_id to make resuming/debugging easier while
-    preserving the original exception via exception chaining.
+    Carries the conversation_id and persistence_dir to make resuming/debugging
+    easier while preserving the original exception via exception chaining.
     """
 
     conversation_id: ConversationID
+    persistence_dir: str | None
     original_exception: BaseException
 
     def __init__(
         self,
         conversation_id: ConversationID,
         original_exception: BaseException,
+        persistence_dir: str | None = None,
         message: str | None = None,
     ) -> None:
         self.conversation_id = conversation_id
+        self.persistence_dir = persistence_dir
         self.original_exception = original_exception
-        default_msg = (
-            f"Conversation run failed for id={conversation_id}: {original_exception}"
+        default_msg = self._build_error_message(
+            conversation_id, original_exception, persistence_dir
         )
         super().__init__(message or default_msg)
+
+    @staticmethod
+    def _build_error_message(
+        conversation_id: ConversationID,
+        original_exception: BaseException,
+        persistence_dir: str | None,
+    ) -> str:
+        """Build a detailed error message with debugging information."""
+        lines = [
+            f"Conversation run failed for id={conversation_id}: {original_exception}",
+        ]
+
+        if persistence_dir:
+            lines.append(f"\nConversation logs are stored at: {persistence_dir}")
+            lines.append("\nTo help debug this issue, please file a bug report at:")
+            lines.append(f"  {ISSUE_URL}")
+            lines.append("and attach the conversation logs from the directory above.")
+
+        return "\n".join(lines)

openhands/sdk/conversation/impl/local_conversation.py

@@ -18,17 +18,20 @@ from openhands.sdk.conversation.types import (
     ConversationCallbackType,
     ConversationID,
     ConversationTokenCallbackType,
+    StuckDetectionThresholds,
 )
 from openhands.sdk.conversation.visualizer import (
     ConversationVisualizerBase,
     DefaultConversationVisualizer,
 )
 from openhands.sdk.event import (
+    CondensationRequest,
     MessageEvent,
     PauseEvent,
     UserRejectObservation,
 )
 from openhands.sdk.event.conversation_error import ConversationErrorEvent
+from openhands.sdk.hooks import HookConfig, HookEventProcessor, create_hook_callback
 from openhands.sdk.llm import LLM, Message, TextContent
 from openhands.sdk.llm.llm_registry import LLMRegistry
 from openhands.sdk.logger import get_logger
@@ -54,6 +57,7 @@ class LocalConversation(BaseConversation):
     _stuck_detector: StuckDetector | None
     llm_registry: LLMRegistry
     _cleanup_initiated: bool
+    _hook_processor: HookEventProcessor | None
 
     def __init__(
         self,
@@ -63,8 +67,12 @@ class LocalConversation(BaseConversation):
         conversation_id: ConversationID | None = None,
         callbacks: list[ConversationCallbackType] | None = None,
         token_callbacks: list[ConversationTokenCallbackType] | None = None,
+        hook_config: HookConfig | None = None,
         max_iteration_per_run: int = 500,
         stuck_detection: bool = True,
+        stuck_detection_thresholds: (
+            StuckDetectionThresholds | Mapping[str, int] | None
+        ) = None,
         visualizer: (
             type[ConversationVisualizerBase] | ConversationVisualizerBase | None
         ) = DefaultConversationVisualizer,
@@ -84,6 +92,7 @@ class LocalConversation(BaseConversation):
                       suffix their persistent filestore with this ID.
             callbacks: Optional list of callback functions to handle events
             token_callbacks: Optional list of callbacks invoked for streaming deltas
+            hook_config: Optional hook configuration to auto-wire session hooks
             max_iteration_per_run: Maximum number of iterations per run
             visualizer: Visualization configuration. Can be:
                        - ConversationVisualizerBase subclass: Class to instantiate
@@ -91,6 +100,11 @@ class LocalConversation(BaseConversation):
                        - ConversationVisualizerBase instance: Use custom visualizer
                        - None: No visualization
             stuck_detection: Whether to enable stuck detection
+            stuck_detection_thresholds: Optional configuration for stuck detection
+                      thresholds. Can be a StuckDetectionThresholds instance or
+                      a dict with keys: 'action_observation', 'action_error',
+                      'monologue', 'alternating_pattern'. Values are integers
+                      representing the number of repetitions before triggering.
         """
         super().__init__()  # Initialize with span tracking
         # Mark cleanup as initiated as early as possible to avoid races or partially
@@ -126,7 +140,20 @@ class LocalConversation(BaseConversation):
         def _default_callback(e):
             self._state.events.append(e)
 
-        composed_list = (callbacks if callbacks else []) + [_default_callback]
+        self._hook_processor = None
+        hook_callback = None
+        if hook_config is not None:
+            self._hook_processor, hook_callback = create_hook_callback(
+                hook_config=hook_config,
+                working_dir=str(self.workspace.working_dir),
+                session_id=str(desired_id),
+            )
+
+        callback_list = list(callbacks) if callbacks else []
+        if hook_callback is not None:
+            callback_list.insert(0, hook_callback)
+
+        composed_list = callback_list + [_default_callback]
         # Handle visualization configuration
         if isinstance(visualizer, ConversationVisualizerBase):
             # Use custom visualizer instance
@@ -158,7 +185,24 @@ class LocalConversation(BaseConversation):
         self.max_iteration_per_run = max_iteration_per_run
 
         # Initialize stuck detector
-        self._stuck_detector = StuckDetector(self._state) if stuck_detection else None
+        if stuck_detection:
+            # Convert dict to StuckDetectionThresholds if needed
+            if isinstance(stuck_detection_thresholds, Mapping):
+                threshold_config = StuckDetectionThresholds(
+                    **stuck_detection_thresholds
+                )
+            else:
+                threshold_config = stuck_detection_thresholds
+            self._stuck_detector = StuckDetector(
+                self._state,
+                thresholds=threshold_config,
+            )
+        else:
+            self._stuck_detector = None
+
+        if self._hook_processor is not None:
+            self._hook_processor.set_conversation_state(self._state)
+            self._hook_processor.run_session_start()
 
         with self._state:
             self.agent.init_state(self._state, on_event=self._on_event)
@@ -333,9 +377,24 @@ class LocalConversation(BaseConversation):
                     if (
                         self.state.execution_status
                         == ConversationExecutionStatus.WAITING_FOR_CONFIRMATION
-                        or iteration >= self.max_iteration_per_run
                     ):
                         break
+
+                    if iteration >= self.max_iteration_per_run:
+                        error_msg = (
+                            f"Agent reached maximum iterations limit "
+                            f"({self.max_iteration_per_run})."
+                        )
+                        logger.error(error_msg)
+                        self._state.execution_status = ConversationExecutionStatus.ERROR
+                        self._on_event(
+                            ConversationErrorEvent(
+                                source="environment",
+                                code="MaxIterationsReached",
+                                detail=error_msg,
+                            )
+                        )
+                        break
         except Exception as e:
             self._state.execution_status = ConversationExecutionStatus.ERROR
 
@@ -348,10 +407,10 @@ class LocalConversation(BaseConversation):
                 )
             )
 
-            # Re-raise with conversation id for better UX; include original traceback
-            raise ConversationRunError(self._state.id, e) from e
-        finally:
-            self._end_observability_span()
+            # Re-raise with conversation id and persistence dir for better UX
+            raise ConversationRunError(
+                self._state.id, e, persistence_dir=self._state.persistence_dir
+            ) from e
 
     def set_confirmation_policy(self, policy: ConfirmationPolicyBase) -> None:
         """Set the confirmation policy and store it in conversation state."""
@@ -435,16 +494,25 @@ class LocalConversation(BaseConversation):
 
     def close(self) -> None:
         """Close the conversation and clean up all tool executors."""
-        if self._cleanup_initiated:
+        # Use getattr for safety - object may be partially constructed
+        if getattr(self, "_cleanup_initiated", False):
             return
         self._cleanup_initiated = True
         logger.debug("Closing conversation and cleaning up tool executors")
+        hook_processor = getattr(self, "_hook_processor", None)
+        if hook_processor is not None:
+            hook_processor.run_session_end()
         try:
             self._end_observability_span()
         except AttributeError:
             # Object may be partially constructed; span fields may be missing.
             pass
-        for tool in self.agent.tools_map.values():
+        try:
+            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()
@@ -540,6 +608,55 @@ class LocalConversation(BaseConversation):
             events=self._state.events, llm=llm_to_use, max_length=max_length
         )
 
+    def condense(self) -> None:
+        """Synchronously force condense the conversation history.
+
+        If the agent is currently running, `condense()` will wait for the
+        ongoing step to finish before proceeding.
+
+        Raises ValueError if no compatible condenser exists.
+        """
+
+        # Check if condenser is configured and handles condensation requests
+        if (
+            self.agent.condenser is None
+            or not self.agent.condenser.handles_condensation_requests()
+        ):
+            condenser_info = (
+                "No condenser configured"
+                if self.agent.condenser is None
+                else (
+                    f"Condenser {type(self.agent.condenser).__name__} does not handle "
+                    "condensation requests"
+                )
+            )
+            raise ValueError(
+                f"Cannot condense conversation: {condenser_info}. "
+                "To enable manual condensation, configure an "
+                "LLMSummarizingCondenser:\n\n"
+                "from openhands.sdk.context.condenser import LLMSummarizingCondenser\n"
+                "agent = Agent(\n"
+                "    llm=your_llm,\n"
+                "    condenser=LLMSummarizingCondenser(\n"
+                "        llm=your_llm,\n"
+                "        max_size=120,\n"
+                "        keep_first=4\n"
+                "    )\n"
+                ")"
+            )
+
+        # Add a condensation request event
+        condensation_request = CondensationRequest()
+        self._on_event(condensation_request)
+
+        # Force the agent to take a single step to process the condensation request
+        # This will trigger the condenser if it handles condensation requests
+        with self._state:
+            # Take a single step to process the condensation request
+            self.agent.step(self, on_event=self._on_event, on_token=self._on_token)
+
+        logger.info("Condensation request processed")
+
     def __del__(self) -> None:
         """Ensure cleanup happens when conversation is destroyed."""
         try:

openhands/sdk/conversation/impl/remote_conversation.py

@@ -2,6 +2,7 @@ import asyncio
 import json
 import os
 import threading
+import time
 import uuid
 from collections.abc import Mapping
 from typing import SupportsIndex, overload
@@ -17,7 +18,11 @@ from openhands.sdk.conversation.events_list_base import EventsListBase
 from openhands.sdk.conversation.exceptions import ConversationRunError
 from openhands.sdk.conversation.secret_registry import SecretValue
 from openhands.sdk.conversation.state import ConversationExecutionStatus
-from openhands.sdk.conversation.types import ConversationCallbackType, ConversationID
+from openhands.sdk.conversation.types import (
+    ConversationCallbackType,
+    ConversationID,
+    StuckDetectionThresholds,
+)
 from openhands.sdk.conversation.visualizer import (
     ConversationVisualizerBase,
     DefaultConversationVisualizer,
@@ -28,6 +33,12 @@ from openhands.sdk.event.conversation_state import (
     ConversationStateUpdateEvent,
 )
 from openhands.sdk.event.llm_completion_log import LLMCompletionLogEvent
+from openhands.sdk.hooks import (
+    HookConfig,
+    HookEventProcessor,
+    HookEventType,
+    HookManager,
+)
 from openhands.sdk.llm import LLM, Message, TextContent
 from openhands.sdk.logger import DEBUG, get_logger
 from openhands.sdk.observability.laminar import observe
@@ -425,6 +436,8 @@ class RemoteConversation(BaseConversation):
     max_iteration_per_run: int
     workspace: RemoteWorkspace
     _client: httpx.Client
+    _hook_processor: HookEventProcessor | None
+    _cleanup_initiated: bool
 
     def __init__(
         self,
@@ -434,6 +447,10 @@ class RemoteConversation(BaseConversation):
         callbacks: list[ConversationCallbackType] | None = None,
         max_iteration_per_run: int = 500,
         stuck_detection: bool = True,
+        stuck_detection_thresholds: (
+            StuckDetectionThresholds | Mapping[str, int] | None
+        ) = None,
+        hook_config: HookConfig | None = None,
         visualizer: (
             type[ConversationVisualizerBase] | ConversationVisualizerBase | None
         ) = DefaultConversationVisualizer,
@@ -449,6 +466,12 @@ class RemoteConversation(BaseConversation):
             callbacks: Optional callbacks to receive events (not yet streamed)
             max_iteration_per_run: Max iterations configured on server
             stuck_detection: Whether to enable stuck detection on server
+            stuck_detection_thresholds: Optional configuration for stuck detection
+                      thresholds. Can be a StuckDetectionThresholds instance or
+                      a dict with keys: 'action_observation', 'action_error',
+                      'monologue', 'alternating_pattern'. Values are integers
+                      representing the number of repetitions before triggering.
+            hook_config: Optional hook configuration for session hooks
             visualizer: Visualization configuration. Can be:
                        - ConversationVisualizerBase subclass: Class to instantiate
                          (default: ConversationVisualizer)
@@ -462,6 +485,8 @@ class RemoteConversation(BaseConversation):
         self.max_iteration_per_run = max_iteration_per_run
         self.workspace = workspace
         self._client = workspace.client
+        self._hook_processor = None
+        self._cleanup_initiated = False
 
         if conversation_id is None:
             payload = {
@@ -476,6 +501,15 @@ class RemoteConversation(BaseConversation):
                     working_dir=self.workspace.working_dir
                 ).model_dump(),
             }
+            if stuck_detection_thresholds is not None:
+                # Convert to StuckDetectionThresholds if dict, then serialize
+                if isinstance(stuck_detection_thresholds, Mapping):
+                    threshold_config = StuckDetectionThresholds(
+                        **stuck_detection_thresholds
+                    )
+                else:
+                    threshold_config = stuck_detection_thresholds
+                payload["stuck_detection_thresholds"] = threshold_config.model_dump()
             resp = _send_request(
                 self._client, "POST", "/api/conversations", json=payload
             )
@@ -548,6 +582,25 @@ class RemoteConversation(BaseConversation):
             self.update_secrets(secret_values)
 
         self._start_observability_span(str(self._id))
+        if hook_config is not None:
+            unsupported = (
+                HookEventType.PRE_TOOL_USE,
+                HookEventType.POST_TOOL_USE,
+                HookEventType.USER_PROMPT_SUBMIT,
+                HookEventType.STOP,
+            )
+            if any(hook_config.has_hooks_for_event(t) for t in unsupported):
+                logger.warning(
+                    "RemoteConversation only supports SessionStart/SessionEnd hooks; "
+                    "other hook types will not be enforced."
+                )
+            hook_manager = HookManager(
+                config=hook_config,
+                working_dir=os.getcwd(),
+                session_id=str(self._id),
+            )
+            self._hook_processor = HookEventProcessor(hook_manager=hook_manager)
+            self._hook_processor.run_session_start()
 
     def _create_llm_completion_log_callback(self) -> ConversationCallbackType:
         """Create a callback that writes LLM completion logs to client filesystem."""
@@ -623,7 +676,25 @@ class RemoteConversation(BaseConversation):
         )
 
     @observe(name="conversation.run")
-    def run(self) -> None:
+    def run(
+        self,
+        blocking: bool = True,
+        poll_interval: float = 1.0,
+        timeout: float = 3600.0,
+    ) -> None:
+        """Trigger a run on the server.
+
+        Args:
+            blocking: If True (default), wait for the run to complete by polling
+                the server. If False, return immediately after triggering the run.
+            poll_interval: Time in seconds between status polls (only used when
+                blocking=True). Default is 1.0 second.
+            timeout: Maximum time in seconds to wait for the run to complete
+                (only used when blocking=True). Default is 3600 seconds.
+
+        Raises:
+            ConversationRunError: If the run fails or times out.
+        """
         # Trigger a run on the server using the dedicated run endpoint.
         # Let the server tell us if it's already running (409), avoiding an extra GET.
         try:
@@ -632,16 +703,74 @@ class RemoteConversation(BaseConversation):
                 "POST",
                 f"/api/conversations/{self._id}/run",
                 acceptable_status_codes={200, 201, 204, 409},
-                timeout=1800,
+                timeout=30,  # Short timeout for trigger request
             )
         except Exception as e:  # httpx errors already logged by _send_request
             # Surface conversation id to help resuming
             raise ConversationRunError(self._id, e) from e
+
         if resp.status_code == 409:
             logger.info("Conversation is already running; skipping run trigger")
+            if blocking:
+                # Still wait for the existing run to complete
+                self._wait_for_run_completion(poll_interval, timeout)
             return
+
         logger.info(f"run() triggered successfully: {resp}")
 
+        if blocking:
+            self._wait_for_run_completion(poll_interval, timeout)
+
+    def _wait_for_run_completion(
+        self,
+        poll_interval: float = 1.0,
+        timeout: float = 1800.0,
+    ) -> None:
+        """Poll the server until the conversation is no longer running.
+
+        Args:
+            poll_interval: Time in seconds between status polls.
+            timeout: Maximum time in seconds to wait.
+
+        Raises:
+            ConversationRunError: If the wait times out.
+        """
+        start_time = time.monotonic()
+
+        while True:
+            elapsed = time.monotonic() - start_time
+            if elapsed > timeout:
+                raise ConversationRunError(
+                    self._id,
+                    TimeoutError(
+                        f"Run timed out after {timeout} seconds. "
+                        "The conversation may still be running on the server."
+                    ),
+                )
+
+            try:
+                resp = _send_request(
+                    self._client,
+                    "GET",
+                    f"/api/conversations/{self._id}",
+                    timeout=30,
+                )
+                info = resp.json()
+                status = info.get("execution_status")
+
+                if status != ConversationExecutionStatus.RUNNING.value:
+                    logger.info(
+                        f"Run completed with status: {status} (elapsed: {elapsed:.1f}s)"
+                    )
+                    return
+
+            except Exception as e:
+                # Log but continue polling - transient network errors shouldn't
+                # stop us from waiting for the run to complete
+                logger.warning(f"Error polling status (will retry): {e}")
+
+            time.sleep(poll_interval)
+
     def set_confirmation_policy(self, policy: ConfirmationPolicyBase) -> None:
         payload = {"policy": policy.model_dump()}
         _send_request(
@@ -746,6 +875,21 @@ class RemoteConversation(BaseConversation):
         data = resp.json()
         return data["title"]
 
+    def condense(self) -> None:
+        """Force condensation of the conversation history.
+
+        This method sends a condensation request to the remote agent server.
+        The server will use the existing condensation request pattern to trigger
+        condensation if a condenser is configured and handles condensation requests.
+
+        The condensation will be applied on the server side and will modify the
+        conversation state by adding a condensation event to the history.
+
+        Raises:
+            HTTPError: If the server returns an error (e.g., no condenser configured).
+        """
+        _send_request(self._client, "POST", f"/api/conversations/{self._id}/condense")
+
     def close(self) -> None:
         """Close the conversation and clean up resources.
 
@@ -753,6 +897,11 @@ class RemoteConversation(BaseConversation):
         The workspace owns the client and will close it during its own cleanup.
         Closing it here would prevent the workspace from making cleanup API calls.
         """
+        if self._cleanup_initiated:
+            return
+        self._cleanup_initiated = True
+        if self._hook_processor is not None:
+            self._hook_processor.run_session_end()
         try:
             # Stop WebSocket client if it exists
             if self._ws_client:

openhands/sdk/conversation/state.py

@@ -42,6 +42,7 @@ class ConversationExecutionStatus(str, Enum):
     FINISHED = "finished"  # Conversation has completed the current task
     ERROR = "error"  # Conversation encountered an error (optional for future use)
     STUCK = "stuck"  # Conversation is stuck in a loop or unable to proceed
+    DELETING = "deleting"  # Conversation is in the process of being deleted
 
 
 class ConversationState(OpenHandsModel):
@@ -93,6 +94,18 @@ class ConversationState(OpenHandsModel):
         description="List of activated knowledge skills name",
     )
 
+    # Hook-blocked actions: action_id -> blocking reason
+    blocked_actions: dict[str, str] = Field(
+        default_factory=dict,
+        description="Actions blocked by PreToolUse hooks, keyed by action ID",
+    )
+
+    # Hook-blocked messages: message_id -> blocking reason
+    blocked_messages: dict[str, str] = Field(
+        default_factory=dict,
+        description="Messages blocked by UserPromptSubmit hooks, keyed by message ID",
+    )
+
     # Conversation statistics for LLM usage tracking
     stats: ConversationStats = Field(
         default_factory=ConversationStats,
@@ -166,7 +179,9 @@ class ConversationState(OpenHandsModel):
         Else: create fresh (agent required), persist base, and return.
         """
         file_store = (
-            LocalFileStore(persistence_dir) if persistence_dir else InMemoryFileStore()
+            LocalFileStore(persistence_dir, cache_limit_size=max_iterations)
+            if persistence_dir
+            else InMemoryFileStore()
         )
 
         try:
@@ -275,6 +290,32 @@ class ConversationState(OpenHandsModel):
                         f"State change callback failed for field {name}", exc_info=True
                     )
 
+    def block_action(self, action_id: str, reason: str) -> None:
+        """Persistently record a hook-blocked action."""
+        self.blocked_actions = {**self.blocked_actions, action_id: reason}
+
+    def pop_blocked_action(self, action_id: str) -> str | None:
+        """Remove and return a hook-blocked action reason, if present."""
+        if action_id not in self.blocked_actions:
+            return None
+        updated = dict(self.blocked_actions)
+        reason = updated.pop(action_id)
+        self.blocked_actions = updated
+        return reason
+
+    def block_message(self, message_id: str, reason: str) -> None:
+        """Persistently record a hook-blocked user message."""
+        self.blocked_messages = {**self.blocked_messages, message_id: reason}
+
+    def pop_blocked_message(self, message_id: str) -> str | None:
+        """Remove and return a hook-blocked message reason, if present."""
+        if message_id not in self.blocked_messages:
+            return None
+        updated = dict(self.blocked_messages)
+        reason = updated.pop(message_id)
+        self.blocked_messages = updated
+        return reason
+
     @staticmethod
     def get_unmatched_actions(events: Sequence[Event]) -> list[ActionEvent]:
         """Find actions in the event history that don't have matching observations.