Skip to content

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

4.3 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.

"""Stable sandbox diagnostics commands backed by the Python SDK."""

from __future__ import annotations

import click
from opensandbox.models.diagnostics import DiagnosticContent

from opensandbox_cli.client import ClientContext
from opensandbox_cli.utils import handle_errors, output_option, prepare_output


def render_diagnostic_content(
    obj: ClientContext,
    content: DiagnosticContent,
    output_format: str | None,
    *,
    title: str,
) -> None:
    """Render diagnostics descriptor or raw diagnostic payload."""
    output = prepare_output(
        obj,
        output_format,
        allowed=("table", "json", "yaml", "raw"),
        fallback="raw",
    )

    if output.fmt == "raw":
        if content.truncated:
            click.echo("Warning: diagnostic content was truncated.", err=True)
        for warning in content.warnings or []:
            click.echo(f"Warning: {warning}", err=True)
        if content.delivery == "inline":
            click.echo(content.content or "")
            return
        if content.content_url:
            click.echo(content.content_url)
            return
        raise click.ClickException(
            "Diagnostic response did not include inline content or a content URL."
        )

    output.print_dict(content.model_dump(mode="json"), title=title)


@click.group("diagnostics", invoke_without_command=True)
@click.pass_context
def diagnostics_group(ctx: click.Context) -> None:
    """Stable sandbox diagnostics backed by the OpenSandbox SDK."""
    if ctx.invoked_subcommand is None:
        click.echo(ctx.get_help())


@diagnostics_group.command("context")
@click.argument("sandbox_id")
@output_option("table", "json", "yaml")
@click.pass_obj
@handle_errors
def diagnostics_context(
    obj: ClientContext,
    sandbox_id: str,
    output_format: str | None,
) -> None:
    """Identify the sandbox backend and its diagnostic identifiers."""
    context = obj.get_manager().get_diagnostic_context(sandbox_id)
    output = prepare_output(
        obj, output_format, allowed=("table", "json", "yaml"), fallback="table"
    )
    output.print_dict(context.model_dump(mode="json"), title="Diagnostic Context")


@diagnostics_group.command("logs")
@click.argument("sandbox_id")
@click.option(
    "--scope",
    "-s",
    required=True,
    help=(
        "Diagnostic log scope. Built-in server scopes: container and all; "
        "other scopes are server-defined."
    ),
)
@output_option(
    "table",
    "json",
    "yaml",
    "raw",
    help_text="Output format. raw prints inline text, or the content URL for URL-delivered diagnostics.",
)
@click.pass_obj
@handle_errors
def diagnostics_logs(
    obj: ClientContext,
    sandbox_id: str,
    scope: str,
    output_format: str | None,
) -> None:
    """Retrieve diagnostic logs for a sandbox."""
    content = obj.get_manager().get_diagnostic_logs(sandbox_id, scope=scope)
    render_diagnostic_content(obj, content, output_format, title="Diagnostic Logs")


@diagnostics_group.command("events")
@click.argument("sandbox_id")
@click.option(
    "--scope",
    "-s",
    required=True,
    help=(
        "Diagnostic event scope. Built-in server scopes: runtime and all; "
        "other scopes are server-defined."
    ),
)
@output_option(
    "table",
    "json",
    "yaml",
    "raw",
    help_text="Output format. raw prints inline text, or the content URL for URL-delivered diagnostics.",
)
@click.pass_obj
@handle_errors
def diagnostics_events(
    obj: ClientContext,
    sandbox_id: str,
    scope: str,
    output_format: str | None,
) -> None:
    """Retrieve diagnostic events for a sandbox."""
    content = obj.get_manager().get_diagnostic_events(sandbox_id, scope=scope)
    render_diagnostic_content(obj, content, output_format, title="Diagnostic Events")