@fastgpt-sdk/sandbox-adapter 0.0.1

package/README.md

@@ -0,0 +1,163 @@
+# @fastgpt/sandbox
+
+A unified, high-level abstraction layer for cloud sandbox providers. It offers a consistent, vendor-agnostic interface for creating, managing, and interacting with sandboxed environments like OpenSandbox.
+
+> 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.
+
+```ts
+import { createSandbox } from '@fastgpt/sandbox';
+
+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',
+    },
+  });
+
+  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}`);
+
+    // 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

@@ -0,0 +1,59 @@
+import type { ISandbox } from '../interfaces/ISandbox';
+import { CommandPolyfillService } from '../polyfill/CommandPolyfillService';
+import type { ContentReplaceEntry, DirectoryEntry, ExecuteOptions, ExecuteResult, FileDeleteResult, FileInfo, FileReadResult, FileWriteEntry, FileWriteResult, MoveEntry, PermissionEntry, ReadFileOptions, SandboxConfig, SandboxId, SandboxInfo, SandboxMetrics, SandboxStatus, SearchResult, StreamHandlers } from '../types';
+/**
+ * Abstract base class for all sandbox adapters.
+ *
+ * Provides default polyfilled implementations for common filesystem,
+ * search, health, and metrics operations via CommandPolyfillService.
+ * Subclasses can override the polyfill service in their constructor.
+ */
+export declare abstract class BaseSandboxAdapter implements ISandbox {
+    abstract readonly id: SandboxId;
+    abstract readonly provider: string;
+    protected _status: SandboxStatus;
+    protected polyfillService?: CommandPolyfillService;
+    constructor();
+    get status(): SandboxStatus;
+    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>;
+    executeStream(command: string, handlers: StreamHandlers, options?: ExecuteOptions): Promise<void>;
+    executeBackground(_command: string, _options?: ExecuteOptions): Promise<{
+        sessionId: string;
+        kill(): Promise<void>;
+    }>;
+    interrupt(_sessionId: string): Promise<void>;
+    readFiles(paths: string[], options?: ReadFileOptions): Promise<FileReadResult[]>;
+    writeFiles(entries: FileWriteEntry[]): Promise<FileWriteResult[]>;
+    deleteFiles(paths: string[]): Promise<FileDeleteResult[]>;
+    moveFiles(entries: MoveEntry[]): Promise<void>;
+    replaceContent(entries: ContentReplaceEntry[]): Promise<void>;
+    createDirectories(paths: string[], options?: {
+        mode?: number;
+        owner?: string;
+        group?: string;
+    }): Promise<void>;
+    deleteDirectories(paths: string[], options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+    listDirectory(path: string): Promise<DirectoryEntry[]>;
+    readFileStream(path: string): AsyncIterable<Uint8Array>;
+    writeFileStream(path: string, stream: ReadableStream<Uint8Array>): Promise<void>;
+    getFileInfo(paths: string[]): Promise<Map<string, FileInfo>>;
+    setPermissions(entries: PermissionEntry[]): Promise<void>;
+    search(pattern: string, path?: string): Promise<SearchResult[]>;
+    ping(): Promise<boolean>;
+    getMetrics(): Promise<SandboxMetrics>;
+    protected sleep(ms: number): Promise<void>;
+    protected requirePolyfillService(feature: string, message: string): CommandPolyfillService;
+}

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

@@ -0,0 +1,85 @@
+import type { ExecuteOptions, ExecuteResult, SandboxConfig, SandboxId, SandboxInfo } from '../../types';
+import { BaseSandboxAdapter } from '../BaseSandboxAdapter';
+/**
+ * Configuration for FastGPT Sandbox Adapter.
+ */
+export interface FastGPTSandboxConfig {
+    /** Base URL for the FastGPT Sandbox Server API */
+    baseUrl: string;
+    /** Authentication token */
+    token: string;
+    /** Container name (used as sandbox ID) */
+    containerName: string;
+}
+export declare class FastGPTSandboxAdapter extends BaseSandboxAdapter {
+    private config;
+    /** Provider identifier */
+    readonly provider: "fastgpt";
+    /** SDK instance */
+    private sdk;
+    /** Container name (used as sandbox ID) */
+    private _id;
+    /**
+     * Creates a new FastGPTSandboxAdapter instance.
+     *
+     * @param config - Connection configuration
+     */
+    constructor(config: FastGPTSandboxConfig);
+    /**
+     * Get the sandbox ID (container name).
+     */
+    get id(): SandboxId;
+    /**
+     * Get detailed information about the sandbox.
+     */
+    getInfo(): Promise<SandboxInfo | null>;
+    /**
+     * Create a new sandbox container.
+     *
+     * Note: The FastGPT SDK only accepts container name for creation.
+     * Image and resource configuration are handled server-side.
+     *
+     * @param _config - Sandbox configuration (not fully used by this SDK)
+     */
+    create(_config: SandboxConfig): Promise<void>;
+    /**
+     * Start a stopped or paused sandbox.
+     * Uses SDK's start method which resumes paused containers.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the sandbox.
+     * Note: FastGPT SDK uses pause instead of stop.
+     */
+    stop(): Promise<void>;
+    /**
+     * Pause a running sandbox.
+     */
+    pause(): Promise<void>;
+    /**
+     * Resume a paused sandbox.
+     */
+    resume(): Promise<void>;
+    /**
+     * Delete the sandbox permanently.
+     */
+    delete(): Promise<void>;
+    /**
+     * Close the connection and release resources.
+     */
+    close(): 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
+     */
+    execute(command: string, options?: ExecuteOptions): Promise<ExecuteResult>;
+    /**
+     * Check if the sandbox is healthy.
+     *
+     * @returns true if healthy, false otherwise
+     */
+    ping(): Promise<boolean>;
+}

package/dist/adapters/MinimalProviderAdapter.d.ts

@@ -0,0 +1,52 @@
+import type { ExecuteOptions, ExecuteResult, SandboxConfig, SandboxId, SandboxInfo, SandboxStatus } from '../types';
+import { BaseSandboxAdapter } from './BaseSandboxAdapter';
+/**
+ * Connection interface for minimal providers.
+ * Represents a provider that only supports basic command execution.
+ */
+export interface MinimalProviderConnection {
+    /** Unique identifier for the sandbox */
+    id: string;
+    /** Execute a command and return result */
+    execute(command: string): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+    /** Get current status */
+    getStatus(): Promise<SandboxStatus>;
+    /** Close the connection */
+    close(): Promise<void>;
+}
+export type MinimalProviderConfig = {
+    connectionFactory?: () => Promise<MinimalProviderConnection>;
+};
+/**
+ * Minimal provider adapter.
+ *
+ * This demonstrates how to adapt 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.
+ */
+export declare class MinimalProviderAdapter extends BaseSandboxAdapter {
+    private config?;
+    readonly provider = "minimal";
+    private _id;
+    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>;
+    execute(command: string, options?: ExecuteOptions): Promise<ExecuteResult>;
+}

package/dist/adapters/OpenSandboxAdapter.d.ts

@@ -0,0 +1,229 @@
+import type { ExecuteOptions, ExecuteResult, SandboxConfig, SandboxId, SandboxInfo, SandboxMetrics, StreamHandlers } from '../types';
+import { BaseSandboxAdapter } from './BaseSandboxAdapter';
+/**
+ * Sandbox runtime type.
+ * - docker: Full-featured runtime with pause/resume support
+ * - kubernetes: Container orchestration runtime (no pause/resume, stop = delete)
+ */
+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') */
+    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;
+}
+/**
+ * OpenSandbox provider adapter.
+ *
+ * This is the "Gold Standard" implementation with full native
+ * support for all features. Uses the OpenSandbox TypeScript SDK
+ * for all operations.
+ *
+ * @example
+ * ```typescript
+ * const adapter = new OpenSandboxAdapter({
+ *   baseUrl: 'https://api.opensandbox.example.com',
+ *   apiKey: 'your-api-key'
+ * });
+ *
+ * await adapter.create({
+ *   image: { repository: 'node', tag: '18-alpine' }
+ * });
+ *
+ * const result = await adapter.execute('node --version');
+ * console.log(result.stdout); // v18.x.x
+ * ```
+ */
+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 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
+     */
+    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/index.d.ts

