wuying-agentbay-sdk 0.10.2 → 0.11.0

package/docs/examples/common-features/basics/archive-upload-mode-example/README.md

@@ -0,0 +1,236 @@
+# Archive Upload Mode Context Sync Example
+
+This directory contains examples demonstrating the Archive upload mode functionality for context synchronization in the AgentBay SDK.
+
+## Overview
+
+The Archive upload mode is designed for efficient file transfer by compressing files before uploading them to the context storage. This is particularly useful when:
+
+- Working with large files
+- Dealing with many files
+- Optimizing bandwidth usage
+- Reducing upload time for compressible content
+
+## Files
+
+### `archive-upload-mode-example.ts`
+
+A comprehensive example that demonstrates:
+
+1. **Context Creation**: Creating a context for Archive upload mode
+2. **Sync Policy Configuration**: Setting up sync policy with Archive uploadMode
+3. **Session Management**: Creating and managing sessions with context sync
+4. **File Operations**: Writing files to the context path
+5. **Context Sync**: Synchronizing context before retrieving information
+6. **Context Info**: Retrieving context status information
+7. **File Listing**: Listing files in context sync directory
+8. **Cleanup**: Proper session cleanup and error handling
+
+## Key Features Demonstrated
+
+### Archive Upload Mode Configuration
+
+```typescript
+import { UploadMode } from "wuying-agentbay-sdk";
+
+// Configure sync policy with Archive upload mode
+const syncPolicy = newSyncPolicy();
+syncPolicy.uploadPolicy!.uploadMode = UploadMode.Archive; // Set to Archive mode
+
+// Create context sync with Archive mode
+const contextSync = newContextSync(
+  contextId,
+  "/tmp/archive-mode-test",
+  syncPolicy
+);
+```
+
+### Session Creation with Context Sync
+
+```typescript
+const sessionParams: CreateSessionParams = {
+  labels: {
+    example: `archive-mode-${uniqueId}`,
+    type: "archive-upload-demo",
+    uploadMode: UploadMode.Archive
+  },
+  contextSync: [contextSync]
+};
+
+const sessionResult = await agentBay.create(sessionParams);
+```
+
+### File Operations
+
+```typescript
+const fileSystem = new FileSystem(session);
+
+// Write file to context path
+const writeResult = await fileSystem.writeFile(filePath, fileContent, "overwrite");
+```
+
+### Context Sync and Information Retrieval
+
+```typescript
+// Call context sync before getting info
+const syncResult = await session.context.sync();
+
+// Get context status information after sync
+const infoResult = await session.context.info();
+
+// Display context status details
+infoResult.contextStatusData.forEach((status, index) => {
+  console.log(`Context ID: ${status.contextId}`);
+  console.log(`Path: ${status.path}`);
+  console.log(`Status: ${status.status}`);
+  console.log(`Task Type: ${status.taskType}`);
+});
+```
+
+### File Listing in Context Directory
+
+```typescript
+// List files in context sync directory
+const listResult = await agentBay.context.listFiles(contextId, syncDirPath, 1, 10);
+
+// Display file entries
+listResult.entries.forEach((entry, index) => {
+  console.log(`FilePath: ${entry.filePath}`);
+  console.log(`FileType: ${entry.fileType}`);
+  console.log(`FileName: ${entry.fileName}`);
+  console.log(`Size: ${entry.size} bytes`);
+});
+```
+
+## Running the Example
+
+### Prerequisites
+
+1. **Environment Setup**: Set your AgentBay API key
+   ```bash
+   export AGENTBAY_API_KEY="your-api-key-here"
+   ```
+
+2. **Dependencies**: Ensure you have the AgentBay SDK installed
+   ```bash
+   npm install
+   ```
+
+### Execution
+
+```bash
+# Navigate to the project root
+cd /path/to/wuying-agentbay-sdk
+
+# Run the example
+npx ts-node docs/example/archive-upload-mode-example.ts
+```
+
+### Expected Output
+
+The example will output detailed logs showing:
+
+```
+🚀 Archive Upload Mode Context Sync Example
+============================================================
+
+📦 Step 1: Creating context for Archive upload mode...
+✅ Context created successfully!
+   Context ID: ctx_xxxxx
+   Request ID: req_xxxxx
+
+⚙️  Step 2: Configuring sync policy with Archive upload mode...
+✅ Sync policy configured with uploadMode: Archive
+
+🔧 Step 3: Creating context sync configuration...
+✅ Context sync created:
+   Context ID: ctx_xxxxx
+   Path: /tmp/archive-mode-test
+   Upload Mode: Archive
+
+🏗️  Step 4: Creating session with Archive mode context sync...
+✅ Session created successfully!
+   Session ID: sess_xxxxx
+   Request ID: req_xxxxx
+   App Instance ID: app_xxxxx
+
+📝 Step 5: Creating test files in Archive mode context...
+📄 Creating file: /tmp/archive-mode-test/test-file-5kb.txt
+📊 File content size: 5120 bytes
+✅ File write successful!
+   Request ID: req_xxxxx
+
+📊 Step 6: Testing context sync and info functionality...
+🔄 Calling context sync before getting info...
+✅ Context sync successful!
+   Sync Request ID: req_xxxxx
+📋 Calling context info after sync...
+✅ Context info retrieved successfully!
+   Info Request ID: req_xxxxx
+   Context status data count: X
+
+📋 Context status details:
+   [0] Context ID: ctx_xxxxx
+       Path: /tmp/archive-mode-test
+       Status: Success
+       Task Type: upload
+
+🔍 Step 7: Listing files in context sync directory...
+✅ List files successful!
+   Request ID: req_xxxxx
+   Total files found: X
+
+📋 Files in context sync directory:
+   [0] FilePath: /tmp/archive-mode-test/test-file-5kb.txt
+       FileType: file
+       FileName: test-file-5kb.txt
+       Size: 5120 bytes
+
+🎉 Archive upload mode example completed successfully!
+✅ All operations completed without errors.
+
+🧹 Step 8: Cleaning up session...
+✅ Session deleted successfully!
+   Success: true
+   Request ID: req_xxxxx
+```
+
+## Related Documentation
+
+- [Context Sync Documentation](../../../../../../docs/guides/common-features/basics/data-persistence.md)
+- [Session Management Guide](../../../../../../docs/guides/common-features/basics/session-management.md)
+- [File Operations Guide](../../../../../../docs/guides/common-features/basics/file-operations.md)
+
+## Troubleshooting
+
+### Common Issues
+
+1. **API Key Not Set**
+   ```
+   Warning: AGENTBAY_API_KEY environment variable not set
+   ```
+   **Solution**: Set the environment variable or update the API key in the code
+
+2. **Context Creation Failed**
+   ```
+   Context creation failed: [error message]
+   ```
+   **Solution**: Check your API key and network connectivity
+
+3. **Session Creation Failed**
+   ```
+   Session creation failed: [error message]
+   ```
+   **Solution**: Verify context sync configuration and try again
+
+4. **File Operation Failed**
+   ```
+   File write failed: [error message]
+   ```
+   **Solution**: Check file path permissions and available disk space
+
+## Support
+
+For additional help:
+- [GitHub Issues](https://github.com/aliyun/wuying-agentbay-sdk/issues)
+- [Documentation Home](../../../../../docs/api/README.md)

package/docs/examples/common-features/basics/archive-upload-mode-example/main.ts

@@ -0,0 +1,236 @@
+import { AgentBay, CreateSessionParams, Session, newContextSync, newSyncPolicy, FileSystem, UploadMode } from "wuying-agentbay-sdk";
+
+/**
+ * Archive Upload Mode Context Sync Example
+ * 
+ * This example demonstrates how to use Archive upload mode for context synchronization.
+ * Archive mode compresses files before uploading, which is more efficient for large files
+ * or when dealing with many files.
+ * 
+ * Features demonstrated:
+ * - Creating context with Archive upload mode
+ * - Session creation with context sync
+ * - File operations in the context path
+ * - Context sync and info operations
+ * - Proper cleanup and error handling
+ */
+
+function getAPIKey(): string {
+  const apiKey = process.env.AGENTBAY_API_KEY;
+  if (!apiKey) {
+    console.warn("Warning: AGENTBAY_API_KEY environment variable not set. Using default key.");
+    return "your-api-key-here"; // Replace with your actual API key
+  }
+  return apiKey;
+}
+
+function generateUniqueId(): string {
+  const timestamp = Date.now() * 1000 + Math.floor(Math.random() * 1000);
+  const randomPart = Math.floor(Math.random() * 10000);
+  return `${timestamp}-${randomPart}`;
+}
+
+async function archiveUploadModeExample(): Promise<void> {
+  console.log("🚀 Archive Upload Mode Context Sync Example");
+  console.log("=" .repeat(60));
+
+  // Initialize AgentBay client
+  const agentBay = new AgentBay({ apiKey: getAPIKey() });
+  const uniqueId = generateUniqueId();
+  
+  let session: Session | null = null;
+
+  try {
+    // Step 1: Create context for Archive mode
+    console.log("\n📦 Step 1: Creating context for Archive upload mode...");
+    const contextName = `archive-mode-context-${uniqueId}`;
+    const contextResult = await agentBay.context.get(contextName, true);
+    
+    if (!contextResult.success) {
+      throw new Error(`Context creation failed: ${contextResult.errorMessage}`);
+    }
+    
+    console.log(`✅ Context created successfully!`);
+    console.log(`   Context ID: ${contextResult.contextId}`);
+    console.log(`   Request ID: ${contextResult.requestId}`);
+
+    // Step 2: Configure sync policy with Archive upload mode
+    console.log("\n⚙️  Step 2: Configuring sync policy with Archive upload mode...");
+    const syncPolicy = newSyncPolicy();
+    syncPolicy.uploadPolicy!.uploadMode = UploadMode.Archive; // Set to Archive mode
+    
+    console.log(`✅ Sync policy configured with uploadMode: ${syncPolicy.uploadPolicy!.uploadMode}`);
+
+    // Step 3: Create context sync configuration
+    console.log("\n🔧 Step 3: Creating context sync configuration...");
+    const contextSync = newContextSync(
+      contextResult.contextId,
+      "/tmp/archive-mode-test",
+      syncPolicy
+    );
+
+    console.log(`✅ Context sync created:`);
+    console.log(`   Context ID: ${contextSync.contextId}`);
+    console.log(`   Path: ${contextSync.path}`);
+    console.log(`   Upload Mode: ${contextSync.policy?.uploadPolicy?.uploadMode}`);
+
+    // Step 4: Create session with Archive mode context sync
+    console.log("\n🏗️  Step 4: Creating session with Archive mode context sync...");
+    const sessionParams: CreateSessionParams = {
+      labels: {
+        example: `archive-mode-${uniqueId}`,
+        type: "archive-upload-demo",
+        uploadMode: UploadMode.Archive
+      },
+      contextSync: [contextSync]
+    };
+
+    const sessionResult = await agentBay.create(sessionParams);
+    if (!sessionResult.success) {
+      throw new Error(`Session creation failed: ${sessionResult.errorMessage}`);
+    }
+
+    session = sessionResult.session!;
+    console.log(`✅ Session created successfully!`);
+    console.log(`   Session ID: ${session!.sessionId}`);
+    console.log(`   Request ID: ${sessionResult.requestId}`);
+
+    // Get session info to verify setup
+    const sessionInfo = await agentBay.getSession(session!.sessionId);
+    if (sessionInfo.success && sessionInfo.data) {
+      console.log(`   App Instance ID: ${sessionInfo.data.appInstanceId}`);
+    }
+
+    // Step 5: Create and write test files
+    console.log("\n📝 Step 5: Creating test files in Archive mode context...");
+    const fileSystem = new FileSystem(session!);
+    
+    // Generate 5KB test content
+    const contentSize = 5 * 1024; // 5KB
+    const baseContent = "Archive mode test successful! This is a test file created in the session path. ";
+    const repeatedContent = baseContent.repeat(Math.ceil(contentSize / baseContent.length));
+    const fileContent = repeatedContent.substring(0, contentSize);
+    
+    const filePath = "/tmp/archive-mode-test/test-file-5kb.txt";
+    
+    console.log(`📄 Creating file: ${filePath}`);
+    console.log(`📊 File content size: ${fileContent.length} bytes`);
+
+    const writeResult = await fileSystem.writeFile(filePath, fileContent, "overwrite");
+    
+    if (!writeResult.success) {
+      throw new Error(`File write failed: ${writeResult.errorMessage}`);
+    }
+
+    console.log(`✅ File write successful!`);
+    console.log(`   Request ID: ${writeResult.requestId}`);
+
+    // Step 6: Test context sync and info functionality
+    console.log("\n📊 Step 6: Testing context sync and info functionality...");
+    
+    // Call context sync before getting info
+    console.log("🔄 Calling context sync before getting info...");
+    const syncResult = await session!.context.sync();
+    
+    if (!syncResult.success) {
+      throw new Error(`Context sync failed: ${syncResult.errorMessage}`);
+    }
+
+    console.log(`✅ Context sync successful!`);
+    console.log(`   Sync Request ID: ${syncResult.requestId}`);
+
+    // Now call context info after sync
+    console.log("📋 Calling context info after sync...");
+    const infoResult = await session!.context.info();
+    
+    if (!infoResult.success) {
+      throw new Error(`Context info failed: ${infoResult.errorMessage}`);
+    }
+
+    console.log(`✅ Context info retrieved successfully!`);
+    console.log(`   Info Request ID: ${infoResult.requestId}`);
+    console.log(`   Context status data count: ${infoResult.contextStatusData.length}`);
+    
+    // Display context status details
+    if (infoResult.contextStatusData.length > 0) {
+      console.log("\n📋 Context status details:");
+      infoResult.contextStatusData.forEach((status:any, index:any) => {
+        console.log(`   [${index}] Context ID: ${status.contextId}`);
+        console.log(`       Path: ${status.path}`);
+        console.log(`       Status: ${status.status}`);
+        console.log(`       Task Type: ${status.taskType}`);
+        if (status.errorMessage) {
+          console.log(`       Error: ${status.errorMessage}`);
+        }
+      });
+    }
+
+    // Step 7: List files in context sync directory
+    console.log("\n🔍 Step 7: Listing files in context sync directory...");
+    
+    // Use the sync directory path
+    const syncDirPath = "/tmp/archive-mode-test";
+    
+    const listResult = await agentBay.context.listFiles(contextResult.contextId, syncDirPath, 1, 10);
+    
+    if (!listResult.success) {
+      throw new Error(`List files failed: ${listResult.errorMessage || 'Unknown error'}`);
+    }
+
+    console.log(`✅ List files successful!`);
+    console.log(`   Request ID: ${listResult.requestId}`);
+    console.log(`   Total files found: ${listResult.entries.length}`);
+    
+    if (listResult.entries.length > 0) {
+      console.log("\n📋 Files in context sync directory:");
+      listResult.entries.forEach((entry:any, index:any) => {
+        console.log(`   [${index}] FilePath: ${entry.filePath}`);
+        console.log(`       FileType: ${entry.fileType}`);
+        console.log(`       FileName: ${entry.fileName}`);
+        console.log(`       Size: ${entry.size} bytes`);
+      });
+    } else {
+      console.log("   No files found in context sync directory");
+    }
+
+    console.log("\n🎉 Archive upload mode example completed successfully!");
+    console.log("✅ All operations completed without errors.");
+
+  } catch (error) {
+    console.error("\n❌ Error occurred during example execution:");
+    console.error(error);
+  } finally {
+    // Step 8: Cleanup
+    if (session) {
+      console.log("\n🧹 Step 8: Cleaning up session...");
+      try {
+        const deleteResult = await agentBay.delete(session, true);
+        console.log(`✅ Session deleted successfully!`);
+        console.log(`   Success: ${deleteResult.success}`);
+        console.log(`   Request ID: ${deleteResult.requestId}`);
+      } catch (deleteError) {
+        console.error(`❌ Failed to delete session: ${deleteError}`);
+      }
+    }
+  }
+}
+
+// Main execution
+async function main(): Promise<void> {
+  try {
+    await archiveUploadModeExample();
+  } catch (error) {
+    console.error("❌ Example execution failed:", error);
+    process.exit(1);
+  }
+}
+
+// Run the example if this file is executed directly
+if (require.main === module) {
+  main().catch((error) => {
+    console.error("❌ Unhandled error:", error);
+    process.exit(1);
+  });
+}
+
+export { archiveUploadModeExample };

package/docs/examples/common-features/basics/command-example/README.md

@@ -0,0 +1,47 @@
+# Command Execution Example
+
+This example demonstrates how to use the command execution features of the AgentBay SDK for TypeScript.
+
+## Features Demonstrated
+
+- Executing shell commands
+- Setting custom timeouts for commands
+- Running Python code
+- Running JavaScript code
+- Executing multi-line command sequences
+
+## Running the Example
+
+1. Make sure you have installed the AgentBay SDK:
+
+```bash
+npm install wuying-agentbay-sdk
+```
+
+2. Set your API key as an environment variable (recommended):
+
+```bash
+export AGENTBAY_API_KEY=your_api_key_here
+```
+
+3. Compile and run the example:
+
+```bash
+# Compile TypeScript
+cd command-example
+npx ts-node command-example.ts
+```
+
+## Code Explanation
+
+The example demonstrates different ways to execute commands:
+
+1. Basic shell command execution
+2. Command execution with custom timeout
+3. Running Python code
+4. Running JavaScript code with custom timeout
+5. Executing a multi-line shell command sequence
+
+The code also demonstrates proper error handling and resource cleanup using try-finally.
+
+For more details on command execution, see the [Command API Reference](../../../../api/common-features/basics/command.md) and [Command Execution Tutorial](../../../../../../docs/guides/common-features/basics/command-execution.md).

package/docs/examples/common-features/basics/command-example/command-example.ts

@@ -0,0 +1,153 @@
+import { AgentBay, log, logError } from 'wuying-agentbay-sdk';
+
+/**
+ * Helper function to truncate long output text
+ */
+function truncateOutput(output: string, maxLines: number): string {
+  const lines = output.split('\n');
+  if (lines.length <= maxLines) {
+    return output;
+  }
+
+  const truncated = lines.slice(0, maxLines);
+  return truncated.join('\n') + '\n... (output truncated)';
+}
+
+async function main() {
+  // Get API key from environment variable or use a placeholder value
+  const apiKey = process.env.AGENTBAY_API_KEY || 'akm-xxx'; // Replace with your actual API key
+  if (!process.env.AGENTBAY_API_KEY) {
+    log('Warning: Using placeholder API key. Set AGENTBAY_API_KEY environment variable for production use.');
+  }
+
+  // Initialize the AgentBay client
+  const agentBay = new AgentBay({ apiKey });
+
+  // Create session parameters with imageId set to code_latest to support code execution
+  const params = {
+    imageId: 'code_latest'
+  };
+
+  // Create a new session
+  log('\nCreating a new session with code_latest image...');
+  const createResponse = await agentBay.create(params);
+  const session = createResponse.session;
+  log(`\nSession created with ID: ${session.sessionId}`);
+  log(`Create Session RequestId: ${createResponse.requestId}`);
+
+  try {
+    // 1. Execute simple shell command
+    log('\n1. Executing simple shell command (echo)...');
+    try {
+      const echoCommand = "echo 'Hello from AgentBay SDK!'";
+      const echoResponse = await session.command.executeCommand(echoCommand);
+      log(`Echo command output:\n${echoResponse.output}`);
+      log(`Execute Command RequestId: ${echoResponse.requestId}`);
+    } catch (error) {
+      log(`Error executing echo command: ${error}`);
+    }
+
+    // 2. Execute command with longer timeout
+    log('\n2. Executing command with custom timeout...');
+    try {
+      const lsCommand = "ls -la /etc";
+      const timeoutMs = 5000; // 5 seconds timeout
+      const lsResponse = await session.command.executeCommand(lsCommand, timeoutMs);
+      log(`Directory listing (first few lines):\n${truncateOutput(lsResponse.output, 5)}`);
+      log(`Execute Command with Timeout RequestId: ${lsResponse.requestId}`);
+    } catch (error) {
+      log(`Error executing ls command: ${error}`);
+    }
+
+    // 3. Execute Python code
+    log('\n3. Running Python code...');
+    try {
+      const pythonCode = `
+import platform
+import sys
+
+print(f"Python version: {platform.python_version()}")
+print(f"System info: {platform.system()} {platform.release()}")
+print("Working with numbers in Python:")
+for i in range(1, 6):
+    print(f"{i} squared is {i*i}")
+`;
+      const pythonResponse = await session.code.runCode(pythonCode, "python");
+      log(`Python code output:\n${pythonResponse.result}`);
+      log(`Run Python Code RequestId: ${pythonResponse.requestId}`);
+
+      if (!pythonResponse.result || pythonResponse.result.trim() === '') {
+        log('Warning: Python code execution returned empty result');
+        if (pythonResponse.errorMessage) {
+          log(`Error message: ${pythonResponse.errorMessage}`);
+        }
+      }
+    } catch (error) {
+      log(`Error running Python code: ${error}`);
+    }
+
+    // 4. Execute JavaScript code with custom timeout
+    log('\n4. Running JavaScript code with custom timeout...');
+    try {
+      const jsCode = `
+console.log("JavaScript execution in AgentBay");
+console.log("Basic operations:");
+
+// Simple array operations
+const numbers = [1, 2, 3, 4, 5];
+console.log("Original array:", numbers);
+
+const doubled = numbers.map(n => n * 2);
+console.log("Doubled values:", doubled);
+
+const sum = numbers.reduce((total, n) => total + n, 0);
+console.log("Sum of array:", sum);
+`;
+      const timeoutS = 10; // 10 seconds timeout
+      const jsResponse = await session.code.runCode(jsCode, "javascript", timeoutS);
+      log(`JavaScript code output:\n${jsResponse.result}`);
+      log(`Run JavaScript Code RequestId: ${jsResponse.requestId}`);
+    } catch (error) {
+      log(`Error running JavaScript code: ${error}`);
+    }
+
+    // 5. Execute a more complex shell command sequence
+    log('\n5. Executing a sequence of shell commands...');
+    try {
+      const complexCommand = `
+echo "Current working directory:"
+pwd
+echo "\nSystem information:"
+uname -a
+echo "\nMemory usage:"
+free -h 2>/dev/null || vm_stat 2>/dev/null || echo "Memory info not available"
+echo "\nDisk usage:"
+df -h | head -5
+`;
+      const complexResponse = await session.command.executeCommand(complexCommand);
+      log(`Complex command output:\n${truncateOutput(complexResponse.output, 15)}`);
+      log(`Execute Complex Command RequestId: ${complexResponse.requestId}`);
+    } catch (error) {
+      log(`Error executing complex command: ${error}`);
+    }
+
+    log('\nCommand examples completed successfully!');
+
+  } finally {
+    // Clean up by deleting the session when we're done
+    log('\nDeleting the session...');
+    try {
+      const deleteResponse = await agentBay.delete(session);
+      log('Session deleted successfully');
+      log(`Delete Session RequestId: ${deleteResponse.requestId}`);
+    } catch (error) {
+      log(`Error deleting session: ${error}`);
+    }
+  }
+}
+
+// Execute the main function
+main().catch(error => {
+  logError('Error in main execution:', error);
+  process.exit(1);
+});