openhands-sdk 1.7.0__py3-none-any.whl → 1.7.1__py3-none-any.whl

openhands/sdk/conversation/state.py

@@ -94,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,
@@ -167,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:
@@ -276,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.

openhands/sdk/hooks/__init__.py

@@ -0,0 +1,30 @@
+"""
+OpenHands Hooks System - Event-driven hooks for automation and control.
+
+Hooks are event-driven scripts that execute at specific lifecycle events
+during agent execution, enabling deterministic control over agent behavior.
+"""
+
+from openhands.sdk.hooks.config import HookConfig, HookDefinition, HookMatcher
+from openhands.sdk.hooks.conversation_hooks import (
+    HookEventProcessor,
+    create_hook_callback,
+)
+from openhands.sdk.hooks.executor import HookExecutor, HookResult
+from openhands.sdk.hooks.manager import HookManager
+from openhands.sdk.hooks.types import HookDecision, HookEvent, HookEventType
+
+
+__all__ = [
+    "HookConfig",
+    "HookDefinition",
+    "HookMatcher",
+    "HookExecutor",
+    "HookResult",
+    "HookManager",
+    "HookEvent",
+    "HookEventType",
+    "HookDecision",
+    "HookEventProcessor",
+    "create_hook_callback",
+]

openhands/sdk/hooks/config.py

