wuying-agentbay-sdk 0.10.2 → 0.12.0

package/docs/examples/common-features/basics/context-management/README.md

@@ -0,0 +1,55 @@
+# Context Management Example
+
+This example demonstrates how to use the Context Management features of the AgentBay SDK for TypeScript.
+
+## Features Demonstrated
+
+- Listing all contexts
+- Getting or creating a context
+- Creating a session with a context
+- Updating a context
+- Clearing context data (synchronous clear)
+- Deleting a context
+
+## 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 context-management
+npx ts-node context-management.ts
+```
+
+## Code Explanation
+
+The example demonstrates a full lifecycle of context management:
+
+1. Initialize the AgentBay client with an API key
+2. List all existing contexts to see what's available
+3. Get an existing context by name, or create it if it doesn't exist
+4. Create a session using the context
+5. Update the context's properties
+6. Clear the context's persistent data (demonstrates synchronous clear method)
+7. Clean up by deleting the session and context
+
+Context management allows you to work with persistent storage areas that can be used across multiple sessions. This enables scenarios like:
+
+- Preserving file system changes between sessions
+- Maintaining application state across session restarts
+- Sharing data between different sessions
+- Creating templates for quick session initialization
+
+For more details on context management, see the [Context API Reference](../../../../api/common-features/basics/context.md) and [Data Persistence Tutorial](../../../../../../docs/guides/common-features/basics/data-persistence.md).

package/docs/examples/common-features/basics/context-management/context-management.ts

@@ -0,0 +1,140 @@
+import { AgentBay, logError, log, ContextSync } from 'wuying-agentbay-sdk';
+
+/**
+ * Context Management Example
+ *
+ * This example demonstrates how to use the Context API in TypeScript.
+ */
+async function main() {
+  try {
+    // Initialize the AgentBay client
+    // You can provide the API key as a parameter or set the AGENTBAY_API_KEY environment variable
+    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.');
+    }
+
+    const agentBay = new AgentBay({ apiKey });
+
+    // Example 1: List all contexts
+    log('\nExample 1: Listing all contexts...');
+    try {
+      const listResult = await agentBay.context.list();
+      log(`Found ${listResult.contexts.length} contexts (RequestID: ${listResult.requestId}):`);
+      for (const ctx of listResult.contexts) {
+        log(`- ${ctx.name} (${ctx.id}): state=${ctx.state}, os=${ctx.osType}`);
+      }
+    } catch (error) {
+      log(`Error listing contexts: ${error}`);
+    }
+
+    // Example 2: Get a context (create if it doesn't exist)
+    log('\nExample 2: Getting a context (creating if it doesn\'t exist)...');
+    const contextName = 'my-test-context';
+    const getResult = await agentBay.context.get(contextName, true);
+    if (!getResult.contextId || getResult.contextId === '') {
+      log('Context not found and could not be created');
+      return;
+    }
+
+    log(`Got context: ${getResult.context.name} (${getResult.contextId}) with RequestID: ${getResult.requestId}`);
+
+    // Use the Context object directly
+    const context = getResult.context;
+
+    // Example 3: Create a session with the context
+    log('\nExample 3: Creating a session with the context...');
+    const contextSync = new ContextSync(context.id, '/mnt/persistent');
+    const sessionResult = await agentBay.create({
+      contextSync: [contextSync],
+      labels: {
+        username: 'alice',
+        project: 'my-project'
+      }
+    });
+
+    if (!sessionResult.session) {
+      log('Error creating session');
+      return;
+    }
+
+    log(`Session created with ID: ${sessionResult.session.sessionId} (RequestID: ${sessionResult.requestId})`);
+    log('Note: The create() method automatically monitored the context status');
+    log('and only returned after all context operations were complete or reached maximum retries.');
+    const session = sessionResult.session;
+
+    // Example 4: Update the context
+    log('\nExample 4: Updating the context...');
+    context.name = 'renamed-test-context';
+    try {
+      const updateResult = await agentBay.context.update(context);
+      if (!updateResult.success) {
+        log('Context update was not successful');
+      } else {
+        log(`Context updated successfully to: ${context.name} (RequestID: ${updateResult.requestId})`);
+      }
+    } catch (error) {
+      log(`Error updating context: ${error}`);
+    }
+
+    // Clean up
+    log('\nCleaning up...');
+
+    // Delete the session with context synchronization
+    try {
+      log('Deleting the session with context synchronization...');
+      const deleteSessionResult = await agentBay.delete(session, true); // Using syncContext=true
+      log(`Session deleted successfully with context synchronization (RequestID: ${deleteSessionResult.requestId})`);
+      log('Note: The delete() method synchronized the context before session deletion');
+      log('and monitored all context operations until completion.');
+
+      // Alternative method using session's delete method:
+      // const deleteSessionResult = await session.delete(true);
+    } catch (error) {
+      log(`Error deleting session: ${error}`);
+    }
+
+    // Example 5: Clear context data
+    log('\nExample 5: Clearing context data...');
+    log('Starting synchronous context clear (recommended approach)...');
+    try {
+      const clearResult = await agentBay.context.clear(context.id, 30, 2.0);
+      log(`Clear result: Success=${clearResult.success}, Status=${clearResult.status}, RequestID=${clearResult.requestId}`);
+
+      if (clearResult.success) {
+        log('✅ Context data cleared successfully');
+        log(`   Context ID: ${clearResult.contextId}`);
+        log(`   Final Status: ${clearResult.status}`);
+      } else {
+        log(`❌ Context data clearing failed: ${clearResult.errorMessage}`);
+      }
+    } catch (clearError: any) {
+      if (clearError.message.includes('timed out')) {
+        log(`⏱️ Clear timed out: ${clearError.message}`);
+      } else {
+        log(`❌ Error during context clear: ${clearError.message}`);
+      }
+    }
+
+    // Clean up
+    log('\nCleaning up...');
+    log('Note: Context data has been cleared, but the context itself still exists.');
+
+    // Delete the context
+    log('Deleting the context...');
+    try {
+      const deleteContextResult = await agentBay.context.delete(context);
+      log(`Context deleted successfully (RequestID: ${deleteContextResult.requestId})`);
+    } catch (error) {
+      log(`Error deleting context: ${error}`);
+    }
+  } catch (error) {
+    logError(`Error initializing AgentBay: ${error}`);
+  }
+}
+
+// Execute the main function
+main().catch(error => {
+  logError('Error in main execution:', error);
+  process.exit(1);
+});

package/docs/examples/common-features/basics/data-persistence/README.md

@@ -0,0 +1,129 @@
+# Data Persistence Examples
+
+This directory contains examples demonstrating data persistence functionality in AgentBay SDK for TypeScript.
+
+## Examples
+
+### 1. `data-persistence.ts` - Basic Data Persistence
+
+Demonstrates the fundamental data persistence features:
+
+- Context creation for persistent storage
+- File persistence across multiple sessions
+- Context synchronization and file sharing
+- Multi-session data verification
+
+### 2. `context-sync-demo.ts` - Advanced Sync with Callbacks
+
+Demonstrates the callback-based context synchronization:
+
+- Async context sync operations
+- Timing analysis and performance monitoring
+- Status verification using `context.info()`
+- Multiple sync operations and error handling
+- Backward compatibility with traditional sync
+
+### 3. `recycle-policy-example.ts` - Data Lifecycle Management
+
+Demonstrates RecyclePolicy for controlling context data lifecycle:
+
+- Using default RecyclePolicy (keeps data forever)
+- Setting custom lifecycle durations (1 day, 3 days, etc.)
+- Applying RecyclePolicy to specific paths
+- Available lifecycle options
+
+## Key Features
+
+### Data Persistence
+
+- **Context Creation**: Create persistent storage contexts
+- **Cross-Session Persistence**: Data survives session deletion
+- **File Synchronization**: Automatic sync of files to persistent storage
+- **Multi-Session Access**: Access data from different sessions
+
+### Context Sync Callbacks
+
+- **Async Operations**: Non-blocking sync operations
+- **Real-time Feedback**: Immediate notification on completion
+- **Timing Information**: Detailed performance metrics
+- **Error Handling**: Graceful handling of failures and timeouts
+- **Status Monitoring**: Track sync progress and completion
+
+### Data Lifecycle Management
+
+- **RecyclePolicy**: Control how long context data is retained in the cloud
+- **Lifecycle Options**: 1 day to forever (10 options available)
+- **Path-Specific Policies**: Apply different lifecycles to different directories
+- **Automatic Cleanup**: Data is automatically deleted after specified duration
+- **Path Validation**: Ensures path safety (no wildcard patterns)
+
+## Usage
+
+### Basic Data Persistence
+
+```bash
+cd typescript/docs/examples/data-persistence
+npx ts-node data-persistence.ts
+```
+
+### Context Sync Demo
+
+```bash
+cd typescript/docs/examples/data-persistence
+npx ts-node context-sync-demo.ts
+```
+
+### RecyclePolicy Example
+
+```bash
+cd typescript/docs/examples/data-persistence
+npx ts-node recycle-policy-example.ts
+```
+
+## Prerequisites
+
+- AgentBay SDK installed
+- Valid API key configured (via environment variable `AGENTBAY_API_KEY`)
+- Network access to AgentBay services
+- Node.js 16 or later
+- TypeScript 4.5 or later
+
+## Expected Behavior
+
+All examples will:
+
+1. Create a persistent context
+2. Create a session with context synchronization
+3. Write test data to the persistent storage
+4. Demonstrate data persistence across sessions
+5. Clean up resources
+
+The callback example additionally shows:
+
+- Async sync operations with timing
+- Callback notifications
+- Status monitoring
+- Error handling scenarios
+
+## Output
+
+All examples provide detailed console output showing:
+
+- Step-by-step progress
+- Success/failure status for each operation
+- Timing information (callback example)
+- Data verification results
+- Cleanup confirmation
+
+## Notes
+
+- Examples use temporary contexts that are cleaned up after execution
+- File paths use `/tmp/` for demonstration purposes
+- Timing may vary based on network conditions and file sizes
+- The callback example includes timeout handling for robustness
+
+## Related Documentation
+
+- [Data Persistence Guide](../../../../../../docs/guides/common-features/basics/data-persistence.md) - Comprehensive guide on data persistence
+- [Context Management](../context-management/README.md) - Context creation and management
+- [File Operations](../filesystem-example/README.md) - File handling and management

package/docs/examples/common-features/basics/data-persistence/context-sync-demo.md

@@ -0,0 +1,144 @@
+# Context Sync Dual-Mode Example (TypeScript)
+
+This example demonstrates the dual-mode `context.sync()` functionality in the TypeScript SDK, showing both asynchronous callback-based and synchronous await-based usage patterns.
+
+## Features Demonstrated
+
+- **Context Creation**: Creates persistent contexts for data storage
+- **Test Data Generation**: Creates sample files and directories for sync testing
+- **Dual-Mode Context Sync**: Shows both callback and await patterns
+- **Session Management**: Proper session creation and cleanup
+- **Error Handling**: Comprehensive error handling and cleanup
+- **Timing Measurement**: Tracks sync operation duration
+- **Concurrent Execution**: Demonstrates running multiple sync operations
+
+## Usage Patterns
+
+### 1. Async Mode with Callback
+
+```typescript
+// Immediate return with callback handling
+const syncResult = await session.context.sync(
+  undefined, // contextId
+  undefined, // path
+  undefined, // mode
+  (success: boolean) => {
+    if (success) {
+      console.log("✅ Context sync completed successfully");
+    } else {
+      console.log("❌ Context sync completed with failures");
+    }
+  }
+);
+```
+
+### 2. Sync Mode with Await
+
+```typescript
+// Wait for completion before returning
+const syncResult = await session.context.sync();
+if (syncResult.success) {
+  console.log("✅ Context sync completed successfully");
+} else {
+  console.log("❌ Context sync completed with failures");
+}
+```
+
+## Key Differences from Python Version
+
+- **TypeScript/JavaScript**: Uses `Promise` and `async/await` instead of Python's `asyncio`
+- **Callback Pattern**: Uses arrow functions for callbacks
+- **Timing**: Uses `Date.now()` for millisecond precision timing
+- **Error Handling**: Uses try/catch blocks with Promise-based error handling
+
+## Running the Example
+
+```bash
+# From the typescript directory
+npm run build
+node dist/docs/examples/data-persistence/context-sync-demo.js
+```
+
+## Expected Output
+
+```
+🔄 AgentBay Context Sync Dual-Mode Example (TypeScript)
+
+============================================================
+🔄 Method 1: context_sync_with_callback (Async with callback)
+============================================================
+🔄 Starting context sync with callback demo...
+
+📦 Creating context for persistent storage...
+✅ Context created: sync-callback-demo
+
+📦 Creating session with context sync...
+✅ Session created: session-123
+
+💾 Creating test data...
+✅ Created file: /tmp/sync_data/test_files/small.txt
+✅ Created file: /tmp/sync_data/test_files/medium.txt
+✅ Created file: /tmp/sync_data/config.json
+📊 Created 3/3 test files
+
+📞 Calling context.sync() with callback...
+📤 Sync initiation result: success=true, requestId=req-456
+⏳ Waiting for callback to complete...
+✅ Context sync completed successfully in 2000ms
+🗑️  Deleting session from callback...
+✅ Session deleted successfully from callback
+
+⏳ Sleeping 3 seconds before next demo...
+
+============================================================
+🔄 Method 2: context_sync (Sync with await)
+============================================================
+🔄 Starting context sync demo...
+
+📦 Creating context for persistent storage...
+✅ Context created: sync-await-demo
+
+📦 Creating session with context sync...
+✅ Session created: session-789
+
+💾 Creating test data...
+✅ Created file: /tmp/sync_data/test_files/small.txt
+✅ Created file: /tmp/sync_data/test_files/medium.txt
+✅ Created file: /tmp/sync_data/config.json
+📊 Created 3/3 test files
+
+⏳ Calling context.sync() with await...
+✅ Context sync completed successfully in 1500ms
+📤 Sync result: success=true, requestId=req-101
+🗑️  Deleting session...
+✅ Session deleted successfully
+
+⏳ Waiting for callback demo to complete...
+
+✅ Context sync dual-mode example completed
+```
+
+## Configuration
+
+The example uses default configuration values:
+
+- **Max Retries**: 150 attempts
+- **Retry Interval**: 1500ms (1.5 seconds)
+- **Timeout**: ~5 minutes (150 × 1.5s)
+
+## Error Handling
+
+The example includes comprehensive error handling:
+
+- Sync operation failures
+- Session creation failures
+- Session deletion failures
+- Automatic cleanup on errors
+
+## Integration with Session Deletion
+
+The example demonstrates how `context.sync()` integrates with session deletion:
+
+- Callback mode: Session deletion happens in the callback
+- Await mode: Session deletion happens after sync completion
+- Both modes avoid double-syncing by passing `false` to `session.delete()`