talkops-opscloud 0.3.0b1__py3-none-any.whl

opscloud/backend/sandbox_factory.py

@@ -0,0 +1,432 @@
+# pyright: reportMissingImports=false
+"""Factory for creating sandbox backends (LangSmith, Daytona, Modal, Runloop).
+
+Note: Sandbox providers (LangSmith, Daytona, Modal, Runloop, Vercel) are optional
+dependencies and are imported lazily inside their respective creation functions
+to avoid hard dependency requirements at startup.
+"""
+
+from __future__ import annotations
+
+import atexit
+import os
+from pathlib import Path
+import shlex
+import string
+import threading
+from typing import Any
+
+from opscloud.backend.local import LocalShellBackend
+from opscloud.backend.sandbox_config import SandboxConfig
+from opscloud.config.paths import find_project_root
+from opscloud.utils.logger import AgentLogger
+
+logger = AgentLogger("SandboxFactory")
+
+# Thread-safe global cache for active sandbox backends, keyed by thread_id
+_active_sandboxes: dict[str, Any] = {}
+_active_sandboxes_lock = threading.Lock()
+
+# Registry of active context managers or providers to delete at exit
+_active_providers: dict[str, Any] = {}
+
+# Default working directories inside the sandbox containers
+WORKING_DIRS = {
+    "langsmith": "/root",
+    "modal": "/workspace",
+    "daytona": "/home/daytona",
+    "runloop": "/home/user",
+    "vercel": "/vercel/sandbox",
+    "agentcore": "/workspace",
+}
+
+# Directories to exclude from remote sandbox file synchronization
+WORKSPACE_IGNORE_DIRS: frozenset[str] = frozenset(
+    {
+        ".git",
+        ".venv",
+        "__pycache__",
+        ".pytest_cache",
+        ".mypy_cache",
+        ".gemini",
+        ".agents",
+        ".opscloud",
+        "tests",
+        "scratch",
+        ".terraform",
+        ".terragrunt-cache",
+        "cdk.out",
+        "node_modules",
+        "dist",
+        "build",
+    }
+)
+
+WORKSPACE_IGNORE_EXTS: frozenset[str] = frozenset(
+    {
+        ".pyc",
+        ".pyo",
+        ".pyd",
+        ".bak",
+        ".tmp",
+    }
+)
+
+
+def get_sandbox_working_dir(provider: str) -> str:
+    """Return default working directory for a given provider."""
+    return WORKING_DIRS.get(provider, "/workspace")
+
+
+def get_project_root() -> Path:
+    """Return the resolved project root or current working directory."""
+    root = find_project_root()
+    if root is not None:
+        return root
+    try:
+        from opscloud.project_utils import get_server_project_context
+
+        ctx = get_server_project_context()
+        if ctx is not None:
+            return ctx.user_cwd
+    except Exception:
+        pass
+    return Path.cwd().resolve()
+
+
+def _sync_workspace_to_sandbox(backend: Any, provider: str) -> None:
+    """Upload project workspace files to the remote sandbox container."""
+    root = get_project_root()
+    working_dir = get_sandbox_working_dir(provider)
+    logger.info(f"Syncing workspace {root} to sandbox {working_dir}...")
+
+    files_to_upload: list[tuple[str, bytes]] = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        # Prune ignored directories in-place
+        dirnames[:] = [d for d in dirnames if d not in WORKSPACE_IGNORE_DIRS]
+
+        for fname in filenames:
+            ext = os.path.splitext(fname)[1].lower()
+            if ext in WORKSPACE_IGNORE_EXTS:
+                continue
+
+            local_path = Path(dirpath) / fname
+            try:
+                # Calculate relative path and target absolute path in the sandbox
+                rel_path = local_path.relative_to(root)
+                remote_path = f"{working_dir}/{rel_path}"
+
+                # Check file size (skip large files > 10MB)
+                file_size = local_path.stat().st_size
+                if file_size > 10 * 1024 * 1024:
+                    logger.debug(f"Skipping large file during sync: {rel_path} ({file_size} bytes)")
+                    continue
+
+                content = local_path.read_bytes()
+                files_to_upload.append((remote_path, content))
+            except Exception as e:
+                logger.warning(f"Failed to prepare file {local_path} for upload: {e}")
+
+    # Upload files in batches to prevent hitting request payload or token limits
+    batch_size = 20
+    logger.info(f"Uploading {len(files_to_upload)} files to sandbox...")
+    for i in range(0, len(files_to_upload), batch_size):
+        batch = files_to_upload[i : i + batch_size]
+        try:
+            responses = backend.upload_files(batch)
+            for resp in responses:
+                if getattr(resp, "error", None):
+                    logger.warning(f"Failed to upload {resp.path}: {resp.error}")
+        except Exception as e:
+            logger.error(f"Error uploading batch {i // batch_size + 1}: {e}")
+
+    logger.info("Workspace synchronization completed.")
+
+
+def _run_sandbox_setup(backend: Any, setup_script_path: str) -> None:
+    """Run user's setup script inside the sandbox after expanding environment variables."""
+    script_path = Path(setup_script_path)
+    if not script_path.exists():
+        raise FileNotFoundError(f"Setup script not found at {setup_script_path}")
+
+    logger.info(f"Executing setup script: {setup_script_path}...")
+    script_content = script_path.read_text(encoding="utf-8")
+
+    # Substitute environment variables
+    template = string.Template(script_content)
+    expanded_script = template.safe_substitute(os.environ)
+
+    # Run in sandbox
+    result = backend.execute(f"bash -c {shlex.quote(expanded_script)}")
+    if result.exit_code != 0:
+        logger.error(f"Setup script failed with exit code {result.exit_code}:\n{result.output}")
+        raise RuntimeError(f"Sandbox setup script execution failed: exit {result.exit_code}")
+
+    logger.info("Sandbox setup complete.")
+
+
+def _create_langsmith_sandbox(config: SandboxConfig) -> Any:
+    """Create a LangSmith sandbox backend."""
+    try:
+        from deepagents.backends.langsmith import (
+            LangSmithSandbox,  # Lazy import: optional dependency
+        )
+        from langsmith.sandbox import SandboxClient  # Lazy import: optional dependency
+    except ImportError as e:
+        raise ImportError(
+            "LangSmith sandbox dependencies not installed. Install them to use LangSmith sandboxes."
+        ) from e
+
+    api_key = (
+        os.getenv("OPSCLOUD_LANGSMITH_API_KEY")
+        or os.getenv("LANGSMITH_SANDBOX_API_KEY")
+        or os.getenv("LANGSMITH_API_KEY")
+        or os.getenv("LANGCHAIN_API_KEY")
+    )
+    if not api_key:
+        raise ValueError("No LangSmith API key found. Set LANGSMITH_API_KEY.")
+
+    client = SandboxClient(api_key=api_key)
+
+    if config.sandbox_id:
+        logger.info(f"Connecting to existing LangSmith sandbox ID: {config.sandbox_id}")
+        sandbox = client.get_sandbox(name=config.sandbox_id)
+        return LangSmithSandbox(sandbox)
+
+    snapshot_name = config.snapshot_name or "opscloud-aws-agent"
+    image = config.image or "python:3.12-slim"
+
+    logger.info(f"Ensuring LangSmith snapshot ready: {snapshot_name} (image: {image})")
+    snapshots = client.list_snapshots()
+    snapshot_id = None
+    for snap in snapshots:
+        if snap.name == snapshot_name and snap.status == "ready":
+            snapshot_id = snap.id
+            break
+
+    if not snapshot_id:
+        logger.info(f"Building new LangSmith snapshot: {snapshot_name}")
+        snapshot = client.create_snapshot(
+            name=snapshot_name,
+            docker_image=image,
+            fs_capacity_bytes=16 * 1024**3,
+        )
+        snapshot_id = snapshot.id
+
+    logger.info(f"Creating fresh LangSmith sandbox from snapshot {snapshot_name}...")
+    sandbox = client.create_sandbox(snapshot_id=snapshot_id)
+    return LangSmithSandbox(sandbox)
+
+
+def _import_provider_module(
+    module_name: str,
+    *,
+    provider: str,
+    package: str,
+) -> Any:
+    """Import an optional provider module with a clear install command.
+
+    Args:
+        module_name: Python module name to import.
+        provider: Sandbox provider name (e.g. 'daytona').
+        package: PyPI package name to install if missing.
+
+    Returns:
+        The imported module object.
+
+    Raises:
+        ImportError: If the optional dependency is not installed.
+    """
+    import importlib
+
+    try:
+        return importlib.import_module(module_name)
+    except ImportError as exc:
+        msg = (
+            f"The '{provider}' sandbox provider requires the '{package}' package. "
+            f"Install it with: uv pip install {package}"
+        )
+        raise ImportError(msg) from exc
+
+
+def _create_other_sandbox(config: SandboxConfig) -> Any:
+    """Dynamic fallback provider loader for Daytona, Modal, Runloop, Vercel."""
+    provider = config.provider
+    if provider == "daytona":
+        daytona = _import_provider_module("daytona", provider="daytona", package="daytona")
+        langchain_daytona = _import_provider_module("langchain_daytona", provider="daytona", package="langchain-daytona")
+        DaytonaSandbox = getattr(langchain_daytona, "DaytonaSandbox")
+
+        api_key = os.getenv("DAYTONA_API_KEY")
+        if not api_key:
+            raise ValueError("No Daytona API key found. Set DAYTONA_API_KEY.")
+        client = daytona.Daytona(
+            daytona.DaytonaConfig(
+                api_key=api_key,
+                api_url=os.getenv("DAYTONA_API_URL"),
+            )
+        )
+        sandbox = client.create()
+        return DaytonaSandbox(sandbox=sandbox)
+
+    elif provider == "modal":
+        modal = _import_provider_module("modal", provider="modal", package="modal")
+        langchain_modal = _import_provider_module("langchain_modal", provider="modal", package="langchain-modal")
+        ModalSandbox = getattr(langchain_modal, "ModalSandbox")
+
+        app = modal.App.lookup(name="opscloud-sandbox", create_if_missing=True)
+        if config.sandbox_id:
+            sandbox = modal.Sandbox.from_id(sandbox_id=config.sandbox_id)
+        else:
+            sandbox = modal.Sandbox.create(app=app, workdir="/workspace")
+        return ModalSandbox(sandbox=sandbox)
+
+    elif provider == "runloop":
+        langchain_runloop = _import_provider_module("langchain_runloop", provider="runloop", package="langchain-runloop")
+        RunloopProvider = getattr(langchain_runloop, "RunloopProvider")
+
+        api_key = os.getenv("RUNLOOP_API_KEY")
+        if not api_key:
+            raise ValueError("No Runloop API key found. Set RUNLOOP_API_KEY.")
+        prov = RunloopProvider(api_key=api_key)
+        return prov.get_or_create(sandbox_id=config.sandbox_id, blueprint=config.snapshot_name)
+
+    elif provider == "agentcore":
+        from opscloud.config.aws import get_boto3_session
+
+        agentcore_module = _import_provider_module(
+            "bedrock_agentcore.tools.code_interpreter_client",
+            provider="agentcore",
+            package="langchain-agentcore-codeinterpreter",
+        )
+        agentcore_backend = _import_provider_module(
+            "langchain_agentcore_codeinterpreter",
+            provider="agentcore",
+            package="langchain-agentcore-codeinterpreter",
+        )
+        sess = get_boto3_session()
+        region = sess.region_name or "us-west-2"
+        CodeInterpreter = getattr(agentcore_module, "CodeInterpreter")
+        AgentCoreSandbox = getattr(agentcore_backend, "AgentCoreSandbox")
+        interpreter = CodeInterpreter(region=region, session=sess)
+        interpreter.start()
+        return AgentCoreSandbox(interpreter=interpreter)
+
+    else:
+        raise NotImplementedError(f"Unsupported sandbox provider: {provider}")
+
+
+def get_sandbox_backend(thread_id: str | None = None) -> Any:
+    """Resolve, create, or fetch the cached sandbox backend for the given session thread."""
+    config = SandboxConfig.from_env()
+
+    # If provider is local, bypass the cache and return a local shell backend immediately
+    if config.provider == "local":
+        root = get_project_root()
+        return LocalShellBackend(
+            root_dir=root,
+            virtual_mode=False,
+            inherit_env=True,
+        )
+
+    # Use thread_id or fallback to a global key for execution loops without a session graph context
+    cache_key = thread_id or "__global__"
+
+    with _active_sandboxes_lock:
+        if cache_key in _active_sandboxes:
+            return _active_sandboxes[cache_key]
+
+        logger.info(f"Initializing new sandbox backend for key {cache_key} (provider: {config.provider})...")
+
+        backend = (
+            _create_langsmith_sandbox(config)
+            if config.provider == "langsmith"
+            else _create_other_sandbox(config)
+        )
+
+        # Synchronize workspace if enabled
+        if config.sync_workspace:
+            try:
+                _sync_workspace_to_sandbox(backend, config.provider)
+            except Exception as e:
+                logger.error(f"Workspace sync to sandbox failed: {e}")
+
+        # Run setup script if specified
+        if config.setup_script_path:
+            try:
+                _run_sandbox_setup(backend, config.setup_script_path)
+            except Exception as e:
+                logger.error(f"Sandbox setup script failed: {e}")
+
+        # Cache the initialized backend
+        _active_sandboxes[cache_key] = backend
+        _active_providers[cache_key] = (config.provider, getattr(backend, "id", str(cache_key)))
+
+        logger.info(f"Sandbox backend successfully cached. Key: {cache_key}")
+        return backend
+
+
+def cleanup_sandbox(thread_id: str) -> None:
+    """Terminate the sandbox backend associated with a thread ID."""
+    with _active_sandboxes_lock:
+        backend = _active_sandboxes.pop(thread_id, None)
+        provider_info = _active_providers.pop(thread_id, None)
+
+        if backend and provider_info:
+            provider, sandbox_id = provider_info
+            logger.info(f"Terminating sandbox {sandbox_id} ({provider}) for thread {thread_id}...")
+            try:
+                if provider == "langsmith":
+                    from langsmith.sandbox import SandboxClient
+
+                    client = SandboxClient()
+                    client.delete_sandbox(sandbox_id)
+                elif provider == "daytona":
+                    daytona = _import_provider_module("daytona", provider="daytona", package="daytona")
+                    client = daytona.Daytona()
+                    sandbox = client.get(sandbox_id)
+                    client.delete(sandbox)
+                elif provider == "modal":
+                    modal = _import_provider_module("modal", provider="modal", package="modal")
+                    sandbox = modal.Sandbox.from_id(sandbox_id=sandbox_id)
+                    sandbox.terminate()
+                elif provider == "runloop":
+                    langchain_runloop = _import_provider_module("langchain_runloop", provider="runloop", package="langchain-runloop")
+                    RunloopProvider = getattr(langchain_runloop, "RunloopProvider")
+                    api_key = os.getenv("RUNLOOP_API_KEY")
+                    if not api_key:
+                        logger.warning("No Runloop API key found during cleanup. Runloop sandbox cannot be deleted.")
+                    else:
+                        prov = RunloopProvider(api_key=api_key)
+                        prov.delete(sandbox_id=sandbox_id)
+                logger.info(f"Sandbox {sandbox_id} terminated.")
+            except Exception as e:
+                logger.warning(f"Error during sandbox termination for {sandbox_id}: {e}")
+
+
+def cleanup_all_sandboxes() -> None:
+    """Cleanup exit handler to shut down all active sandboxes on process shutdown."""
+    keys = list(_active_sandboxes.keys())
+    if keys:
+        logger.info("Process exit detected. Cleaning up all active sandboxes...")
+        for key in keys:
+            cleanup_sandbox(key)
+
+
+# Register exit handler
+atexit.register(cleanup_all_sandboxes)
+
+create_sandbox_backend = get_sandbox_backend
+clear_sandbox_cache = cleanup_all_sandboxes
+
+__all__ = [
+    "WORKSPACE_IGNORE_DIRS",
+    "WORKSPACE_IGNORE_EXTS",
+    "clear_sandbox_cache",
+    "cleanup_all_sandboxes",
+    "cleanup_sandbox",
+    "create_sandbox_backend",
+    "get_project_root",
+    "get_sandbox_backend",
+    "get_sandbox_working_dir",
+]

