Skip to content

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

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

using System.Diagnostics;
using OpenSandbox.CodeInterpreter.Factory;
using OpenSandbox.CodeInterpreter.Services;
using OpenSandbox.Config;
using OpenSandbox.Core;
using OpenSandbox.Factory;
using OpenSandbox.Internal;
using OpenSandbox.Services;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Logging.Abstractions;

namespace OpenSandbox.CodeInterpreter;

/// <summary>
/// Strict health check helpers for code interpreters.
/// </summary>
public static class CodeInterpreterHealthCheck
{
    /// <summary>
    /// The shell command run inside the sandbox to verify the interpreter runtime
    /// (Jupyter kernel gateway) is actually serving. execd starts serving
    /// <c>/ping</c> before the entrypoint launches Jupyter, and the setup stage may
    /// run short-lived "jupyter kernelspec" helpers, so a daemon ping or a
    /// process-name grep cannot prove the runtime is ready. Probing the Jupyter
    /// listen port (127.0.0.1:${JUPYTER_PORT:-44771}, same default as the entrypoint)
    /// only passes once the server accepts connections.
    /// </summary>
    public const string RuntimeCheckCommand =
        "bash -c 'exec 3<>/dev/tcp/127.0.0.1/${JUPYTER_PORT:-44771}' && exit 0 || exit 1";
}

/// <summary>
/// Options for creating a code interpreter.
/// </summary>
public class CodeInterpreterCreateOptions
{
    /// <summary>
    /// Gets or sets the adapter factory. If not provided, a default factory is used.
    /// </summary>
    public ICodeInterpreterAdapterFactory? AdapterFactory { get; set; }

    /// <summary>
    /// Gets or sets diagnostics options such as logging.
    /// </summary>
    public SdkDiagnosticsOptions? Diagnostics { get; set; }

    /// <summary>
    /// Gets or sets whether to skip the strict code-executor readiness check.
    /// The returned interpreter may fail on first use if the execd daemon is
    /// not serving yet.
    /// </summary>
    public bool SkipHealthCheck { get; set; }

    /// <summary>
    /// Gets or sets the timeout for the code execution service health check, in seconds.
    /// </summary>
    public int? ReadyTimeoutSeconds { get; set; }

    /// <summary>
    /// Gets or sets the health check polling interval, in milliseconds.
    /// </summary>
    public int? HealthCheckPollingInterval { get; set; }
}

/// <summary>
/// Options for waiting until a code interpreter is ready.
/// </summary>
public class CodeInterpreterWaitUntilReadyOptions
{
    /// <summary>
    /// Gets or sets the timeout in seconds.
    /// </summary>
    public int ReadyTimeoutSeconds { get; set; }

    /// <summary>
    /// Gets or sets the polling interval in milliseconds.
    /// </summary>
    public int PollingIntervalMillis { get; set; }
}

/// <summary>
/// Code interpreter facade for executing code in multiple languages.
/// </summary>
/// <remarks>
/// This class wraps an existing <see cref="Sandbox"/> and provides a high-level API for code execution.
/// Use <see cref="Codes"/> to create contexts and run code.
/// <see cref="Files"/>, <see cref="Commands"/>, and <see cref="Metrics"/> are exposed for convenience
/// and are the same instances as on the underlying <see cref="Sandbox"/>.
/// This type does not own the remote sandbox lifecycle. Call <see cref="Sandbox.KillAsync"/> when you want to terminate
/// the remote instance. Dispose the wrapped <see cref="Sandbox"/> to release local SDK resources.
/// </remarks>
public sealed class CodeInterpreter
{
    /// <summary>
    /// Gets the underlying sandbox instance.
    /// </summary>
    public Sandbox Sandbox { get; }

    /// <summary>
    /// Gets the codes service for code execution operations.
    /// </summary>
    public ICodes Codes { get; }

    /// <summary>
    /// Gets the sandbox ID.
    /// </summary>
    public string Id => Sandbox.Id;

    /// <summary>
    /// Gets the filesystem service.
    /// </summary>
    public ISandboxFiles Files => Sandbox.Files;

    /// <summary>
    /// Gets the command execution service.
    /// </summary>
    public IExecdCommands Commands => Sandbox.Commands;

    /// <summary>
    /// Gets the metrics service.
    /// </summary>
    public IExecdMetrics Metrics => Sandbox.Metrics;

    private readonly ILogger _logger;
    private readonly HttpClientWrapper? _fallbackExecdClient;