@@ -0,0 +1,180 @@
+"""Hook configuration loading and management."""
+
+import json
+import logging
+import re
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from openhands.sdk.hooks.types import HookEventType
+
+
+logger = logging.getLogger(__name__)
+
+
+class HookType(str, Enum):
+    """Types of hooks that can be executed."""
+
+    COMMAND = "command"  # Shell command executed via subprocess
+    PROMPT = "prompt"  # LLM-based evaluation (future)
+
+
+class HookDefinition(BaseModel):
+    """A single hook definition."""
+
+    type: HookType = HookType.COMMAND
+    command: str
+    timeout: int = 60
+
+
+class HookMatcher(BaseModel):
+    """Matches events to hooks based on patterns.
+
+    Supports exact match, wildcard (*), and regex (auto-detected or /pattern/).
+    """
+
+    matcher: str = "*"
+    hooks: list[HookDefinition] = Field(default_factory=list)
+
+    # Regex metacharacters that indicate a pattern should be treated as regex
+    _REGEX_METACHARACTERS = set("|.*+?[]()^$\\")
+
+    def matches(self, tool_name: str | None) -> bool:
+        """Check if this matcher matches the given tool name."""
+        # Wildcard matches everything
+        if self.matcher == "*" or self.matcher == "":
+            return True
+
+        if tool_name is None:
+            return self.matcher in ("*", "")
+
+        # Check for explicit regex pattern (enclosed in /)
+        is_regex = (
+            self.matcher.startswith("/")
+            and self.matcher.endswith("/")
+            and len(self.matcher) > 2
+        )
+        if is_regex:
+            pattern = self.matcher[1:-1]
+            try:
+                return bool(re.fullmatch(pattern, tool_name))
+            except re.error:
+                return False
+
+        # Auto-detect regex: if matcher contains metacharacters, treat as regex
+        if any(c in self.matcher for c in self._REGEX_METACHARACTERS):
+            try:
+                return bool(re.fullmatch(self.matcher, tool_name))
+            except re.error:
+                # Invalid regex, fall through to exact match
+                pass
+
+        # Exact match
+        return self.matcher == tool_name
+
+
+class HookConfig(BaseModel):
+    """Configuration for all hooks, loaded from .openhands/hooks.json."""
+
+    hooks: dict[str, list[HookMatcher]] = Field(default_factory=dict)
+
+    @classmethod
+    def load(
+        cls, path: str | Path | None = None, working_dir: str | Path | None = None
+    ) -> "HookConfig":
+        """Load config from path or search .openhands/hooks.json locations.
+
+        Args:
+            path: Explicit path to hooks.json file. If provided, working_dir is ignored.
+            working_dir: Project directory for discovering .openhands/hooks.json.
+                Falls back to cwd if not provided.
+        """
+        if path is None:
+            # Search for hooks.json in standard locations
+            base_dir = Path(working_dir) if working_dir else Path.cwd()
+            search_paths = [
+                base_dir / ".openhands" / "hooks.json",
+                Path.home() / ".openhands" / "hooks.json",
+            ]
+            for search_path in search_paths:
+                if search_path.exists():
+                    path = search_path
+                    break
+
+        if path is None:
+            return cls()
+
+        path = Path(path)
+        if not path.exists():
+            return cls()
+
+        try:
+            with open(path) as f:
+                data = json.load(f)
+            return cls.from_dict(data)
+        except (json.JSONDecodeError, OSError) as e:
+            # Log warning but don't fail - just return empty config
+            logger.warning(f"Failed to load hooks from {path}: {e}")
+            return cls()
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "HookConfig":
+        """Create HookConfig from a dictionary."""
+        hooks_data = data.get("hooks", {})
+        hooks: dict[str, list[HookMatcher]] = {}
+
+        for event_type, matchers in hooks_data.items():
+            if not isinstance(matchers, list):
+                continue
+
+            hooks[event_type] = []
+            for matcher_data in matchers:
+                if isinstance(matcher_data, dict):
+                    # Parse hooks within the matcher
+                    hook_defs = []
+                    for hook_data in matcher_data.get("hooks", []):
+                        if isinstance(hook_data, dict):
+                            hook_defs.append(HookDefinition(**hook_data))
+
+                    hooks[event_type].append(
+                        HookMatcher(
+                            matcher=matcher_data.get("matcher", "*"),
+                            hooks=hook_defs,
+                        )
+                    )
+
+        return cls(hooks=hooks)
+
+    def get_hooks_for_event(
+        self, event_type: HookEventType, tool_name: str | None = None
+    ) -> list[HookDefinition]:
+        """Get all hooks that should run for an event."""
+        event_key = event_type.value
+        matchers = self.hooks.get(event_key, [])
+
+        result: list[HookDefinition] = []
+        for matcher in matchers:
+            if matcher.matches(tool_name):
+                result.extend(matcher.hooks)
+
+        return result
+
+    def has_hooks_for_event(self, event_type: HookEventType) -> bool:
+        """Check if there are any hooks configured for an event type."""
+        return event_type.value in self.hooks and len(self.hooks[event_type.value]) > 0
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary format for serialization."""
+        hooks_dict = {k: [m.model_dump() for m in v] for k, v in self.hooks.items()}
+        return {"hooks": hooks_dict}
+
+    def save(self, path: str | Path) -> None:
+        """Save hook configuration to a JSON file."""
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+        with open(path, "w") as f:
+            json.dump(self.to_dict(), f, indent=2)

openhands/sdk/hooks/conversation_hooks.py

@@ -0,0 +1,227 @@
+"""Hook integration for conversations."""
+
+from typing import TYPE_CHECKING, Any
+
+from openhands.sdk.event import ActionEvent, Event, MessageEvent, ObservationEvent
+from openhands.sdk.hooks.config import HookConfig
+from openhands.sdk.hooks.manager import HookManager
+from openhands.sdk.hooks.types import HookEventType
+from openhands.sdk.logger import get_logger
+
+
+if TYPE_CHECKING:
+    from openhands.sdk.conversation.state import ConversationState
+
+logger = get_logger(__name__)
+
+
+class HookEventProcessor:
+    """Processes events and runs hooks at appropriate points.
+
+    Call set_conversation_state() after creating Conversation for blocking to work.
+
+    Note on persistence: HookEvent/HookResult are ephemeral (for hook script I/O).
+    If hook execution traces need to be persisted (e.g., for observability), create
+    a HookExecutionObservation inheriting from Observation and emit it through the
+    event stream, rather than modifying these hook classes.
+    """
+
+    def __init__(
+        self,
+        hook_manager: HookManager,
+        original_callback: Any = None,
+    ):
+        self.hook_manager = hook_manager
+        self.original_callback = original_callback
+        self._conversation_state: ConversationState | None = None
+
+    def set_conversation_state(self, state: "ConversationState") -> None:
+        """Set conversation state for blocking support."""
+        self._conversation_state = state
+
+    def on_event(self, event: Event) -> None:
+        """Process an event and run appropriate hooks."""
+        # Run PreToolUse hooks for action events
+        if isinstance(event, ActionEvent) and event.action is not None:
+            self._handle_pre_tool_use(event)
+
+        # Run PostToolUse hooks for observation events
+        if isinstance(event, ObservationEvent):
+            self._handle_post_tool_use(event)
+
+        # Run UserPromptSubmit hooks for user messages
+        if isinstance(event, MessageEvent) and event.source == "user":
+            self._handle_user_prompt_submit(event)
+
+        # Call original callback
+        if self.original_callback:
+            self.original_callback(event)
+
+    def _handle_pre_tool_use(self, event: ActionEvent) -> None:
+        """Handle PreToolUse hooks. Blocked actions are marked in conversation state."""
+        if not self.hook_manager.has_hooks(HookEventType.PRE_TOOL_USE):
+            return
+
+        tool_name = event.tool_name
+        tool_input = {}
+
+        # Extract tool input from action
+        if event.action is not None:
+            try:
+                tool_input = event.action.model_dump()
+            except Exception as e:
+                logger.debug(f"Could not extract tool input: {e}")
+
+        should_continue, results = self.hook_manager.run_pre_tool_use(
+            tool_name=tool_name,
+            tool_input=tool_input,
+        )
+
+        if not should_continue:
+            reason = self.hook_manager.get_blocking_reason(results)
+            logger.warning(f"Hook blocked action {tool_name}: {reason}")
+
+            # Mark this action as blocked in the conversation state
+            # The Agent will check this and emit a rejection instead of executing
+            if self._conversation_state is not None:
+                block_reason = reason or "Blocked by hook"
+                self._conversation_state.block_action(event.id, block_reason)
+            else:
+                logger.warning(
+                    "Cannot block action: conversation state not set. "
+                    "Call processor.set_conversation_state(conversation.state) "
+                    "after creating the Conversation."
+                )
+
+    def _handle_post_tool_use(self, event: ObservationEvent) -> None:
+        """Handle PostToolUse hooks after an action completes."""
+        if not self.hook_manager.has_hooks(HookEventType.POST_TOOL_USE):
+            return
+
+        # O(1) lookup of corresponding action from state events
+        action_event = None
+        if self._conversation_state is not None:
+            try:
+                idx = self._conversation_state.events.get_index(event.action_id)
+                event_at_idx = self._conversation_state.events[idx]
+                if isinstance(event_at_idx, ActionEvent):
+                    action_event = event_at_idx
+            except KeyError:
+                pass  # action not found
+
+        if action_event is None:
+            return
+
+        tool_name = event.tool_name
+        tool_input: dict[str, Any] = {}
+        tool_response: dict[str, Any] = {}
+
+        # Extract tool input from action
+        if action_event.action is not None:
+            try:
+                tool_input = action_event.action.model_dump()
+            except Exception as e:
+                logger.debug(f"Could not extract tool input: {e}")
+
+        # Extract structured tool response from observation
+        if event.observation is not None:
+            try:
+                tool_response = event.observation.model_dump()
+            except Exception as e:
+                logger.debug(f"Could not extract tool response: {e}")
+
+        results = self.hook_manager.run_post_tool_use(
+            tool_name=tool_name,
+            tool_input=tool_input,
+            tool_response=tool_response,
+        )
+
+        # Log any hook errors
+        for result in results:
+            if result.error:
+                logger.warning(f"PostToolUse hook error: {result.error}")
+
+    def _handle_user_prompt_submit(self, event: MessageEvent) -> None:
+        """Handle UserPromptSubmit hooks before processing a user message."""
+        if not self.hook_manager.has_hooks(HookEventType.USER_PROMPT_SUBMIT):
+            return
+
+        # Extract message text
+        message = ""
+        if event.llm_message and event.llm_message.content:
+            from openhands.sdk.llm import TextContent
+
+            for content in event.llm_message.content:
+                if isinstance(content, TextContent):
+                    message += content.text
+
+        should_continue, additional_context, results = (
+            self.hook_manager.run_user_prompt_submit(message=message)
+        )
+
+        if not should_continue:
+            reason = self.hook_manager.get_blocking_reason(results)
+            logger.warning(f"Hook blocked user message: {reason}")
+
+            # Mark this message as blocked in the conversation state
+            # The Agent will check this and skip processing the message
+            if self._conversation_state is not None:
+                block_reason = reason or "Blocked by hook"
+                self._conversation_state.block_message(event.id, block_reason)
+            else:
+                logger.warning(
+                    "Cannot block message: conversation state not set. "
+                    "Call processor.set_conversation_state(conversation.state) "
+                    "after creating the Conversation."
+                )
+
+        # TODO: Inject additional_context into the message
+        if additional_context:
+            logger.info(f"Hook injected context: {additional_context[:100]}...")
+
+    def is_action_blocked(self, action_id: str) -> bool:
+        """Check if an action was blocked by a hook."""
+        if self._conversation_state is None:
+            return False
+        return action_id in self._conversation_state.blocked_actions
+
+    def is_message_blocked(self, message_id: str) -> bool:
+        """Check if a message was blocked by a hook."""
+        if self._conversation_state is None:
+            return False
+        return message_id in self._conversation_state.blocked_messages
+
+    def run_session_start(self) -> None:
+        """Run SessionStart hooks. Call after conversation is created."""
+        results = self.hook_manager.run_session_start()
+        for r in results:
+            if r.error:
+                logger.warning(f"SessionStart hook error: {r.error}")
+
+    def run_session_end(self) -> None:
+        """Run SessionEnd hooks. Call before conversation is closed."""
+        results = self.hook_manager.run_session_end()
+        for r in results:
+            if r.error:
+                logger.warning(f"SessionEnd hook error: {r.error}")
+
+
+def create_hook_callback(
+    hook_config: HookConfig | None = None,
+    working_dir: str | None = None,
+    session_id: str | None = None,
+    original_callback: Any = None,
+) -> tuple[HookEventProcessor, Any]:
+    """Create a hook-enabled event callback. Returns (processor, callback)."""
+    hook_manager = HookManager(
+        config=hook_config,
+        working_dir=working_dir,
+        session_id=session_id,
+    )
+
+    processor = HookEventProcessor(
+        hook_manager=hook_manager,
+        original_callback=original_callback,
+    )
+
+    return processor, processor.on_event

openhands/sdk/hooks/executor.py

@@ -0,0 +1,155 @@
+"""Hook executor - runs shell commands with JSON I/O."""
+
+import json
+import os
+import subprocess
+
+from pydantic import BaseModel
+
+from openhands.sdk.hooks.config import HookDefinition
+from openhands.sdk.hooks.types import HookDecision, HookEvent
+
+
+class HookResult(BaseModel):
+    """Result from executing a hook.
+
+    Exit code 0 = success, exit code 2 = block operation.
+    """
+
+    success: bool = True
+    blocked: bool = False
+    exit_code: int = 0
+    stdout: str = ""
+    stderr: str = ""
+    decision: HookDecision | None = None
+    reason: str | None = None
+    additional_context: str | None = None
+    error: str | None = None
+
+    @property
+    def should_continue(self) -> bool:
+        """Whether the operation should continue after this hook."""
+        if self.blocked:
+            return False
+        if self.decision == HookDecision.DENY:
+            return False
+        return True
+
+
+class HookExecutor:
+    """Executes hook commands with JSON I/O."""
+
+    def __init__(self, working_dir: str | None = None):
+        self.working_dir = working_dir or os.getcwd()
+
+    def execute(
+        self,
+        hook: HookDefinition,
+        event: HookEvent,
+        env: dict[str, str] | None = None,
+    ) -> HookResult:
+        """Execute a single hook."""
+        # Prepare environment
+        hook_env = os.environ.copy()
+        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
+        if event.tool_name:
+            hook_env["OPENHANDS_TOOL_NAME"] = event.tool_name
+
+        if env:
+            hook_env.update(env)
+
+        # Serialize event to JSON for stdin
+        event_json = event.model_dump_json()
+
+        try:
+            # Execute the hook command
+            result = subprocess.run(
+                hook.command,
+                shell=True,
+                cwd=self.working_dir,
+                env=hook_env,
+                input=event_json,
+                capture_output=True,
+                text=True,
+                timeout=hook.timeout,
+            )
+
+            # Parse the result
+            hook_result = HookResult(
+                success=result.returncode == 0,
+                blocked=result.returncode == 2,
+                exit_code=result.returncode,
+                stdout=result.stdout,
+                stderr=result.stderr,
+            )
+
+            # Try to parse JSON from stdout
+            if result.stdout.strip():
+                try:
+                    output_data = json.loads(result.stdout)
+                    if isinstance(output_data, dict):
+                        # Parse decision
+                        if "decision" in output_data:
+                            decision_str = output_data["decision"].lower()
+                            if decision_str == "allow":
+                                hook_result.decision = HookDecision.ALLOW
+                            elif decision_str == "deny":
+                                hook_result.decision = HookDecision.DENY
+                                hook_result.blocked = True
+
+                        # Parse other fields
+                        if "reason" in output_data:
+                            hook_result.reason = str(output_data["reason"])
+                        if "additionalContext" in output_data:
+                            hook_result.additional_context = str(
+                                output_data["additionalContext"]
+                            )
+                        if "continue" in output_data:
+                            if not output_data["continue"]:
+                                hook_result.blocked = True
+
+                except json.JSONDecodeError:
+                    # Not JSON, that's okay - just use stdout as-is
+                    pass
+
+            return hook_result
+
+        except subprocess.TimeoutExpired:
+            return HookResult(
+                success=False,
+                exit_code=-1,
+                error=f"Hook timed out after {hook.timeout} seconds",
+            )
+        except FileNotFoundError as e:
+            return HookResult(
+                success=False,
+                exit_code=-1,
+                error=f"Hook command not found: {e}",
+            )
+        except Exception as e:
+            return HookResult(
+                success=False,
+                exit_code=-1,
+                error=f"Hook execution failed: {e}",
+            )
+
+    def execute_all(
+        self,
+        hooks: list[HookDefinition],
+        event: HookEvent,
+        env: dict[str, str] | None = None,
+        stop_on_block: bool = True,
+    ) -> list[HookResult]:
+        """Execute multiple hooks in order, optionally stopping on block."""
+        results: list[HookResult] = []
+
+        for hook in hooks:
+            result = self.execute(hook, event, env)
+            results.append(result)
+
+            if stop_on_block and result.blocked:
+                break
+
+        return results