Skip to content

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

2.7 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 type { Execution } from "./execution.js";

/**
 * Domain models for execd interactions.
 *
 * IMPORTANT:
 * - These are NOT OpenAPI-generated types.
 * - They are intentionally stable and JS-friendly.
 */
export interface ServerStreamEvent extends Record<string, unknown> {
  type:
    | "init"
    | "stdout"
    | "stderr"
    | "result"
    | "execution_count"
    | "execution_complete"
    | "error"
    | string;
  timestamp?: number;
  text?: string;
  results?: Record<string, unknown>;
  error?: Record<string, unknown>;
}

export interface CodeContextRequest extends Record<string, unknown> {
  language: string;
}

export type SupportedLanguage =
  | "python"
  | "go"
  | "javascript"
  | "typescript"
  | "bash"
  | "java";

export interface RunCommandOpts {
  /**
   * Working directory for command execution (maps to API `cwd`).
   */
  workingDirectory?: string;
  /**
   * Run command in detached mode.
   */
  background?: boolean;
  /**
   * Maximum execution time in seconds; server will terminate the command when reached.
   * If omitted, the server will not enforce any timeout.
   */
  timeoutSeconds?: number;
  /**
   * Unix user ID used to run the command process.
   */
  uid?: number;
  /**
   * Unix group ID used to run the command process. Requires `uid`.
   */
  gid?: number;
  /**
   * Environment variables injected into the command process.
   */
  envs?: Record<string, string>;
}

export interface CommandStatus {
  id?: string;
  content?: string;
  running?: boolean;
  exitCode?: number | null;
  error?: string;
  startedAt?: Date;
  finishedAt?: Date | null;
}

export interface CommandLogs {
  content: string;
  cursor?: number;
}

export type CommandExecution = Execution;

export interface Metrics extends Record<string, unknown> {
  cpu_count?: number;
  cpu_used_pct?: number;
  mem_total_mib?: number;
  mem_used_mib?: number;
  timestamp?: number;
}

/**
 * Normalized, JS-friendly metrics.
 */
export interface SandboxMetrics {
  cpuCount: number;
  cpuUsedPercentage: number;
  memoryTotalMiB: number;
  memoryUsedMiB: number;
  timestamp: number;
}

export type PingResponse = Record<string, unknown>;