Skip to content

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

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

import {
  DEFAULT_EXECD_PORT,
  DEFAULT_HEALTH_CHECK_POLLING_INTERVAL_MILLIS,
  DEFAULT_READY_TIMEOUT_SECONDS,
  SandboxReadyTimeoutException,
} from "@alibaba-group/opensandbox";
import { createExecdClient } from "@alibaba-group/opensandbox/internal";
import { createRedirectSafeExecdFetch } from "./transport.js";
import type { Sandbox } from "@alibaba-group/opensandbox";

import { createDefaultAdapterFactory } from "./factory/defaultAdapterFactory.js";
import type { AdapterFactory } from "./factory/adapterFactory.js";
import type { Codes } from "./services/codes.js";

export interface CodeInterpreterCreateOptions {
  adapterFactory?: AdapterFactory;
  /**
   * Skip the strict code-executor readiness check. The returned interpreter
   * may fail on first use if the execd daemon is not serving yet.
   */
  skipHealthCheck?: boolean;
  /**
   * Max time to wait for the code execution service (execd) health check, in seconds.
   */
  readyTimeoutSeconds?: number;
  /**
   * Polling interval for the code execution service health check, in milliseconds.
   */
  healthCheckPollingInterval?: number;
  /**
   * Optional signal used to cancel the health check.
   */
  signal?: AbortSignal;
}

/**
 * Strict health check script: verifies the code interpreter runtime (Jupyter
 * kernel gateway) is actually serving inside the sandbox. execd starts serving
 * /ping 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.
 */
const RUNTIME_CHECK_COMMAND =
  "bash -c 'exec 3<>/dev/tcp/127.0.0.1/${JUPYTER_PORT:-44771}' && exit 0 || exit 1";

function throwIfAborted(signal?: AbortSignal): void {
  signal?.throwIfAborted();
}

function sleep(ms: number, signal?: AbortSignal): Promise<void> {
  if (!signal) return new Promise((resolve) => setTimeout(resolve, ms));
  throwIfAborted(signal);

  return new Promise<void>((resolve, reject) => {
    const timer = setTimeout(() => {
      signal.removeEventListener("abort", onAbort);
      resolve();
    }, ms);
    const onAbort = () => {
      clearTimeout(timer);
      signal.removeEventListener("abort", onAbort);
      reject(signal.reason);
    };
    signal.addEventListener("abort", onAbort, { once: true });
  });
}

/**
 * Code interpreter facade (JS/TS).
 *
 * This class wraps an existing {@link Sandbox} and provides a high-level API for code execution.
 *
 * - Use {@link codes} to create contexts and run code.
 * - {@link files}, {@link commands}, and {@link metrics} are exposed for convenience and are
 *   the same instances as on the underlying {@link Sandbox}.
 */
export class CodeInterpreter {
  private constructor(
    readonly sandbox: Sandbox,
    readonly codes: Codes,
    private readonly execdBaseUrl: string,
    private readonly execdHeaders: Record<string, string> | undefined,
  ) {}

  static async create(sandbox: Sandbox, opts: CodeInterpreterCreateOptions = {}): Promise<CodeInterpreter> {
    const endpoint = await sandbox.getEndpoint(DEFAULT_EXECD_PORT);
    const execdBaseUrl = `${sandbox.connectionConfig.protocol}://${endpoint.endpoint}`;
    const execdHeaders = endpoint.headers;
    const adapterFactory = opts.adapterFactory ?? createDefaultAdapterFactory();
    const codes = adapterFactory.createCodes({
      sandbox,
      execdBaseUrl,
      endpointHeaders: endpoint.headers,
    });

    const interpreter = new CodeInterpreter(sandbox, codes, execdBaseUrl, execdHeaders);

    if (!(opts.skipHealthCheck ?? false)) {
      await interpreter.waitUntilReady({
        readyTimeoutSeconds: opts.readyTimeoutSeconds ?? DEFAULT_READY_TIMEOUT_SECONDS,
        pollingIntervalMillis:
          opts.healthCheckPollingInterval ?? DEFAULT_HEALTH_CHECK_POLLING_INTERVAL_MILLIS,
        signal: opts.signal,
      });
    }

    return interpreter;
  }

