talkops-opscloud 0.3.0b1__py3-none-any.whl

opscloud/integrations/hooks.py

@@ -0,0 +1,238 @@
+"""Event hook dispatch for opscloud.
+
+Hooks allow external tools to react to agent events. Configured in
+``~/.opscloud/hooks.json``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from opscloud.utils.logger import get_logger
+import os
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+logger = get_logger(__name__)
+
+HOOK_SUBPROCESS_TIMEOUT = 5
+"""Seconds before a hook subprocess is killed."""
+
+HOOK_TOOL_OUTPUT_LIMIT = 2000
+"""Max chars kept in tool_output payload fields."""
+
+# Standard events
+STANDARD_EVENTS = frozenset(
+    {
+        "session.start",
+        "session.end",
+        "user.prompt",
+        "tool.use",
+        "tool.result",
+        "tool.error",
+        "task.complete",
+        "user.name.set",
+        "context.compact",
+        "permission.request",
+    }
+)
+
+# Cloud / DevOps events
+DEVOPS_EVENTS = frozenset(
+    {
+        "terraform.plan",
+        "terraform.apply",
+        "helm.install",
+        "kubectl.apply",
+        "deploy.start",
+        "deploy.complete",
+        "aws.resource.create",
+        "aws.resource.update",
+        "aws.resource.delete",
+    }
+)
+
+ALL_KNOWN_EVENTS = STANDARD_EVENTS | DEVOPS_EVENTS
+
+
+@dataclass(frozen=True)
+class HookConfig:
+    """A single hook definition from ``hooks.json``."""
+
+    command: list[str]
+    """Subprocess command to execute."""
+
+    events: frozenset[str]
+    """Events this hook listens to. Empty -> all events."""
+
+    def matches(self, event: str) -> bool:
+        """Return True if this hook should fire for event."""
+        return len(self.events) == 0 or event in self.events
+
+
+_hooks: list[HookConfig] = []
+_pending_tasks: set[asyncio.Task[None]] = set()
+_loaded = False
+
+
+def _default_hooks_path() -> Path:
+    from opscloud.config.paths import HOOKS_PATH
+    return HOOKS_PATH
+
+
+def load_hooks(path: Path | None = None) -> list[HookConfig]:
+    """Parse hooks.json and populate the module-level hook list."""
+    global _hooks, _loaded
+
+    parsed: list[HookConfig] = []
+
+    def _parse_hooks_data(data: dict[str, Any], source_name: str) -> None:
+        for entry in data.get("hooks", []):
+            cmd = entry.get("command")
+            if not isinstance(cmd, list) or not cmd:
+                logger.warning("Skipping hook with invalid command from %s: %r", source_name, entry)
+                continue
+            events_raw = entry.get("events", [])
+            if not isinstance(events_raw, list):
+                events_raw = []
+            parsed.append(
+                HookConfig(
+                    command=cmd,
+                    events=frozenset(events_raw),
+                )
+            )
+
+    hooks_file = path or _default_hooks_path()
+    if hooks_file.is_file():
+        try:
+            data = json.loads(hooks_file.read_text(encoding="utf-8"))
+            if isinstance(data, dict):
+                _parse_hooks_data(data, str(hooks_file))
+        except (json.JSONDecodeError, OSError) as exc:
+            logger.warning("Failed to parse hooks config %s: %s", hooks_file, exc)
+
+    # Discover and merge plugin hooks
+    try:
+        from opscloud.plugins.discovery import discover_plugins
+
+        plugins = discover_plugins().plugins
+        for plugin in plugins:
+            plugin_hooks_file = plugin.root / "hooks" / "hooks.json"
+            if plugin_hooks_file.is_file():
+                try:
+                    p_data = json.loads(plugin_hooks_file.read_text(encoding="utf-8"))
+                    if isinstance(p_data, dict):
+                        _parse_hooks_data(p_data, f"plugin:{plugin.plugin_id}")
+                except (json.JSONDecodeError, OSError) as exc:
+                    logger.warning("Failed to parse plugin hooks config %s: %s", plugin_hooks_file, exc)
+    except Exception as exc:
+        logger.debug("Plugin hook discovery skipped: %s", exc)
+
+    _hooks = parsed
+    _loaded = True
+    return _hooks
+
+
+def _ensure_loaded() -> list[HookConfig]:
+    if not _loaded:
+        load_hooks()
+    return _hooks
+
+
+def _sanitise_payload(payload: dict[str, Any]) -> dict[str, Any]:
+    out = dict(payload)
+    if "tool_output" in out and isinstance(out["tool_output"], str):
+        if len(out["tool_output"]) > HOOK_TOOL_OUTPUT_LIMIT:
+            out["tool_output"] = out["tool_output"][:HOOK_TOOL_OUTPUT_LIMIT] + "…[truncated]"
+    return out
+
+
+async def _run_hook(hook: HookConfig, event: str, payload: dict[str, Any]) -> None:
+    from opscloud.hooks.env import sanitize_hook_environ
+
+    env = {**sanitize_hook_environ(), "OPSCLOUD_HOOK_EVENT": event}
+    json_payload = json.dumps(_sanitise_payload(payload))
+
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            *hook.command,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.PIPE,
+            env=env,
+        )
+        _, stderr = await asyncio.wait_for(
+            proc.communicate(input=json_payload.encode()),
+            timeout=HOOK_SUBPROCESS_TIMEOUT,
+        )
+        if proc.returncode != 0:
+            logger.debug(
+                "Hook %s exited %d for event %s: %s",
+                hook.command[0],
+                proc.returncode,
+                event,
+                stderr.decode(errors="replace")[:200],
+            )
+    except asyncio.TimeoutError:
+        logger.debug("Hook %s timed out after %ds for event %s", hook.command[0], HOOK_SUBPROCESS_TIMEOUT, event)
+        with suppress_os_errors():
+            proc.kill()  # type: ignore[possibly-undefined]
+    except OSError as exc:
+        logger.debug("Hook %s failed to start: %s", hook.command[0], exc)
+
+
+class suppress_os_errors:
+    def __enter__(self) -> None:
+        pass
+
+    def __exit__(self, exc_type: type | None, *_: object) -> bool:
+        return exc_type is not None and issubclass(exc_type, OSError)
+
+
+async def dispatch_hook(event: str, payload: dict[str, Any]) -> None:
+    """Dispatch event to all matching hooks and await completion."""
+    hooks = _ensure_loaded()
+    tasks = [_run_hook(h, event, payload) for h in hooks if h.matches(event)]
+    if tasks:
+        await asyncio.gather(*tasks, return_exceptions=True)
+
+
+def dispatch_hook_fire_and_forget(event: str, payload: dict[str, Any]) -> None:
+    """Dispatch event without waiting."""
+    hooks = _ensure_loaded()
+    matching = [h for h in hooks if h.matches(event)]
+    if not matching:
+        return
+
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        return
+
+    for hook in matching:
+        task = loop.create_task(_run_hook(hook, event, payload))
+        _pending_tasks.add(task)
+        task.add_done_callback(_pending_tasks.discard)
+
+
+async def drain_pending_hooks() -> None:
+    """Wait for all fire-and-forget hooks to complete."""
+    if _pending_tasks:
+        await asyncio.gather(*_pending_tasks, return_exceptions=True)
+        _pending_tasks.clear()
+
+
+__all__ = [
+    "ALL_KNOWN_EVENTS",
+    "DEVOPS_EVENTS",
+    "HOOK_SUBPROCESS_TIMEOUT",
+    "HOOK_TOOL_OUTPUT_LIMIT",
+    "HookConfig",
+    "STANDARD_EVENTS",
+    "dispatch_hook",
+    "dispatch_hook_fire_and_forget",
+    "drain_pending_hooks",
+    "load_hooks",
+]

opscloud/integrations/identity.py

@@ -0,0 +1,181 @@
+"""User identity resolution and cloud RBAC authorization mapping.
+
+Resolves terminal operators and external callers to internal identities,
+AWS IAM/cloud authorization roles, and scoped resource boundaries.
+
+Identity mappings are loaded from:
+
+1. ``IDENTITY_MAPPING_FILE`` env var — path to a JSON file.
+2. ``IDENTITY_MAPPING`` env var — inline JSON string.
+3. Default: unmapped callers receive the ``"viewer"`` role with read-only access.
+
+Example mapping file::
+
+    {
+        "terminal:local": {
+            "internal_id": "alice@company.com",
+            "display_name": "Alice",
+            "rbac_role": "admin",
+            "accounts": ["123456789012"],
+            "regions": ["us-east-1", "us-west-2"],
+            "services": ["*"],
+            "operations": ["read", "deploy", "delete", "scale"]
+        },
+        "event_bus:ci-pipeline": {
+            "internal_id": "ci-runner@company.com",
+            "display_name": "CI Runner",
+            "rbac_role": "operator",
+            "accounts": ["123456789012"],
+            "regions": ["us-east-1"],
+            "services": ["ec2", "s3"],
+            "operations": ["read", "deploy"]
+        }
+    }
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import getpass
+import json
+import os
+from typing import Any
+
+from opscloud.utils.logger import AgentLogger
+
+logger = AgentLogger("IdentityIntegration")
+
+
+@dataclass
+class UserIdentity:
+    """Resolved user identity with cloud authorization and boundary context.
+
+    Attributes:
+        platform: Source platform or interface (e.g. ``"terminal"``, ``"event_bus"``).
+        platform_user_id: Caller identifier on that platform.
+        internal_user_id: Internal corporate/IAM user identifier or email.
+        display_name: Human-readable display name.
+        rbac_role: Cloud authorization role (``"admin"``, ``"operator"``, ``"viewer"``).
+        allowed_accounts: Permitted cloud account IDs (``["*"]`` for all).
+        allowed_regions: Permitted cloud regions (``["*"]`` for all).
+        allowed_services: Permitted cloud services (e.g. ``["ec2", "s3"]`` or ``["*"]``).
+        allowed_operations: Permitted operations: ``"read"``, ``"deploy"``, ``"delete"``, etc.
+        allowed_namespaces: Permitted Kubernetes namespaces if cluster operations are used.
+    """
+
+    platform: str = "terminal"
+    platform_user_id: str = "local"
+    internal_user_id: str = "local"
+    display_name: str = "Terminal Operator"
+    rbac_role: str = "viewer"
+    allowed_accounts: list[str] = field(default_factory=lambda: ["*"])
+    allowed_regions: list[str] = field(default_factory=lambda: ["*"])
+    allowed_services: list[str] = field(default_factory=lambda: ["*"])
+    allowed_operations: list[str] = field(default_factory=lambda: ["read"])
+    allowed_namespaces: list[str] = field(default_factory=lambda: ["*"])
+
+
+class IdentityMapper:
+    """Resolves platform users to :class:`UserIdentity` with cloud RBAC context.
+
+    Uses composite keys of the form ``"platform:user_id"`` (e.g. ``"terminal:local"``).
+    """
+
+    def __init__(self) -> None:
+        """Initialize IdentityMapper and load configured user mappings."""
+        self._mapping: dict[str, dict[str, Any]] = {}
+        self._load_mapping()
+
+    # ── Loading ───────────────────────────────────────────────────────
+
+    def _load_mapping(self) -> None:
+        """Load identity mapping from env var sources."""
+        # Priority 1: JSON file
+        mapping_file = os.getenv("IDENTITY_MAPPING_FILE")
+        if mapping_file:
+            try:
+                with open(mapping_file, encoding="utf-8") as fh:
+                    self._mapping = json.load(fh)
+                    logger.info(f"Loaded identity mapping from file: {mapping_file} ({len(self._mapping):d} entries)")
+                    return
+            except (FileNotFoundError, json.JSONDecodeError, OSError) as exc:
+                logger.warning(f"Failed to load identity mapping file {mapping_file}: {exc}")
+
+        # Priority 2: Inline JSON string
+        mapping_str = os.getenv("IDENTITY_MAPPING")
+        if mapping_str:
+            try:
+                self._mapping = json.loads(mapping_str)
+                logger.info(f"Loaded identity mapping from IDENTITY_MAPPING env ({len(self._mapping):d} entries)")
+                return
+            except json.JSONDecodeError as exc:
+                logger.warning(f"Failed to parse IDENTITY_MAPPING env: {exc}")
+
+        logger.info("No identity mapping configured — using default viewer role")
+
+    # ── Resolution ────────────────────────────────────────────────────
+
+    def resolve(
+        self,
+        platform: str = "terminal",
+        platform_user_id: str | None = None,
+    ) -> UserIdentity:
+        """Resolve a caller identity to a :class:`UserIdentity`.
+
+        Unmapped callers receive the ``"viewer"`` role with read-only access.
+
+        Args:
+            platform: Platform key (e.g. ``"terminal"``, ``"event_bus"``).
+            platform_user_id: Platform-native or local user identifier.
+                Defaults to current operating system user when platform is "terminal".
+
+        Returns:
+            Resolved :class:`UserIdentity` with cloud authorization context.
+        """
+        if platform_user_id is None:
+            if platform == "terminal":
+                try:
+                    platform_user_id = getpass.getuser()
+                except Exception:
+                    platform_user_id = "local"
+            else:
+                platform_user_id = "anonymous"
+
+        key = f"{platform}:{platform_user_id}"
+        user_data = self._mapping.get(key, {})
+
+        accounts = user_data.get("accounts") or user_data.get("allowed_accounts") or ["*"]
+        regions = user_data.get("regions") or user_data.get("allowed_regions") or ["*"]
+        services = user_data.get("services") or user_data.get("allowed_services") or ["*"]
+        namespaces = user_data.get("namespaces") or user_data.get("allowed_namespaces") or ["*"]
+        operations = user_data.get("operations") or user_data.get("allowed_operations") or ["read"]
+
+        return UserIdentity(
+            platform=platform,
+            platform_user_id=platform_user_id,
+            internal_user_id=user_data.get("internal_id", platform_user_id),
+            display_name=user_data.get("display_name", platform_user_id.title()),
+            rbac_role=user_data.get("rbac_role", "viewer"),
+            allowed_accounts=list(accounts),
+            allowed_regions=list(regions),
+            allowed_services=list(services),
+            allowed_operations=list(operations),
+            allowed_namespaces=list(namespaces),
+        )
+
+    # ── Utilities ─────────────────────────────────────────────────────
+
+    def is_mapped(self, platform: str, platform_user_id: str) -> bool:
+        """Check if a user has an explicit mapping configured.
+
+        Args:
+            platform: Platform key.
+            platform_user_id: User identifier.
+
+        Returns:
+            True if user is explicitly present in the mapping.
+        """
+        return f"{platform}:{platform_user_id}" in self._mapping
+
+
+__all__ = ["IdentityMapper", "UserIdentity"]

