@lleverage-ai/agent-sdk 0.0.1 → 0.0.2-alpha.3

package/dist/backend.js

@@ -41,31 +41,41 @@ export function isBackend(value) {
         typeof obj.edit === "function");
 }
 /**
- * Check if a value implements the SandboxBackendProtocol interface.
+ * Check if a backend supports command execution.
  *
- * @param value - Value to check
- * @returns True if value is a SandboxBackendProtocol
+ * Use this to safely narrow a BackendProtocol to one that supports the `execute()` method.
+ * This is the recommended way to check for execute capability.
+ *
+ * @param backend - Backend to check
+ * @returns True if the backend supports execute()
  *
  * @example
  * ```typescript
- * function maybeExecute(backend: BackendProtocol, command: string) {
- *   if (isSandboxBackend(backend)) {
+ * function maybeRunCommand(backend: BackendProtocol, command: string) {
+ *   if (hasExecuteCapability(backend)) {
  *     return backend.execute(command);
  *   }
  *   throw new Error("Backend does not support command execution");
  * }
+ *
+ * // With FilesystemBackend that has bash enabled
+ * const backend = new FilesystemBackend({
+ *   rootDir: process.cwd(),
+ *   enableBash: true,
+ * });
+ *
+ * if (hasExecuteCapability(backend)) {
+ *   const result = await backend.execute("npm test");
+ * }
  * ```
  *
  * @category Backend
  */