  get id() {
    return this.sandbox.id;
  }

  get files() {
    return this.sandbox.files;
  }

  get commands() {
    return this.sandbox.commands;
  }

  get metrics() {
    return this.sandbox.metrics;
  }

  /**
   * Ping the execd daemon on the interpreter's own endpoint.
   *
   * Prefers the codes service's optional `ping` capability; custom adapters
   * that do not implement it fall back to a direct execd probe built from the
   * sandbox connection config.
   */
  private async pingExecd(signal?: AbortSignal): Promise<boolean> {
    if (typeof this.codes.ping === "function") {
      return await this.codes.ping(signal);
    }
    const { response } = await this.execdPingClient().GET("/ping", {
      parseAs: "text",
      signal,
    });
    return response.ok;
  }

  private execdPingClient() {
    return createExecdClient({
      baseUrl: this.execdBaseUrl,
      headers: this.execdHeaders ?? {},
      fetch: createRedirectSafeExecdFetch(this.sandbox, this.execdBaseUrl),
    });
  }

  /**
   * Check if the code interpreter is healthy (strict check).
   *
   * Healthy means both:
   * - the code execution service (execd) answers `GET /ping`; and
   * - the code interpreter runtime (Jupyter kernel gateway) is serving
   *   inside the sandbox, verified by probing its listen port through the
   *   execd command API.
   *
   * Exceptions from either leg are treated as unhealthy.
   */
  async isHealthy(signal?: AbortSignal): Promise<boolean> {
    try {
      if (!(await this.pingExecd(signal))) {
        return false;
      }
      return await this.isRuntimeServing(signal);
    } catch {
      return false;
    }
  }

  private async isRuntimeServing(signal?: AbortSignal): Promise<boolean> {
    try {
      const execution = await this.sandbox.commands.run(
        RUNTIME_CHECK_COMMAND,
        undefined,
        undefined,
        signal,
      );
      return execution.error == null;
    } catch {
      return false;
    }
  }

  /**
   * Poll the strict health check (execd `GET /ping` + runtime process alive)
   * until it passes, or throw {@link SandboxReadyTimeoutException} when the
   * deadline expires.
   */
  async waitUntilReady(opts: {
    readyTimeoutSeconds: number;
    pollingIntervalMillis: number;
    signal?: AbortSignal;
  }): Promise<void> {
    const deadline = Date.now() + opts.readyTimeoutSeconds * 1000;
    let attempt = 0;
    let errorDetail = "Health check returned false continuously.";

    while (true) {
      throwIfAborted(opts.signal);
      if (Date.now() >= deadline) break;
      attempt++;
      try {
        const ok = await this.isHealthy(opts.signal);
        throwIfAborted(opts.signal);
        if (ok) {
          return;
        }
        errorDetail = "Health check returned false continuously.";
      } catch (err) {
        throwIfAborted(opts.signal);
        const message = err instanceof Error ? err.message : String(err);
        errorDetail = `Last health check error: ${message}`;
      }
      // Clamp the sleep to the remaining budget so the final failed check
      // does not overshoot the timeout by a full polling interval.
      const remaining = deadline - Date.now();
      if (remaining <= 0) break;
      await sleep(Math.min(opts.pollingIntervalMillis, remaining), opts.signal);
    }

    throw new SandboxReadyTimeoutException({
      message:
        `Code interpreter ${this.id} health check timed out after ` +
        `${opts.readyTimeoutSeconds}s (${attempt} attempts). ${errorDetail} ` +
        `The code execution service (execd) or the interpreter runtime (Jupyter) ` +
        `did not become ready. Pass skipHealthCheck to skip this check.`,
    });
  }
}