    private CodeInterpreter(Sandbox sandbox, ICodes codes, ILogger logger, HttpClientWrapper? fallbackExecdClient = null)
    {
        Sandbox = sandbox ?? throw new ArgumentNullException(nameof(sandbox));
        Codes = codes ?? throw new ArgumentNullException(nameof(codes));
        _logger = logger ?? throw new ArgumentNullException(nameof(logger));
        _fallbackExecdClient = fallbackExecdClient;
        _logger.LogDebug("Code interpreter initialized for sandbox: {SandboxId}", sandbox.Id);
    }

    /// <summary>
    /// Creates a new code interpreter from an existing sandbox.
    /// </summary>
    /// <remarks>
    /// By default a strict health check runs before the interpreter is returned: the code
    /// execution service (execd) must answer <c>GET /ping</c> AND the code interpreter
    /// runtime (Jupyter kernel gateway) must be serving, both within
    /// <see cref="CodeInterpreterCreateOptions.ReadyTimeoutSeconds"/>. execd starts
    /// serving before the runtime launches, so the daemon ping alone is not enough.
    /// Set <see cref="CodeInterpreterCreateOptions.SkipHealthCheck"/> to opt out.
    /// </remarks>
    /// <param name="sandbox">The sandbox to wrap.</param>
    /// <param name="options">Optional creation options.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>A new code interpreter instance.</returns>
    /// <exception cref="InvalidArgumentException">Thrown when <paramref name="sandbox"/> is null.</exception>
    /// <exception cref="SandboxException">Thrown when endpoint discovery or adapter initialization fails.</exception>
    /// <exception cref="SandboxReadyTimeoutException">Thrown when the code execution service health check times out.</exception>
    public static async Task<CodeInterpreter> CreateAsync(
        Sandbox sandbox,
        CodeInterpreterCreateOptions? options = null,
        CancellationToken cancellationToken = default)
    {
        if (sandbox == null)
        {
            throw new InvalidArgumentException("sandbox cannot be null");
        }

        var loggerFactory = options?.Diagnostics?.LoggerFactory ?? sandbox.SharedLoggerFactory ?? NullLoggerFactory.Instance;
        var logger = loggerFactory.CreateLogger("OpenSandbox.CodeInterpreter.CodeInterpreter");
        var endpoint = await sandbox.GetEndpointAsync(Constants.DefaultExecdPort, cancellationToken).ConfigureAwait(false);
        logger.LogInformation("Creating code interpreter for sandbox: {SandboxId}", sandbox.Id);
        var protocol = sandbox.ConnectionConfig.Protocol == ConnectionProtocol.Https ? "https" : "http";
        var execdBaseUrl = $"{protocol}://{endpoint.EndpointAddress}";
        var execdHeaders = DefaultAdapterFactory.BuildDataPlaneHeaders(sandbox.ConnectionConfig, endpoint.Headers);
        var adapterFactory = options?.AdapterFactory ?? DefaultCodeInterpreterAdapterFactory.Create();

        var codes = adapterFactory.CreateCodes(new CreateCodesStackOptions
        {
            ConnectionConfig = sandbox.ConnectionConfig,
            ExecdBaseUrl = execdBaseUrl,
            ExecdHeaders = execdHeaders,
            HttpClientProvider = sandbox.SharedHttpClientProvider,
            LoggerFactory = loggerFactory
        });

        // Fallback execd probe for custom codes adapters that do not implement
        // IExecdHealth; shares the sandbox's HTTP client.
        var fallbackExecdClient = new HttpClientWrapper(
            sandbox.SharedHttpClientProvider.HttpClient,
            execdBaseUrl,
            execdHeaders,
            loggerFactory.CreateLogger("OpenSandbox.CodeInterpreter.HttpClientWrapper"));

        var interpreter = new CodeInterpreter(sandbox, codes, logger, fallbackExecdClient);

        if (!(options?.SkipHealthCheck ?? false))
        {
            await interpreter.WaitUntilReadyAsync(new CodeInterpreterWaitUntilReadyOptions
            {
                ReadyTimeoutSeconds = options?.ReadyTimeoutSeconds ?? Constants.DefaultReadyTimeoutSeconds,
                PollingIntervalMillis = options?.HealthCheckPollingInterval ?? Constants.DefaultHealthCheckPollingIntervalMillis,
            }, cancellationToken).ConfigureAwait(false);
        }

        return interpreter;
    }

