@fastgpt-sdk/sandbox-adapter 0.0.3 → 0.0.5

package/README.md

@@ -4,160 +4,25 @@ A unified, high-level abstraction layer for cloud sandbox providers. It offers a
 
 > This package is ESM-only (`"type": "module"`) and requires Node.js **>= 20**.
 
-## Installation
+## 安装
 
 ```bash
 pnpm add @fastgpt/sandbox
 ```
 
-## Quick Start
+## 用途
 
-The following example demonstrates the complete lifecycle of a sandbox: creating, executing commands, managing files, and finally, deleting it.
+### 1. 操作沙盒
 
-```ts
-import { createSandbox } from '@fastgpt/sandbox';
+1. 执行命令：执行命令并返回结果
+   1. Create 接口：成功返回，则认为沙盒已创建成功，可以执行命令。
+   2. 执行
+2. 下载文件。
 
-async function main() {
-  // 1. Create a sandbox with the OpenSandbox provider
-  const sandbox = createSandbox({
-    provider: 'opensandbox',
-    connection: {
-      apiKey: process.env.OPEN_SANDBOX_API_KEY,
-      baseUrl: 'http://127.0.0.1:8080', // Your OpenSandbox server
-      runtime: 'kubernetes',
-    },
-  });
+### 2. 管理沙盒
 
-  console.log(`Provider: ${sandbox.provider}`);
-  try {
-    // 2. Create the sandbox instance with a specific image
-    await sandbox.create({
-      image: { repository: 'nginx', tag: 'latest' },
-      timeout: 3600, // Expiration in seconds
-    });
-    console.log(`Sandbox created: ${sandbox.id}`);
+1. 定期暂停：每 n 分钟不活跃则暂停
+2. 定期销毁：每 n 分钟不活跃则销毁
 
-    // 3. Wait until the sandbox is fully ready
-    await sandbox.waitUntilReady(60000); // 60-second timeout
-    console.log('Sandbox is ready.');
 
-    // 4. Execute a simple command
-    const version = await sandbox.execute('nginx -v');
-    console.log(`Nginx version: ${version.stdout || version.stderr}`);
-
-    // 5. Execute a command with streaming output
-    console.log('--- Streaming Execution ---');
-    await sandbox.executeStream('for i in 1 2 3; do echo "Line $i"; sleep 0.5; done', {
-      onStdout: (msg) => console.log(`  [stdout] ${msg.text}`),
-      onStderr: (msg) => console.log(`  [stderr] ${msg.text}`),
-      onComplete: (result) => console.log(`  [done] Exit code: ${result.exitCode}`),
-    });
-
-    // 6. Work with the filesystem
-    console.log('\n--- Filesystem Operations ---');
-    // Write a file
-    await sandbox.writeFiles([
-      {
-        path: '/app/hello.js',
-        data: `console.log('Hello from sandbox!');`,
-      },
-    ]);
-    console.log('Written /app/hello.js');
-
-    // Read the file back
-    const [file] = await sandbox.readFiles(['/app/hello.js']);
-    if (file && !file.error) {
-        const content = new TextDecoder().decode(file.content);
-        console.log(`Read content: "${content}"`);
-    }
-
-    // List directory
-    const entries = await sandbox.listDirectory('/app');
-    console.log('Directory listing for /app:', entries.map(e => e.name));
-
-
-    // 7. Stop and delete the sandbox
-    console.log('\n--- Cleanup ---');
-    await sandbox.stop();
-    console.log('Sandbox stopped.');
-    
-    if (sandbox.runtime !== 'kubernetes') {
-      await sandbox.delete();
-      console.log('Sandbox deleted.');
-    }
-
-  } catch (error) {
-    console.error('An error occurred:', error);
-  } finally {
-    // 8. Close the connection
-    await sandbox.close();
-    console.log('Connection closed.');
-  }
-}
-
-main();
-```
-
-## API (`ISandbox`)
-
-The `createSandbox(options)` function returns an instance that implements the `ISandbox` interface.
-
-### Lifecycle Management
-
-- **`create(options)`**: Creates a new sandbox instance.
-- **`getInfo()`**: Retrieves detailed information about the sandbox.
-- **`waitUntilReady(timeout)`**: Waits for the sandbox to become fully operational.
-- **`renewExpiration(seconds)`**: Extends the sandbox's lifetime.
-- **`pause()` / `resume()`**: Pauses and resumes a running sandbox (if supported).
-- **`stop()`**: Stops the sandbox gracefully.
-- **`delete()`**: Deletes the sandbox instance.
-- **`close()`**: Closes the connection to the provider.
-
-### Command Execution
-
-- **`execute(command)`**: Executes a command and returns the result after completion.
-- **`executeStream(command, handlers)`**: Executes a command and streams `stdout` and `stderr` in real-time.
-- **`executeBackground(command)`**: Starts a command in the background and returns a session handle.
-
-### Filesystem Operations
-
-- **`writeFiles(files)`**: Writes one or more files to the sandbox.
-- **`readFiles(paths)`**: Reads one or more files from the sandbox.
-- **`listDirectory(path)`**: Lists the contents of a directory.
-- **`createDirectories(paths)`**: Creates directories.
-- **`deleteFiles(paths)`**: Deletes files.
-- **`moveFiles(files)`**: Moves or renames files.
-
-### Health and Metrics
-
-- **`ping()`**: Performs a quick health check.
-- **`getMetrics()`**: Retrieves CPU and memory usage statistics.
-
-## Polyfill Behavior
-
-The SDK uses `CommandPolyfillService` to provide filesystem, search, health, and metrics
-operations by running shell commands inside the sandbox. Providers can override these
-methods if they have native APIs, but the default behavior is consistent across adapters.
-
-## Error Handling
-
-The SDK exports specific error types to facilitate robust error handling:
-
-- `SandboxException`
-- `FeatureNotSupportedError`
-- `FileOperationError`
-- `CommandExecutionError`
-- `TimeoutError`
-
-Example:
-```ts
-import { FileOperationError } from '@fastgpt/sandbox';
-
-try {
-  await sandbox.readFiles(['/nonexistent-file']);
-} catch (error) {
-  if (error instanceof FileOperationError) {
-    console.error(`File operation failed: ${error.message}`);
-  }
-}
-```
+## 添加新适配器

