wuying-agentbay-sdk 0.10.2 → 0.11.0

package/docs/examples/common-features/basics/filesystem-example/watch-directory-example.ts

@@ -0,0 +1,168 @@
+/**
+ * Watch Directory Example
+ * 
+ * This example demonstrates how to use the watch_directory functionality
+ * to monitor file changes in a directory.
+ */
+
+import { AgentBay, CreateSessionParams } from "wuying-agentbay-sdk";
+import { FileChangeEvent } from "wuying-agentbay-sdk";
+
+async function main(): Promise<void> {
+  // Get API key from environment variable
+  const apiKey = process.env.AGENTBAY_API_KEY;
+  if (!apiKey) {
+    console.log("❌ Please set the AGENTBAY_API_KEY environment variable");
+    return;
+  }
+
+  console.log("🚀 Watch Directory Example");
+  console.log("=".repeat(50));
+
+  try {
+    // Initialize AgentBay client
+    const agentbay = new AgentBay({ apiKey });
+    console.log("✅ AgentBay client initialized");
+
+    // Create session with code_latest ImageId
+    const sessionParams: CreateSessionParams = { imageId: "code_latest" };
+    const sessionResult = await agentbay.create(sessionParams);
+
+    if (!sessionResult.success) {
+      console.log(`❌ Failed to create session: ${sessionResult.errorMessage}`);
+      return;
+    }
+
+    const session = sessionResult.session;
+    console.log(`✅ Session created: ${session.getSessionId()}`);
+
+    try {
+      // Create a test directory to monitor
+      const testDir = "/tmp/watch_example";
+      console.log(`\n📁 Creating test directory: ${testDir}`);
+
+      const createResult = await session.fileSystem.createDirectory(testDir);
+      if (!createResult.success) {
+        console.log(`❌ Failed to create directory: ${createResult.errorMessage}`);
+        return;
+      }
+
+      console.log("✅ Test directory created");
+
+      // Set up file change monitoring
+      const detectedChanges: FileChangeEvent[] = [];
+
+      const onFileChange = (events: FileChangeEvent[]) => {
+        console.log(`\n🔔 Detected ${events.length} file changes:`);
+        for (const event of events) {
+          console.log(`   📄 ${event.eventType.toUpperCase()}: ${event.path} (${event.pathType})`);
+        }
+        detectedChanges.push(...events);
+      };
+
+      console.log("\n👁️  Starting directory monitoring...");
+      console.log("   Press Ctrl+C to stop monitoring");
+
+      // Start monitoring
+      const controller = new AbortController();
+      const watchPromise = session.fileSystem.watchDirectory(
+        testDir,
+        onFileChange,
+        1000, // Check every second
+        controller.signal
+      );
+
+      console.log("✅ Directory monitoring started");
+
+      // Demonstrate file operations
+      console.log("\n🔨 Demonstrating file operations...");
+
+      // Create some files
+      const filesToCreate = [
+        { name: "example1.txt", content: "Hello, World!" },
+        { name: "example2.txt", content: "This is a test file." },
+        { name: "config.json", content: '{"setting": "value"}' }
+      ];
+
+      for (const file of filesToCreate) {
+        const filepath = `${testDir}/${file.name}`;
+        console.log(`   Creating: ${file.name}`);
+
+        const writeResult = await session.fileSystem.writeFile(filepath, file.content);
+        if (writeResult.success) {
+          console.log(`   ✅ Created: ${file.name}`);
+        } else {
+          console.log(`   ❌ Failed to create ${file.name}: ${writeResult.errorMessage}`);
+        }
+
+        // Give time for monitoring to detect changes
+        await new Promise(resolve => setTimeout(resolve, 1500));
+      }
+
+      // Modify a file
+      console.log("\n   Modifying example1.txt...");
+      const modifyResult = await session.fileSystem.writeFile(
+        `${testDir}/example1.txt`,
+        "Hello, World! - Modified content"
+      );
+      if (modifyResult.success) {
+        console.log("   ✅ Modified example1.txt");
+      } else {
+        console.log(`   ❌ Failed to modify file: ${modifyResult.errorMessage}`);
+      }
+
+      // Wait a bit more to capture all events
+      console.log("\n⏳ Waiting for final events...");
+      await new Promise(resolve => setTimeout(resolve, 3000));
+
+      // Stop monitoring
+      console.log("\n🛑 Stopping directory monitoring...");
+      controller.abort();
+      await watchPromise;
+      console.log("✅ Directory monitoring stopped");
+
+      // Summary
+      console.log("\n📊 Summary:");
+      console.log(`   Total events detected: ${detectedChanges.length}`);
+
+      if (detectedChanges.length > 0) {
+        console.log("   Event breakdown:");
+        const eventTypes: Record<string, number> = {};
+        for (const event of detectedChanges) {
+          eventTypes[event.eventType] = (eventTypes[event.eventType] || 0) + 1;
+        }
+
+        for (const [eventType, count] of Object.entries(eventTypes)) {
+          console.log(`     ${eventType}: ${count}`);
+        }
+      }
+
+      console.log("\n✨ Example completed successfully!");
+
+    } finally {
+      // Clean up session
+      console.log("\n🧹 Cleaning up...");
+      const deleteResult = await agentbay.delete(session);
+      if (deleteResult.success) {
+        console.log("✅ Session cleaned up successfully");
+      } else {
+        console.log(`⚠️  Session cleanup warning: ${deleteResult.errorMessage}`);
+      }
+    }
+
+  } catch (error) {
+    if (error instanceof Error && error.name === 'AbortError') {
+      console.log("\n\n⏹️  Monitoring stopped by user");
+    } else {
+      console.log(`\n❌ An error occurred: ${error}`);
+    }
+  }
+}
+
+// Handle Ctrl+C gracefully
+process.on('SIGINT', () => {
+  console.log("\n\n⏹️  Received interrupt signal, stopping...");
+  process.exit(0);
+});
+
+main().catch(console.error); 