-export function isSandboxBackend(value) {
-    if (!isBackend(value)) {
+export function hasExecuteCapability(backend) {
+    if (!backend || typeof backend !== "object") {
         return false;
     }
-    const obj = value;
-    return (typeof obj.id === "string" &&
-        typeof obj.execute === "function" &&
-        typeof obj.uploadFiles === "function" &&
-        typeof obj.downloadFiles === "function");
+    const obj = backend;
+    return typeof obj.id === "string" && typeof obj.execute === "function";
 }
 //# sourceMappingURL=backend.js.map

package/dist/backend.js.map

@@ -1 +1 @@
-{"version":3,"file":"backend.js","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAyYH,gFAAgF;AAChF,cAAc;AACd,gFAAgF;AAEhF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,GAAG,GAAG,KAAgC,CAAC;IAC7C,OAAO,CACL,OAAO,GAAG,CAAC,MAAM,KAAK,UAAU;QAChC,OAAO,GAAG,CAAC,IAAI,KAAK,UAAU;QAC9B,OAAO,GAAG,CAAC,OAAO,KAAK,UAAU;QACjC,OAAO,GAAG,CAAC,OAAO,KAAK,UAAU;QACjC,OAAO,GAAG,CAAC,QAAQ,KAAK,UAAU;QAClC,OAAO,GAAG,CAAC,KAAK,KAAK,UAAU;QAC/B,OAAO,GAAG,CAAC,IAAI,KAAK,UAAU,CAC/B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,GAAG,GAAG,KAA2C,CAAC;IACxD,OAAO,CACL,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ;QAC1B,OAAO,GAAG,CAAC,OAAO,KAAK,UAAU;QACjC,OAAO,GAAG,CAAC,WAAW,KAAK,UAAU;QACrC,OAAO,GAAG,CAAC,aAAa,KAAK,UAAU,CACxC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAwYH,gFAAgF;AAChF,cAAc;AACd,gFAAgF;AAEhF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,GAAG,GAAG,KAAgC,CAAC;IAC7C,OAAO,CACL,OAAO,GAAG,CAAC,MAAM,KAAK,UAAU;QAChC,OAAO,GAAG,CAAC,IAAI,KAAK,UAAU;QAC9B,OAAO,GAAG,CAAC,OAAO,KAAK,UAAU;QACjC,OAAO,GAAG,CAAC,OAAO,KAAK,UAAU;QACjC,OAAO,GAAG,CAAC,QAAQ,KAAK,UAAU;QAClC,OAAO,GAAG,CAAC,KAAK,KAAK,UAAU;QAC/B,OAAO,GAAG,CAAC,IAAI,KAAK,UAAU,CAC/B,CAAC;AACJ,CAAC;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAA2C;IAE3C,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAC5C,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,GAAG,GAAG,OAA6C,CAAC;IAC1D,OAAO,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,UAAU,CAAC;AACzE,CAAC"}

package/dist/backends/filesystem.d.ts

@@ -26,17 +26,25 @@
  *
  * @packageDocumentation
  */
-import type { BackendProtocol, EditResult, FileData, FileInfo, GrepMatch, WriteResult } from "../backend.js";
+import type { BackendProtocol, EditResult, ExecuteResponse, FileData, FileInfo, FileUploadResponse, GrepMatch, WriteResult } from "../backend.js";
 /**
  * Configuration options for FilesystemBackend.
  *
  * @example
  * ```typescript
- * const options: FilesystemBackendOptions = {
+ * // Basic filesystem backend (no bash)
+ * const backend = new FilesystemBackend({
  *   rootDir: "/home/user/project",
  *   maxFileSizeMb: 5,
- *   followSymlinks: false,
- * };
+ * });
+ *
+ * // Filesystem backend with bash enabled
+ * const backendWithBash = new FilesystemBackend({
+ *   rootDir: "/home/user/project",
+ *   enableBash: true,
+ *   timeout: 30000,
+ *   blockedCommands: ["rm -rf /"],
+ * });
  * ```
  *
  * @category Backend
@@ -65,6 +73,54 @@ export interface FilesystemBackendOptions {
      * Useful for accessing system paths like /tmp.
      */
     allowedPaths?: string[];
+    /**
+     * Enable shell command execution via the `execute()` method.
+     * When false (default), the backend only supports file operations.
+     * @defaultValue false
+     */
+    enableBash?: boolean;
+    /**
+     * Default timeout in milliseconds for command execution.
+     * Only used when enableBash is true.
+     * @defaultValue 120000 (2 minutes)
+     */
+    timeout?: number;
+    /**
+     * Maximum output size in bytes before truncation.
+     * Only used when enableBash is true.
+     * @defaultValue 1048576 (1MB)
+     */
+    maxOutputSize?: number;
+    /**
+     * Shell to use for command execution.
+     * Only used when enableBash is true.
+     * @defaultValue "/bin/sh" on Unix, "cmd.exe" on Windows
+     */
+    shell?: string;
+    /**
+     * Environment variables to set for all commands.
+     * Only used when enableBash is true.
+     */
+    env?: Record<string, string>;
+    /**
+     * Commands or patterns that are blocked from execution.
+     * Supports simple string matching and regex patterns.
+     * Only used when enableBash is true.
+     */
+    blockedCommands?: Array<string | RegExp>;
+    /**
+     * Only allow these commands to be executed.
+     * If set, only commands matching these patterns are allowed.
+     * Only used when enableBash is true.
+     */
+    allowedCommands?: Array<string | RegExp>;
+    /**
+     * Whether to allow potentially dangerous commands.
+     * When false (default), certain dangerous patterns are blocked.
+     * Only used when enableBash is true.
+     * @defaultValue false
+     */
+    allowDangerous?: boolean;
 }
 /**
  * Error thrown when a path traversal attack is detected.
@@ -96,6 +152,33 @@ export declare class FileSizeLimitError extends Error {
     readonly limitMb: number;
     constructor(path: string, sizeMb: number, limitMb: number);
 }
+/**
+ * Default patterns that are considered dangerous.
+ * These are blocked unless allowDangerous is true.
+ *
+ * @category Backend
+ */
+export declare const DANGEROUS_COMMAND_PATTERNS: RegExp[];
+/**
+ * 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);
+}
+/**
+ * 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);
+}
 /**
  * Filesystem backend implementation for real disk operations.
  *
@@ -104,12 +187,21 @@ export declare class FileSizeLimitError extends Error {
  * - Symlink attacks
  * - Excessive file sizes
  *
+ * Optionally supports shell command execution when `enableBash` is true.
+ *
  * @example
  * ```typescript
+ * // Basic usage - file operations only
  * const backend = new FilesystemBackend({
  *   rootDir: "/home/user/project",
  *   maxFileSizeMb: 10,
- *   followSymlinks: false,
+ * });
+ *
+ * // With bash enabled
+ * const backend = new FilesystemBackend({
+ *   rootDir: "/home/user/project",
+ *   enableBash: true,
+ *   timeout: 30000,
  * });
  *
  * // List files
@@ -120,15 +212,30 @@ export declare class FileSizeLimitError extends Error {
  *
  * // Search for patterns
  * const matches = await backend.grepRaw("TODO", "./src", "*.ts");
+ *
+ * // Execute commands (if enableBash is true)
+ * if (hasExecuteCapability(backend)) {
+ *   const result = await backend.execute("npm test");
+ * }
  * ```
  *
  * @category Backend
  */
 export declare class FilesystemBackend implements BackendProtocol {
+    /** Unique identifier for this backend instance */
+    readonly id: string;
     private readonly rootDir;
     private readonly maxFileSizeMb;
     private readonly followSymlinks;
     private readonly allowedPaths;
+    private readonly enableBash;
+    private readonly timeout;
+    private readonly maxOutputSize;
+    private readonly shell;
+    private readonly env;
+    private readonly blockedCommands;
+    private readonly allowedCommands?;
+    private readonly allowDangerous;
     /**
      * Create a new FilesystemBackend.
      *
@@ -193,6 +300,47 @@ export declare class FilesystemBackend implements BackendProtocol {
      * @returns Result indicating success or failure
      */
     edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): Promise<EditResult>;
+    /**
+     * Execute a shell command.
+     *
+     * Only available when `enableBash` is true in the constructor options.
+     *
+     * @param command - Shell command to execute
+     * @returns Execution result with output and exit code
+     * @throws {Error} If bash is not enabled
+     * @throws {CommandBlockedError} If the command is blocked
+     */
+    execute(command: string): Promise<ExecuteResponse>;
+    /**
+     * Upload files to the backend.
+     *
+     * @param files - Array of [path, content] tuples
+     * @returns Array of upload results
+     */
+    uploadFiles(files: Array<[string, Uint8Array]>): Promise<FileUploadResponse[]>;
+    /**
+     * Download files from the backend.
+     *
+     * @param paths - Paths to download
+     * @returns Array of { path, content } objects
+     */
+    downloadFiles(paths: string[]): Promise<Array<{
+        path: string;
+        content: Uint8Array;
+    }>>;
+    /**
+     * 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 matchesCommandPattern;
     /**
      * Resolve a path and validate it's within the allowed boundaries.
      *

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

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

package/dist/backends/filesystem.js

@@ -26,6 +26,8 @@
  *
  * @packageDocumentation
  */
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import * as fsSync from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
@@ -78,6 +80,70 @@ export class FileSizeLimitError extends Error {
     }
 }
 // =============================================================================