opscloud/built_in_skills/remember/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: remember
+description: "Distill the conversation to capture cloud infrastructure decisions, DevOps patterns, operator preferences, and operational runbooks into persistent memory (AGENTS.md) or reusable OpsCloud skills. Use when the operator says: (1) remember this, (2) save cloud preferences, (3) update memory, (4) persist operational learnings."
+license: MIT
+compatibility: designed for opscloud
+---
+
+Review the conversation and capture valuable operational knowledge. Focus especially on **cloud & DevOps best practices**, **infrastructure conventions**, and **operator preferences**—these are the most important things to preserve across sessions.
+
+## Step 1: Identify Best Practices and Key Learnings
+
+Scan the conversation for:
+
+### Cloud Infrastructure & DevOps Practices (highest priority)
+- **Patterns that worked well** - cloud architectures, Terraform modules, Helm values, Kubernetes configurations, and deployment pipelines proven effective
+- **Gotchas and anti-patterns to avoid** - cloud misconfigurations, IAM privilege pitfalls, security group leaks, egress cost surprises, or brittle CLI commands
+- **Operational & reliability standards** - SLAs, backup policies, tagging conventions, health check setups, and disaster recovery procedures
+- **Architectural decision rationale** - why specific instance types (e.g. Graviton), regions, cloud providers, or networking topologies were selected
+
+### Operator & Environment Context
+- Operator personal details (names, family context, preferences) and communication style
+- Active cloud profiles (e.g., AWS profiles like `krayak`), default accounts, and preferred regions
+- Project infrastructure layout, workspace paths, and toolchain versions
+- Operator feedback on agent behavior, automated remediation steps, or approval thresholds
+
+## Step 2: Decide Where to Store Each Learning
+
+For each learning or convention, choose the appropriate destination:
+
+### -> Persistent Memory (AGENTS.md) for preferences, conventions, and rules
+Use persistent memory when the knowledge is:
+- An operator preference, personal detail, or environment default
+- A global or project cloud convention (e.g., "always deploy to us-west-2", "tag all AWS resources with CostCenter")
+- A rule or constraint the agent must always respect
+
+**Global** (`$OPSCLOUD_HOME/AGENTS.md` or `~/.opscloud/AGENTS.md`): Universal operator identity, personal details, cross-cloud defaults, and global DevOps preferences
+**Project** (`.opscloud/AGENTS.md` or `AGENTS.md`): Project-specific infrastructure conventions, cloud accounts, Terraform workspace rules, and cluster topologies
+
+### -> Reusable Skill for multi-step DevOps workflows and runbooks
+**Create a skill when** we developed:
+- A multi-step operational runbook or deployment workflow
+- A methodology for troubleshooting complex cloud incidents (e.g., EKS node drain failures, VPC peering issues)
+- An infrastructure automation pattern with safety checks and best practices baked in
+- A procedure that should be executed consistently
+
+Skills are more powerful than memory entries because they can encode **how** to execute operational procedures safely, not just **what** to remember.
+
+## Step 3: Create Skills for Significant Operational Procedures
+
+If we established best practices around a cloud workflow or runbook, capture them in a reusable skill.
+
+**Example:** If we established a standard procedure for provisioning EKS clusters with Karpenter, rotating IAM credentials, or triaging S3 lifecycle rules, create an OpsCloud skill that encodes those practices into a structured workflow.
+
+### Skill Location
+- Global: `$OPSCLOUD_HOME/skills/<skill-name>/SKILL.md` (or `~/.opscloud/skills/<skill-name>/SKILL.md`)
+- Project: `.opscloud/skills/<skill-name>/SKILL.md`
+
+### Skill Structure
+```
+skill-name/
+├── SKILL.md          (required - main instructions with best practices)
+├── scripts/          (optional - automation scripts)
+├── references/       (optional - cloud specs, architecture docs)
+└── assets/           (optional - templates, policy examples)
+```
+
+### SKILL.md Format
+```markdown
+---
+name: skill-name
+description: "What this cloud skill does AND when to activate it. Include specific triggers like 'when deploying to EKS' or 'when configuring AWS VPC'."
+---
+
+# Skill Name
+
+## Overview
+Brief explanation of what this cloud skill accomplishes.
+
+## Best Practices
+Capture the key cloud & DevOps practices upfront:
+- Best practice 1: explanation
+- Best practice 2: explanation
+
+## Operational Procedure
+Step-by-step instructions (imperative form):
+1. First, verify active cloud credentials and target account
+2. Next, validate configuration with dry-run or plan
+3. Apply changes and verify health metrics
+
+## Common Pitfalls
+- Pitfall to avoid and why
+- Anti-pattern discovered during past operations
+```
+
+### Key Principles
+1. **Encode safety & best practices prominently** - Put credential checks and dry-run steps near the top
+2. **Concise is key** - Only include non-obvious knowledge; justify every paragraph's token cost
+3. **Clear triggers** - The description determines when OpsCloud activates the skill; be specific
+4. **Imperative form** - Write commands: "Verify cluster status" not "You should verify cluster status"
+5. **Include anti-patterns** - What NOT to do in production is often as critical as what to do
+
+## Step 4: Update Persistent Memory for Simpler Learnings
+
+For operator preferences, identity details, and DevOps guidelines that don't warrant a full skill:
+
+```markdown
+## Operator Preferences & Identity
+- Preferred name: Sandeep
+- Personal / family context: ...
+- Preferred AWS region: us-west-2
+- Always use Graviton (arm64) instances for cost efficiency
+
+## Infrastructure Standards & Conventions
+- Enforce tags: Environment, Owner, ManagedBy=OpsCloud
+- Avoid public S3 buckets unless explicitly authorized
+```
+
+Use `read_file` to inspect the target `AGENTS.md` (e.g. `~/.opscloud/AGENTS.md`) first. Check if the section or preference already exists. Then use `edit_file` to update/insert, or `write_file` if creating anew. Preserve existing markers and structure.
+
+## Step 5: Summarize Changes
+
+List what was captured and where it was stored:
+- Skills created (with key operational practices encoded)
+- Memory entries added (with location e.g. `Saved to persistent memory (~/.opscloud/AGENTS.md):`)