test-wuying-agentbay-sdk 0.13.0-beta.20251209195417 → 0.13.0-beta.20251209225815

package/dist/index.d.mts

@@ -133,10 +133,18 @@ interface CommandResult extends ApiResponse {
     requestId: string;
     /** Whether the command execution was successful */
     success: boolean;
-    /** The command output */
+    /** The command output (for backward compatibility, equals stdout + stderr) */
     output: string;
     /** Optional error message if the operation failed */
     errorMessage?: string;
+    /** The exit code of the command execution. Default is 0. */
+    exitCode?: number;
+    /** Standard output from the command execution */
+    stdout?: string;
+    /** Standard error from the command execution */
+    stderr?: string;
+    /** Trace ID for error tracking. Only present when errorCode != 0. Used for quick problem localization. */
+    traceId?: string;
 }
 /**
  * Interface for code execution operation responses
@@ -3687,14 +3695,28 @@ declare class Command {
      */
     private sanitizeError;
     /**
-     * Executes a shell command in the session environment.
+     * Execute a shell command with optional working directory and environment variables.
      *
-     * @param command - The shell command to execute.
-     * @param timeoutMs - Timeout in milliseconds. Defaults to 1000ms.
+     * Executes a shell command in the session environment with configurable timeout,
+     * working directory, and environment variables. The command runs with session
+     * user permissions in a Linux shell environment.
+     *
+     * @param command - The shell command to execute
+     * @param timeoutMs - Timeout in milliseconds (default: 1000ms/1s). Maximum allowed
+     *                    timeout is 50000ms (50s). If a larger value is provided,
+     *                    it will be automatically limited to 50000ms
+     * @param cwd - The working directory for command execution. If not specified,
+     *              the command runs in the default session directory
+     * @param envs - Environment variables as a dictionary of key-value pairs.
+     *              These variables are set for the command execution only
      *
      * @returns Promise resolving to CommandResult containing:
-     *          - success: Whether the command executed successfully
-     *          - output: Combined stdout and stderr output
+     *          - success: Whether the command executed successfully (exitCode === 0)
+     *          - output: Command output for backward compatibility (stdout + stderr)
+     *          - exitCode: The exit code of the command execution (0 for success)
+     *          - stdout: Standard output from the command execution
+     *          - stderr: Standard error from the command execution
+     *          - traceId: Trace ID for error tracking (only present when exitCode !== 0)
      *          - requestId: Unique identifier for this API request
      *          - errorMessage: Error description if execution failed
      *
@@ -3703,22 +3725,31 @@ declare class Command {
      * const agentBay = new AgentBay({ apiKey: 'your_api_key' });
      * const result = await agentBay.create();
      * if (result.success) {
-     *   const cmdResult = await result.session.command.executeCommand('echo "Hello"', 3000);
+     *   const cmdResult = await result.session.command.executeCommand('echo "Hello"', 5000);
      *   console.log('Command output:', cmdResult.output);
+     *   console.log('Exit code:', cmdResult.exitCode);
+     *   console.log('Stdout:', cmdResult.stdout);
      *   await result.session.delete();
      * }
      * ```
      *
-     * @remarks
-     * **Behavior:**
-     * - Executes in a Linux shell environment
-     * - Combines stdout and stderr in the output
-     * - Default timeout is 1000ms (1 second)
-     * - Command runs with session user permissions
-     *
-     * @see {@link FileSystem.readFile}, {@link FileSystem.writeFile}
+     * @example
+     * ```typescript
+     * const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+     * const result = await agentBay.create();
+     * if (result.success) {
+     *   const cmdResult = await result.session.command.executeCommand(
+     *     'pwd',
+     *     5000,
+     *     '/tmp',
+     *     { TEST_VAR: 'test_value' }
+     *   );
+     *   console.log('Working directory:', cmdResult.stdout);
+     *   await result.session.delete();
+     * }
+     * ```
      */
-    executeCommand(command: string, timeoutMs?: number): Promise<CommandResult>;
+    executeCommand(command: string, timeoutMs?: number, cwd?: string, envs?: Record<string, string>): Promise<CommandResult>;
 }
 
 /**

package/dist/index.d.ts

@@ -133,10 +133,18 @@ interface CommandResult extends ApiResponse {
     requestId: string;
     /** Whether the command execution was successful */
     success: boolean;
-    /** The command output */
+    /** The command output (for backward compatibility, equals stdout + stderr) */
     output: string;
     /** Optional error message if the operation failed */
     errorMessage?: string;
