wuying-agentbay-sdk 0.10.2 → 0.12.0

package/docs/api/common-features/basics/command.md

@@ -0,0 +1,83 @@
+# Class: Command
+
+## ⚡ Related Tutorial
+
+- [Command Execution Guide](../../../../../docs/guides/common-features/basics/command-execution.md) - Learn how to execute commands in sessions
+
+## Overview
+
+The Command module provides methods for executing shell commands within a session in the AgentBay cloud environment.
+It supports both synchronous command execution with configurable timeouts.
+
+Handles command execution operations in the AgentBay cloud environment.
+
+## Table of contents
+
+
+### Methods
+
+- [executeCommand](#executecommand)
+
+## Methods
+
+### executeCommand
+
+▸ **executeCommand**(`command`, `timeoutMs?`): `Promise`\<`CommandResult`\>
+
+Executes a shell command in the session environment.
+
+#### Parameters
+
+| Name | Type | Default value | Description |
+| :------ | :------ | :------ | :------ |
+| `command` | `string` | `undefined` | The shell command to execute. |
+| `timeoutMs` | `number` | `1000` | Timeout in milliseconds. Defaults to 1000ms. |
+
+#### Returns
+
+`Promise`\<`CommandResult`\>
+
+Promise resolving to CommandResult containing:
+         - success: Whether the command executed successfully
+         - output: Combined stdout and stderr output
+         - requestId: Unique identifier for this API request
+         - errorMessage: Error description if execution failed
+
+**`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('echo "Hello"', 3000);
+  console.log('Command output:', cmdResult.output);
+  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`**
+
+[FileSystem.readFile](filesystem.md#readfile), [FileSystem.writeFile](filesystem.md#writefile)
+
+## Best Practices
+
+1. Always specify appropriate timeout values based on expected command duration
+2. Handle command execution errors gracefully
+3. Use absolute paths when referencing files in commands
+4. Be aware that commands run with session user permissions
+5. Clean up temporary files created by commands
+
+
+## Related Resources
+
+- [Session API Reference](session.md)
+- [FileSystem API Reference](filesystem.md)
+

package/docs/api/common-features/basics/context-manager.md

@@ -0,0 +1,149 @@
+# Class: ContextManager
+
+## 🗂️ Related Tutorial
+
+- [Data Persistence Guide](../../../../../docs/guides/common-features/basics/data-persistence.md) - Learn about context management and data persistence
+
+## Table of contents
+
+
+### Methods
+
+- [info](#info)
+- [infoWithParams](#infowithparams)
+- [sync](#sync)
+
+## Methods
+
+### info
+
+▸ **info**(): `Promise`\<``ContextInfoResult``\>
+
+Gets information about context synchronization status for the current session.
+
+#### Returns
+
+`Promise`\<``ContextInfoResult``\>
+
+Promise resolving to ContextInfoResult containing context status data and request ID
+
+**`Throws`**
+
+Error if the API call fails
+
+**`Example`**
+
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const result = await agentBay.create();
+if (result.success) {
+  const info = await result.session.context.info();
+  console.log(`Context count: ${info.contextStatusData.length}`);
+  await result.session.delete();
+}
+```
+
+___
+
+### infoWithParams
+
+▸ **infoWithParams**(`contextId?`, `path?`, `taskType?`): `Promise`\<``ContextInfoResult``\>
+
+Gets information about context synchronization status with optional filter parameters.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `contextId?` | `string` | Optional context ID to filter results |
+| `path?` | `string` | Optional path to filter results |
+| `taskType?` | `string` | Optional task type to filter results (e.g., "upload", "download") |
+
+#### Returns
+
+`Promise`\<``ContextInfoResult``\>
+
+Promise resolving to ContextInfoResult containing filtered context status data and request ID
+
+**`Throws`**
+
+Error if the API call fails
+
+**`Example`**
+
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const result = await agentBay.create();
+if (result.success) {
+  const info = await result.session.context.infoWithParams('SdkCtx-xxx', '/mnt/persistent');
+  console.log(`Context status: ${info.contextStatusData[0]?.status}`);
+  await result.session.delete();
+}
+```
+
+___
+
+### sync
+
+▸ **sync**(`contextId?`, `path?`, `mode?`, `callback?`, `maxRetries?`, `retryInterval?`): `Promise`\<``ContextSyncResult``\>
+
+Synchronizes a context with the session. Supports both async and callback modes.
+
+#### Parameters
+
+| Name | Type | Default value | Description |
+| :------ | :------ | :------ | :------ |
+| `contextId?` | `string` | `undefined` | Optional context ID to synchronize. If provided, `path` must also be provided. |
+| `path?` | `string` | `undefined` | Optional path where the context should be mounted. If provided, `contextId` must also be provided. |
+| `mode?` | `string` | `undefined` | Optional synchronization mode (e.g., "upload", "download") |
+| `callback?` | ``SyncCallback`` | `undefined` | Optional callback function. If provided, runs in background and calls callback when complete |
+| `maxRetries` | `number` | `150` | Maximum number of retries for polling completion status (default: 150) |
+| `retryInterval` | `number` | `1500` | Milliseconds to wait between retries (default: 1500) |
+
+#### Returns
+
+`Promise`\<``ContextSyncResult``\>
+
+Promise resolving to ContextSyncResult with success status and request ID
+
+**`Throws`**
+
+Error if the API call fails
+
+**`Throws`**
+
+Error if `contextId` or `path` is provided without the other parameter.
+              Both must be provided together, or both must be omitted.
+
+**`Example`**
+
+Sync all contexts (no parameters):
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const result = await agentBay.create();
+if (result.success) {
+  const syncResult = await result.session.context.sync();
+  console.log(`Sync: ${syncResult.success}`);
+  await result.session.delete();
+}
+```
+
+**`Example`**
+
+Sync specific context with path:
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const result = await agentBay.create();
+if (result.success) {
+  const ctxResult = await agentBay.context.get('my-context', true);
+  const syncResult = await result.session.context.sync(ctxResult.context!.id, '/mnt/persistent', 'upload');
+  console.log(`Sync: ${syncResult.success}`);
+  await result.session.delete();
+}
+```
+
+## Related Resources
+
+- [Context API Reference](context.md)
+- [Session API Reference](session.md)
+

package/docs/api/common-features/basics/context-sync.md

@@ -0,0 +1,51 @@
+# Interface: ContextSyncResult
+
+Base interface for API responses
+
+## Hierarchy
+
+- ``ApiResponse``
+
+  ↳ **`ContextSyncResult`**
+
+## Table of contents
+
+### Properties
+
+- `errorMessage`
+- `requestId`
+
+## Properties
+
+```typescript
+success: `boolean`
+```
+
+
+### errorMessage
+
+• `Optional` **errorMessage**: `string`
+
+Optional error message if the operation failed
+
+#### Overrides
+
+`ApiResponse`.`errorMessage`
+
+___
+
+### requestId
+
+• `Optional` **requestId**: `string`
+
+Optional request identifier for tracking API calls
+
+#### Inherited from
+
+`ApiResponse`.`requestId`
+
+___
+
+#### Overrides
+
+`ApiResponse`.`success`

package/docs/api/common-features/basics/context.md

@@ -0,0 +1,348 @@
+# Class: ContextService
+
+## 💾 Related Tutorial
+
+- [Data Persistence Guide](../../../../../docs/guides/common-features/basics/data-persistence.md) - Learn about context management and data persistence
+
+Provides methods to manage persistent contexts in the AgentBay cloud environment.
+
+## Table of contents
+
+
+### Methods
+
+- [clear](#clear)
+- [clearAsync](#clearasync)
+- [create](#create)
+- [delete](#delete)
+- [deleteFile](#deletefile)
+- [get](#get)
+- [list](#list)
+- [listFiles](#listfiles)
+- [update](#update)
+
+## Methods
+
+### clear
+
+▸ **clear**(`contextId`, `timeout?`, `pollInterval?`): `Promise`\<`ClearContextResult`\>
+
+Synchronously clear the context's persistent data and wait for the final result.
+
+This method wraps the `clearAsync` and `getClearStatus` polling logic,
+providing the simplest and most direct way to handle clearing tasks.
+
+The clearing process transitions through the following states:
+- "clearing": Data clearing is in progress
+- "available": Clearing completed successfully (final success state)
+
+#### Parameters
+
+| Name | Type | Default value | Description |
+| :------ | :------ | :------ | :------ |
+| `contextId` | `string` | `undefined` | Unique ID of the context to clear. |
+| `timeout` | `number` | `60` | (Optional) Timeout in seconds to wait for task completion, default is 60 seconds. |
+| `pollInterval` | `number` | `2.0` | (Optional) Interval in seconds between status polls, default is 2 seconds. |
+
+#### Returns
+
+`Promise`\<`ClearContextResult`\>
+
+A ClearContextResult object containing the final task result.
+         The status field will be "available" on success, or other states if interrupted.
+
+**`Throws`**
+
+APIError - If the task fails to complete within the specified timeout.
+
+**`Example`**
+
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const getResult = await agentBay.context.get('my-context');
+if (getResult.success) {
+  const clearResult = await agentBay.context.clear(getResult.context.id);
+  console.log('Context cleared:', clearResult.success);
+  console.log('Final status:', clearResult.status);
+}
+```
+
+___
+
+### clearAsync
+
+▸ **clearAsync**(`contextId`): `Promise`\<`ClearContextResult`\>
+
+Asynchronously initiate a task to clear the context's persistent data.
+
+This is a non-blocking method that returns immediately after initiating the clearing task
+on the backend. The context's state will transition to "clearing" while the operation
+is in progress.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `contextId` | `string` | Unique ID of the context to clear. |
+
+#### Returns
+
+`Promise`\<`ClearContextResult`\>
+
+A ClearContextResult object indicating the task has been successfully started,
+         with status field set to "clearing".
+
+**`Throws`**
+
+APIError - If the backend API rejects the clearing request (e.g., invalid ID).
+
+**`Example`**
+
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const getResult = await agentBay.context.get('my-context');
+if (getResult.success) {
+  const clearResult = await agentBay.context.clearAsync(getResult.context.id);
+  console.log('Clear task started:', clearResult.success);
+  console.log('Status:', clearResult.status);
+}
+```
+
+___
+
+### create
+
+▸ **create**(`name`): `Promise`\<`ContextResult`\>
+
+Creates a new context with the given name.
+Corresponds to Python's create() method
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `name` | `string` | The name for the new context. |
+
+#### Returns
+
+`Promise`\<`ContextResult`\>
+
+ContextResult with created context data and requestId
+
+**`Example`**
+
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const result = await agentBay.context.create('my-new-context');
+if (result.success) {
+  console.log(`Context ID: ${result.context.id}`);
+  console.log(`Context Name: ${result.context.name}`);
+}
+```
+
+___
+
+### delete
+
+▸ **delete**(`context`): `Promise`\<`OperationResult`\>
+
+Deletes the specified context.
+Corresponds to Python's delete() method
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `context` | ``Context`` | The Context object to delete. |
+
+#### Returns
+
+`Promise`\<`OperationResult`\>
+
+OperationResult with requestId
+
+**`Example`**
+
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const getResult = await agentBay.context.get('my-context');
+if (getResult.success && getResult.context) {
+  const deleteResult = await agentBay.context.delete(getResult.context);
+  console.log('Context deleted:', deleteResult.success);
+}
+```
+
+___
+
+### deleteFile
+
+▸ **deleteFile**(`contextId`, `filePath`): `Promise`\<`OperationResult`\>
+
+Delete a file in a context.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `contextId` | `string` | The ID of the context. |
+| `filePath` | `string` | The path to the file to delete. |
+
+#### Returns
+
+`Promise`\<`OperationResult`\>
+
+OperationResult indicating success or failure.
+
+**`Example`**
+
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const contextResult = await agentBay.context.get('my-context');
+if (contextResult.success) {
+  const deleteResult = await agentBay.context.deleteFile(contextResult.context.id, '/data/file.txt');
+  console.log('File deleted:', deleteResult.success);
+}
+```
+
+___
+
+### get
+
+▸ **get**(`name`, `create?`): `Promise`\<`ContextResult`\>
+
+Retrieves an existing context or creates a new one.
+
+#### Parameters
+
+| Name | Type | Default value | Description |
+| :------ | :------ | :------ | :------ |
+| `name` | `string` | `undefined` | The name of the context to retrieve or create. |
+| `create` | `boolean` | `false` | If true, creates the context if it doesn't exist. Defaults to false. |
+
+#### Returns
+
+`Promise`\<`ContextResult`\>
+
+Promise resolving to ContextResult containing the Context object.
+
+**`Example`**
+
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const result = await agentBay.context.get('my-context', true);
+if (result.success) {
+  console.log(`Context ID: ${result.context.id}`);
+  console.log(`Context Name: ${result.context.name}`);
+}
+```
+
+**`See`**
+
+[update](#update), [list](#list)
+
+### list
+
+▸ **list**(`params?`): `Promise`\<`ContextListResult`\>
+
+Lists all available contexts with pagination support.
+Corresponds to Python's list() method
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `params?` | `ContextListParams` | Optional parameters for listing contexts. |
+
+#### Returns
+
+`Promise`\<`ContextListResult`\>
+
+ContextListResult with contexts list and pagination information
+
+**`Example`**
+
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const result = await agentBay.context.list({ maxResults: 10 });
+if (result.success) {
+  console.log(`Total contexts: ${result.totalCount}`);
+  console.log(`Page has ${result.contexts.length} contexts`);
+}
+```
+
+___
+
+### listFiles
+
+▸ **listFiles**(`contextId`, `parentFolderPath`, `pageNumber?`, `pageSize?`): `Promise`\<`ContextFileListResult`\>
+
+List files under a specific folder path in a context.
+
+#### Parameters
+
+| Name | Type | Default value | Description |
+| :------ | :------ | :------ | :------ |
+| `contextId` | `string` | `undefined` | The ID of the context. |
+| `parentFolderPath` | `string` | `undefined` | The parent folder path to list files from. |
+| `pageNumber` | `number` | `1` | Page number for pagination (default: 1). |
+| `pageSize` | `number` | `50` | Number of files per page (default: 50). |
+
+#### Returns
+
+`Promise`\<`ContextFileListResult`\>
+
+ContextFileListResult with file entries and total count.
+
+**`Example`**
+
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const contextResult = await agentBay.context.get('my-context');
+if (contextResult.success) {
+  const listResult = await agentBay.context.listFiles(contextResult.context.id, '/data');
+  console.log(`Found ${listResult.entries.length} files`);
+  console.log(`Total count: ${listResult.count}`);
+}
+```
+
+___
+
+### update
+
+▸ **update**(`context`): `Promise`\<`OperationResult`\>
+
+Updates a context's name.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `context` | ``Context`` | The Context object with updated name. |
+
+#### Returns
+
+`Promise`\<`OperationResult`\>
+
+Promise resolving to OperationResult with success status.
+
+**`Example`**
+
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const getResult = await agentBay.context.get('old-name');
+if (getResult.success && getResult.context) {
+  getResult.context.name = 'new-name';
+  const updateResult = await agentBay.context.update(getResult.context);
+  console.log('Context updated:', updateResult.success);
+}
+```
+
+**`See`**
+
+[get](#get), [list](#list)
+
+## Related Resources
+
+- [Session API Reference](session.md)
+- [Context Manager API Reference](context-manager.md)
+