@fastgpt-sdk/sandbox-adapter 0.0.1

package/dist/interfaces/ICommandExecution.d.ts

@@ -0,0 +1,41 @@
+import type { ExecuteOptions, ExecuteResult, StreamHandlers } from '../types';
+/**
+ * Interface for command execution within a sandbox.
+ * Follows Interface Segregation Principle.
+ */
+export interface ICommandExecution {
+    /**
+     * 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 {CommandExecutionError} If command fails
+     * @throws {TimeoutError} If execution times out
+     */
+    execute(command: string, options?: ExecuteOptions): Promise<ExecuteResult>;
+    /**
+     * Execute a command with streaming output.
+     * Provides real-time access to stdout/stderr via handlers.
+     * @param command The command to execute
+     * @param handlers Stream handlers for output
+     * @param options Execution options
+     * @throws {CommandExecutionError} If command fails
+     */
+    executeStream(command: string, handlers: StreamHandlers, options?: ExecuteOptions): Promise<void>;
+    /**
+     * Execute a command in the background.
+     * Returns immediately with a handle to control the execution.
+     * @param command The command to execute
+     * @param options Execution options
+     * @returns Handle for background execution
+     */
+    executeBackground(command: string, options?: ExecuteOptions): Promise<{
+        sessionId: string;
+        kill(): Promise<void>;
+    }>;
+    /**
+     * Interrupt/kill a running command session.
+     * @param sessionId The session ID from executeBackground
+     */
+    interrupt(sessionId: string): Promise<void>;
+}

package/dist/interfaces/IFileSystem.d.ts