+    /** The exit code of the command execution. Default is 0. */
+    exitCode?: number;
+    /** Standard output from the command execution */
+    stdout?: string;
+    /** Standard error from the command execution */
+    stderr?: string;
+    /** Trace ID for error tracking. Only present when errorCode != 0. Used for quick problem localization. */
+    traceId?: string;
 }
 /**
  * Interface for code execution operation responses
@@ -3687,14 +3695,28 @@ declare class Command {
      */
     private sanitizeError;
     /**
-     * Executes a shell command in the session environment.
+     * Execute a shell command with optional working directory and environment variables.
      *
-     * @param command - The shell command to execute.
-     * @param timeoutMs - Timeout in milliseconds. Defaults to 1000ms.
+     * Executes a shell command in the session environment with configurable timeout,
+     * working directory, and environment variables. The command runs with session
+     * user permissions in a Linux shell environment.
+     *
+     * @param command - The shell command to execute
+     * @param timeoutMs - Timeout in milliseconds (default: 1000ms/1s). Maximum allowed
+     *                    timeout is 50000ms (50s). If a larger value is provided,
+     *                    it will be automatically limited to 50000ms
+     * @param cwd - The working directory for command execution. If not specified,
+     *              the command runs in the default session directory
+     * @param envs - Environment variables as a dictionary of key-value pairs.
+     *              These variables are set for the command execution only
      *
      * @returns Promise resolving to CommandResult containing:
-     *          - success: Whether the command executed successfully
-     *          - output: Combined stdout and stderr output
+     *          - success: Whether the command executed successfully (exitCode === 0)
+     *          - output: Command output for backward compatibility (stdout + stderr)
+     *          - exitCode: The exit code of the command execution (0 for success)
+     *          - stdout: Standard output from the command execution
+     *          - stderr: Standard error from the command execution
+     *          - traceId: Trace ID for error tracking (only present when exitCode !== 0)
      *          - requestId: Unique identifier for this API request
      *          - errorMessage: Error description if execution failed
      *
@@ -3703,22 +3725,31 @@ declare class Command {
      * const agentBay = new AgentBay({ apiKey: 'your_api_key' });
      * const result = await agentBay.create();
      * if (result.success) {
-     *   const cmdResult = await result.session.command.executeCommand('echo "Hello"', 3000);
+     *   const cmdResult = await result.session.command.executeCommand('echo "Hello"', 5000);
      *   console.log('Command output:', cmdResult.output);
+     *   console.log('Exit code:', cmdResult.exitCode);
+     *   console.log('Stdout:', cmdResult.stdout);
      *   await result.session.delete();
      * }
      * ```
      *
-     * @remarks
-     * **Behavior:**
-     * - Executes in a Linux shell environment
-     * - Combines stdout and stderr in the output
-     * - Default timeout is 1000ms (1 second)
-     * - Command runs with session user permissions
-     *
-     * @see {@link FileSystem.readFile}, {@link FileSystem.writeFile}
+     * @example
+     * ```typescript
+     * const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+     * const result = await agentBay.create();
+     * if (result.success) {
+     *   const cmdResult = await result.session.command.executeCommand(
+     *     'pwd',
+     *     5000,
+     *     '/tmp',
+     *     { TEST_VAR: 'test_value' }
+     *   );
+     *   console.log('Working directory:', cmdResult.stdout);
+     *   await result.session.delete();
+     * }
+     * ```
      */
-    executeCommand(command: string, timeoutMs?: number): Promise<CommandResult>;
+    executeCommand(command: string, timeoutMs?: number, cwd?: string, envs?: Record<string, string>): Promise<CommandResult>;
 }
 
 /**

package/dist/index.mjs

@@ -5485,14 +5485,28 @@ var _Command = class _Command {
     return errorString.replace(/Bearer\s+[^\s]+/g, "Bearer [REDACTED]");
   }
   /**
-   * Executes a shell command in the session environment.
+   * Execute a shell command with optional working directory and environment variables.
    *
-   * @param command - The shell command to execute.
-   * @param timeoutMs - Timeout in milliseconds. Defaults to 1000ms.
+   * Executes a shell command in the session environment with configurable timeout,
+   * working directory, and environment variables. The command runs with session
+   * user permissions in a Linux shell environment.
+   *
+   * @param command - The shell command to execute
+   * @param timeoutMs - Timeout in milliseconds (default: 1000ms/1s). Maximum allowed
+   *                    timeout is 50000ms (50s). If a larger value is provided,
+   *                    it will be automatically limited to 50000ms
+   * @param cwd - The working directory for command execution. If not specified,
+   *              the command runs in the default session directory
+   * @param envs - Environment variables as a dictionary of key-value pairs.
+   *              These variables are set for the command execution only
    *
    * @returns Promise resolving to CommandResult containing:
-   *          - success: Whether the command executed successfully
-   *          - output: Combined stdout and stderr output
+   *          - success: Whether the command executed successfully (exitCode === 0)
+   *          - output: Command output for backward compatibility (stdout + stderr)
+   *          - exitCode: The exit code of the command execution (0 for success)
+   *          - stdout: Standard output from the command execution
+   *          - stderr: Standard error from the command execution
+   *          - traceId: Trace ID for error tracking (only present when exitCode !== 0)
    *          - requestId: Unique identifier for this API request
    *          - errorMessage: Error description if execution failed
    *
@@ -5501,34 +5515,124 @@ var _Command = class _Command {
    * const agentBay = new AgentBay({ apiKey: 'your_api_key' });
    * const result = await agentBay.create();
    * if (result.success) {
-   *   const cmdResult = await result.session.command.executeCommand('echo "Hello"', 3000);
+   *   const cmdResult = await result.session.command.executeCommand('echo "Hello"', 5000);
    *   console.log('Command output:', cmdResult.output);
+   *   console.log('Exit code:', cmdResult.exitCode);
+   *   console.log('Stdout:', cmdResult.stdout);
    *   await result.session.delete();
    * }
    * ```
    *
-   * @remarks
-   * **Behavior:**
-   * - Executes in a Linux shell environment
-   * - Combines stdout and stderr in the output
-   * - Default timeout is 1000ms (1 second)
-   * - Command runs with session user permissions
-   *
-   * @see {@link FileSystem.readFile}, {@link FileSystem.writeFile}
+   * @example
+   * ```typescript
+   * const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+   * const result = await agentBay.create();
+   * if (result.success) {
+   *   const cmdResult = await result.session.command.executeCommand(
+   *     'pwd',
+   *     5000,
+   *     '/tmp',
+   *     { TEST_VAR: 'test_value' }
+   *   );
+   *   console.log('Working directory:', cmdResult.stdout);
+   *   await result.session.delete();
+   * }
+   * ```
    */
