talkops-opscloud 0.3.0b1__py3-none-any.whl

opscloud/hooks/interrupt.py

@@ -0,0 +1,121 @@
+"""Client↔server interrupt transport for Hooks v2 server-owned events."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, TypeAdapter
+
+from opscloud.hooks.models.adapters import HOOK_INVOCATION_RESPONSE_ADAPTER
+from opscloud.hooks.models.transport import (
+    HookInvocationRequest,
+    HookInvocationResponse,
+)
+
+if TYPE_CHECKING:
+    from uuid import UUID
+
+HOOK_INVOCATION_INTERRUPT_TYPE: Literal["hook_invocation"] = "hook_invocation"
+
+
+class HookInvocationInterrupt(BaseModel):
+    """LangGraph interrupt envelope for a server-owned hook invocation."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Literal["hook_invocation"] = HOOK_INVOCATION_INTERRUPT_TYPE
+    request: HookInvocationRequest
+
+
+HOOK_INVOCATION_INTERRUPT_ADAPTER: TypeAdapter[HookInvocationInterrupt] = TypeAdapter(HookInvocationInterrupt)
+
+type HookResumeValue = dict[str, Any]
+
+
+def build_hook_interrupt_payload(request: HookInvocationRequest) -> dict[str, Any]:
+    """Serialize a hook invocation request for `interrupt()`.
+
+    Args:
+        request: Versioned server-owned invocation request.
+
+    Returns:
+        JSON-compatible interrupt payload with a stable `type` discriminator.
+    """
+    return HOOK_INVOCATION_INTERRUPT_ADAPTER.dump_python(
+        HookInvocationInterrupt(request=request),
+        mode="json",
+    )
+
+
+def parse_hook_interrupt_payload(value: object) -> HookInvocationRequest | None:
+    """Parse a hook invocation interrupt payload when present.
+
+    Args:
+        value: Raw interrupt value from LangGraph.
+
+    Returns:
+        The embedded request, or None when value is not a hook interrupt.
+    """
+    if not isinstance(value, dict) or value.get("type") != HOOK_INVOCATION_INTERRUPT_TYPE:
+        return None
+    interrupt_data = HOOK_INVOCATION_INTERRUPT_ADAPTER.validate_python(value)
+    return interrupt_data.request
+
+
+def build_hook_resume_value(response: HookInvocationResponse) -> HookResumeValue:
+    """Serialize a hook invocation response for `Command(resume=...)`.
+
+    Args:
+        response: Decision returned by the client runtime.
+
+    Returns:
+        JSON-compatible resume value for the matching interrupt id.
+    """
+    return HOOK_INVOCATION_RESPONSE_ADAPTER.dump_python(response, mode="json")
+
+
+def parse_hook_resume_value(
+    value: object,
+    *,
+    invocation_id: UUID,
+    snapshot_id: str,
+) -> HookInvocationResponse:
+    """Validate a resumed hook response against the outstanding request.
+
+    Args:
+        value: Resume payload returned by the client.
+        invocation_id: Expected invocation id from the request.
+        snapshot_id: Expected configuration snapshot id.
+
+    Returns:
+        Validated hook invocation response.
+
+    Raises:
+        ValueError: If the resume payload is not a JSON object or if the
+            invocation_id or snapshot_id does not match expectations.
+    """
+    if not isinstance(value, dict):
+        msg = "Hook resume payload must be a JSON object"
+        raise ValueError(msg)
+    response = HOOK_INVOCATION_RESPONSE_ADAPTER.validate_python(value)
+    if response.invocation_id != invocation_id:
+        msg = f"Resume invocation id {response.invocation_id} does not match {invocation_id}"
+        raise ValueError(msg)
+    if response.snapshot_id != snapshot_id:
+        msg = f"Resume snapshot id {response.snapshot_id} does not match {snapshot_id}"
+        raise ValueError(msg)
+    return response
+
+
+def is_hook_interrupt_payload(value: object) -> bool:
+    """Return whether value looks like a Hooks v2 invocation interrupt.
+
+    Args:
+        value: Any interrupt payload value to check.
+
+    Returns:
+        True if the value is a dict with type 'hook_invocation', False otherwise.
+    """
+    return (
+        isinstance(value, dict) and value.get("type") == HOOK_INVOCATION_INTERRUPT_TYPE
+    )

opscloud/hooks/models/__init__.py

