@lleverage-ai/agent-sdk 0.0.1

package/dist/backends/sandbox.d.ts

@@ -0,0 +1,315 @@
+/**
+ * Sandbox backend for command execution.
+ *
+ * SandboxBackend provides isolated environments for running shell commands safely.
+ * The base class provides a foundation for various sandbox implementations including
+ * local processes, containers, or cloud sandboxes.
+ *
+ * This module provides:
+ * - {@link BaseSandbox} - Abstract base class for all sandbox implementations
+ * - {@link LocalSandbox} - Local shell execution with security controls
+ *
+ * @example
+ * ```typescript
+ * // Create a local sandbox for development
+ * const sandbox = new LocalSandbox({
+ *   cwd: process.cwd(),
+ *   timeout: 30000,
+ *   maxOutputSize: 1024 * 1024,
+ * });
+ *
+ * // Execute a command
+ * const result = await sandbox.execute("npm test");
+ * console.log(`Exit code: ${result.exitCode}`);
+ * console.log(`Output: ${result.output}`);
+ *
+ * // Use file operations
+ * const files = await sandbox.lsInfo("./src");
+ * ```
+ *
+ * @packageDocumentation
+ */
+import type { BackendProtocol, EditResult, ExecuteResponse, FileData, FileInfo, FileUploadResponse, GrepMatch, SandboxBackendProtocol, WriteResult } from "../backend.js";
+import { FileSizeLimitError, PathTraversalError, SymlinkError } from "./filesystem.js";
+/**
+ * Error thrown when a command execution times out.
+ *
+ * @category Backend
+ */
+export declare class CommandTimeoutError extends Error {
+    readonly command: string;
+    readonly timeoutMs: number;
+    constructor(command: string, timeoutMs: number);
+}
+/**
+ * Error thrown when a command is blocked by security filters.
+ *
+ * @category Backend
+ */
+export declare class CommandBlockedError extends Error {
+    readonly command: string;
+    readonly reason: string;
+    constructor(command: string, reason: string);
+}
+/**
+ * Configuration options for LocalSandbox.
+ *
+ * @example
+ * ```typescript
+ * const options: LocalSandboxOptions = {
+ *   cwd: "/home/user/project",
+ *   timeout: 60000,
+ *   maxOutputSize: 1024 * 1024,
+ *   blockedCommands: ["rm -rf /", "shutdown"],
+ * };
+ * ```
+ *
+ * @category Backend
+ */
+export interface LocalSandboxOptions {
+    /**
+     * Working directory for command execution.
+     * @defaultValue process.cwd()
+     */
+    cwd?: string;
+    /**
+     * Default timeout in milliseconds for command execution.
+     * @defaultValue 120000 (2 minutes)
+     */
+    timeout?: number;
+    /**
+     * Maximum output size in bytes before truncation.
+     * @defaultValue 1048576 (1MB)
+     */
+    maxOutputSize?: number;
+    /**
+     * Shell to use for command execution.
+     * @defaultValue "/bin/sh" on Unix, "cmd.exe" on Windows
+     */
+    shell?: string;
+    /**
+     * Environment variables to set for all commands.
+     */
+    env?: Record<string, string>;
+    /**
+     * Commands or patterns that are blocked from execution.
+     * Supports simple string matching and regex patterns.
+     */
+    blockedCommands?: Array<string | RegExp>;
+    /**
+     * Only allow these commands to be executed.
+     * If set, only commands matching these patterns are allowed.
+     */
+    allowedCommands?: Array<string | RegExp>;
+    /**
+     * Whether to allow potentially dangerous commands.
+     * When false (default), certain dangerous patterns are blocked.
+     * @defaultValue false
+     */
+    allowDangerous?: boolean;
+    /**
+     * Maximum file size in MB for file operations.
+     * @defaultValue 10
+     */
+    maxFileSizeMb?: number;
+    /**
+     * Whether to follow symbolic links.
+     * @defaultValue false
+     */
+    followSymlinks?: boolean;
+    /**
+     * Additional paths allowed for file operations.
+     */
+    allowedPaths?: string[];
+}
+/**
+ * Abstract base class for sandbox implementations.
+ *
+ * This class provides the foundation for various sandbox backends. Subclasses
+ * must implement the core execution method, while file operations can optionally
+ * be delegated to a wrapped backend.
+ *
+ * @example
+ * ```typescript
+ * class MyCloudSandbox extends BaseSandbox {
+ *   async execute(command: string): Promise<ExecuteResponse> {
+ *     // Implement cloud-based execution
+ *     return await this.cloudProvider.runCommand(command);
+ *   }
+ * }
+ * ```
+ *
+ * @category Backend
+ */
+export declare abstract class BaseSandbox implements SandboxBackendProtocol {
+    /** Unique identifier for this sandbox instance */
+    readonly id: string;
+    /** Wrapped backend for file operations */
+    protected readonly fileBackend: BackendProtocol;
+    /**
+     * Create a new BaseSandbox.
+     *
+     * @param fileBackend - Backend to use for file operations
+     * @param id - Optional unique identifier (auto-generated if not provided)
+     */
+    constructor(fileBackend: BackendProtocol, id?: string);
+    /**
+     * Execute a shell command in the sandbox.
+     *
+     * @param command - Shell command to execute
+     * @returns Execution result with output and exit code
+     */
+    abstract execute(command: string): Promise<ExecuteResponse>;
+    /**
+     * List files and directories at the given path.
+     */
+    lsInfo(path: string): FileInfo[] | Promise<FileInfo[]>;
+    /**
+     * Read file content with line numbers.
+     */
+    read(filePath: string, offset?: number, limit?: number): string | Promise<string>;
+    /**
+     * Read raw file content as FileData.
+     */
+    readRaw(filePath: string): FileData | Promise<FileData>;
+    /**
+     * Search for pattern matches using regex.
+     */
+    grepRaw(pattern: string, path?: string | null, glob?: string | null): GrepMatch[] | string | Promise<GrepMatch[] | string>;
+    /**
+     * Find files matching a glob pattern.
+     */
+    globInfo(pattern: string, path?: string): FileInfo[] | Promise<FileInfo[]>;
+    /**
+     * Create or overwrite a file.
+     */
+    write(filePath: string, content: string): WriteResult | Promise<WriteResult>;
+    /**
+     * Edit a file by replacing text.
+     */
+    edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): EditResult | Promise<EditResult>;
+    /**
+     * Upload files to the sandbox.
+     *
+     * Default implementation writes files using the file backend.
+     *
+     * @param files - Array of [path, content] tuples
+     * @returns Array of upload results
+     */
+    uploadFiles(files: Array<[string, Uint8Array]>): Promise<FileUploadResponse[]>;
+    /**
+     * Download files from the sandbox.
+     *
+     * Default implementation reads files using the file backend.
+     *
+     * @param paths - Paths to download
+     * @returns Array of { path, content } objects
+     */
+    downloadFiles(paths: string[]): Promise<Array<{
+        path: string;
+        content: Uint8Array;
+    }>>;
+}
+/**
+ * Local sandbox for shell command execution.
+ *
+ * Provides secure command execution with:
+ * - Timeout enforcement
+ * - Output size limits
+ * - Command blocking/allowlisting
+ * - Dangerous pattern detection
+ *
+ * File operations are delegated to a FilesystemBackend with the same security
+ * protections (path traversal, symlink, file size).
+ *
+ * @example
+ * ```typescript
+ * const sandbox = new LocalSandbox({
+ *   cwd: "/home/user/project",
+ *   timeout: 30000,
+ *   blockedCommands: ["rm -rf"],
+ * });
+ *
+ * // Execute a command
+ * const result = await sandbox.execute("ls -la");
+ * console.log(result.output);
+ *
+ * // File operations work too
+ * const files = await sandbox.lsInfo("./src");
+ * ```
+ *
+ * @category Backend
+ */
+export declare class LocalSandbox extends BaseSandbox {
+    private readonly cwd;
+    private readonly timeout;
+    private readonly maxOutputSize;
+    private readonly shell;
+    private readonly env;
+    private readonly blockedCommands;
+    private readonly allowedCommands?;
+    private readonly allowDangerous;
+    /**
+     * Create a new LocalSandbox.
+     *
+     * @param options - Configuration options
+     */
+    constructor(options?: LocalSandboxOptions);
+    /**
+     * Execute a shell command.
+     *
+     * @param command - Shell command to execute
+     * @returns Execution result with output and exit code
+     * @throws {CommandBlockedError} If the command is blocked
+     * @throws {CommandTimeoutError} If the command times out
+     */
+    execute(command: string): Promise<ExecuteResponse>;
+    /**
+     * Validate a command before execution.
+     *
+     * @param command - Command to validate
+     * @throws {CommandBlockedError} If the command is blocked
+     * @internal
+     */
+    private validateCommand;
+    /**
+     * Check if a command matches a pattern.
+     * @internal
+     */
+    private matchesPattern;
+    /**
+     * Create a LocalSandbox with restricted permissions.
+     *
+     * This factory creates a sandbox that only allows read-only commands.
+     *
+     * @param options - Base options
+     * @returns A restricted LocalSandbox
+     *
+     * @example
+     * ```typescript
+     * const sandbox = LocalSandbox.readOnly({ cwd: "/home/user/project" });
+     * await sandbox.execute("ls -la"); // OK
+     * await sandbox.execute("rm file.txt"); // Throws CommandBlockedError
+     * ```
+     */
+    static readOnly(options?: Omit<LocalSandboxOptions, "allowedCommands" | "blockedCommands">): LocalSandbox;
+}
+/**
+ * Create a LocalSandbox with the specified options.
+ *
+ * @param options - Configuration options
+ * @returns A new LocalSandbox instance
+ *
+ * @example
+ * ```typescript
+ * const sandbox = createLocalSandbox({
+ *   cwd: "/home/user/project",
+ *   timeout: 30000,
+ * });
+ * ```
+ *
+ * @category Backend
+ */
+export declare function createLocalSandbox(options?: LocalSandboxOptions): LocalSandbox;
+export { PathTraversalError, SymlinkError, FileSizeLimitError };
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/backends/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../../src/backends/sandbox.ts"],"names":[],"mappings":"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"}