opscloud/integrations/notifications.py

@@ -0,0 +1,134 @@
+"""Convenience notification helpers for OpsCloud events.
+
+Thin wrappers around :func:`~opscloud.integrations.hooks.dispatch_hook` and
+:func:`~opscloud.integrations.hooks.dispatch_hook_fire_and_forget` that assemble
+standard event payload dictionaries for callers.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from opscloud.integrations.hooks import (
+    dispatch_hook,
+    dispatch_hook_fire_and_forget,
+)
+
+
+async def notify_session_start(session_id: str, model: str) -> None:
+    """Fire ``session.start`` event (awaited).
+
+    Args:
+        session_id: Unique session identifier.
+        model: Active model identifier.
+    """
+    await dispatch_hook(
+        "session.start",
+        {"session_id": session_id, "model": model},
+    )
+
+
+async def notify_session_end(session_id: str, duration_s: float) -> None:
+    """Fire ``session.end`` event (awaited).
+
+    Args:
+        session_id: Unique session identifier.
+        duration_s: Total session duration in seconds.
+    """
+    await dispatch_hook(
+        "session.end",
+        {"session_id": session_id, "duration_s": duration_s},
+    )
+
+
+def notify_tool_use(
+    tool_name: str,
+    tool_id: str,
+    tool_args: dict[str, Any] | None = None,
+) -> None:
+    """Fire ``tool.use`` event (fire-and-forget).
+
+    Args:
+        tool_name: Name of tool being invoked.
+        tool_id: Unique tool execution ID.
+        tool_args: Arguments passed to the tool.
+    """
+    dispatch_hook_fire_and_forget(
+        "tool.use",
+        {
+            "tool_name": tool_name,
+            "tool_id": tool_id,
+            "tool_args": tool_args or {},
+        },
+    )
+
+
+def notify_tool_result(
+    tool_name: str,
+    tool_status: str = "success",
+    tool_output: str = "",
+) -> None:
+    """Fire ``tool.result`` event (fire-and-forget).
+
+    Args:
+        tool_name: Name of completed tool.
+        tool_status: Execution status (e.g. ``"success"``, ``"error"``).
+        tool_output: Tool output string.
+    """
+    dispatch_hook_fire_and_forget(
+        "tool.result",
+        {
+            "tool_name": tool_name,
+            "tool_status": tool_status,
+            "tool_output": tool_output,
+        },
+    )
+
+
+async def notify_task_complete(summary: str) -> None:
+    """Fire ``task.complete`` event (awaited).
+
+    Args:
+        summary: Human-readable task completion summary.
+    """
+    await dispatch_hook("task.complete", {"summary": summary})
+
+
+def notify_deploy_event(
+    event_type: str,
+    details: dict[str, Any] | None = None,
+) -> None:
+    """Fire a DevOps deployment lifecycle event (fire-and-forget).
+
+    Args:
+        event_type: One of ``"deploy.start"``, ``"deploy.complete"``,
+            ``"terraform.plan"``, ``"terraform.apply"``, ``"helm.install"``,
+            ``"kubectl.apply"``.
+        details: Additional payload parameters.
+    """
+    dispatch_hook_fire_and_forget(event_type, details or {})
+
+
+def notify_cloud_event(
+    event_type: str,
+    details: dict[str, Any] | None = None,
+) -> None:
+    """Fire a cloud infrastructure lifecycle event (fire-and-forget).
+
+    Args:
+        event_type: Cloud event name (e.g. ``"aws.resource.create"``,
+            ``"aws.resource.update"``, ``"aws.resource.delete"``).
+        details: Details of the cloud resource or operation.
+    """
+    dispatch_hook_fire_and_forget(event_type, details or {})
+
+
+__all__ = [
+    "notify_cloud_event",
+    "notify_deploy_event",
+    "notify_session_end",
+    "notify_session_start",
+    "notify_task_complete",
+    "notify_tool_result",
+    "notify_tool_use",
+]