@@ -0,0 +1,99 @@
+import type { ContentReplaceEntry, DirectoryEntry, FileDeleteResult, FileInfo, FileReadResult, FileWriteEntry, FileWriteResult, MoveEntry, PermissionEntry, ReadFileOptions, SearchResult } from '../types';
+/**
+ * Interface for filesystem operations within a sandbox.
+ * Follows Interface Segregation Principle.
+ *
+ * All methods support batch operations for efficiency.
+ * Providers without native batch support will have operations
+ * automatically parallelized by the base adapter.
+ */
+export interface IFileSystem {
+    /**
+     * Read files from the sandbox.
+     * @param paths Array of file paths to read
+     * @param options Read options
+     * @returns Array of results (one per path, may include errors)
+     */
+    readFiles(paths: string[], options?: ReadFileOptions): Promise<FileReadResult[]>;
+    /**
+     * Write files to the sandbox.
+     * Supports strings, bytes, and streams.
+     * @param entries Files to write
+     * @returns Array of results with bytes written
+     */
+    writeFiles(entries: FileWriteEntry[]): Promise<FileWriteResult[]>;
+    /**
+     * Delete files from the sandbox.
+     * @param paths Files to delete
+     * @returns Array of results
+     */
+    deleteFiles(paths: string[]): Promise<FileDeleteResult[]>;
+    /**
+     * Move/rename files within the sandbox.
+     * @param entries Move operations to perform
+     */
+    moveFiles(entries: MoveEntry[]): Promise<void>;
+    /**
+     * Replace content within files.
+     * @param entries Replacement operations
+     */
+    replaceContent(entries: ContentReplaceEntry[]): Promise<void>;
+    /**
+     * Read a file as a stream.
+     * Efficient for large files.
+     * @param path File path
+     * @returns Async iterable of file chunks
+     */
+    readFileStream(path: string): AsyncIterable<Uint8Array>;
+    /**
+     * Write a file from a stream.
+     * Efficient for large files.
+     * @param path File path
+     * @param stream Data stream
+     */
+    writeFileStream(path: string, stream: ReadableStream<Uint8Array>): Promise<void>;
+    /**
+     * Create directories.
+     * Creates parent directories as needed.
+     * @param paths Directories to create
+     * @param options Directory options (mode, owner, group)
+     */
+    createDirectories(paths: string[], options?: {
+        mode?: number;
+        owner?: string;
+        group?: string;
+    }): Promise<void>;
+    /**
+     * Delete directories and their contents.
+     * @param paths Directories to delete
+     * @param options Options (recursive, force)
+     */
+    deleteDirectories(paths: string[], options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+    /**
+     * List directory contents.
+     * @param path Directory path
+     * @returns Array of directory entries
+     */
+    listDirectory(path: string): Promise<DirectoryEntry[]>;
+    /**
+     * Get file/directory information.
+     * @param paths Paths to query
+     * @returns Map of path to file info
+     */
+    getFileInfo(paths: string[]): Promise<Map<string, FileInfo>>;
+    /**
+     * Set file permissions.
+     * @param entries Permission changes to apply
+     */
+    setPermissions(entries: PermissionEntry[]): Promise<void>;
+    /**
+     * Search for files matching a pattern.
+     * @param pattern Search pattern (glob or regex, provider-dependent)
+     * @param path Directory to search in
+     * @returns Array of matching results
+     */
+    search(pattern: string, path?: string): Promise<SearchResult[]>;
+}

package/dist/interfaces/IHealthCheck.d.ts

@@ -0,0 +1,23 @@
+import type { SandboxMetrics } from '../types';
+/**
+ * Interface for health checking and metrics.
+ * Follows Interface Segregation Principle.
+ */
+export interface IHealthCheck {
+    /**
+     * Check if the sandbox is healthy and responsive.
+     * @returns true if healthy, false otherwise
+     */
+    ping(): Promise<boolean>;
+    /**
+     * Get current resource metrics.
+     * @returns Current metrics (CPU, memory usage)
+     */
+    getMetrics(): Promise<SandboxMetrics>;
+    /**
+     * Stream metrics in real-time.
+     * Not all providers support this.
+     * @returns Async iterable of metric snapshots
+     */
+    streamMetrics?(): AsyncIterable<SandboxMetrics>;
+}

package/dist/interfaces/ISandbox.d.ts

@@ -0,0 +1,23 @@
+import type { ICommandExecution } from './ICommandExecution';
+import type { IFileSystem } from './IFileSystem';
+import type { IHealthCheck } from './IHealthCheck';
+import type { ISandboxLifecycle } from './ISandboxLifecycle';
+/**
+ * Unified sandbox interface.
+ * Composes all sandbox behaviors into a single interface.
+ *
+ * This is the primary interface that consumers interact with.
+ * All concrete adapters must implement this interface.
+ *
+ * Following Interface Segregation Principle, this interface
+ * is composed of smaller, focused interfaces.
+ */
+export interface ISandbox extends ISandboxLifecycle, ICommandExecution, IFileSystem, IHealthCheck {
+    /** Provider name (e.g., 'opensandbox') */
+    readonly provider: string;
+    /**
+     * Close the connection and release resources.
+     * Should be called when done with the sandbox.
+     */
+    close(): Promise<void>;
+}

package/dist/interfaces/ISandboxLifecycle.d.ts

@@ -0,0 +1,54 @@
+import type { SandboxConfig, SandboxId, SandboxInfo, SandboxStatus } from '../types';
+/**
+ * Interface for sandbox lifecycle operations.
+ * Follows Interface Segregation Principle - only lifecycle methods.
+ */
+export interface ISandboxLifecycle {
+    /** Unique identifier for this sandbox */
+    readonly id: SandboxId;
+    /** Current status of the sandbox */
+    readonly status: SandboxStatus;
+    /**
+     * Create a new sandbox with the given configuration.
+     * The sandbox ID is assigned after creation.
+     */
+    create(config: SandboxConfig): Promise<void>;
+    /**
+     * Start a stopped sandbox.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop a running sandbox (graceful shutdown).
+     */
+    stop(): Promise<void>;
+    /**
+     * Pause a running sandbox.
+     * Not all providers support this.
+     */
+    pause(): Promise<void>;
+    /**
+     * Resume a paused sandbox.
+     * Not all providers support this.
+     */
+    resume(): Promise<void>;
+    /**
+     * Delete the sandbox permanently.
+     */
+    delete(): Promise<void>;
+    /**
+     * Get detailed information about the sandbox.
+     */
+    getInfo(): Promise<SandboxInfo | null>;
+    /**
+     * Wait until the sandbox is ready (healthy and responsive).
+     * @param timeoutMs Maximum time to wait in milliseconds
+     * @throws {SandboxReadyTimeoutError} If timeout is exceeded
+     */
+    waitUntilReady(timeoutMs?: number): Promise<void>;
+    /**
+     * Renew the sandbox expiration, extending its lifetime.
+     * Not all providers support this.
+     * @param additionalSeconds Seconds to extend
+     */
+    renewExpiration(additionalSeconds: number): Promise<void>;
+}

package/dist/interfaces/index.d.ts

@@ -0,0 +1,5 @@
+export type { ICommandExecution } from './ICommandExecution';
+export type { IFileSystem } from './IFileSystem';
+export type { IHealthCheck } from './IHealthCheck';
+export type { ISandbox } from './ISandbox';
+export type { ISandboxLifecycle } from './ISandboxLifecycle';

package/dist/polyfill/CommandPolyfillService.d.ts

@@ -0,0 +1,122 @@
+import type { ICommandExecution } from '../interfaces';
+import type { DirectoryEntry, FileInfo, SearchResult } from '../types';
+/**
+ * Service that implements filesystem operations via command execution.
+ *
+ * This is the core polyfill mechanism that enables feature parity
+ * for providers that only offer raw command execution without
+ * native filesystem APIs.
+ *
+ * All commands use POSIX-compliant syntax for maximum compatibility.
+ */
+export declare class CommandPolyfillService {
+    private readonly executor;
+    constructor(executor: ICommandExecution);
+    /**
+     * Read a file via base64 encoding.
+     * Uses: cat <file> | base64
+     */
+    readFile(path: string): Promise<Uint8Array>;
+    /**
+     * Read a portion of a file via dd + base64.
+     */
+    readFileRange(path: string, start: number, end?: number): Promise<Uint8Array>;
+    /**
+     * Write a file via base64 decoding.
+     * Uses: echo <base64> | base64 -d > <file>
+     */
+    writeFile(path: string, data: Uint8Array): Promise<number>;
+    /**
+     * Write a text file directly.
+     */
+    writeTextFile(path: string, content: string): Promise<number>;
+    /**
+     * Delete files via rm command.
+     */
+    deleteFiles(paths: string[]): Promise<{
+        path: string;
+        success: boolean;
+        error?: Error;
+    }[]>;
+    /**
+     * Create directories via mkdir -p.
+     */
+    createDirectories(paths: string[], options?: {
+        mode?: number;
+        owner?: string;
+        group?: string;
+    }): Promise<void>;
+    /**
+     * Delete directories via rm -rf.
+     */
+    deleteDirectories(paths: string[], options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+    /**
+     * List directory contents via ls -la.
+     */
+    listDirectory(path: string): Promise<DirectoryEntry[]>;
+    /**
+     * Create parent directory for a file path.
+     */
+    private createParentDirectory;
+    /**
+     * Get file information via stat.
+     */
+    getFileInfo(paths: string[]): Promise<Map<string, FileInfo>>;
+    /**
+     * Set file permissions via chmod.
+     */
+    setPermissions(entries: {
+        path: string;
+        mode?: number;
+        owner?: string;
+        group?: string;
+    }[]): Promise<void>;
+    /**
+     * Search for files via find command.
+     */
+    search(pattern: string, path?: string): Promise<SearchResult[]>;
+    /**
+     * Move/rename files via mv command.
+     */
+    moveFiles(entries: {
+        source: string;
+        destination: string;
+    }[]): Promise<void>;
+    /**
+     * Replace content in files via sed.
+     */
+    replaceContent(entries: {
+        path: string;
+        oldContent: string;
+        newContent: string;
+    }[]): Promise<void>;
+    /**
+     * Simple health check via echo command.
+     */
+    ping(): Promise<boolean>;
+    /**
+     * Get metrics via /proc filesystem.
+     */
+    getMetrics(): Promise<{
+        cpuCount: number;
+        cpuUsedPercentage: number;
+        memoryTotalMiB: number;
+        memoryUsedMiB: number;
+        timestamp: number;
+    }>;
+    /**
+     * Escape a path for safe shell usage.
+     */
+    private escapePath;
+    /**
+     * Parse ls -la output into DirectoryEntry objects.
+     */
+    private parseLsOutput;
+    /**
+     * Create a FileOperationError from stderr.
+     */
+    private createFileError;
+}

package/dist/types/execution.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Options for executing commands.
+ */
+export interface ExecuteOptions {
+    /** Working directory for execution */
+    workingDirectory?: string;
+    /** Run in background (don't wait for completion) */
+    background?: boolean;
+    /** Timeout in milliseconds */
+    timeoutMs?: number;
+    /** Environment variables to set */
+    env?: Record<string, string>;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Result of command execution.
+ */
+export interface ExecuteResult {
+    /** Standard output */
+    stdout: string;
+    /** Standard error */
+    stderr: string;
+    /** Exit code (null if not completed) */
+    exitCode: number | null;
+    /** Whether output was truncated */
+    truncated?: boolean;
+    /** Execution duration in milliseconds */
+    durationMs?: number;
+}
+/**
+ * Output message from streaming execution.
+ */
+export interface OutputMessage {
+    /** Message content */
+    text: string;
+    /** Timestamp (Unix milliseconds) */
+    timestamp?: number;
+}
+/**
+ * Handlers for streaming command output.
+ */
+export interface StreamHandlers {
+    /** Called for each stdout message */
+    onStdout?: (msg: OutputMessage) => void | Promise<void>;
+    /** Called for each stderr message */
+    onStderr?: (msg: OutputMessage) => void | Promise<void>;
+    /** Called when execution completes */
+    onComplete?: (result: ExecuteResult) => void | Promise<void>;
+    /** Called on error */
+    onError?: (error: Error) => void | Promise<void>;
+}
+/**
+ * Background execution handle.
+ */
+export interface BackgroundExecution {
+    /** Session ID for the background execution */
+    sessionId: string;
+    /** Kill the background execution */
+    kill(): Promise<void>;
+}

package/dist/types/filesystem.d.ts

@@ -0,0 +1,106 @@
+/**
+ * File information/metadata.
+ */
+export interface FileInfo {
+    path: string;
+    size?: number;
+    modifiedAt?: Date;
+    createdAt?: Date;
+    mode?: number;
+    owner?: string;
+    group?: string;
+    isDirectory?: boolean;
+    isFile?: boolean;
+    isSymlink?: boolean;
+}
+/**
+ * Directory entry.
+ */
+export interface DirectoryEntry {
+    name: string;
+    path: string;
+    isDirectory: boolean;
+    isFile: boolean;
+    size?: number;
+    modifiedAt?: Date;
+}
+/**
+ * Entry for writing a file.
+ */
+export interface FileWriteEntry {
+    /** File path */
+    path: string;
+    /** File content (various types supported) */
+    data: string | Uint8Array | ArrayBuffer | Blob | ReadableStream<Uint8Array>;
+    /** File permissions (octal) */
+    mode?: number;
+    /** Owner */
+    owner?: string;
+    /** Group */
+    group?: string;
+}
+/**
+ * Entry for permission changes.
+ */
+export interface PermissionEntry {
+    path: string;
+    mode?: number;
+    owner?: string;
+    group?: string;
+}
+/**
+ * Result of reading a file.
+ */
+export interface FileReadResult {
+    path: string;
+    content: Uint8Array;
+    error: Error | null;
+}
+/**
+ * Result of writing a file.
+ */
+export interface FileWriteResult {
+    path: string;
+    bytesWritten: number;
+    error: Error | null;
+}
+/**
+ * Result of deleting a file.
+ */
+export interface FileDeleteResult {
+    path: string;
+    success: boolean;
+    error: Error | null;
+}
+/**
+ * Search result.
+ */
+export interface SearchResult {
+    path: string;
+    isDirectory?: boolean;
+    isFile?: boolean;
+}
+/**
+ * Move/rename entry.
+ */
+export interface MoveEntry {
+    source: string;
+    destination: string;
+}
+/**
+ * Content replacement entry.
+ */
+export interface ContentReplaceEntry {
+    path: string;
+    oldContent: string;
+    newContent: string;
+}
+/**
+ * File read options.
+ */
+export interface ReadFileOptions {
+    /** Character encoding (default: binary/Uint8Array) */
+    encoding?: 'utf-8' | 'base64' | 'binary';
+    /** Byte range to read (format: "start-end" or "start-") */
+    range?: string;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export type { BackgroundExecution, ExecuteOptions, ExecuteResult, OutputMessage, StreamHandlers } from './execution';
+export type { ContentReplaceEntry, DirectoryEntry, FileDeleteResult, FileInfo, FileReadResult, FileWriteEntry, FileWriteResult, MoveEntry, PermissionEntry, ReadFileOptions, SearchResult } from './filesystem';
+export type { Endpoint, ImageSpec, NetworkPolicy, ResourceLimits, SandboxConfig, SandboxId, SandboxInfo, SandboxMetrics, SandboxState, SandboxStatus } from './sandbox';

package/dist/types/sandbox.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Unique identifier for a sandbox.
+ */
+export type SandboxId = string;
+/**
+ * Sandbox status states.
+ */
+export type SandboxState = 'Creating' | 'Running' | 'Pausing' | 'Paused' | 'Resuming' | 'Deleting' | 'Deleted' | 'Error' | string;
+/**
+ * Sandbox status information.
+ */
+export interface SandboxStatus {
+    state: SandboxState;
+    reason?: string;
+    message?: string;
+}
+/**
+ * Resource limits for a sandbox.
+ */
+export interface ResourceLimits {
+    cpuCount?: number;
+    memoryMiB?: number;
+    diskGiB?: number;
+}
+/**
+ * Image specification for sandbox creation.
+ */
+export interface ImageSpec {
+    repository: string;
+    tag?: string;
+    digest?: string;
+}
+/**
+ * Network policy for sandbox.
+ */
+export interface NetworkPolicy {
+    allowEgress?: boolean;
+    allowedHosts?: string[];
+}
+/**
+ * Configuration for creating a sandbox.
+ */
+export interface SandboxConfig {
+    /** Container image specification */
+    image: ImageSpec;
+    /** Entrypoint command */
+    entrypoint?: string[];
+    /** Timeout in seconds (0 for no timeout) */
+    timeout?: number;
+    /** Resource limits */
+    resourceLimits?: ResourceLimits;
+    /** Environment variables */
+    env?: Record<string, string>;
+    /** Metadata for the sandbox */
+    metadata?: Record<string, any>;
+    /** Network access policy */
+    networkPolicy?: NetworkPolicy;
+    /** Provider-specific extensions */
+    extensions?: Record<string, unknown>;
+}
+/**
+ * Information about a sandbox.
+ */
+export interface SandboxInfo {
+    id: SandboxId;
+    image: ImageSpec;
+    entrypoint: string[];
+    metadata?: Record<string, string>;
+    status: SandboxStatus;
+    createdAt: Date;
+    expiresAt?: Date;
+    resourceLimits?: ResourceLimits;
+}
+/**
+ * Sandbox metrics.
+ */
+export interface SandboxMetrics {
+    cpuCount: number;
+    cpuUsedPercentage: number;
+    memoryTotalMiB: number;
+    memoryUsedMiB: number;
+    timestamp: number;
+}
+/**
+ * Endpoint information for accessing sandbox services.
+ */
+export interface Endpoint {
+    host: string;
+    port: number;
+    protocol: 'http' | 'https';
+    url: string;
+}

package/dist/utils/base64.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Base64 encoding/decoding utilities.
+ * Works in both Node.js and browser environments.
+ */
+/**
+ * Encode a Uint8Array to base64 string.
+ */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+/**
+ * Decode a base64 string to Uint8Array.
+ */
+export declare function base64ToBytes(base64: string): Uint8Array;
+/**
+ * Encode a string to base64.
+ */
+export declare function stringToBase64(str: string): string;
+/**
+ * Decode a base64 string to utf-8 string.
+ */
+export declare function base64ToString(base64: string): string;

package/dist/utils/streams.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Stream utilities for working with ReadableStream and AsyncIterable.
+ */
+/**
+ * Convert an AsyncIterable to a Uint8Array.
+ * Collects all chunks into a single buffer.
+ */
+export declare function asyncIterableToBuffer(iterable: AsyncIterable<Uint8Array>): Promise<Uint8Array>;
+/**
+ * Convert a Uint8Array to a ReadableStream.
+ */
+export declare function bufferToReadableStream(buffer: Uint8Array): ReadableStream<Uint8Array>;
+/**
+ * Convert a string to a ReadableStream.
+ */
+export declare function stringToReadableStream(str: string): ReadableStream<Uint8Array>;
+/**
+ * Convert a ReadableStream to an AsyncIterable.
+ * (Native ReadableStream is already async iterable in modern environments,
+ * but this ensures compatibility.)
+ */
+export declare function readableStreamToAsyncIterable(stream: ReadableStream<Uint8Array>): AsyncIterable<Uint8Array>;
+/**
+ * Read a stream and convert to string.
+ */
+export declare function streamToString(stream: ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>): Promise<string>;