package/docs/examples/common-features/basics/get/README.md

@@ -0,0 +1,136 @@
+# Get API Example
+
+This example demonstrates how to use the `get` API to retrieve a session by its ID.
+
+## Description
+
+The `get` API allows you to retrieve a session object by providing its session ID. This is useful when you have a session ID from a previous operation and want to access or manage that session.
+
+## Prerequisites
+
+- Node.js 16 or higher
+- TypeScript 4.5 or higher
+- Valid API key set in `AGENTBAY_API_KEY` environment variable
+- wuying-agentbay-sdk package installed
+
+## Installation
+
+```bash
+npm install wuying-agentbay-sdk
+# or
+yarn add wuying-agentbay-sdk
+```
+
+## Usage
+
+```bash
+# Set your API key
+export AGENTBAY_API_KEY="your-api-key-here"
+
+# Compile and run the example
+npx ts-node main.ts
+```
+
+## Code Example
+
+```typescript
+import { AgentBay } from "wuying-agentbay-sdk";
+
+async function main() {
+  // Initialize AgentBay client
+  const apiKey = process.env.AGENTBAY_API_KEY;
+  const agentBay = new AgentBay({ apiKey });
+
+  // Retrieve a session by ID
+  const sessionId = "your-session-id";
+  const result = await agentBay.get(sessionId);
+
+  if (result.success && result.session) {
+    console.log(`Retrieved session: ${result.session.sessionId}`);
+    console.log(`Request ID: ${result.requestId}`);
+    // Use the session for further operations
+    // ...
+  } else {
+    console.error(`Failed to get session: ${result.errorMessage}`);
+  }
+}
+
+main();
+```
+
+## API Reference
+
+### get
+
+```typescript
+async get(sessionId: string): Promise<SessionResult>
+```
+
+Get a session by its ID.
+
+**Parameters:**
+- `sessionId` (string): The ID of the session to retrieve
+
+**Returns:**
+- `Promise<SessionResult>`: Promise resolving to result object containing:
+  - `success` (boolean): Whether the operation succeeded
+  - `session` (Session): The Session instance if successful
+  - `requestId` (string): The API request ID
+  - `errorMessage` (string): Error message if failed
+
+## Expected Output
+
+```
+Creating a session...
+Created session with ID: session-xxxxxxxxxxxxx
+
+Retrieving session using Get API...
+Successfully retrieved session:
+  Session ID: session-xxxxxxxxxxxxx
+  Request ID: DAD825FE-2CD8-19C8-BB30-CC3BA26B9398
+
+Session is ready for use
+
+Cleaning up...
+Session session-xxxxxxxxxxxxx deleted successfully
+```
+
+## Notes
+
+- The session ID must be valid and from an existing session
+- The get API internally calls the GetSession API endpoint
+- The returned session object can be used for all session operations (commands, files, etc.)
+- Always clean up sessions when done to avoid resource waste
+
+## Error Handling
+
+The `get` method returns a `SessionResult` object with error information:
+
+1. **Empty session_id**: Result will have `success: false`
+   ```typescript
+   const result = await agentBay.get("");
+   if (!result.success) {
+     console.error(`Error: ${result.errorMessage}`);  // "session_id is required"
+   }
+   ```
+
+2. **Non-existent session**: Result will have `success: false`
+   ```typescript
+   const result = await agentBay.get("non-existent-session-id");
+   if (!result.success) {
+     console.error(`Error: ${result.errorMessage}`);  // "Failed to get session..."
+   }
+   ```
+
+## TypeScript Support
+
+This example is fully typed with TypeScript. The `get` method returns a typed `SessionResult` object with full IDE autocomplete support.
+
+```typescript
+import { AgentBay, Session } from "wuying-agentbay-sdk";
+
+const agentBay = new AgentBay({ apiKey: "your-key" });
+const session: Session = await agentBay.get("session-id");
+// TypeScript knows all methods and properties of session
+```
+

