openhands-sdk 1.7.3__py3-none-any.whl

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

openhands/sdk/hooks/manager.py

@@ -0,0 +1,170 @@
+"""Hook manager - orchestrates hook execution within conversations."""
+
+from typing import Any
+
+from openhands.sdk.hooks.config import HookConfig
+from openhands.sdk.hooks.executor import HookExecutor, HookResult
+from openhands.sdk.hooks.types import HookEvent, HookEventType
+
+
+class HookManager:
+    """Manages hook execution for a conversation."""
+
+    def __init__(
+        self,
+        config: HookConfig | None = None,
+        working_dir: str | None = None,
+        session_id: str | None = None,
+    ):
+        self.config = config or HookConfig.load(working_dir=working_dir)
+        self.executor = HookExecutor(working_dir=working_dir)
+        self.session_id = session_id
+        self.working_dir = working_dir
+
+    def _create_event(
+        self,
+        event_type: HookEventType,
+        tool_name: str | None = None,
+        tool_input: dict[str, Any] | None = None,
+        tool_response: dict[str, Any] | None = None,
+        message: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> HookEvent:
+        """Create a hook event with common fields populated."""
+        return HookEvent(
+            event_type=event_type,
+            tool_name=tool_name,
+            tool_input=tool_input,
+            tool_response=tool_response,
+            message=message,
+            session_id=self.session_id,
+            working_dir=self.working_dir,
+            metadata=metadata or {},
+        )
+
+    def run_pre_tool_use(
+        self,
+        tool_name: str,
+        tool_input: dict[str, Any],
+    ) -> tuple[bool, list[HookResult]]:
+        """Run PreToolUse hooks. Returns (should_continue, results)."""
+        hooks = self.config.get_hooks_for_event(HookEventType.PRE_TOOL_USE, tool_name)
+        if not hooks:
+            return True, []
+
+        event = self._create_event(
+            HookEventType.PRE_TOOL_USE,
+            tool_name=tool_name,
+            tool_input=tool_input,
+        )
+
+        results = self.executor.execute_all(hooks, event, stop_on_block=True)
+
+        # Check if any hook blocked the operation
+        should_continue = all(r.should_continue for r in results)
+
+        return should_continue, results
+
+    def run_post_tool_use(
+        self,
+        tool_name: str,
+        tool_input: dict[str, Any],
+        tool_response: dict[str, Any],
+    ) -> list[HookResult]:
+        """Run PostToolUse hooks after a tool completes."""
+        hooks = self.config.get_hooks_for_event(HookEventType.POST_TOOL_USE, tool_name)
+        if not hooks:
+            return []
+
+        event = self._create_event(
+            HookEventType.POST_TOOL_USE,
+            tool_name=tool_name,
+            tool_input=tool_input,
+            tool_response=tool_response,
+        )
+
+        # PostToolUse hooks don't block - they just run
+        return self.executor.execute_all(hooks, event, stop_on_block=False)
+
+    def run_user_prompt_submit(
+        self,
+        message: str,
+    ) -> tuple[bool, str | None, list[HookResult]]:
+        """Run UserPromptSubmit hooks."""
+        hooks = self.config.get_hooks_for_event(HookEventType.USER_PROMPT_SUBMIT)
+        if not hooks:
+            return True, None, []
+
+        event = self._create_event(
+            HookEventType.USER_PROMPT_SUBMIT,
+            message=message,
+        )
+
+        results = self.executor.execute_all(hooks, event, stop_on_block=True)
+
+        # Check if any hook blocked
+        should_continue = all(r.should_continue for r in results)
+
+        # Collect additional context from hooks
+        additional_context_parts = [
+            r.additional_context for r in results if r.additional_context
+        ]
+        additional_context = (
+            "\n".join(additional_context_parts) if additional_context_parts else None
+        )
+
+        return should_continue, additional_context, results
+
+    def run_session_start(self) -> list[HookResult]:
+        """Run SessionStart hooks when a conversation begins."""
+        hooks = self.config.get_hooks_for_event(HookEventType.SESSION_START)
+        if not hooks:
+            return []
+
+        event = self._create_event(HookEventType.SESSION_START)
+        return self.executor.execute_all(hooks, event, stop_on_block=False)
+
+    def run_session_end(self) -> list[HookResult]:
+        """Run SessionEnd hooks when a conversation ends."""
+        hooks = self.config.get_hooks_for_event(HookEventType.SESSION_END)
+        if not hooks:
+            return []
+
+        event = self._create_event(HookEventType.SESSION_END)
+        return self.executor.execute_all(hooks, event, stop_on_block=False)
+
+    def run_stop(
+        self,
+        reason: str | None = None,
+    ) -> tuple[bool, list[HookResult]]:
+        """Run Stop hooks. Returns (should_stop, results)."""
+        hooks = self.config.get_hooks_for_event(HookEventType.STOP)
+        if not hooks:
+            return True, []
+
+        event = self._create_event(
+            HookEventType.STOP,
+            metadata={"reason": reason} if reason else {},
+        )
+
+        results = self.executor.execute_all(hooks, event, stop_on_block=True)
+
+        # If a hook blocks, the agent should NOT stop (continue running)
+        should_stop = all(r.should_continue for r in results)
+
+        return should_stop, results
+
+    def has_hooks(self, event_type: HookEventType) -> bool:
+        """Check if there are hooks configured for an event type."""
+        return self.config.has_hooks_for_event(event_type)
+
+    def get_blocking_reason(self, results: list[HookResult]) -> str | None:
+        """Get the reason for blocking from hook results."""
+        for result in results:
+            if result.blocked:
+                if result.reason:
+                    return result.reason
+                if result.stderr:
+                    return result.stderr.strip()
+                return "Blocked by hook"
+        return None

openhands/sdk/hooks/types.py

@@ -0,0 +1,40 @@
+"""Hook event types and data structures."""
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class HookEventType(str, Enum):
+    """Types of hook events that can trigger hooks."""
+
+    PRE_TOOL_USE = "PreToolUse"
+    POST_TOOL_USE = "PostToolUse"
+    USER_PROMPT_SUBMIT = "UserPromptSubmit"
+    SESSION_START = "SessionStart"
+    SESSION_END = "SessionEnd"
+    STOP = "Stop"
+
+
+class HookEvent(BaseModel):
+    """Data passed to hook scripts via stdin as JSON."""
+
+    event_type: HookEventType
+    tool_name: str | None = None
+    tool_input: dict[str, Any] | None = None
+    tool_response: dict[str, Any] | None = None
+    message: str | None = None
+    session_id: str | None = None
+    working_dir: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+    model_config = {"use_enum_values": True}
+
+
+class HookDecision(str, Enum):
+    """Decisions a hook can make about an operation."""
+
+    ALLOW = "allow"
+    DENY = "deny"
+    # ASK = "ask"  # Future: prompt user for confirmation before proceeding

openhands/sdk/io/__init__.py

@@ -0,0 +1,6 @@
+from .base import FileStore
+from .local import LocalFileStore
+from .memory import InMemoryFileStore
+
+
+__all__ = ["LocalFileStore", "FileStore", "InMemoryFileStore"]

openhands/sdk/io/base.py

@@ -0,0 +1,48 @@
+from abc import ABC, abstractmethod
+
+
+class FileStore(ABC):
+    """Abstract base class for file storage operations.
+
+    This class defines the interface for file storage backends that can
+    handle basic file operations like reading, writing, listing, and deleting files.
+    """
+
+    @abstractmethod
+    def write(self, path: str, contents: str | bytes) -> None:
+        """Write contents to a file at the specified path.
+
+        Args:
+            path: The file path where contents should be written.
+            contents: The data to write, either as string or bytes.
+        """
+
+    @abstractmethod
+    def read(self, path: str) -> str:
+        """Read and return the contents of a file as a string.
+
+        Args:
+            path: The file path to read from.
+
+        Returns:
+            The file contents as a string.
+        """
+
+    @abstractmethod
+    def list(self, path: str) -> list[str]:
+        """List all files and directories at the specified path.
+
+        Args:
+            path: The directory path to list contents from.
+
+        Returns:
+            A list of file and directory names in the specified path.
+        """
+
+    @abstractmethod
+    def delete(self, path: str) -> None:
+        """Delete the file or directory at the specified path.
+
+        Args:
+            path: The file or directory path to delete.
+        """