-  async executeCommand(command, timeoutMs = 1e3) {
+  async executeCommand(command, timeoutMs = 1e3, cwd, envs) {
+    if (envs !== void 0) {
+      const invalidVars = [];
+      for (const [key, value] of Object.entries(envs)) {
+        if (typeof key !== "string") {
+          invalidVars.push(`key '${key}' (type: ${typeof key})`);
+        }
+        if (typeof value !== "string") {
+          invalidVars.push(`value for key '${key}' (type: ${typeof value})`);
+        }
+      }
+      if (invalidVars.length > 0) {
+        throw new Error(
+          `Invalid environment variables: all keys and values must be strings. Found invalid entries: ${invalidVars.join(", ")}`
+        );
+      }
+    }
     try {
+      const MAX_TIMEOUT_MS = 5e4;
+      if (timeoutMs > MAX_TIMEOUT_MS) {
+        timeoutMs = MAX_TIMEOUT_MS;
+      }
       const args = {
         command,
         timeout_ms: timeoutMs
       };
+      if (cwd !== void 0) {
+        args.cwd = cwd;
+      }
+      if (envs !== void 0) {
+        args.envs = envs;
+      }
       const result = await this.session.callMcpTool("shell", args);
-      return {
-        requestId: result.requestId,
-        success: result.success,
-        output: result.data,
-        errorMessage: result.errorMessage
-      };
+      if (result.success) {
+        try {
+          let dataJson;
+          if (typeof result.data === "string") {
+            dataJson = JSON.parse(result.data);
+          } else {
+            dataJson = result.data;
+          }
+          const stdout = dataJson.stdout || "";
+          const stderr = dataJson.stderr || "";
+          const errorCode = dataJson.errorCode || 0;
+          const traceId = dataJson.traceId || "";
+          const success = errorCode === 0;
+          const output = stdout + stderr;
+          return {
+            requestId: result.requestId,
+            success,
+            output,
+            exitCode: errorCode,
+            stdout,
+            stderr,
+            traceId: traceId || void 0,
+            errorMessage: result.errorMessage
+          };
+        } catch (parseError) {
+          return {
+            requestId: result.requestId,
+            success: true,
+            output: typeof result.data === "string" ? result.data : String(result.data),
+            errorMessage: result.errorMessage
+          };
+        }
+      } else {
+        try {
+          const errorData = typeof result.errorMessage === "string" ? JSON.parse(result.errorMessage) : result.errorMessage;
+          if (errorData && typeof errorData === "object") {
+            const stdout = errorData.stdout || "";
+            const stderr = errorData.stderr || "";
+            const errorCode = errorData.errorCode || 0;
+            const traceId = errorData.traceId || "";
+            const output = stdout + stderr;
+            return {
+              requestId: result.requestId,
+              success: false,
+              output,
+              exitCode: errorCode,
+              stdout,
+              stderr,
+              traceId: traceId || void 0,
+              errorMessage: stderr || result.errorMessage
+            };
+          }
+        } catch {
+        }
+        return {
+          requestId: result.requestId,
+          success: false,
+          output: "",
+          errorMessage: result.errorMessage || "Failed to execute command"
+        };
+      }
     } catch (error) {
       return {
         requestId: "",