Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

7.1 KB
Raw Blame
# Copyright 2026 The OpenSandbox Authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""Built-in OpenSandbox skill metadata and rendering helpers."""

from __future__ import annotations

import importlib.resources
from dataclasses import dataclass
from pathlib import Path


@dataclass(frozen=True)
class SkillSpec:
    """A bundled skill shipped with the CLI."""

    slug: str
    package_file: str
    title: str
    summary: str
    trigger_hint: str
    marker_id: str


BUILTIN_SKILLS: dict[str, SkillSpec] = {
    "sandbox-troubleshooting": SkillSpec(
        slug="sandbox-troubleshooting",
        package_file="opensandbox-sandbox-troubleshooting.md",
        title="OpenSandbox Sandbox Troubleshooting",
        summary=(
            "Triage failed or unhealthy sandboxes with state, health, stable "
            "diagnostic logs/events, and concrete remediation steps."
        ),
        trigger_hint=(
            "Use when the user reports sandbox startup failures, crashes, OOM, "
            "image pull problems, pending sandboxes, or unreachable services."
        ),
        marker_id="opensandbox-sandbox-troubleshooting",
    ),
    "sandbox-lifecycle": SkillSpec(
        slug="sandbox-lifecycle",
        package_file="opensandbox-sandbox-lifecycle.md",
        title="OpenSandbox Sandbox Lifecycle",
        summary=(
            "Create, inspect, renew, pause, resume, and terminate sandboxes, "
            "manage template (golden-image) builds and snapshots, with the "
            "right defaults and follow-up checks."
        ),
        trigger_hint=(
            "Use when the user wants to create or manage a sandbox, build or "
            "use templates, or snapshot and restore sandboxes and needs the "
            "exact OpenSandbox CLI/API flow."
        ),
        marker_id="opensandbox-sandbox-lifecycle",
    ),
    "command-execution": SkillSpec(
        slug="command-execution",
        package_file="opensandbox-command-execution.md",
        title="OpenSandbox Command Execution",
        summary=(
            "Run foreground and background commands, inspect status/logs, and "
            "use persistent sessions inside a sandbox."
        ),
        trigger_hint=(
            "Use when the user wants to execute commands in a sandbox, collect "
            "logs, interrupt work, or reuse a persistent shell session."
        ),
        marker_id="opensandbox-command-execution",
    ),
    "file-operations": SkillSpec(
        slug="file-operations",
        package_file="opensandbox-file-operations.md",
        title="OpenSandbox File Operations",
        summary=(
            "Read, write, upload, download, search, replace, and manage files "
            "inside a sandbox without hand-wavy shell advice."
        ),
        trigger_hint=(
            "Use when the user needs file or directory manipulation inside an "
            "OpenSandbox sandbox."
        ),
        marker_id="opensandbox-file-operations",
    ),
    "network-egress": SkillSpec(
        slug="network-egress",
        package_file="opensandbox-network-egress.md",
        title="OpenSandbox Network Egress",
        summary=(
            "Inspect and patch sandbox runtime egress rules when the user "
            "needs to allow or deny outbound domains."
        ),
        trigger_hint=(
            "Use when the user needs to view or modify outbound network access "
            "for a sandbox, or debug domain allow and deny behavior."
        ),
        marker_id="opensandbox-network-egress",
    ),
    "credential-vault": SkillSpec(
        slug="credential-vault",
        package_file="opensandbox-credential-vault.md",
        title="OpenSandbox Credential Vault",
        summary=(
            "Create, inspect, patch, and delete sandbox-local Credential Vault "
            "state without exposing plaintext secrets in shell flags."
        ),
        trigger_hint=(
            "Use when the user needs outbound credential injection for tools "
            "inside a sandbox, or wants to manage Credential Vault credentials "
            "and bindings at runtime."
        ),
        marker_id="opensandbox-credential-vault",
    ),
}

DEFAULT_SKILL = "sandbox-troubleshooting"


def list_builtin_skills() -> list[SkillSpec]:
    """Return bundled skills in stable declaration order."""
    return list(BUILTIN_SKILLS.values())


def get_builtin_skill(slug: str) -> SkillSpec:
    """Return a bundled skill definition."""
    return BUILTIN_SKILLS[slug]


def get_builtin_skill_source(skill: SkillSpec) -> Path:
    """Locate the bundled skill file shipped with the CLI package."""
    pkg = importlib.resources.files("opensandbox_cli") / "skills" / skill.package_file
    if hasattr(pkg, "__fspath__"):
        return Path(str(pkg))
    with importlib.resources.as_file(pkg) as resolved:
        return Path(resolved)


def read_skill_markdown(skill: SkillSpec) -> str:
    """Load bundled skill markdown."""
    return get_builtin_skill_source(skill).read_text(encoding="utf-8")


def split_frontmatter(markdown: str) -> tuple[str | None, str]:
    """Split markdown into YAML frontmatter and body."""
    if not markdown.startswith("---\n"):
        return None, markdown

    closing = markdown.find("\n---\n", 4)
    if closing == -1:
        return None, markdown

    frontmatter = markdown[4:closing]
    body = markdown[closing + 5 :]
    return frontmatter, body


def extract_section(body: str, heading: str) -> str | None:
    """Extract a markdown section by exact heading text."""
    lines = body.splitlines()
    capture = False
    capture_level = 0
    captured: list[str] = []

    for line in lines:
        if line.startswith("## ") or line.startswith("### "):
            if capture:
                if capture_level == 2 and line.startswith("## "):
                    break
                if capture_level == 3 and (line.startswith("## ") or line.startswith("### ")):
                    break
            if line == f"## {heading}":
                capture = True
                capture_level = 2
                continue
            if line == f"### {heading}":
                capture = True
                capture_level = 3
                continue
        if capture:
            captured.append(line)

    if not captured:
        return None

    return "\n".join(captured).strip() or None


def render_skill_for_target(
    skill: SkillSpec,
    markdown: str,
    *,
    preserve_frontmatter: bool,
) -> str:
    """Render skill content for the target tool."""
    frontmatter, body = split_frontmatter(markdown)
    body = body.strip()

    if preserve_frontmatter or not frontmatter:
        return markdown.strip() + "\n"

    return (
        f"# {skill.title}\n\n"
        f"{skill.summary}\n\n"
        f"{body}\n"
    )