+// Dangerous Command Patterns
+// =============================================================================
+/**
+ * Default patterns that are considered dangerous.
+ * These are blocked unless allowDangerous is true.
+ *
+ * @category Backend
+ */
+export const DANGEROUS_COMMAND_PATTERNS = [
+    // Recursive force delete from root or home
+    /rm\s+(-[a-z]*r[a-z]*\s+)?(-[a-z]*f[a-z]*\s+)?[/~]/i,
+    /rm\s+(-[a-z]*f[a-z]*\s+)?(-[a-z]*r[a-z]*\s+)?[/~]/i,
+    // Format/wipe commands
+    /mkfs\./i,
+    /dd\s+.*of=\/dev\//i,
+    // Shutdown/reboot
+    /shutdown/i,
+    /reboot/i,
+    /halt/i,
+    /poweroff/i,
+    // Fork bombs
+    /:\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;?\s*:/,
+    // Overwrite important files
+    />\s*\/etc\/(passwd|shadow|sudoers)/i,
+    // Downloading and executing
+    /curl.*\|\s*(ba)?sh/i,
+    /wget.*\|\s*(ba)?sh/i,
+    // Chmod dangerous patterns
+    /chmod\s+777\s+\//i,
+    /chmod\s+-R\s+777/i,
+    // Environment manipulation that could be dangerous
+    /export\s+PATH\s*=\s*$/i,
+];
+/**
+ * Error thrown when a command is blocked by security filters.
+ *
+ * @category Backend
+ */
+export class CommandBlockedError extends Error {
+    command;
+    reason;
+    constructor(command, reason) {
+        super(`Command blocked: ${reason}`);
+        this.command = command;
+        this.reason = reason;
+        this.name = "CommandBlockedError";
+    }
+}
+/**
+ * Error thrown when a command execution times out.
+ *
+ * @category Backend
+ */
+export class CommandTimeoutError extends Error {
+    command;
+    timeoutMs;
+    constructor(command, timeoutMs) {
+        super(`Command timed out after ${timeoutMs}ms: "${command.slice(0, 100)}${command.length > 100 ? "..." : ""}"`);
+        this.command = command;
+        this.timeoutMs = timeoutMs;
+        this.name = "CommandTimeoutError";
+    }
+}
+// =============================================================================
 // Filesystem Backend Implementation
 // =============================================================================
 /**
@@ -88,12 +154,21 @@ export class FileSizeLimitError extends Error {
  * - Symlink attacks
  * - Excessive file sizes
  *
+ * Optionally supports shell command execution when `enableBash` is true.
+ *
  * @example
  * ```typescript
+ * // Basic usage - file operations only
  * const backend = new FilesystemBackend({
  *   rootDir: "/home/user/project",
  *   maxFileSizeMb: 10,
- *   followSymlinks: false,
+ * });
+ *
+ * // With bash enabled
+ * const backend = new FilesystemBackend({
+ *   rootDir: "/home/user/project",
+ *   enableBash: true,
+ *   timeout: 30000,
  * });
  *
  * // List files
@@ -104,21 +179,39 @@ export class FileSizeLimitError extends Error {
  *
  * // Search for patterns
  * const matches = await backend.grepRaw("TODO", "./src", "*.ts");
+ *
+ * // Execute commands (if enableBash is true)
+ * if (hasExecuteCapability(backend)) {
+ *   const result = await backend.execute("npm test");
+ * }
  * ```
  *
  * @category Backend
  */
 export class FilesystemBackend {
+    /** Unique identifier for this backend instance */
+    id;
     rootDir;
     maxFileSizeMb;
     followSymlinks;
     allowedPaths;
+    // Bash execution options
+    enableBash;
+    timeout;
+    maxOutputSize;
+    shell;
+    env;
+    blockedCommands;
+    allowedCommands;
+    allowDangerous;
     /**
      * Create a new FilesystemBackend.
      *
      * @param options - Configuration options
      */
     constructor(options = {}) {
+        // Generate unique ID
+        this.id = `fs-${randomUUID()}`;
         // Resolve symlinks in rootDir to handle cases like /tmp -> /private/tmp on macOS
         // This ensures symlink checks within rootDir work correctly
         const resolvedRoot = path.resolve(options.rootDir ?? process.cwd());
@@ -141,6 +234,15 @@ export class FilesystemBackend {
                 return resolved;
             }
         }));