package/dist/adapters/BaseSandboxAdapter.d.ts

@@ -18,11 +18,8 @@ export declare abstract class BaseSandboxAdapter implements ISandbox {
     abstract create(config: SandboxConfig): Promise<void>;
     abstract start(): Promise<void>;
     abstract stop(): Promise<void>;
-    abstract pause(): Promise<void>;
-    abstract resume(): Promise<void>;
     abstract delete(): Promise<void>;
     abstract getInfo(): Promise<SandboxInfo | null>;
-    abstract close(): Promise<void>;
     waitUntilReady(timeoutMs?: number): Promise<void>;
     renewExpiration(_additionalSeconds: number): Promise<void>;
     abstract execute(command: string, options?: ExecuteOptions): Promise<ExecuteResult>;

package/dist/adapters/MinimalProviderAdapter.d.ts

@@ -15,7 +15,6 @@ export interface MinimalProviderConnection {
     }>;
     /** Get current status */
     getStatus(): Promise<SandboxStatus>;
-    /** Close the connection */
     close(): Promise<void>;
 }
 export type MinimalProviderConfig = {
@@ -24,9 +23,8 @@ export type MinimalProviderConfig = {
 /**
  * Minimal provider adapter.
  *
- * This demonstrates how to adapt a provider with minimal capabilities
- * (only command execution) to the full ISandbox interface using
- * the CommandPolyfillService.
+ * Adapts a provider with minimal capabilities (only command execution)
+ * to the full ISandbox interface using the CommandPolyfillService.
  *
  * Use case: Legacy SSH-based sandboxes, custom container providers,
  * or any provider that only exposes a shell interface.
@@ -38,15 +36,11 @@ export declare class MinimalProviderAdapter extends BaseSandboxAdapter {
     private connection?;
     constructor(config?: MinimalProviderConfig | undefined);
     get id(): SandboxId;
-    get status(): SandboxStatus;
     create(config: SandboxConfig): Promise<void>;
     connect(connection: MinimalProviderConnection): Promise<void>;
     start(): Promise<void>;
     stop(): Promise<void>;
-    pause(): Promise<void>;
-    resume(): Promise<void>;
     delete(): Promise<void>;
-    getInfo(): Promise<SandboxInfo>;
-    close(): Promise<void>;
+    getInfo(): Promise<SandboxInfo | null>;
     execute(command: string, options?: ExecuteOptions): Promise<ExecuteResult>;
 }

package/dist/adapters/OpenSandboxAdapter.d.ts

@@ -3,21 +3,19 @@ import { BaseSandboxAdapter } from './BaseSandboxAdapter';
 /**
  * Sandbox runtime type.
  * - docker: Full-featured runtime with pause/resume support
- * - kubernetes: Container orchestration runtime (no pause/resume, stop = delete)
+ * - kubernetes: Container orchestration runtime
  */
 export type SandboxRuntimeType = 'docker' | 'kubernetes';
 /**
  * Connection configuration options for OpenSandboxAdapter.
  */
 export interface OpenSandboxConnectionConfig {
-    /** Base URL for the OpenSandbox API (e.g., 'https://api.opensandbox.example.com') */
+    /** Base URL for the OpenSandbox API */
     baseUrl?: string;
     /** API key for authentication */
     apiKey?: string;
     /**
      * Sandbox runtime type.
-     * - docker: Full-featured with pause/resume support
-     * - kubernetes: No pause/resume, stop operation deletes the sandbox
      * @default 'docker'
      */
     runtime?: SandboxRuntimeType;
@@ -25,9 +23,7 @@ export interface OpenSandboxConnectionConfig {
 /**
  * OpenSandbox provider adapter.
  *
- * This is the "Gold Standard" implementation with full native
- * support for all features. Uses the OpenSandbox TypeScript SDK
- * for all operations.
+ * Full native support for all features via the OpenSandbox TypeScript SDK.
  *
  * @example
  * ```typescript
@@ -46,184 +42,35 @@ export interface OpenSandboxConnectionConfig {
  */
 export declare class OpenSandboxAdapter extends BaseSandboxAdapter {
     private connectionConfig;
-    /** Provider identifier */
     readonly provider: "opensandbox";
-    /** Runtime type for this adapter instance */
     readonly runtime: SandboxRuntimeType;
-    /** Internal SDK sandbox instance */
     private _sandbox?;
-    /** SDK connection configuration */
     private _connection;
-    /** Cached sandbox ID */
     private _id;
-    /** Current adapter state */
-    private _connectionState;
-    /**
-     * Creates a new OpenSandboxAdapter instance.
-     *
-     * @param connectionConfig - Connection configuration options
-     */
     constructor(connectionConfig?: OpenSandboxConnectionConfig);
-    /**
-     * Get the sandbox ID. Returns empty string if not created/connected.
-     */
     get id(): SandboxId;
-    /**
-     * Get the current connection state.
-     */
-    get connectionState(): typeof this._connectionState;
-    /**
-     * Get the underlying SDK sandbox instance.
-     * @throws {SandboxStateError} If sandbox is not initialized
-     */
     private get sandbox();
-    /**
-     * Create ConnectionConfig from adapter's connection options.
-     * Handles URL parsing with fallback to domain string.
-     */
     private createConnectionConfig;
-    /**
-     * Convert ImageSpec to SDK image format (string).
-     * Format: repository[:tag][@digest]
-     */
+    private static readonly STATE_MAP;
+    private mapStatus;
     private convertImageSpec;
-    /**
-     * Parse SDK image string into ImageSpec.
-     * Handles formats: repository, repository:tag, repository@digest
-     */
     private parseImageSpec;
-    /**
-     * Convert ResourceLimits to SDK resource format.
-     * Maps cpuCount -> cpu, memoryMiB -> memory, diskGiB -> disk
-     */
     private convertResourceLimits;
-    /**
-     * Parse SDK resource limits (Record<string, string>) to ResourceLimits.
-     * Handles memory format: 512Mi, 2Gi
-     */
     private parseResourceLimits;
-    /**
-     * Create a new sandbox with the given configuration.
-     *
-     * @param config - Sandbox configuration
-     * @throws {ConnectionError} If connection to the API fails
-     * @throws {CommandExecutionError} If sandbox creation fails
-     */
     create(config: SandboxConfig): Promise<void>;
-    /**
-     * Connect to an existing OpenSandbox instance.
-     *
-     * @param sandboxId - The ID of the sandbox to connect to
-     * @throws {ConnectionError} If connection fails or sandbox not found
-     */
     connect(sandboxId: string): Promise<void>;
-    /**
-     * Start a stopped or paused sandbox.
-     * For OpenSandbox, this resumes from paused state if applicable.
-     *
-     * @throws {SandboxStateError} If sandbox is not initialized
-     */
     start(): Promise<void>;
-    /**
-     * Stop the sandbox (graceful shutdown).
-     *
-     * @throws {SandboxStateError} If sandbox is not initialized
-     */
     stop(): Promise<void>;
-    /**
-     * Pause a running sandbox.
-     *
-     * @throws {SandboxStateError} If sandbox is not initialized
-     * @throws {FeatureNotSupportedError} If pause is not supported by the runtime
-     * @throws {CommandExecutionError} If pause fails
-     */
-    pause(): Promise<void>;
-    /**
-     * Resume a paused sandbox.
-     *
-     * @throws {SandboxStateError} If sandbox is not initialized
-     * @throws {FeatureNotSupportedError} If resume is not supported by the runtime
-     * @throws {CommandExecutionError} If resume fails
-     */
-    resume(): Promise<void>;
-    /**
-     * Delete the sandbox permanently.
-     *
-     * @throws {SandboxStateError} If sandbox is not initialized
-     * @throws {CommandExecutionError} If deletion fails
-     */
     delete(): Promise<void>;
-    /**
-     * Get detailed information about the sandbox.
-     *
-     * @returns Sandbox information
-     * @throws {SandboxStateError} If sandbox is not initialized
-     */
-    getInfo(): Promise<SandboxInfo>;
-    /**
-     * Close the connection and release resources.
-     */
-    close(): Promise<void>;
-    /**
-     * Renew the sandbox expiration.
-     *
-     * @param additionalSeconds - Seconds to extend the expiration by
-     * @throws {SandboxStateError} If sandbox is not initialized
-     * @throws {CommandExecutionError} If renewal fails
-     */
+    getInfo(): Promise<SandboxInfo | null>;
     renewExpiration(additionalSeconds: number): Promise<void>;
-    /**
-     * Execute a command and wait for completion.
-     *
-     * @param command - The command to execute
-     * @param options - Execution options
-     * @returns Execution result with stdout, stderr, and exit code
-     * @throws {SandboxStateError} If sandbox is not initialized
-     * @throws {CommandExecutionError} If execution fails
-     */
     execute(command: string, options?: ExecuteOptions): Promise<ExecuteResult>;
-    /**
-     * Execute a command with streaming output.
-     *
-     * @param command - The command to execute
-     * @param handlers - Stream handlers for output
-     * @param options - Execution options
-     * @throws {SandboxStateError} If sandbox is not initialized
-     * @throws {CommandExecutionError} If execution fails
-     */
     executeStream(command: string, handlers: StreamHandlers, options?: ExecuteOptions): Promise<void>;
-    /**
-     * Execute a command in the background.
-     *
-     * @param command - The command to execute
-     * @param options - Execution options
-     * @returns Handle with sessionId and kill function
-     * @throws {SandboxStateError} If sandbox is not initialized
-     * @throws {CommandExecutionError} If execution fails
-     */
     executeBackground(command: string, options?: ExecuteOptions): Promise<{
         sessionId: string;
         kill(): Promise<void>;
     }>;
-    /**
-     * Interrupt/kill a running command session.
-     *
-     * @param sessionId - The session ID from executeBackground
-     * @throws {SandboxStateError} If sandbox is not initialized
-     * @throws {CommandExecutionError} If interruption fails
-     */
     interrupt(sessionId: string): Promise<void>;
-    /**
-     * Check if the sandbox is healthy.
-     *
-     * @returns true if healthy, false otherwise
-     */
     ping(): Promise<boolean>;
-    /**
-     * Get current resource metrics.
-     *
-     * @returns Current metrics
-     * @throws {SandboxStateError} If sandbox is not initialized
-     */
     getMetrics(): Promise<SandboxMetrics>;
 }

package/dist/adapters/SealosDevboxAdapter/api.d.ts

@@ -0,0 +1,29 @@
+import { type DevboxApiConfig, type DevboxApiResponse, type DevboxInfoData, type DevboxMutationData, type DownloadFileParams, type ExecRequest, type ExecResponseData, type UploadFileParams, type UploadResponseData } from './type';
+/**
+ * HTTP client for the Sealos Devbox REST API.
+ *
+ * @see https://devbox-server.staging-usw-1.sealos.io
+ */
+export declare class DevboxApi {
+    private baseUrl;
+    private token;
+    constructor(config: DevboxApiConfig);
+    private url;
+    private request;
+    /** POST /api/v1/devbox — create a devbox */
+    create(name: string): Promise<DevboxApiResponse<DevboxMutationData>>;
+    /** GET /api/v1/devbox/{name} — query devbox info (state + SSH) */
+    info(name: string): Promise<DevboxApiResponse<DevboxInfoData>>;
+    /** POST /api/v1/devbox/{name}/pause */
+    pause(name: string): Promise<DevboxApiResponse<DevboxMutationData>>;
+    /** POST /api/v1/devbox/{name}/resume */
+    resume(name: string): Promise<DevboxApiResponse<DevboxMutationData>>;
+    /** DELETE /api/v1/devbox/{name} */
+    delete(name: string): Promise<DevboxApiResponse<DevboxMutationData>>;
+    /** POST /api/v1/devbox/{name}/exec */
+    exec(name: string, req: ExecRequest): Promise<DevboxApiResponse<ExecResponseData>>;
+    /** POST /api/v1/devbox/{name}/files/upload */
+    uploadFile(name: string, params: UploadFileParams, content: BodyInit): Promise<DevboxApiResponse<UploadResponseData>>;
+    /** GET /api/v1/devbox/{name}/files/download */
+    downloadFile(name: string, params: DownloadFileParams): Promise<ArrayBuffer>;
+}

package/dist/adapters/SealosDevboxAdapter/index.d.ts

@@ -0,0 +1,33 @@
+import type { ExecuteOptions, ExecuteResult, SandboxConfig, SandboxId, SandboxInfo } from '../../types';
+import { BaseSandboxAdapter } from '../BaseSandboxAdapter';
+/**
+ * Configuration for Sealos Devbox Adapter.
+ */
+export interface SealosDevboxConfig {
+    /** Base URL for the Sealos Devbox Server API */
+    baseUrl: string;
+    /** JWT authentication token */
+    token: string;
+    sandboxId: string;
+}
+export declare class SealosDevboxAdapter extends BaseSandboxAdapter {
+    private config;
+    readonly provider: "sealos-devbox";
+    private api;
+    private _id;
+    constructor(config: SealosDevboxConfig);
+    get id(): SandboxId;
+    private StatusAdapt;
+    private waitUntilDeleted;
+    getInfo(): Promise<SandboxInfo | null>;
+    create(_config: SandboxConfig): Promise<void>;
+    stop(): Promise<void>;
+    start(): Promise<void>;
+    delete(): Promise<void>;
+    execute(command: string, options?: ExecuteOptions): Promise<ExecuteResult>;
+    /**
+     * Check if the devbox is ready by querying info endpoint.
+     * Ready when spec, status, and phase are all "Running".
+     */
+    ping(): Promise<boolean>;
+}

package/dist/adapters/SealosDevboxAdapter/type.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Devbox phases representing various lifecycle states.
+ */
+export declare enum DevboxPhaseEnum {
+    Running = "Running",
+    Pending = "Pending",
+    Paused = "Paused",
+    Pausing = "Pausing",
+    Stopped = "Stopped",
+    Stopping = "Stopping",
+    Shutdown = "Shutdown",
+    Shutting = "Shutting",
+    Error = "Error",
+    Unknown = "Unknown"
+}
+/** Configuration for the Devbox REST API client. */
+export interface DevboxApiConfig {
+    /** Base URL of the devbox server */
+    baseUrl: string;
+    /** JWT token for authentication */
+    token: string;
+}
+/** Unified API response envelope. */
+export interface DevboxApiResponse<T> {
+    code: number;
+    message: string;
+    data: T;
+}
+/** Request body for the exec endpoint. */
+export interface ExecRequest {
+    command: string[];
+    /** Optional stdin content */
+    stdin?: string;
+    /** Timeout in seconds [1, 600], default 30 */
+    timeoutSeconds?: number;
+    /** Target container name, defaults to first container in Pod */
+    container?: string;
+}
+/** Response data from the exec endpoint. */
+export interface ExecResponseData {
+    podName: string;
+    container: string;
+    command: string[];
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    executedAt: string;
+}
+/** Response data from create/pause/resume/delete endpoints. */
+export interface DevboxMutationData {
+    name: string;
+    state?: string;
+    status?: string;
+}
+/** SSH connection info returned by the info endpoint. */
+export interface DevboxSshInfo {
+    user: string;
+    host: string;
+    port: number;
+    target: string;
+    link: string;
+    command: string;
+    privateKeyEncoding: string;
+    privateKeyBase64: string;
+}
+/** Response data from the GET info endpoint. */
+export interface DevboxInfoData {
+    name: string;
+    deletionTimestamp?: string | null;
+    state: {
+        phase: `${DevboxPhaseEnum}`;
+    };
+    ssh: DevboxSshInfo;
+}
+/** Response data from the upload endpoint. */
+export interface UploadResponseData {
+    name: string;
+    podName: string;
+    container: string;
+    path: string;
+    sizeBytes: number;
+    mode: string;
+    uploadedAt: string;
+    timeoutSecond: number;
+}
+/** Query parameters for file upload. */
+export interface UploadFileParams {
+    /** Remote path inside the container */
+    path: string;
+    /** File permission, octal string e.g. "0644" */
+    mode?: string;
+    /** Timeout in seconds [1, 3600], default 300 */
+    timeoutSeconds?: number;
+    /** Target container name */
+    container?: string;
+}
+/** Query parameters for file download. */
+export interface DownloadFileParams {
+    /** Remote file path inside the container */
+    path: string;
+    /** Suggested filename for the response header */
+    filename?: string;
+    /** Timeout in seconds [1, 3600], default 300 */
+    timeoutSeconds?: number;
+    /** Target container name */
+    container?: string;
+}

package/dist/adapters/index.d.ts

@@ -1,9 +1,9 @@
 import { ISandbox } from '../interfaces';
-import { type FastGPTSandboxConfig } from './FastGPTSandboxAdapter';
+import { type SealosDevboxConfig } from './SealosDevboxAdapter';
 import { type MinimalProviderConfig } from './MinimalProviderAdapter';
 import { type OpenSandboxConnectionConfig } from './OpenSandboxAdapter';
 export { BaseSandboxAdapter } from './BaseSandboxAdapter';
-export { FastGPTSandboxAdapter, type FastGPTSandboxConfig } from './FastGPTSandboxAdapter';
+export { SealosDevboxAdapter, type SealosDevboxConfig } from './SealosDevboxAdapter';
 export { MinimalProviderAdapter, type MinimalProviderConfig, type MinimalProviderConnection } from './MinimalProviderAdapter';
 export { OpenSandboxAdapter, type OpenSandboxConnectionConfig, type SandboxRuntimeType } from './OpenSandboxAdapter';
 type CreateProviderType = {
@@ -13,8 +13,8 @@ type CreateProviderType = {
     provider: 'minimal';
     config: MinimalProviderConfig;
 } | {
-    provider: 'fastgpt';
-    config: FastGPTSandboxConfig;
+    provider: 'sealos-devbox';
+    config: SealosDevboxConfig;
 };
 /**
  * Create a sandbox provider instance.