@tencent-ai/agent-sdk 0.3.98 → 0.3.100

package/cli/dist/web-ui/docs/en/cli/sandboxing.md

@@ -0,0 +1,316 @@
+# Sandbox Usage Guide (Beta)
+
+> ⚠️ **Beta Feature**: The Sandbox feature is currently in Beta. APIs and functionality may change.
+
+CodeBuddy supports running in isolated sandbox environments, providing secure code execution and project development environments.
+
+## 🎯 Sandbox Types
+
+- **Container Sandbox**: Local container environment based on Docker/Podman
+- **E2B Sandbox**: Remote isolated environment based on E2B cloud service
+- **Teleport Mode**: Connect to remotely deployed sandbox services
+
+## 🚀 Quick Start
+
+### Container Sandbox
+
+```bash
+# Basic usage - automatically mounts current directory
+codebuddy --sandbox "Help me analyze this project"
+
+# Equivalent to
+codebuddy --sandbox container "Help me analyze this project"
+
+# Pipe mode
+echo "Run tests" | codebuddy --sandbox --print
+```
+
+**Prerequisites**:
+- Docker or Podman installed
+- Docker daemon running
+
+### E2B Sandbox (Cloud)
+
+```bash
+# Set E2B API Key
+export E2B_API_KEY=your_api_key
+
+# Basic usage (requires full API URL)
+codebuddy --sandbox https://api.e2b.dev "Create a Python web application"
+
+# Upload current working directory
+codebuddy --sandbox https://api.e2b.dev --sandbox-upload-dir "Analyze this project"
+```
+
+### Teleport Mode (Remote Connection)
+
+Teleport mode is used to connect to remote sandbox environments created by BGA (Background Agent). This is a special connection mode primarily used for cloud scheduling scenarios.
+
+```bash
+# Connect to remote sandbox using teleport value
+codebuddy --teleport session_abc123XYZ4567890 "Connect to remote sandbox"
+
+# Custom headers (for authentication or routing)
+codebuddy --teleport session_abc123XYZ4567890 \
+  -H "X-Domain: example.com" \
+  -H "X-Enterprise-Id: ent123" \
+  "Execute task"
+```
+
+**Teleport Value Format**:
+- Format: `session_{cliSessionId}`
+- `cliSessionId`: Unique session identifier
+- Example: `session_abc123XYZ4567890`
+
+**How It Works**:
+1. BGA backend generates a unique `cliSessionId`
+2. BGA clones code to `/workspace/{cliSessionId}` directory in the sandbox
+3. BGA generates teleport command: `codebuddy --teleport session_{cliSessionId}`
+4. CLI parses the teleport value, connects to the specified sandbox and switches to the correct working directory
+5. Executes commands as `root` user in the sandbox
+
+**Prerequisites**:
+- Valid teleport value (generated by BGA backend)
+- Correct authentication credentials (via E2B_API_KEY or CODEBUDDY_AUTH_TOKEN)
+- Network connectivity to BGA backend service
+
+**Features**:
+- Code is prepared by BGA backend, no upload needed
+- Automatically executes commands as root user
+- Working directory automatically set to `/workspace/{cliSessionId}`
+- Supports custom HTTP headers for authentication and routing
+
+## 📦 Sandbox Reuse Mechanism
+
+### Alias System
+
+Assign independent sandboxes for users/projects:
+
+```bash
+# Use user ID as alias
+codebuddy --sandbox https://api.e2b.dev --sandbox-id user-123 -p "Task"
+
+# Use project name as alias
+codebuddy --sandbox https://api.e2b.dev --sandbox-id project-foo -p "Task"
+```
+
+Alias mappings are stored in `~/.codebuddy/sandbox-state.json`, supporting automatic creation and reuse.
+
+### Default Behavior
+
+Sandboxes are automatically reused without manually specifying IDs:
+
+```bash
+# First time - creates new sandbox
+$ codebuddy --sandbox https://api.e2b.dev "Hello"
+[Sandbox] Creating new E2B sandbox...
+[Sandbox] Created new sandbox: sb_abc123
+
+# Next launch - automatically reuses
+$ codebuddy --sandbox https://api.e2b.dev "Continue working"
+[Sandbox] Reusing sandbox: sb_abc123
+```
+
+### Multi-Project Management
+
+A single sandbox can host multiple projects, automatically isolated in different directories:
+
+```
+/workspace/
+  ├── home-user-projectA/
+  ├── home-user-projectB/
+  └── var-www-website/
+```
+
+## ⚙️ Advanced Parameters
+
+### Sandbox Creation and Connection
+
+```bash
+# Force create new sandbox (ignore cache)
+codebuddy --sandbox --sandbox-new "Start from scratch"
+
+# Connect to specific sandbox ID (real ID)
+codebuddy --sandbox --sandbox-id sb_abc123 "Continue previous work"
+
+# Use aliases (custom names, auto-create and reuse)
+codebuddy --sandbox https://api.e2b.dev --sandbox-id user-123 -p "Task"     # User ID
+codebuddy --sandbox https://api.e2b.dev --sandbox-id project-foo -p "Task"  # Project name
+codebuddy --sandbox https://api.e2b.dev --sandbox-id team-backend -p "Task" # Team name
+
+# Terminate sandbox on exit (default keeps running for reuse)
+codebuddy --sandbox --sandbox-kill "Clean up after completion"
+```
+
+### Environment Variable Configuration
+
+```bash
+# E2B configuration
+export E2B_API_KEY=your_api_key              # Required
+export E2B_TEMPLATE=base                     # Template name (default: base)
+export E2B_TIMEOUT_MS=3600000                # Timeout (default: 1 hour)
+export E2B_ALLOW_INTERNET_ACCESS=true        # Allow internet access (default: true)
+
+# Container Sandbox configuration
+export CODEBUDDY_SANDBOX_IMAGE=node:20-alpine  # Docker image
+```
+
+## 📊 Sandbox Management
+
+### List Sandboxes
+
+```bash
+$ codebuddy sandbox list
+E2B Sandboxes:
+* sb_abc123 (2 projects, last used 2m ago)
+  sb_xyz789 (1 project, last used 2h ago)
+```
+
+### View Details
+
+```bash
+# View current sandbox
+$ codebuddy sandbox info
+
+# View specific sandbox
+$ codebuddy sandbox info sb_xyz789
+```
+
+### Terminate Sandbox
+
+```bash
+$ codebuddy sandbox kill sb_abc123
+```
+
+### Clean Up Invalid Sandboxes
+
+```bash
+$ codebuddy sandbox clean
+```
+
+## 🔍 How It Works
+
+### Project Directory Mapping
+
+```bash
+Local path: /Users/yangsubo/projectA
+Sandbox path: /workspace/Users-yangsubo-projectA
+```
+
+### State Persistence
+
+Sandbox state is saved in `~/.codebuddy/sandbox-state.json`
+
+## 💡 Best Practices
+
+### 1. Choose the Right Sandbox Type
+
+```bash
+# Need local container isolation
+codebuddy --sandbox container "Local development task"
+
+# Cloud collaboration or no local environment
+codebuddy --sandbox https://api.e2b.dev "Cloud development"
+
+# Connect to remotely deployed sandbox service
+codebuddy --teleport session_abc123XYZ4567890 "Remote development"
+```
+
+### 2. Project Isolation
+
+```bash
+cd ~/work/projectA
+codebuddy --sandbox "Develop feature X"
+
+cd ~/work/projectB
+codebuddy --sandbox "Fix bug Y"
+```
+
+### 3. Long-term Development
+
+```bash
+# Day one
+codebuddy --sandbox "Set up development environment"
+
+# Day two - instant startup, environment preserved
+codebuddy --sandbox "Continue development"
+```
+
+### 4. Temporary Tasks
+
+Use `--sandbox-kill` for automatic cleanup:
+
+```bash
+codebuddy --sandbox --sandbox-kill "Quickly test an idea"
+```
+
+### 5. Regular Cleanup
+
+```bash
+# View all sandboxes
+codebuddy sandbox list
+
+# Clean up invalid ones
+codebuddy sandbox clean
+
+# Manually terminate specific sandbox
+codebuddy sandbox kill sb_old123
+```
+
+## ⚠️ Important Notes
+
+### Container Sandbox
+
+- **Mount Mode**: Container sandbox automatically mounts current directory, file changes sync in real-time
+- **Network Isolation**: Docker container is isolated from host network
+- **Resource Limits**: Subject to Docker configuration limits
+
+### E2B Sandbox
+
+- **Upload Delay**: Initial project upload takes time, more files means slower upload
+- **File Sync**: Automatic sync not supported, requires re-upload or manual sync
+- **Cost**: E2B cloud service may incur charges, check official pricing
+- **Timeout**: Sandboxes have maximum runtime limits (default: 1 hour)
+
+### Interactive Commands
+
+Both E2B and Container support interactive PTY:
+
+```bash
+codebuddy --sandbox "Edit main.py with vim"
+codebuddy --sandbox "Run htop to view processes"
+```
+
+## 🔧 Troubleshooting
+
+### Docker Not Running
+
+```bash
+Error: Neither Docker nor Podman is available
+```
+**Solution**: Start Docker Desktop or Podman
+
+### E2B API Key Missing
+
+```bash
+Error: E2B_API_KEY environment variable is required
+```
+**Solution**: `export E2B_API_KEY=your_key_here`
+
+### Sandbox Connection Failed
+
+```bash
+Failed to connect to sandbox sb_abc123
+```
+**Solution**: Sandbox may have expired, use `--sandbox-new` to create a new one
+
+### View Debug Logs
+
+```bash
+codebuddy --sandbox --debug "Test command"
+```
+
+## 📚 Related Documentation
+
+- [CLI Reference](./cli-reference.md) - Complete command-line parameter documentation
+- [E2B Official Documentation](https://e2b.dev/docs) - E2B cloud service documentation

package/cli/dist/web-ui/docs/en/cli/scheduled-tasks.md

@@ -0,0 +1,160 @@
+# Scheduled Tasks
+
+CodeBuddy Code supports creating and managing scheduled tasks within a session. You can set up tasks that execute instructions on a recurring schedule or trigger a one-time action at a specific future time. Common use cases include: periodically checking build status, polling for task completion, setting reminders at specific times, and more.
+
+> **Note**: Scheduled tasks are session-scoped. Tasks are only active while CodeBuddy Code is running and are automatically cleared upon exit.
+
+
+## Creating One-Time Reminders
+
+If you only need a reminder at a specific future time, you can describe it in natural language:
+
+```
+Remind me at 4:30 PM to sync today's progress
+```
+
+```
+Check the build task output in one hour
+```
+
+```
+Generate a daily work report for yesterday at 9 AM tomorrow
+```
+
+These tasks trigger once at the specified time and are automatically deleted after execution.
+
+---
+
+## Managing Existing Tasks
+
+### View All Current Tasks
+
+```
+What scheduled tasks do I have right now?
+```
+
+The list includes the task ID, execution frequency, task type (recurring / one-time), and the associated instruction.
+
+### Cancel a Task
+
+```
+Cancel the deployment check scheduled task
+```
+
+Or cancel by task ID:
+
+```
+Delete the scheduled task with ID xxx
+```
+
+Under the hood, these correspond to the `CronList` and `CronDelete` tools, which can be operated through conversation without needing to remember specific commands.
+
+---
+
+## Task Execution Mechanism
+
+### Execution Timing
+
+Tasks only trigger when the session is **idle** — that is, when the system is not processing other requests. If an operation is in progress when the task is due, the trigger is deferred until the operation completes.
+
+### Time Jitter
+
+The system adds a small random offset to task trigger times to prevent congestion from many tasks firing simultaneously:
+
+- **Recurring tasks**: Delayed by up to 10% of the cycle duration (capped at 15 minutes)
+- **One-time tasks**: For tasks set to the hour or half-hour, may trigger up to 90 seconds early
+
+For example, a task set to run `every hour` may actually trigger randomly within 0–6 minutes after the hour.
+
+### Auto-Expiration
+
+**Recurring tasks automatically expire and are deleted after 3 days**, with one final trigger before expiration.
+If you need tasks to persist longer, you can recreate them after expiration or use an external scheduling solution (such as GitHub Actions).
+
+---
+
+## Cron Expression Reference
+
+For precise schedules like "every Monday at 10 AM" or "the 1st of every month," simply describe your requirement to the AI, and it will automatically convert it to a cron expression and create the task:
+
+```
+Generate a weekly work plan every Monday at 10 AM
+```
+
+```
+On the 1st of every month, compile last month's code commit statistics grouped by contributor
+```
+
+```
+Every Friday at 5:30 PM, remind me to sync progress and update task status
+```
+
+```
+Every day at noon, check if there are any PRs awaiting my review
+```
+
+```
+On weekdays at 9:15 AM, list yesterday's unmerged PRs
+```
+
+The AI response will include the actual cron expression and execution frequency used, so you can confirm whether it matches your expectations.
+
+**Format:**
+```
+Minute  Hour  Day  Month  Weekday
+```
+
+**Common expressions:**
+
+| Expression | Meaning |
+|--------|------|
+| `*/5 * * * *` | Every 5 minutes |
+| `*/15 * * * *` | Every 15 minutes |
+| `0 * * * *` | Every hour on the hour |
+| `0 9 * * *` | Every day at 9 AM |
+| `0 9 * * 1-5` | Weekdays at 9 AM |
+| `0 0 1 * *` | Midnight on the 1st of every month |
+| `30 18 * * 5` | Every Friday at 6:30 PM |
+
+**Field descriptions:**
+
+| Field | Range | Special Characters |
+|------|---------|---------|
+| Minute | 0–59 | `*` (any), `*/N` (every N minutes), `N,M` (list), `N-M` (range) |
+| Hour | 0–23 | Same as above |
+| Day | 1–31 | Same as above |
+| Month | 1–12 | Same as above |
+| Weekday | 0–6 | 0 or 7 = Sunday, 1 = Monday, and so on |
+
+---
+
+## Notes
+
+| Item | Description |
+|------|------|
+| **Session-bound** | Tasks exist within the session. They are lost when CodeBuddy Code exits and are not persisted to disk |
+| **Recurring task limit** | A maximum of 50 scheduled tasks can exist simultaneously per session |
+| **Minimum interval** | 1 minute (sub-minute intervals are automatically rounded up) |
+| **Task expiration** | Recurring tasks are automatically cleared after 3 days |
+| **No backfill** | Missed tasks during session interruptions are not retroactively executed |
+
+---
+
+## Disabling Scheduled Tasks
+
+To completely disable the scheduled tasks feature, set the following environment variable:
+
+```bash
+CODEBUDDY_DISABLE_CRON=1 codebuddy
+```
+
+Once enabled, the `/loop` skill is no longer available, and the `CronCreate`, `CronList`, and `CronDelete` tools are also disabled.
+
+---
+
+## Related Documentation
+
+- [Skills System](./skills.md)
+- [Slash Command Reference](./slash-commands.md)
+- [Sessions and Context Management](./cli-reference.md)
+- [Hooks Event System](./hooks.md)