@@ -0,0 +1,26 @@
+import { ISandbox } from '../interfaces';
+import { type FastGPTSandboxConfig } from './FastGPTSandboxAdapter';
+import { type MinimalProviderConfig } from './MinimalProviderAdapter';
+import { type OpenSandboxConnectionConfig } from './OpenSandboxAdapter';
+export { BaseSandboxAdapter } from './BaseSandboxAdapter';
+export { FastGPTSandboxAdapter, type FastGPTSandboxConfig } from './FastGPTSandboxAdapter';
+export { MinimalProviderAdapter, type MinimalProviderConfig, type MinimalProviderConnection } from './MinimalProviderAdapter';
+export { OpenSandboxAdapter, type OpenSandboxConnectionConfig, type SandboxRuntimeType } from './OpenSandboxAdapter';
+type CreateProviderType = {
+    provider: 'opensandbox';
+    config: OpenSandboxConnectionConfig;
+} | {
+    provider: 'minimal';
+    config: MinimalProviderConfig;
+} | {
+    provider: 'fastgpt';
+    config: FastGPTSandboxConfig;
+};
+/**
+ * Create a sandbox provider instance.
+ *
+ * @param config Provider configuration
+ * @returns Configured sandbox instance
+ * @throws Error if provider type is unknown
+ */
+export declare const createSandbox: ({ provider, config }: CreateProviderType) => ISandbox;

