opensandbox-cli 0.1.0__py3-none-any.whl

opensandbox_cli/skill_registry.py

@@ -0,0 +1,184 @@
+"""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, summary, "
+            "inspect, events, logs, 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 "
+            "with the right defaults and follow-up checks."
+        ),
+        trigger_hint=(
+            "Use when the user wants to create or manage a sandbox 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",
+    ),
+}
+
+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"
+    )

opensandbox_cli/skills/opensandbox-command-execution.md

@@ -0,0 +1,215 @@
+---
+name: command-execution
+description: Use OpenSandbox command execution commands to run foreground or background processes, inspect tracked execution status and logs, interrupt work, and manage persistent shell sessions inside a sandbox. Trigger when users want to execute commands in a sandbox and need exact OpenSandbox CLI flows.
+---
+
+# OpenSandbox Command Execution
+
+Run commands with `osb command`. Use foreground streaming by default, and add `--background` when you need tracked execution.
+
+## When To Use
+
+- the user wants to run a one-off command in a sandbox
+- the user needs a tracked background command with later status/log inspection
+- the user wants to stop a running command
+- the user wants a persistent shell session that keeps working directory or environment state across runs
+
+## Config Gate
+
+Run this first:
+
+```bash
+osb config show -o json
+```
+
+If `domain` is missing, stop and set it before command execution:
+
+```bash
+osb config set connection.domain <host:port> -o json
+osb config show -o json
+```
+
+If auth is required and `api_key` is missing, stop and set it before command execution:
+
+```bash
+osb config set connection.api_key <api-key> -o json
+osb config show -o json
+```
+
+## Separator Rule
+
+Use `--` before the sandbox command payload. This is required when the payload contains flags like `-l`, `-c`, or `-m`.
+
+```bash
+osb command run <sandbox-id> -o raw -- sh -lc 'echo ready'
+osb command run <sandbox-id> -o raw -- python -m http.server
+osb command session run <sandbox-id> <session-id> -o raw -- sh -lc 'pwd'
+```
+
+## Execution Modes
+
+Treat these as three distinct execution paths:
+
+- `osb command run` without `--background`
+  Use for foreground one-shot commands when the result should stream directly to the terminal
+- `osb command run --background`
+  Use when the user needs an execution ID, later status checks, or log retrieval
+- `osb command session ...`
+  Use when shell state must persist across commands, such as exported variables or a working directory
+
+## Golden Paths
+
+Foreground one-shot command:
+
+```bash
+osb command run <sandbox-id> -o raw -- python -c "print(1 + 1)"
+```
+
+Tracked background command:
+
+```bash
+osb command run <sandbox-id> --background -o json -- sh -c "sleep 10; echo done"
+osb command status <sandbox-id> <execution-id> -o json
+osb command logs <sandbox-id> <execution-id> -o json
+```
+
+Persistent session:
+
+```bash
+osb command session create <sandbox-id> --workdir /workspace -o json
+osb command session run <sandbox-id> <session-id> -o raw -- pwd
+osb command session run <sandbox-id> <session-id> -o raw -- export FOO=bar
+osb command session run <sandbox-id> <session-id> -o raw -- sh -c 'echo $FOO'
+osb command session delete <sandbox-id> <session-id> -o json
+```
+
+## Foreground Commands
+
+For simple one-off execution, use:
+
+```bash
+osb command run <sandbox-id> -o raw -- <command>
+osb command run <sandbox-id> --workdir /workspace -o raw -- <command>
+osb command run <sandbox-id> --timeout 30s -o raw -- <command>
+```
+
+Use foreground mode when the user wants immediate output and does not need a tracked execution ID.
+
+## Background Commands
+
+Use background mode when the user will need follow-up inspection:
+
+```bash
+osb command run <sandbox-id> --background -o json -- <command>
+osb command run <sandbox-id> --background --workdir /workspace -o json -- <command>
+osb command run <sandbox-id> --background --timeout 5m -o json -- <command>
+```
+
+Then inspect the tracked execution:
+
+```bash
+osb command status <sandbox-id> <execution-id> -o json
+osb command logs <sandbox-id> <execution-id> -o json
+osb command logs <sandbox-id> <execution-id> --cursor 0 -o json
+```
+
+Use `status` for lifecycle state and exit information. Use `logs` for tracked background output. Do not suggest `command logs` for foreground commands that already streamed to the terminal.
+
+## Persistent Sessions
+
+Use sessions when commands must share shell state:
+
+```bash
+osb command session create <sandbox-id> --workdir /workspace -o json
+osb command session run <sandbox-id> <session-id> -o raw -- pwd
+osb command session run <sandbox-id> <session-id> -o raw -- export FOO=bar
+osb command session run <sandbox-id> <session-id> -o raw -- sh -c 'echo $FOO'
+osb command session run <sandbox-id> <session-id> --workdir /var -o raw -- pwd
+osb command session delete <sandbox-id> <session-id> -o json
+```
+
+Rules:
+
+- `session create --workdir` sets the initial working directory for the session
+- `session run --workdir` overrides the working directory for that single run only
+- exported variables and shell state persist across `session run` calls in the same session
+- delete the session when the user is done; do not leave idle sessions around
+
+## Interrupting Work
+
+Interrupt only tracked executions:
+
+```bash
+osb command interrupt <sandbox-id> <execution-id> -o json
+```
+
+Only suggest interruption when the user explicitly wants to stop work or the process is clearly stuck.
+
+## Failure Semantics
+
+- foreground `osb command run` streams output directly and requires `-o raw`
+- background `osb command run --background` returns tracked execution metadata and supports structured output
+- `session run` also exits non-zero on execution error
+- tracked background commands should be checked with `status` and `logs`
+- if the command failure is caused by an unhealthy sandbox rather than the command itself, switch to `sandbox-troubleshooting`
+
+## Response Pattern
+
+Structure the answer as:
+
+1. exact command to run
+2. which execution mode it uses
+3. the next inspection or cleanup command if the workflow continues
+
+Keep command examples concrete and ready to paste.
+
+## Minimal Closed Loops
+
+Foreground command with timeout:
+
+```bash
+osb command run <sandbox-id> --timeout 30s -o raw -- python -c "print(1 + 1)"
+```
+
+Tracked background execution:
+
+```bash
+osb command run <sandbox-id> --background -o json -- sh -c "sleep 10; echo done"
+osb command status <sandbox-id> <execution-id> -o json
+osb command logs <sandbox-id> <execution-id> -o json
+```
+
+Background execution with interrupt:
+
+```bash
+osb command run <sandbox-id> --background -o json -- sh -c "sleep 300"
+osb command interrupt <sandbox-id> <execution-id> -o json
+osb command status <sandbox-id> <execution-id> -o json
+```
+
+Persistent session with shared shell state:
+
+```bash
+osb command session create <sandbox-id> --workdir /workspace -o json
+osb command session run <sandbox-id> <session-id> -o raw -- export FOO=bar
+osb command session run <sandbox-id> <session-id> -o raw -- sh -c 'echo $FOO'
+osb command session delete <sandbox-id> <session-id> -o json
+```
+
+Per-run working directory override inside a session:
+
+```bash
+osb command session create <sandbox-id> --workdir /tmp -o json
+osb command session run <sandbox-id> <session-id> -o raw -- pwd
+osb command session run <sandbox-id> <session-id> --workdir /var -o raw -- pwd
+osb command session delete <sandbox-id> <session-id> -o json
+```
+
+## Best Practices
+
+- use `osb command run -o raw -- ...` for quick foreground commands
+- use `--background` when the user will need execution tracking
+- use sessions only when state persistence is actually needed
+- use `--workdir` explicitly when directory context matters
+- use `--timeout` when the command should not run indefinitely
+- prefer `status` before guessing whether a background command is still running or already failed

opensandbox_cli/skills/opensandbox-file-operations.md

@@ -0,0 +1,244 @@
+---
+name: file-operations
+description: Use OpenSandbox file commands to read, write, upload, download, search, replace, move, delete, and inspect files or directories inside a sandbox. Trigger when users want exact sandbox file manipulation commands instead of generic shell guidance.
+---
+
+# OpenSandbox File Operations
+
+Manipulate sandbox files with `osb file` commands. Choose the operation mode first, then use the matching verification step. Do not mix sandbox-internal edits with host-to-sandbox transfer commands casually.
+
+## When To Use
+
+- the user wants to read or write a file inside a sandbox
+- the user needs to upload a local file into a sandbox or download a sandbox file back to the host
+- the user wants to search, replace, move, chmod, or inspect paths
+- the user needs directory creation or cleanup
+
+## Config Gate
+
+Run this first:
+
+```bash
+osb config show -o json
+```
+
+If `domain` is missing, stop and set it before file commands:
+
+```bash
+osb config set connection.domain <host:port> -o json
+osb config show -o json
+```
+
+If auth is required and `api_key` is missing, stop and set it before file commands:
+
+```bash
+osb config set connection.api_key <api-key> -o json
+osb config show -o json
+```
+
+## Operation Modes
+
+Treat these as distinct categories:
+
+- sandbox-only content operations
+  `cat`, `write`, `replace`, `mv`, `mkdir`, `rm`, `rmdir`, `info`, `chmod`
+- host-to-sandbox transfer
+  `upload`
+- sandbox-to-host transfer
+  `download`
+- discovery before modification
+  `search`, then `info`
+
+If the path is uncertain, search first. If the file boundary crosses between host and sandbox, use `upload` or `download` instead of `write` or `cat`.
+
+## Golden Paths
+
+Write and verify inside the sandbox:
+
+```bash
+osb file write <sandbox-id> /workspace/app.txt -c "hello" -o json
+osb file cat <sandbox-id> /workspace/app.txt -o raw
+```
+
+Upload from host and verify in the sandbox:
+
+```bash
+osb file upload <sandbox-id> ./local.txt /workspace/local.txt -o json
+osb file cat <sandbox-id> /workspace/local.txt -o raw
+```
+
+Search before editing:
+
+```bash
+osb file search <sandbox-id> /workspace --pattern "*.py" -o json
+osb file info <sandbox-id> /workspace/main.py -o json
+```
+
+## Sandbox-Only File Edits
+
+Read and write:
+
+```bash
+osb file cat <sandbox-id> /path/to/file -o raw
+osb file write <sandbox-id> /path/to/file -c "hello" -o json
+```
+
+Use `write` with `-c/--content` when the new content is known directly. If the content should come from stdin, omit `-c` and pipe or paste the content into the command.
+
+Edit existing content:
+
+```bash
+osb file replace <sandbox-id> /path/to/file --old old --new new -o json
+osb file mv <sandbox-id> /old/path /new/path -o json
+```
+
+Prefer `replace` for small text substitutions and `mv` for rename/path changes. Do not rewrite a full file when a targeted replace is enough.
+
+Create directories:
+
+```bash
+osb file mkdir <sandbox-id> /workspace/output -o json
+osb file mkdir <sandbox-id> /workspace/a /workspace/b --mode 755 -o json
+```
+
+## Host <-> Sandbox Transfer
+
+Host to sandbox:
+
+```bash
+osb file upload <sandbox-id> ./local.txt /remote/path/local.txt -o json
+```
+
+Sandbox to host:
+
+```bash
+osb file download <sandbox-id> /remote/path/result.json ./result.json -o json
+```
+
+Rules:
+
+- use `upload` when the source file is on the host
+- use `download` when the destination should be written to the host filesystem
+- use `write` and `cat` only when the operation stays entirely inside the sandbox
+
+## Metadata and Permissions
+
+Inspect metadata:
+
+```bash
+osb file info <sandbox-id> /path/to/file -o json
+osb file info <sandbox-id> /path/one /path/two -o json
+```
+
+Search by pattern:
+
+```bash
+osb file search <sandbox-id> /workspace --pattern "*.py" -o json
+```
+
+Set permissions:
+
+```bash
+osb file chmod <sandbox-id> /path/to/script --mode 755 -o json
+osb file chmod <sandbox-id> /path/to/file --mode 644 --owner root --group root -o json
+```
+
+Use `info` after `chmod` when the user needs to confirm mode, ownership, or timestamps changed as expected.
+
+## Destructive Operations
+
+Delete files or directories only after verifying the target path:
+
+```bash
+osb file info <sandbox-id> /workspace/tmp.txt -o json
+osb file rm <sandbox-id> /workspace/tmp.txt -o json
+```
+
+```bash
+osb file search <sandbox-id> /workspace --pattern "old-*" -o json
+osb file rmdir <sandbox-id> /workspace/old-dir -o json
+```
+
+Rules:
+
+- prefer `info` when the exact path is known
+- prefer `search` when the path is uncertain
+- do not suggest `rm` or `rmdir` until the target has been verified
+- after `mv`, `rm`, or `rmdir`, verify the new state with `info` or `search`
+
+## Failure Semantics
+
+- `upload` and `download` have host filesystem side effects; treat them as cross-boundary operations
+- `download` writes to the local path immediately, so be explicit about the destination
+- permission or ownership failures are usually path/runtime permission issues, not a reason to switch away from `osb file`
+- if multiple file commands fail unexpectedly, check sandbox health before assuming a file-command bug
+
+## Response Pattern
+
+Structure the answer as:
+
+1. exact `osb file` command
+2. which operation mode it uses
+3. the next verification command if the workflow continues
+
+Keep command examples concrete and ready to paste.
+
+## Minimal Closed Loops
+
+Write and verify:
+
+```bash
+osb file write <sandbox-id> /workspace/app.txt -c "hello" -o json
+osb file cat <sandbox-id> /workspace/app.txt -o raw
+```
+
+Upload and verify:
+
+```bash
+osb file upload <sandbox-id> ./local.txt /workspace/local.txt -o json
+osb file cat <sandbox-id> /workspace/local.txt -o raw
+```
+
+Replace and verify:
+
+```bash
+osb file replace <sandbox-id> /workspace/app.txt --old hello --new world -o json
+osb file cat <sandbox-id> /workspace/app.txt -o raw
+```
+
+Change permissions and inspect:
+
+```bash
+osb file chmod <sandbox-id> /workspace/script.sh --mode 755 -o json
+osb file info <sandbox-id> /workspace/script.sh -o json
+```
+
+Create a directory and inspect it:
+
+```bash
+osb file mkdir <sandbox-id> /workspace/output -o json
+osb file info <sandbox-id> /workspace/output -o json
+```
+
+Move a file and verify the new path:
+
+```bash
+osb file mv <sandbox-id> /workspace/app.txt /workspace/archive/app.txt -o json
+osb file info <sandbox-id> /workspace/archive/app.txt -o json
+```
+
+Delete and verify removal:
+
+```bash
+osb file info <sandbox-id> /workspace/tmp.txt -o json
+osb file rm <sandbox-id> /workspace/tmp.txt -o json
+osb file search <sandbox-id> /workspace --pattern "tmp.txt" -o json
+```
+
+## Best Practices
+
+- prefer `search` before modification when the path is not certain
+- prefer `info` before destructive actions
+- prefer `replace` over full rewrites for small text changes
+- prefer `upload` and `download` only for host boundary crossings
+- prefer explicit verification after `mv`, `chmod`, `rm`, and `rmdir`