package/docs/examples/common-features/basics/get/main.ts

@@ -0,0 +1,79 @@
+/**
+ * Example demonstrating how to use the Get API to retrieve a session by its ID.
+ *
+ * This example shows:
+ * 1. Creating a session
+ * 2. Retrieving the session using the Get API
+ * 3. Using the session for operations
+ * 4. Cleaning up resources
+ * 5. Attempting to get a deleted session (error handling demonstration)
+ */
+
+import { AgentBay } from "wuying-agentbay-sdk";
+
+async function main() {
+  // Get API key from environment variable
+  const apiKey = process.env.AGENTBAY_API_KEY;
+  if (!apiKey) {
+    throw new Error("AGENTBAY_API_KEY environment variable is not set");
+  }
+
+  // Initialize AgentBay client
+  const agentBay = new AgentBay({ apiKey });
+
+  // For demonstration, first create a session
+  console.log("Creating a session...");
+  const createResult = await agentBay.create();
+  if (!createResult.success || !createResult.session) {
+    throw new Error(`Failed to create session: ${createResult.errorMessage}`);
+  }
+
+  const sessionId = createResult.session.sessionId;
+  console.log(`Created session with ID: ${sessionId}`);
+
+  // Retrieve the session by ID using Get API
+  console.log("\nRetrieving session using Get API...");
+  const getResult = await agentBay.get(sessionId);
+  
+  if (!getResult.success || !getResult.session) {
+    throw new Error(`Failed to get session: ${getResult.errorMessage}`);
+  }
+  
+  const session = getResult.session;
+
+  // Display session information
+  console.log("Successfully retrieved session:");
+  console.log(`  Session ID: ${session.sessionId}`);
+  console.log(`  Request ID: ${getResult.requestId}`);
+
+  // The session object can be used for further operations
+  // For example, you can execute commands, work with files, etc.
+  console.log("\nSession is ready for use");
+
+  // Clean up: Delete the session when done
+  console.log("\nCleaning up...");
+  const deleteResult = await session.delete();
+
+  if (deleteResult.success) {
+    console.log(`Session ${sessionId} deleted successfully`);
+  } else {
+    console.log(`Failed to delete session ${sessionId}`);
+  }
+
+  // Try to get the session again after deletion (should fail)
+  console.log("\nAttempting to get the deleted session...");
+  const getAfterDeleteResult = await agentBay.get(sessionId);
+
+  if (!getAfterDeleteResult.success) {
+    console.log("Expected behavior: Cannot retrieve deleted session");
+    console.log(`Error message: ${getAfterDeleteResult.errorMessage}`);
+  } else {
+    console.log("Unexpected: Session still exists after deletion");
+  }
+}
+
+main().catch((error) => {
+  console.error("Error:", error);
+  process.exit(1);
+});
+