package/dist/errors/CommandExecutionError.d.ts

@@ -0,0 +1,16 @@
+import { SandboxException } from './SandboxException';
+/**
+ * Thrown when command execution fails.
+ */
+export declare class CommandExecutionError extends SandboxException {
+    readonly command: string;
+    readonly exitCode?: number;
+    readonly stdout?: string;
+    readonly stderr?: string;
+    readonly commandError?: Error;
+    constructor(message: string, command: string, exitCodeOrCause?: number | Error, stdout?: string, stderr?: string);
+    /**
+     * Returns the combined output (stdout + stderr).
+     */
+    getCombinedOutput(): string;
+}

package/dist/errors/ConnectionError.d.ts

@@ -0,0 +1,8 @@
+import { SandboxException } from './SandboxException';
+/**
+ * Thrown when connection to a sandbox fails.
+ */
+export declare class ConnectionError extends SandboxException {
+    readonly endpoint?: string | undefined;
+    constructor(message: string, endpoint?: string | undefined, cause?: unknown);
+}

package/dist/errors/FeatureNotSupportedError.d.ts

@@ -0,0 +1,10 @@
+import { SandboxException } from './SandboxException';
+/**
+ * Thrown when a provider does not natively support a feature
+ * and no polyfill is available.
+ */
+export declare class FeatureNotSupportedError extends SandboxException {
+    readonly feature: string;
+    readonly provider: string;
+    constructor(message: string, feature: string, provider: string);
+}

package/dist/errors/FileOperationError.d.ts

@@ -0,0 +1,13 @@
+import { SandboxException } from './SandboxException';
+/**
+ * Error codes specific to file operations.
+ */
+export type FileErrorCode = 'FILE_NOT_FOUND' | 'FILE_ALREADY_EXISTS' | 'PERMISSION_DENIED' | 'PATH_IS_DIRECTORY' | 'PATH_NOT_DIRECTORY' | 'INVALID_PATH' | 'QUOTA_EXCEEDED' | 'TRANSFER_ERROR';
+/**
+ * Thrown when a file operation fails.
+ */
+export declare class FileOperationError extends SandboxException {
+    readonly path: string;
+    readonly fileErrorCode: FileErrorCode;
+    constructor(message: string, path: string, fileErrorCode: FileErrorCode, cause?: unknown);
+}

package/dist/errors/SandboxException.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Base exception class for all sandbox-related errors.
+ * Provides structured error information with codes and optional metadata.
+ */
+export declare class SandboxException extends Error {
+    readonly code: SandboxErrorCode;
+    constructor(message: string, code?: SandboxErrorCode, cause?: unknown);
+    /**
+     * Returns a structured representation of the error for logging.
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Error codes for sandbox exceptions.
+ * Extensible via string intersection.
+ */
+export type SandboxErrorCode = 'INTERNAL_UNKNOWN_ERROR' | 'CONNECTION_ERROR' | 'TIMEOUT' | 'READY_TIMEOUT' | 'UNHEALTHY' | 'INVALID_ARGUMENT' | 'UNEXPECTED_RESPONSE' | 'FEATURE_NOT_SUPPORTED' | 'SANDBOX_NOT_FOUND' | 'PERMISSION_DENIED' | 'FILE_NOT_FOUND' | 'FILE_ALREADY_EXISTS' | 'COMMAND_FAILED' | (string & {});