+        // Initialize bash execution options
+        this.enableBash = options.enableBash ?? false;
+        this.timeout = options.timeout ?? 120000; // 2 minutes default
+        this.maxOutputSize = options.maxOutputSize ?? 1048576; // 1MB default
+        this.shell = options.shell ?? (process.platform === "win32" ? "cmd.exe" : "/bin/sh");
+        this.env = { ...process.env, ...options.env };
+        this.blockedCommands = options.blockedCommands ?? [];
+        this.allowedCommands = options.allowedCommands;
+        this.allowDangerous = options.allowDangerous ?? false;
     }
     /**
      * List files and directories at the given path.
@@ -382,6 +484,177 @@ export class FilesystemBackend {
         }
     }
     // ===========================================================================
+    // Command Execution Methods
+    // ===========================================================================
+    /**
+     * Execute a shell command.
+     *
+     * Only available when `enableBash` is true in the constructor options.
+     *
+     * @param command - Shell command to execute
+     * @returns Execution result with output and exit code
+     * @throws {Error} If bash is not enabled
+     * @throws {CommandBlockedError} If the command is blocked
+     */
+    async execute(command) {
+        if (!this.enableBash) {
+            throw new Error("Bash execution is not enabled. Create FilesystemBackend with enableBash: true");
+        }
+        // Validate command
+        this.validateCommand(command);
+        return new Promise((resolve) => {
+            let output = "";
+            let truncated = false;
+            let resolved = false;
+            const shellArgs = process.platform === "win32" ? ["/c", command] : ["-c", command];
+            const child = spawn(this.shell, shellArgs, {
+                cwd: this.rootDir,
+                env: this.env,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+            const handleOutput = (data) => {
+                if (truncated)
+                    return;
+                const chunk = data.toString();
+                if (output.length + chunk.length > this.maxOutputSize) {
+                    output += chunk.slice(0, this.maxOutputSize - output.length);
+                    truncated = true;
+                }
+                else {
+                    output += chunk;
+                }
+            };
+            child.stdout?.on("data", handleOutput);
+            child.stderr?.on("data", handleOutput);
+            // Set up timeout
+            const timeoutId = setTimeout(() => {
+                if (!resolved) {
+                    resolved = true;
+                    child.kill("SIGTERM");
+                    // Give it a moment to terminate gracefully
+                    setTimeout(() => {
+                        child.kill("SIGKILL");
+                    }, 1000);
+                    resolve({
+                        output: `${output}\n[Command timed out after ${this.timeout}ms]`,
+                        exitCode: null,
+                        truncated,
+                    });
+                }
+            }, this.timeout);
+            child.on("close", (code) => {
+                if (!resolved) {
+                    resolved = true;
+                    clearTimeout(timeoutId);
+                    resolve({
+                        output,
+                        exitCode: code,
+                        truncated,
+                    });
+                }
+            });
+            child.on("error", (error) => {
+                if (!resolved) {
+                    resolved = true;
+                    clearTimeout(timeoutId);
+                    resolve({
+                        output: `Error: ${error.message}`,
+                        exitCode: 1,
+                        truncated: false,
+                    });
+                }
+            });
+        });
+    }
+    /**
+     * Upload files to the backend.
+     *
+     * @param files - Array of [path, content] tuples
+     * @returns Array of upload results
+     */
+    async uploadFiles(files) {
+        const results = [];
+        for (const [filePath, content] of files) {
+            try {
+                const textContent = new TextDecoder().decode(content);
+                const result = await this.write(filePath, textContent);
+                results.push({
+                    path: filePath,
+                    success: result.success,
+                    error: result.error,
+                });
+            }
+            catch (error) {
+                results.push({
+                    path: filePath,
+                    success: false,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        return results;
+    }
+    /**
+     * Download files from the backend.
+     *
+     * @param paths - Paths to download
+     * @returns Array of { path, content } objects
+     */
+    async downloadFiles(paths) {
+        const results = [];
+        for (const filePath of paths) {
+            try {
+                const fileData = await this.readRaw(filePath);
+                const content = new TextEncoder().encode(fileData.content.join("\n"));
+                results.push({ path: filePath, content });
+            }
+            catch {
+                // Skip files we can't read
+            }
+        }
+        return results;
+    }
+    /**
+     * Validate a command before execution.
+     *
+     * @param command - Command to validate
+     * @throws {CommandBlockedError} If the command is blocked
+     * @internal
+     */
+    validateCommand(command) {
+        // Check allowlist first (if configured)
+        if (this.allowedCommands && this.allowedCommands.length > 0) {
+            const isAllowed = this.allowedCommands.some((pattern) => this.matchesCommandPattern(command, pattern));
+            if (!isAllowed) {
+                throw new CommandBlockedError(command, "Command not in allowlist");
+            }
+        }
+        // Check blocklist
+        for (const pattern of this.blockedCommands) {
+            if (this.matchesCommandPattern(command, pattern)) {
+                throw new CommandBlockedError(command, "Command matches blocked pattern");
+            }
+        }
+        // Check dangerous patterns (unless explicitly allowed)
+        if (!this.allowDangerous) {
+            for (const pattern of DANGEROUS_COMMAND_PATTERNS) {
+                if (pattern.test(command)) {
+                    throw new CommandBlockedError(command, `Command matches dangerous pattern: ${pattern.source.slice(0, 50)}`);
+                }
+            }
+        }
+    }
+    /**
+     * Check if a command matches a pattern.
+     * @internal
+     */
+    matchesCommandPattern(command, pattern) {
+        if (typeof pattern === "string") {
+            return command.includes(pattern);
+        }
+        return pattern.test(command);
+    }
+    // ===========================================================================
     // Security Methods
     // ===========================================================================
     /**