talkops-opscloud 0.3.0b1__py3-none-any.whl

opscloud/approval_mode.py

@@ -0,0 +1,44 @@
+"""Approval modes for OpsCloud.
+
+Re-exports canonical definitions and store/acknowledgement utilities from `opscloud.security.approval_mode`.
+"""
+
+from opscloud.security.approval_mode import (
+    APPROVAL_MODE_NAMESPACE,
+    AUTO_NOTICE_VERSION,
+    ApprovalMode,
+    ApprovalModePayload,
+    approval_mode_key,
+    approval_mode_payload,
+    approval_mode_scope,
+    approval_state_path,
+    aread_approval_mode_from_store,
+    awrite_approval_mode,
+    coerce_approval_mode,
+    get_approval_mode,
+    has_auto_mode_notice,
+    next_approval_mode,
+    read_approval_mode_from_store,
+    save_auto_mode_notice,
+    set_approval_mode,
+)
+
+__all__ = [
+    "APPROVAL_MODE_NAMESPACE",
+    "AUTO_NOTICE_VERSION",
+    "ApprovalMode",
+    "ApprovalModePayload",
+    "approval_mode_key",
+    "approval_mode_payload",
+    "approval_mode_scope",
+    "approval_state_path",
+    "aread_approval_mode_from_store",
+    "awrite_approval_mode",
+    "coerce_approval_mode",
+    "get_approval_mode",
+    "has_auto_mode_notice",
+    "next_approval_mode",
+    "read_approval_mode_from_store",
+    "save_auto_mode_notice",
+    "set_approval_mode",
+]

opscloud/backend/__init__.py