@@ -0,0 +1,109 @@
+"""Hook domain and transport models."""
+
+from opscloud.hooks.models.domain import (
+    AgentIdentity,
+    BackgroundTaskSnapshot,
+    BaseHookDecision,
+    CompactTrigger,
+    EffortLevel,
+    HookContext,
+    HookDecision,
+    HookDiagnostic,
+    HookDomainEvent,
+    HookEffect,
+    HookEvent,
+    HookInvocation,
+    HookOwner,
+    NotificationDecision,
+    NotificationEvent,
+    OpscloudNotification,
+    OpscloudNotificationKind,
+    PermissionEffect,
+    PermissionRequestDecision,
+    PermissionRequestEvent,
+    PostToolUseDecision,
+    PostToolUseEvent,
+    PostToolUseFailureDecision,
+    PostToolUseFailureEvent,
+    PreCompactDecision,
+    PreCompactEvent,
+    PreToolUseDecision,
+    PreToolUseEvent,
+    SessionCronSnapshot,
+    SessionEndCause,
+    SessionEndDecision,
+    SessionEndEvent,
+    SessionStartCause,
+    SessionStartDecision,
+    SessionStartEvent,
+    StopDecision,
+    StopEvent,
+    SubagentStartDecision,
+    SubagentStartEvent,
+    SubagentStopDecision,
+    SubagentStopEvent,
+    ToolCallData,
+    UserPromptSubmitDecision,
+    UserPromptSubmitEvent,
+)
+from opscloud.hooks.models.config import (
+    CommandHandlerSpec,
+    HooksConfig,
+    MatcherGroup,
+)
+from opscloud.hooks.models.transport import (
+    HookInvocationRequest,
+    HookInvocationResponse,
+)
+
+__all__ = [
+    "AgentIdentity",
+    "BackgroundTaskSnapshot",
+    "BaseHookDecision",
+    "CommandHandlerSpec",
+    "CompactTrigger",
+    "EffortLevel",
+    "HookContext",
+    "HookDecision",
+    "HookDiagnostic",
+    "HookDomainEvent",
+    "HookEffect",
+    "HookEvent",
+    "HookInvocation",
+    "HookInvocationRequest",
+    "HookInvocationResponse",
+    "HookOwner",
+    "HooksConfig",
+    "MatcherGroup",
+    "NotificationDecision",
+    "NotificationEvent",
+    "OpscloudNotification",
+    "OpscloudNotificationKind",
+    "PermissionEffect",
+    "PermissionRequestDecision",
+    "PermissionRequestEvent",
+    "PostToolUseDecision",
+    "PostToolUseEvent",
+    "PostToolUseFailureDecision",
+    "PostToolUseFailureEvent",
+    "PreCompactDecision",
+    "PreCompactEvent",
+    "PreToolUseDecision",
+    "PreToolUseEvent",
+    "SessionCronSnapshot",
+    "SessionEndCause",
+    "SessionEndDecision",
+    "SessionEndEvent",
+    "SessionStartCause",
+    "SessionStartDecision",
+    "SessionStartEvent",
+    "StopDecision",
+    "StopEvent",
+    "SubagentStartDecision",
+    "SubagentStartEvent",
+    "SubagentStopDecision",
+    "SubagentStopEvent",
+    "ToolCallData",
+    "UserPromptSubmitDecision",
+    "UserPromptSubmitEvent",
+]

opscloud/hooks/models/adapters.py

@@ -0,0 +1,19 @@
+"""Cached runtime validators for hook model boundaries."""
+
+from pydantic import TypeAdapter
+
+from opscloud.hooks.models.domain import (
+    HookDecision,
+    HookDomainEvent,
+    HookInvocation,
+)
+from opscloud.hooks.models.transport import (
+    HookInvocationRequest,
+    HookInvocationResponse,
+)
+
+HOOK_DOMAIN_EVENT_ADAPTER: TypeAdapter[HookDomainEvent] = TypeAdapter(HookDomainEvent)
+HOOK_INVOCATION_ADAPTER: TypeAdapter[HookInvocation] = TypeAdapter(HookInvocation)
+HOOK_DECISION_ADAPTER: TypeAdapter[HookDecision] = TypeAdapter(HookDecision)
+HOOK_INVOCATION_REQUEST_ADAPTER: TypeAdapter[HookInvocationRequest] = TypeAdapter(HookInvocationRequest)
+HOOK_INVOCATION_RESPONSE_ADAPTER: TypeAdapter[HookInvocationResponse] = TypeAdapter(HookInvocationResponse)

opscloud/hooks/models/config.py

@@ -0,0 +1,79 @@
+"""Validated hook configuration models for declarative Hooks v2 specifications."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from opscloud.hooks.models.domain import HookEvent
+
+
+class _ConfigModel(BaseModel):
+    """Base model for hook configuration objects."""
+
+    model_config = ConfigDict(extra="ignore", populate_by_name=True)
+
+
+class CommandHandlerSpec(_ConfigModel):
+    """Configuration for a command hook handler.
+
+    Currently supports `type: "command"`. Commands can run shell expressions
+    or direct executable arguments via `argv`.
+    """
+
+    type: Literal["command"]
+    command: str
+    argv: list[str] | None = None
+    timeout: float | None = Field(default=None, gt=0, allow_inf_nan=False)
+    status_message: str | None = Field(default=None, alias="statusMessage")
+    async_: bool | None = Field(default=None, alias="async")
+
+    @field_validator("argv", mode="after")
+    @classmethod
+    def _normalize_argv(cls, value: list[str] | None) -> list[str] | None:
+        """Validate that argv is a non-empty list of strings if provided.
+
+        Args:
+            value: Provided argv list or None.
+
+        Returns:
+            Validated list of string arguments.
+
+        Raises:
+            ValueError: If argv is empty, contains non-strings, or has an empty executable.
+        """
+        if value is None:
+            return None
+        if not value or not all(isinstance(part, str) for part in value):
+            msg = "argv must be a non-empty list of strings when provided."
+            raise ValueError(msg)
+        if not value[0].strip():
+            msg = "argv[0] must be a non-empty executable path."
+            raise ValueError(msg)
+        return value
+
+
+HandlerSpec = CommandHandlerSpec
+
+
+class MatcherGroup(_ConfigModel):
+    """A matcher pattern and its ordered hook handlers.
+
+    Attributes:
+        matcher: Tool name pattern (e.g. 'Bash', 'aws_*', 'Write') or regex.
+        hooks: List of handler specifications to execute on match.
+    """
+
+    matcher: str | None = None
+    hooks: list[HandlerSpec]
+
+
+class HooksConfig(_ConfigModel):
+    """Top-level configuration grouped by hook lifecycle event.
+
+    Attributes:
+        hooks: Mapping from lifecycle HookEvent to list of MatcherGroups.
+    """
+
+    hooks: dict[HookEvent, list[MatcherGroup]]