package/docs/examples/common-features/basics/list_sessions/README.md

@@ -0,0 +1,54 @@
+# List Sessions Example (TypeScript)
+
+This example demonstrates how to use the `list()` API to query and filter sessions in AgentBay.
+
+## Prerequisites
+
+1. **Install dependencies**:
+   ```bash
+   npm install wuying-agentbay-sdk
+   npm install -D typescript ts-node @types/node
+   ```
+
+2. **Set API Key**:
+   ```bash
+   export AGENTBAY_API_KEY='your-api-key-here'
+   ```
+
+## Running the Example
+
+```bash
+cd /path/to/wuying-agentbay-sdk/typescript/docs/examples/list_sessions
+npx ts-node main.ts
+```
+
+## Key Features
+
+- List all sessions
+- Filter by single or multiple labels
+- Pagination support
+- Iterate through all pages
+
+## API Usage
+
+```typescript
+import { AgentBay } from "wuying-agentbay-sdk";
+
+const agentBay = new AgentBay(apiKey);
+
+// List all sessions
+const result = await agentBay.list();
+
+// Filter by labels
+const filtered = await agentBay.list({ project: "my-project" });
+
+// With pagination
+const page1 = await agentBay.list({ project: "my-project" }, 1, 10);
+const page2 = await agentBay.list({ project: "my-project" }, 2, 10);
+```
+
+## Related Documentation
+
+- [Session Management Guide](../../../../../../docs/guides/common-features/basics/session-management.md)
+- [AgentBay API Reference](../../../../api/common-features/basics/agentbay.md)
+

package/docs/examples/common-features/basics/list_sessions/main.ts