    /// <summary>
    /// Checks whether the code interpreter is healthy (strict check).
    /// </summary>
    /// <remarks>
    /// Healthy means both:
    /// <list type="bullet">
    /// <item>the code execution service (execd) answers <c>GET /ping</c>; and</item>
    /// <item>the code interpreter runtime (Jupyter kernel gateway) is serving
    /// inside the sandbox, verified by probing its listen port through the
    /// execd command API.</item>
    /// </list>
    /// Exceptions from either leg are treated as unhealthy.
    /// </remarks>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>True if the code interpreter is healthy, false otherwise.</returns>
    public async Task<bool> IsHealthyAsync(CancellationToken cancellationToken = default)
    {
        try
        {
            if (!await PingExecdAsync(cancellationToken).ConfigureAwait(false))
            {
                return false;
            }

            return await IsRuntimeServingAsync(cancellationToken).ConfigureAwait(false);
        }
        catch (Exception ex)
        {
            _logger.LogDebug(ex, "Health check failed for code interpreter {SandboxId}", Id);
            return false;
        }
    }

    /// <summary>
    /// Pings the execd daemon on the interpreter's own endpoint. Prefers the codes
    /// service's optional <see cref="IExecdHealth"/> capability; custom adapters that
    /// do not implement it fall back to a direct probe sharing the sandbox HTTP client.
    /// </summary>
    private async Task<bool> PingExecdAsync(CancellationToken cancellationToken)
    {
        if (Codes is IExecdHealth health)
        {
            return await health.PingAsync(cancellationToken).ConfigureAwait(false);
        }

        if (_fallbackExecdClient == null)
        {
            return false;
        }

        try
        {
            await _fallbackExecdClient.GetAsync("/ping", cancellationToken: cancellationToken).ConfigureAwait(false);
            return true;
        }
        catch (Exception ex)
        {
            _logger.LogDebug(ex, "Fallback execd ping failed for code interpreter {SandboxId}", Id);
            return false;
        }
    }

    private async Task<bool> IsRuntimeServingAsync(CancellationToken cancellationToken)
    {
        try
        {
            var execution = await Sandbox.Commands.RunAsync(
                CodeInterpreterHealthCheck.RuntimeCheckCommand,
                cancellationToken: cancellationToken).ConfigureAwait(false);
            // A non-zero exit without an error event is still a failure;
            // an indeterminate result (neither Complete nor Error observed,
            // e.g. a dropped stream) is not proof of health either.
            return execution is { Error: null, ExitCode: 0 };
        }
        catch (Exception ex)
        {
            _logger.LogDebug(ex, "Runtime check failed for code interpreter {SandboxId}", Id);
            return false;
        }
    }

    /// <summary>
    /// Waits until the strict health check passes (execd answers <c>GET /ping</c>
    /// and the interpreter runtime process is alive).
    /// </summary>
    /// <param name="options">The wait options.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <exception cref="SandboxReadyTimeoutException">Thrown when the health check times out.</exception>
    /// <exception cref="OperationCanceledException">Thrown when <paramref name="cancellationToken"/> is canceled.</exception>
    public async Task WaitUntilReadyAsync(
        CodeInterpreterWaitUntilReadyOptions options,
        CancellationToken cancellationToken = default)
    {
        _logger.LogDebug(
            "Start readiness check for code interpreter {SandboxId} (timeoutSeconds={TimeoutSeconds})",
            Id, options.ReadyTimeoutSeconds);
        var timeout = TimeSpan.FromSeconds(options.ReadyTimeoutSeconds);
        var stopwatch = Stopwatch.StartNew();
        var attempt = 0;
        var errorDetail = "Health check returned false continuously.";

        while (true)
        {
            cancellationToken.ThrowIfCancellationRequested();

            if (stopwatch.Elapsed > timeout)
            {
                throw new SandboxReadyTimeoutException(
                    $"Code interpreter {Id} health check timed out after {options.ReadyTimeoutSeconds}s ({attempt} attempts). " +
                    $"{errorDetail} The code execution service (execd) or the interpreter runtime (Jupyter) " +
                    "did not become ready. Set SkipHealthCheck to skip this check.");
            }
            attempt++;

            try
            {
                if (await IsHealthyAsync(cancellationToken).ConfigureAwait(false))
                {
                    _logger.LogInformation("Code interpreter is ready: {SandboxId}", Id);
                    return;
                }

                errorDetail = "Health check returned false continuously.";
            }
            catch (Exception ex)
            {
                _logger.LogDebug(ex, "Readiness probe failed for code interpreter {SandboxId}", Id);
                errorDetail = $"Last health check error: {ex.Message}";
            }

            var remaining = timeout - stopwatch.Elapsed;
            if (remaining <= TimeSpan.Zero)
            {
                continue;
            }

            var pollingInterval = TimeSpan.FromMilliseconds(options.PollingIntervalMillis);
            var delay = pollingInterval < remaining ? pollingInterval : remaining;
            await Task.Delay(delay, cancellationToken).ConfigureAwait(false);
        }
    }
}