@@ -0,0 +1,49 @@
+"""Backend module for OpsCloud — shell execution, sandbox environments, and filesystem access."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from opscloud.backend.registry import (
+    BackendRegistry,
+    get_backend_class,
+    get_backend_registry,
+    register_backend,
+)
+
+__all__ = [
+    "BackendRegistry",
+    "CompositeBackend",
+    "LocalShellBackend",
+    "OpsCloudCompositeBackend",
+    "SandboxConfig",
+    "cleanup_all_sandboxes",
+    "cleanup_sandbox",
+    "clear_sandbox_cache",
+    "create_sandbox_backend",
+    "get_backend_class",
+    "get_backend_registry",
+    "get_sandbox_backend",
+    "register_backend",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy-load backend classes to avoid circular imports and unnecessary dependencies."""
+    _lazy_map = {
+        "LocalShellBackend": "opscloud.backend.local",
+        "OpsCloudCompositeBackend": "opscloud.backend.composite",
+        "CompositeBackend": "opscloud.backend.composite",
+        "SandboxConfig": "opscloud.backend.sandbox_config",
+        "get_sandbox_backend": "opscloud.backend.sandbox_factory",
+        "create_sandbox_backend": "opscloud.backend.sandbox_factory",
+        "cleanup_sandbox": "opscloud.backend.sandbox_factory",
+        "cleanup_all_sandboxes": "opscloud.backend.sandbox_factory",
+        "clear_sandbox_cache": "opscloud.backend.sandbox_factory",
+    }
+    if name in _lazy_map:
+        import importlib
+
+        mod = importlib.import_module(_lazy_map[name])
+        return getattr(mod, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

opscloud/backend/composite.py

@@ -0,0 +1,89 @@
+"""Composite backend routing for OpsCloud.
+
+Routes special virtual paths (``/large_tool_results/`` and ``/conversation_history/``)
+to specialized backends while delegating all standard filesystem and command
+execution to the default backend (e.g. ``LocalShellBackend`` or remote sandbox).
+"""
+
+from __future__ import annotations
+
+import atexit
+from pathlib import Path
+import shutil
+import tempfile
+from typing import Any
+
+from deepagents.backends import (
+    BackendProtocol,
+    CompositeBackend as SDKCompositeBackend,
+    FilesystemBackend,
+)
+
+from opscloud.config.paths import ensure_conversation_history_dir
+
+
+class OpsCloudCompositeBackend(SDKCompositeBackend):
+    """Composite backend routing virtual paths (/large_tool_results/, /conversation_history/)."""
+
+    def __init__(
+        self,
+        default: Any,
+        routes: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize OpsCloudCompositeBackend with default and routed backends.
+
+        Args:
+            default: Default backend instance to fall back to.
+            routes: Optional mapping of virtual path prefixes to backend instances.
+            **kwargs: Additional keyword arguments for SDKCompositeBackend.
+        """
+        self._large_results_dir = tempfile.mkdtemp(prefix="opscloud_large_results_")
+        self._conversation_history_dir = ensure_conversation_history_dir()
+
+        atexit.register(self.cleanup)
+
+        large_results_backend = FilesystemBackend(
+            root_dir=self._large_results_dir,
+            virtual_mode=True,
+        )
+        conversation_history_backend = FilesystemBackend(
+            root_dir=self._conversation_history_dir,
+            virtual_mode=True,
+        )
+
+        effective_routes: dict[str, BackendProtocol] = {
+            "/large_tool_results/": large_results_backend,
+            "/conversation_history/": conversation_history_backend,
+        }
+        if routes:
+            effective_routes.update(routes)
+
+        super().__init__(
+            default=default,
+            routes=effective_routes,
+            **kwargs,
+        )
+
+    def cleanup(self) -> None:
+        """Clean up temporary large tool result directories on shutdown.
+
+        Note: Conversation history is persistent and is intentionally preserved.
+        """
+        if hasattr(self, "_large_results_dir") and self._large_results_dir:
+            shutil.rmtree(self._large_results_dir, ignore_errors=True)
+
+    def __enter__(self) -> OpsCloudCompositeBackend:
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self.cleanup()
+
+
+# Alias for convenience
+CompositeBackend = OpsCloudCompositeBackend
+
+__all__ = [
+    "CompositeBackend",
+    "OpsCloudCompositeBackend",
+]

opscloud/backend/local.py

@@ -0,0 +1,183 @@
+"""Local shell and filesystem execution backend for AWS operations.
+
+Extends ``LocalShellBackend`` with a curated shell environment that preserves
+AWS CLI, AWS CDK, Terraform/OpenTofu, Terragrunt, Kubernetes, and DevOps tool
+credentials and environment configurations.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from deepagents.backends import LocalShellBackend as SDKLocalShellBackend
+
+from opscloud.backend.registry import register_backend
+from opscloud.config.paths import AWS_PRESERVE_ENV_VARS
+
+# Tool directories to prepend to PATH for CLI tool discovery
+COMMON_TOOL_DIRS: tuple[str, ...] = (
+    "/opt/homebrew/bin",
+    "/usr/local/bin",
+    "~/.local/bin",
+    "~/.cargo/bin",
+    "~/.aws/bin",
+)
+
+# Prefix matching for AWS and Cloud IaC ecosystem tools
+ALLOWED_ENV_PREFIXES: tuple[str, ...] = (
+    "AWS_",
+    "TF_VAR_",
+    "TF_",
+    "TERRAGRUNT_",
+    "KUBE_",
+    "HELM_",
+    "CDK_",
+    "PULUMI_",
+    "SAM_",
+)
+
+
+def _build_shell_env() -> dict[str, str]:
+    """Curate environment preserving safe shell vars, tool PATHs, and AWS/cloud credentials."""
+    safe_keys = {
+        "PATH",
+        "HOME",
+        "SHELL",
+        "TERM",
+        "LANG",
+        "USER",
+        "LOGNAME",
+        "PWD",
+        "EDITOR",
+        "VISUAL",
+        "LC_ALL",
+        "LOCALE",
+    }
+    env: dict[str, str] = {}
+    for key in safe_keys:
+        if key in os.environ:
+            env[key] = os.environ[key]
+
+    # Prepend standard binary locations to PATH
+    path_val = env.get("PATH", "")
+    for tool_dir in COMMON_TOOL_DIRS:
+        expanded = os.path.expanduser(tool_dir)
+        if expanded not in path_val.split(os.pathsep):
+            path_val = f"{expanded}{os.pathsep}{path_val}" if path_val else expanded
+    env["PATH"] = path_val
+
+    # Ensure AWS_PAGER is disabled by default so aws CLI commands do not hang waiting for paging
+    if "AWS_PAGER" in os.environ:
+        env["AWS_PAGER"] = os.environ["AWS_PAGER"]
+    else:
+        env["AWS_PAGER"] = ""
+
+    # Prevent interactive terminal prompts in subshells (e.g. Git credentials, CLI pagers)
+    env["GIT_TERMINAL_PROMPT"] = os.environ.get("GIT_TERMINAL_PROMPT", "0")
+    if "PAGER" not in env:
+        env["PAGER"] = os.environ.get("PAGER", "cat")
+
+    # Preserve all AWS & Cloud IaC environment variables
+    for key, val in os.environ.items():
+        if key in AWS_PRESERVE_ENV_VARS or key.startswith(ALLOWED_ENV_PREFIXES):
+            env[key] = val
+
+    return env
+
+
+@register_backend("local")
+class LocalShellBackend(SDKLocalShellBackend):
+    """Local shell and filesystem backend specialized for AWS DevOps/SRE operations."""
+
+    def __init__(
+        self,
+        root_dir: Path | str,
+        virtual_mode: bool = False,
+        inherit_env: bool = False,
+        env: dict[str, str] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize LocalShellBackend with sanitized AWS cloud environment.
+
+        Args:
+            root_dir: Root directory for file and command operations.
+            virtual_mode: Whether to restrict operations to virtual filesystem.
+            inherit_env: Whether to inherit parent process environment variables.
+            env: Explicit environment variables dictionary.
+            **kwargs: Additional keyword arguments for SDKLocalShellBackend.
+        """
+        effective_env = env if env is not None else _build_shell_env()
+        super().__init__(
+            root_dir=Path(root_dir),
+            virtual_mode=virtual_mode,
+            inherit_env=inherit_env,
+            env=effective_env,
+            **kwargs,
+        )
+
+    def _sync_cloud_env(self) -> None:
+        """Dynamically sync active AWS profile and credentials into the shell execution environment.
+
+        Reads latest persisted cloud profile from config.toml, ambient AWS_PROFILE,
+        and synchronizes AWS_PROFILE, AWS_DEFAULT_PROFILE, and region.
+        When an explicit named profile is active, purges any static conflicting
+        AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY from self._env so AWS CLI and boto3
+        properly use the profile's authentic credentials rather than failing.
+        """
+        from opscloud.config.cloud_profiles import get_active_aws_profile, get_active_aws_region
+
+        active_profile = get_active_aws_profile()
+        if active_profile:
+            self._env["AWS_PROFILE"] = active_profile
+            self._env["AWS_DEFAULT_PROFILE"] = active_profile
+            os.environ["AWS_PROFILE"] = active_profile
+            os.environ["AWS_DEFAULT_PROFILE"] = active_profile
+
+            # Clear static credentials when a named profile is selected so AWS CLI
+            # authentication precedence does not prioritize stale or unauthenticated env keys.
+            if active_profile != "default":
+                self._env.pop("AWS_ACCESS_KEY_ID", None)
+                self._env.pop("AWS_SECRET_ACCESS_KEY", None)
+                self._env.pop("AWS_SESSION_TOKEN", None)
+
+        active_region = get_active_aws_region()
+        if active_region:
+            self._env["AWS_REGION"] = active_region
+            self._env["AWS_DEFAULT_REGION"] = active_region
+            os.environ["AWS_REGION"] = active_region
+            os.environ["AWS_DEFAULT_REGION"] = active_region
+        else:
+            self._env.pop("AWS_REGION", None)
+            self._env.pop("AWS_DEFAULT_REGION", None)
+            os.environ.pop("AWS_REGION", None)
+            os.environ.pop("AWS_DEFAULT_REGION", None)
+
+    def execute(
+        self,
+        command: str,
+        *,
+        timeout: int | None = None,
+    ) -> Any:
+        """Execute a shell command with dynamically synchronized cloud profile environment."""
+        self._sync_cloud_env()
+        return super().execute(command, timeout=timeout)
+
+    async def aexecute(
+        self,
+        command: str,
+        *,
+        timeout: int | None = None,
+    ) -> Any:
+        """Asynchronously execute shell command with dynamically synchronized cloud profile environment."""
+        self._sync_cloud_env()
+        return await super().aexecute(command, timeout=timeout)
+
+
+__all__ = [
+    "ALLOWED_ENV_PREFIXES",
+    "COMMON_TOOL_DIRS",
+    "LocalShellBackend",
+    "_build_shell_env",
+]

opscloud/backend/registry.py

@@ -0,0 +1,79 @@
+"""Singleton registry for backend providers in OpsCloud."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+import threading
+from typing import Any, TypeVar
+
+T = TypeVar("T", bound=type)
+
+
+class BackendRegistry:
+    """Singleton registry for backend providers."""
+
+    _instance: BackendRegistry | None = None
+    _lock = threading.Lock()
+
+    def __init__(self) -> None:
+        """Initialize BackendRegistry with an empty provider mapping."""
+        self._providers: dict[str, type] = {}
+
+    def register(self, name: str, cls: type) -> None:
+        """Register a backend provider class under *name*."""
+        self._providers[name] = cls
+
+    def build(self, name: str, **kwargs: Any) -> Any:
+        """Instantiate a registered backend by *name*."""
+        cls = self._providers.get(name)
+        if cls is None:
+            raise ValueError(f"Backend provider '{name}' is not registered.")
+        return cls(**kwargs)
+
+    def list_registered(self) -> list[str]:
+        """Return sorted list of registered backend names."""
+        return sorted(self._providers.keys())
+
+    @classmethod
+    def get_instance(cls) -> BackendRegistry:
+        """Return the singleton instance, creating it if needed."""
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = cls()
+        return cls._instance
+
+
+def get_backend_registry() -> BackendRegistry:
+    """Module-level accessor for the singleton ``BackendRegistry``."""
+    return BackendRegistry.get_instance()
+
+
+def register_backend(name: str) -> Callable[[T], T]:
+    """Class decorator to register a backend provider.
+
+    Usage::
+
+        @register_backend("local")
+        class LocalShellBackend(SDKLocalShellBackend):
+            ...
+    """
+
+    def decorator(cls: T) -> T:
+        get_backend_registry().register(name, cls)
+        return cls
+
+    return decorator
+
+
+def get_backend_class(name: str) -> type | None:
+    """Return the registered backend class for *name*, or None."""
+    return get_backend_registry()._providers.get(name)
+
+
+__all__ = [
+    "BackendRegistry",
+    "get_backend_class",
+    "get_backend_registry",
+    "register_backend",
+]

opscloud/backend/sandbox_config.py

@@ -0,0 +1,107 @@
+"""Configuration model for sandboxed backend execution environments in OpsCloud."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import os
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class SandboxConfig:
+    """Settings required to provision, configure, and connect to a sandbox environment."""
+
+    provider: str = "local"
+    """Target provider identifier ('local', 'langsmith', 'daytona', 'modal', 'runloop', 'vercel', 'agentcore')."""
+
+    sandbox_id: str | None = None
+    """Optional existing remote sandbox ID to reconnect to."""
+
+    image: str | None = None
+    """Optional container base image name or Dockerfile ref."""
+
+    setup_script_path: str | None = None
+    """Optional path to a shell script to run inside the sandbox on boot."""
+
+    snapshot_name: str | None = None
+    """Optional snapshot or blueprint name to boot from (supported by LangSmith/Runloop)."""
+
+    sync_workspace: bool = True
+    """Whether to automatically synchronize local project files into the sandbox (default True)."""
+
+    providers: dict[str, Any] = field(default_factory=dict)
+    """Optional provider-specific configurations parsed from [sandboxes.<provider>]."""
+
+    @classmethod
+    def load(cls, config_path: Path | None = None) -> SandboxConfig:
+        """Load sandbox configuration with layered precedence: Env > TOML > Defaults."""
+        from opscloud.config.toml_config import read_config_toml
+
+        toml_data = read_config_toml(config_path)
+        sandboxes_table = toml_data.get("sandboxes", {})
+        if not isinstance(sandboxes_table, dict):
+            sandboxes_table = {}
+
+        # Provider / default
+        env_provider = os.getenv("OPSCLOUD_SANDBOX_PROVIDER") or os.getenv("SANDBOX_PROVIDER")
+        toml_provider = sandboxes_table.get("default") or sandboxes_table.get("provider")
+        provider = env_provider or toml_provider or "local"
+
+        # Sandbox ID
+        env_sandbox_id = os.getenv("OPSCLOUD_SANDBOX_ID") or os.getenv("SANDBOX_ID")
+        toml_sandbox_id = sandboxes_table.get("sandbox_id")
+        sandbox_id = env_sandbox_id or toml_sandbox_id
+
+        # Image
+        env_image = os.getenv("OPSCLOUD_SANDBOX_IMAGE") or os.getenv("SANDBOX_IMAGE")
+        toml_image = sandboxes_table.get("image")
+        image = env_image or toml_image
+
+        # Setup script path
+        env_setup_script = os.getenv("OPSCLOUD_SANDBOX_SETUP_SCRIPT") or os.getenv("SANDBOX_SETUP_SCRIPT")
+        toml_setup_script = sandboxes_table.get("setup_script_path")
+        setup_script_path = env_setup_script or toml_setup_script
+
+        # Snapshot name
+        env_snapshot = os.getenv("OPSCLOUD_SANDBOX_SNAPSHOT") or os.getenv("SANDBOX_SNAPSHOT")
+        toml_snapshot = sandboxes_table.get("snapshot_name") or sandboxes_table.get("snapshot")
+        snapshot_name = env_snapshot or toml_snapshot
+
+        # Sync workspace
+        sync_raw = os.getenv("OPSCLOUD_SANDBOX_SYNC_WORKSPACE") or os.getenv("SANDBOX_SYNC_WORKSPACE")
+        if sync_raw is not None:
+            sync_workspace = sync_raw.lower() not in ("false", "0", "no")
+        elif "sync_workspace" in sandboxes_table:
+            val = sandboxes_table["sync_workspace"]
+            sync_workspace = bool(val) if not isinstance(val, str) else val.lower() not in ("false", "0", "no")
+        else:
+            sync_workspace = True
+
+        # Extract nested provider tables (e.g. [sandboxes.daytona])
+        nested_providers: dict[str, Any] = {}
+        for k, v in sandboxes_table.items():
+            if isinstance(v, dict):
+                nested_providers[k] = v
+
+        provider_clean = str(provider).lower().strip()
+        if provider_clean in ("none", ""):
+            provider_clean = "local"
+
+        return cls(
+            provider=provider_clean,
+            sandbox_id=str(sandbox_id) if sandbox_id else None,
+            image=str(image) if image else None,
+            setup_script_path=str(setup_script_path) if setup_script_path else None,
+            snapshot_name=str(snapshot_name) if snapshot_name else None,
+            sync_workspace=sync_workspace,
+            providers=nested_providers,
+        )
+
+    @classmethod
+    def from_env(cls) -> SandboxConfig:
+        """Load sandbox configuration (delegates to load())."""
+        return cls.load()
+
+
+__all__ = ["SandboxConfig"]