@@ -0,0 +1,258 @@
+/**
+ * AgentBay List Sessions Example
+ *
+ * This example demonstrates how to use the list() API to query sessions with filtering and pagination.
+ *
+ * Features demonstrated:
+ * 1. List all sessions
+ * 2. List sessions with label filtering
+ * 3. List sessions with pagination
+ * 4. Handle pagination to retrieve all results
+ *
+ * Usage:
+ *     npx ts-node main.ts
+ */
+
+import { AgentBay, CreateSessionParams, Session } from "wuying-agentbay-sdk";
+
+async function main() {
+  // Get API key from environment variable
+  const apiKey = process.env.AGENTBAY_API_KEY;
+  if (!apiKey) {
+    console.error("Error: AGENTBAY_API_KEY environment variable not set");
+    console.error(
+      "Please set your API key: export AGENTBAY_API_KEY='your-api-key'"
+    );
+    process.exit(1);
+  }
+
+  // Initialize AgentBay client
+  const agentBay = new AgentBay({ apiKey });
+  console.log("✅ AgentBay client initialized");
+
+  // Create some test sessions with labels for demonstration
+  console.log("\n📝 Creating test sessions...");
+  const testSessions: Session[] = [];
+
+  try {
+    // Create session 1 with labels
+    const params1: CreateSessionParams = {
+      labels: {
+        project: "list-demo",
+        environment: "dev",
+        owner: "demo-user",
+      },
+    };
+    const result1 = await agentBay.create(params1);
+    if (result1.success && result1.session) {
+      testSessions.push(result1.session);
+      console.log(`✅ Created session 1: ${result1.session.sessionId}`);
+      console.log(`   Request ID: ${result1.requestId}`);
+    }
+
+    // Create session 2 with labels
+    const params2: CreateSessionParams = {
+      labels: {
+        project: "list-demo",
+        environment: "staging",
+        owner: "demo-user",
+      },
+    };
+    const result2 = await agentBay.create(params2);
+    if (result2.success && result2.session) {
+      testSessions.push(result2.session);
+      console.log(`✅ Created session 2: ${result2.session.sessionId}`);
+      console.log(`   Request ID: ${result2.requestId}`);
+    }
+
+    // Create session 3 with labels
+    const params3: CreateSessionParams = {
+      labels: {
+        project: "list-demo",
+        environment: "prod",
+        owner: "demo-user",
+      },
+    };
+    const result3 = await agentBay.create(params3);
+    if (result3.success && result3.session) {
+      testSessions.push(result3.session);
+      console.log(`✅ Created session 3: ${result3.session.sessionId}`);
+      console.log(`   Request ID: ${result3.requestId}`);
+    }
+  } catch (error) {
+    console.error(`❌ Error creating test sessions: ${error}`);
+    process.exit(1);
+  }
+
+  try {
+    // Example 1: List all sessions (no filter)
+    console.log("\n" + "=".repeat(60));
+    console.log("Example 1: List all sessions (no filter)");
+    console.log("=".repeat(60));
+
+    const result = await agentBay.list();
+    if (result.success) {
+      console.log(`✅ Found ${result.totalCount} total sessions`);
+      console.log(`📄 Showing ${result.sessionIds.length} session IDs on this page`);
+      console.log(`🔑 Request ID: ${result.requestId}`);
+      console.log(`📊 Max results per page: ${result.maxResults}`);
+
+      // Display first few sessions
+      for (let i = 0; i < Math.min(3, result.sessionIds.length); i++) {
+        console.log(`   ${i + 1}. Session ID: ${result.sessionIds[i]}`);
+      }
+    } else {
+      console.log(`❌ Error: ${result.errorMessage}`);
+    }
+
+    // Example 2: List sessions with specific label
+    console.log("\n" + "=".repeat(60));
+    console.log("Example 2: List sessions filtered by project label");
+    console.log("=".repeat(60));
+
+    const result2 = await agentBay.list({ project: "list-demo" });
+    if (result2.success) {
+      console.log(
+        `✅ Found ${result2.totalCount} sessions with project='list-demo'`
+      );
+      console.log(`📄 Showing ${result2.sessionIds.length} session IDs on this page`);
+      console.log(`🔑 Request ID: ${result2.requestId}`);
+
+      for (let i = 0; i < result2.sessionIds.length; i++) {
+        console.log(`   ${i + 1}. Session ID: ${result2.sessionIds[i]}`);
+      }
+    } else {
+      console.log(`❌ Error: ${result2.errorMessage}`);
+    }
+
+    // Example 3: List sessions with multiple labels
+    console.log("\n" + "=".repeat(60));
+    console.log("Example 3: List sessions filtered by multiple labels");
+    console.log("=".repeat(60));
+
+    const result3 = await agentBay.list({
+      project: "list-demo",
+      environment: "dev",
+    });
+    if (result3.success) {
+      console.log(
+        `✅ Found ${result3.totalCount} sessions with project='list-demo' AND environment='dev'`
+      );
+      console.log(`📄 Showing ${result3.sessionIds.length} session IDs`);
+      console.log(`🔑 Request ID: ${result3.requestId}`);
+
+      for (let i = 0; i < result3.sessionIds.length; i++) {
+        console.log(`   ${i + 1}. Session ID: ${result3.sessionIds[i]}`);
+      }
+    } else {
+      console.log(`❌ Error: ${result3.errorMessage}`);
+    }
+
+    // Example 4: List sessions with pagination
+    console.log("\n" + "=".repeat(60));
+    console.log("Example 4: List sessions with pagination (2 per page)");
+    console.log("=".repeat(60));
+
+    // Get first page
+    const resultPage1 = await agentBay.list({ project: "list-demo" }, 1, 2);
+    if (resultPage1.success) {
+      console.log(`📄 Page 1:`);
+      console.log(`   Total count: ${resultPage1.totalCount}`);
+      console.log(`   Session IDs on this page: ${resultPage1.sessionIds.length}`);
+      console.log(`   Request ID: ${resultPage1.requestId}`);
+
+      for (let i = 0; i < resultPage1.sessionIds.length; i++) {
+        console.log(`   ${i + 1}. Session ID: ${resultPage1.sessionIds[i]}`);
+      }
+
+      // Get second page if available
+      if (resultPage1.nextToken) {
+        console.log(
+          `\n   Has next page (token: ${resultPage1.nextToken.substring(0, 20)}...)`
+        );
+
+        const resultPage2 = await agentBay.list({ project: "list-demo" }, 2, 2);
+        if (resultPage2.success) {
+          console.log(`\n📄 Page 2:`);
+          console.log(`   Session IDs on this page: ${resultPage2.sessionIds.length}`);
+          console.log(`   Request ID: ${resultPage2.requestId}`);
+
+          for (let i = 0; i < resultPage2.sessionIds.length; i++) {
+            console.log(
+              `   ${i + 1}. Session ID: ${resultPage2.sessionIds[i]}`
+            );
+          }
+        }
+      }
+    } else {
+      console.log(`❌ Error: ${resultPage1.errorMessage}`);
+    }
+
+    // Example 5: Retrieve all session IDs across multiple pages
+    console.log("\n" + "=".repeat(60));
+    console.log("Example 5: Retrieve all session IDs with pagination loop");
+    console.log("=".repeat(60));
+
+    const allSessionIds: string[] = [];
+    let page = 1;
+    const limit = 2;
+
+    while (true) {
+      const result = await agentBay.list({ owner: "demo-user" }, page, limit);
+
+      if (!result.success) {
+        console.log(`❌ Error on page ${page}: ${result.errorMessage}`);
+        break;
+      }
+
+      console.log(`📄 Page ${page}: Found ${result.sessionIds.length} session IDs`);
+      allSessionIds.push(...result.sessionIds);
+
+      // Break if no more pages
+      if (!result.nextToken) {
+        break;
+      }
+
+      page++;
+    }
+
+    console.log(
+      `\n✅ Retrieved ${allSessionIds.length} total session IDs across ${page} pages`
+    );
+    for (let i = 0; i < allSessionIds.length; i++) {
+      console.log(`   ${i + 1}. Session ID: ${allSessionIds[i]}`);
+    }
+  } finally {
+    // Clean up: Delete test sessions
+    console.log("\n" + "=".repeat(60));
+    console.log("🧹 Cleaning up test sessions...");
+    console.log("=".repeat(60));
+
+    for (const session of testSessions) {
+      try {
+        const deleteResult = await agentBay.delete(session);
+        if (deleteResult.success) {
+          console.log(`✅ Deleted session: ${session.sessionId}`);
+          console.log(`   Request ID: ${deleteResult.requestId}`);
+        } else {
+          console.log(
+            `❌ Failed to delete session ${session.sessionId}: ${deleteResult.errorMessage}`
+          );
+        }
+      } catch (error) {
+        console.error(
+          `❌ Error deleting session ${session.sessionId}: ${error}`
+        );
+      }
+    }
+  }
+
+  console.log("\n✨ Demo completed successfully!");
+}
+
+// Run the main function
+main().catch((error) => {
+  console.error("❌ Unhandled error:", error);
+  process.exit(1);
+});
+