mirror of
https://github.com/RooVetGit/Roo-Code.git
synced 2026-09-06 08:18:39 +00:00
docs: Add comprehensive cloud integration documentation
- Add CLOUD_INTEGRATION.md with detailed feature documentation - Add CLOUD_QUICKSTART.md for user-friendly quick start guide - Add CLOUD_ARCHITECTURE.md with technical architecture details - Update README.md to reference cloud features and documentation Addresses issue #6614 by documenting the existing cloud integration features that were already implemented in the codebase.
This commit is contained in:
Roo Code
parent
3f966dfaa3
commit
b4a278eb1a
4 changed files with 1259 additions and 0 deletions
11
README.md
11
README.md
|
|
@ -97,6 +97,17 @@ Roo Code comes with powerful [tools](https://docs.roocode.com/basic-usage/how-to
|
|||
|
||||
MCP extends Roo Code's capabilities by allowing you to add unlimited custom tools. Integrate with external APIs, connect to databases, or create specialized development tools - MCP provides the framework to expand Roo Code's functionality to meet your specific needs.
|
||||
|
||||
### Cloud Integration
|
||||
|
||||
Roo Code offers powerful cloud features for teams:
|
||||
|
||||
- **[Cloud-Synchronized Profiles](docs/CLOUD_INTEGRATION.md#cloud-synchronized-provider-profiles):** Share API configurations across your team
|
||||
- **[Task Sharing](docs/CLOUD_INTEGRATION.md#task-sharing):** Share conversations and results with colleagues
|
||||
- **[Organization Settings](docs/CLOUD_INTEGRATION.md#organization-settings):** Centralized configuration management
|
||||
- **[Task Analytics](docs/CLOUD_INTEGRATION.md#task-lifecycle-events):** Track usage and performance metrics
|
||||
|
||||
See our [Cloud Integration Guide](docs/CLOUD_INTEGRATION.md) and [Quick Start Guide](docs/CLOUD_QUICKSTART.md) for details.
|
||||
|
||||
### Customization
|
||||
|
||||
Make Roo Code work your way with:
|
||||
|
|
|
|||
545
docs/CLOUD_ARCHITECTURE.md
Normal file
545
docs/CLOUD_ARCHITECTURE.md
Normal file
|
|
@ -0,0 +1,545 @@
|
|||
# Roo Code Cloud Integration Architecture
|
||||
|
||||
This document describes the technical architecture of Roo Code's cloud integration features, including design decisions, implementation details, and extension points.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ VS Code Extension │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌─────────────┐ ┌──────────────┐ ┌────────────────────────┐ │
|
||||
│ │ Webview │ │ ClineProvider│ │ WebviewMessageHandler │ │
|
||||
│ │ UI │◄─┤ │◄─┤ │ │
|
||||
│ └─────────────┘ └──────┬───────┘ └────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌─────────────────────┐ │ ┌──────────────────────────────────┐ │
|
||||
│ │ CloudService │◄┴─┤ ProviderSettingsManager │ │
|
||||
│ │ (Singleton) │ │ (Profile Management) │ │
|
||||
│ └──────────┬──────────┘ └──────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌──────────┴──────────┐ ┌──────────────────────────────────┐ │
|
||||
│ │ AuthService │ │ SettingsService │ │
|
||||
│ │ - WebAuthService │ │ - CloudSettingsService │ │
|
||||
│ │ - StaticTokenAuth │ │ - StaticSettingsService │ │
|
||||
│ └─────────────────────┘ └──────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌─────────────────────┐ ┌──────────────────────────────────┐ │
|
||||
│ │ CloudShareService │ │ CloudAPI │ │
|
||||
│ │ (Task Sharing) │───┤ (HTTP Client) │ │
|
||||
│ └─────────────────────┘ └──────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌───────────────────────┐
|
||||
│ Roo Cloud Service │
|
||||
│ (External API) │
|
||||
└───────────────────────┘
|
||||
```
|
||||
|
||||
## Core Components
|
||||
|
||||
### CloudService (Singleton)
|
||||
|
||||
The central orchestrator for all cloud functionality:
|
||||
|
||||
```typescript
|
||||
class CloudService extends EventEmitter<CloudServiceEvents> {
|
||||
private static _instance: CloudService | null = null
|
||||
private authService: AuthService
|
||||
private settingsService: SettingsService
|
||||
private shareService: CloudShareService
|
||||
private cloudAPI: CloudAPI
|
||||
|
||||
// Singleton pattern ensures single instance
|
||||
static async createInstance(context: ExtensionContext): Promise<CloudService>
|
||||
static get instance(): CloudService
|
||||
}
|
||||
```
|
||||
|
||||
**Key Responsibilities:**
|
||||
|
||||
- Manages lifecycle of cloud components
|
||||
- Provides unified API for cloud features
|
||||
- Handles event propagation
|
||||
- Ensures proper initialization order
|
||||
|
||||
### Authentication Layer
|
||||
|
||||
#### AuthService Interface
|
||||
|
||||
```typescript
|
||||
interface AuthService {
|
||||
initialize(): Promise<void>
|
||||
login(): Promise<void>
|
||||
logout(): Promise<void>
|
||||
isAuthenticated(): boolean
|
||||
getUserInfo(): CloudUserInfo | null
|
||||
getSessionToken(): string | null
|
||||
}
|
||||
```
|
||||
|
||||
#### WebAuthService
|
||||
|
||||
Handles browser-based OAuth flow:
|
||||
|
||||
```typescript
|
||||
class WebAuthService implements AuthService {
|
||||
private async startAuthFlow() {
|
||||
// 1. Generate state for CSRF protection
|
||||
// 2. Open browser with auth URL
|
||||
// 3. Start local server to receive callback
|
||||
// 4. Exchange code for tokens
|
||||
// 5. Store tokens securely
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### StaticTokenAuthService
|
||||
|
||||
For CI/CD and automated environments:
|
||||
|
||||
```typescript
|
||||
class StaticTokenAuthService implements AuthService {
|
||||
constructor(token: string) {
|
||||
// Use provided token directly
|
||||
// No browser flow needed
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Settings Synchronization
|
||||
|
||||
#### CloudSettingsService
|
||||
|
||||
Manages real-time settings synchronization:
|
||||
|
||||
```typescript
|
||||
class CloudSettingsService extends EventEmitter {
|
||||
private refreshTimer: RefreshTimer
|
||||
private cachedSettings: OrganizationSettings | null
|
||||
|
||||
async initialize() {
|
||||
// 1. Fetch initial settings
|
||||
// 2. Start refresh timer
|
||||
// 3. Listen for auth changes
|
||||
}
|
||||
|
||||
private async fetchSettings() {
|
||||
// 1. Get auth token
|
||||
// 2. Call API
|
||||
// 3. Validate response
|
||||
// 4. Update cache
|
||||
// 5. Emit change event
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Refresh Strategy:**
|
||||
|
||||
- Initial fetch on authentication
|
||||
- Periodic refresh (configurable interval)
|
||||
- Force refresh on specific events
|
||||
- Exponential backoff on failures
|
||||
|
||||
### Profile Management
|
||||
|
||||
#### ProviderSettingsManager
|
||||
|
||||
Handles the complex merge of cloud and local profiles:
|
||||
|
||||
```typescript
|
||||
class ProviderSettingsManager {
|
||||
async syncCloudProfiles(
|
||||
cloudProfiles: Record<string, ProviderSettings>,
|
||||
currentProfileName?: string,
|
||||
): Promise<SyncResult> {
|
||||
// 1. Load local profiles
|
||||
// 2. Identify cloud-sourced profiles
|
||||
// 3. Merge with conflict resolution
|
||||
// 4. Preserve local-only profiles
|
||||
// 5. Update active profile if needed
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Conflict Resolution:**
|
||||
|
||||
- Cloud profiles take precedence
|
||||
- Local modifications are preserved until next sync
|
||||
- Deleted cloud profiles are removed locally
|
||||
- Local-only profiles are never touched
|
||||
|
||||
### Task Sharing
|
||||
|
||||
#### CloudShareService
|
||||
|
||||
Manages task sharing with clipboard integration:
|
||||
|
||||
```typescript
|
||||
class CloudShareService {
|
||||
async shareTask(taskId: string, visibility: ShareVisibility) {
|
||||
// 1. Call API to create share
|
||||
// 2. Copy URL to clipboard
|
||||
// 3. Return share details
|
||||
}
|
||||
|
||||
async canShareTask(): boolean {
|
||||
// Check organization settings
|
||||
// Verify user permissions
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Share Flow:**
|
||||
|
||||
1. User initiates share
|
||||
2. Task data is already on server (if telemetry enabled)
|
||||
3. Create share record with visibility
|
||||
4. Generate shareable URL
|
||||
5. Auto-copy to clipboard
|
||||
|
||||
### Event System
|
||||
|
||||
#### Task Lifecycle Events
|
||||
|
||||
Events flow through multiple layers:
|
||||
|
||||
```typescript
|
||||
// Task emits event
|
||||
task.emit(RooCodeEventName.TaskCompleted, tokenUsage, toolUsage)
|
||||
|
||||
// ClineProvider proxies to CloudService
|
||||
provider.on(RooCodeEventName.TaskCompleted, (...args) => {
|
||||
CloudService.instance.captureEvent({
|
||||
name: "task_completed",
|
||||
properties: { ...args },
|
||||
})
|
||||
})
|
||||
|
||||
// TelemetryClient sends to cloud
|
||||
telemetryClient.capture(event)
|
||||
```
|
||||
|
||||
**Event Categories:**
|
||||
|
||||
- **Lifecycle**: Created, Started, Completed, Aborted
|
||||
- **State**: Focused, Unfocused, Active, Idle
|
||||
- **Execution**: Message, ModeSwitch, ToolUse
|
||||
- **Analytics**: TokenUsage, ToolFailure
|
||||
|
||||
## Data Flow
|
||||
|
||||
### Profile Synchronization Flow
|
||||
|
||||
```
|
||||
1. User signs in
|
||||
└─> AuthService.login()
|
||||
└─> CloudSettingsService.fetchSettings()
|
||||
└─> ProviderSettingsManager.syncCloudProfiles()
|
||||
└─> ClineProvider.postStateToWebview()
|
||||
└─> UI updates
|
||||
|
||||
2. Admin updates profile
|
||||
└─> Cloud webhook (future)
|
||||
└─> CloudSettingsService.refresh()
|
||||
└─> Same flow as above
|
||||
|
||||
3. User switches profile
|
||||
└─> WebviewMessageHandler.loadApiConfiguration()
|
||||
└─> ProviderSettingsManager.activateProfile()
|
||||
└─> Update global state
|
||||
└─> Update current task API
|
||||
```
|
||||
|
||||
### Task Sharing Flow
|
||||
|
||||
```
|
||||
1. User clicks share
|
||||
└─> WebviewMessageHandler.shareCurrentTask()
|
||||
└─> CloudService.shareTask()
|
||||
├─> CloudAPI.shareTask()
|
||||
│ └─> POST /api/extension/share
|
||||
└─> vscode.env.clipboard.writeText()
|
||||
|
||||
2. If task not found (backfill)
|
||||
└─> TelemetryClient.backfillMessages()
|
||||
└─> Retry share
|
||||
```
|
||||
|
||||
## Security Architecture
|
||||
|
||||
### Authentication Security
|
||||
|
||||
1. **OAuth 2.0 Flow**
|
||||
|
||||
- PKCE for enhanced security
|
||||
- State parameter for CSRF protection
|
||||
- Secure token storage in VS Code
|
||||
|
||||
2. **Token Management**
|
||||
|
||||
- Access tokens with short expiry
|
||||
- Refresh tokens for long-lived sessions
|
||||
- Automatic token refresh
|
||||
|
||||
3. **Static Token Mode**
|
||||
- For CI/CD environments only
|
||||
- Environment variable based
|
||||
- No persistent storage
|
||||
|
||||
### Data Security
|
||||
|
||||
1. **API Communication**
|
||||
|
||||
- HTTPS only
|
||||
- Certificate pinning (future)
|
||||
- Request signing (future)
|
||||
|
||||
2. **Profile Security**
|
||||
|
||||
- API keys never synced
|
||||
- Only configuration synced
|
||||
- Local encryption for sensitive data
|
||||
|
||||
3. **Task Sharing Security**
|
||||
- Visibility controls
|
||||
- Expiration dates
|
||||
- Access logging
|
||||
|
||||
## Extension Points
|
||||
|
||||
### Adding New Cloud Features
|
||||
|
||||
1. **New Service Pattern**
|
||||
|
||||
```typescript
|
||||
class NewCloudService {
|
||||
constructor(
|
||||
private cloudAPI: CloudAPI,
|
||||
private settingsService: SettingsService,
|
||||
) {}
|
||||
|
||||
async initialize() {
|
||||
// Setup logic
|
||||
}
|
||||
|
||||
// Feature methods
|
||||
}
|
||||
```
|
||||
|
||||
2. **Integration Steps**
|
||||
- Add to CloudService initialization
|
||||
- Create message handlers
|
||||
- Update webview communication
|
||||
- Add telemetry events
|
||||
|
||||
### Custom Authentication Providers
|
||||
|
||||
```typescript
|
||||
interface AuthProvider {
|
||||
type: "oauth" | "apikey" | "custom"
|
||||
initialize(): Promise<void>
|
||||
authenticate(): Promise<AuthResult>
|
||||
refresh(): Promise<AuthResult>
|
||||
}
|
||||
```
|
||||
|
||||
### Event Extensions
|
||||
|
||||
```typescript
|
||||
// Define new event
|
||||
enum CustomEventName {
|
||||
CustomAction = "customAction",
|
||||
}
|
||||
|
||||
// Add to event schema
|
||||
const customEventSchema = z.object({
|
||||
[CustomEventName.CustomAction]: z.tuple([
|
||||
z.string(), // taskId
|
||||
z.object({
|
||||
/* payload */
|
||||
}),
|
||||
]),
|
||||
})
|
||||
|
||||
// Emit event
|
||||
task.emit(CustomEventName.CustomAction, taskId, payload)
|
||||
```
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Caching Strategy
|
||||
|
||||
1. **Settings Cache**
|
||||
|
||||
- 5-minute TTL
|
||||
- Force refresh on auth change
|
||||
- Invalidate on error
|
||||
|
||||
2. **Profile Cache**
|
||||
|
||||
- Persistent local storage
|
||||
- Sync on startup
|
||||
- Incremental updates
|
||||
|
||||
3. **API Response Cache**
|
||||
- ETag support
|
||||
- Conditional requests
|
||||
- Bandwidth optimization
|
||||
|
||||
### Optimization Techniques
|
||||
|
||||
1. **Lazy Loading**
|
||||
|
||||
- Cloud features load on demand
|
||||
- Defer non-critical operations
|
||||
- Progressive enhancement
|
||||
|
||||
2. **Batching**
|
||||
|
||||
- Group API requests
|
||||
- Debounce rapid changes
|
||||
- Bulk operations
|
||||
|
||||
3. **Background Sync**
|
||||
- Non-blocking UI updates
|
||||
- Queue offline changes
|
||||
- Retry with backoff
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Error Categories
|
||||
|
||||
1. **Authentication Errors**
|
||||
|
||||
- Token expired
|
||||
- Invalid credentials
|
||||
- Network issues
|
||||
|
||||
2. **API Errors**
|
||||
|
||||
- Rate limiting
|
||||
- Server errors
|
||||
- Validation failures
|
||||
|
||||
3. **Sync Errors**
|
||||
- Conflict resolution
|
||||
- Data corruption
|
||||
- Version mismatch
|
||||
|
||||
### Recovery Strategies
|
||||
|
||||
```typescript
|
||||
class ErrorRecovery {
|
||||
async handleAuthError(error: AuthError) {
|
||||
if (error.code === "TOKEN_EXPIRED") {
|
||||
// Attempt refresh
|
||||
// Fallback to re-login
|
||||
}
|
||||
}
|
||||
|
||||
async handleSyncError(error: SyncError) {
|
||||
if (error.code === "CONFLICT") {
|
||||
// User chooses resolution
|
||||
// Or automatic resolution
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Unit Tests
|
||||
|
||||
```typescript
|
||||
describe("CloudShareService", () => {
|
||||
it("should share task with organization visibility", async () => {
|
||||
// Mock CloudAPI
|
||||
// Test share flow
|
||||
// Verify clipboard
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
### Integration Tests
|
||||
|
||||
```typescript
|
||||
describe("Profile Sync", () => {
|
||||
it("should merge cloud and local profiles", async () => {
|
||||
// Setup test profiles
|
||||
// Trigger sync
|
||||
// Verify merge result
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
### E2E Tests
|
||||
|
||||
```typescript
|
||||
describe("Cloud Features E2E", () => {
|
||||
it("should complete full auth and sync flow", async () => {
|
||||
// Simulate login
|
||||
// Wait for sync
|
||||
// Verify UI state
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Planned Features
|
||||
|
||||
1. **Real-time Collaboration**
|
||||
|
||||
- WebSocket connections
|
||||
- Live task sharing
|
||||
- Collaborative editing
|
||||
|
||||
2. **Advanced Analytics**
|
||||
|
||||
- Custom dashboards
|
||||
- Team metrics
|
||||
- Cost tracking
|
||||
|
||||
3. **Enterprise Features**
|
||||
- SSO integration
|
||||
- Audit logging
|
||||
- Compliance tools
|
||||
|
||||
### Architecture Evolution
|
||||
|
||||
1. **Microservices**
|
||||
|
||||
- Separate auth service
|
||||
- Independent share service
|
||||
- Scalable architecture
|
||||
|
||||
2. **Edge Computing**
|
||||
|
||||
- Regional endpoints
|
||||
- CDN integration
|
||||
- Reduced latency
|
||||
|
||||
3. **Offline Support**
|
||||
- Local queue
|
||||
- Sync on reconnect
|
||||
- Conflict resolution
|
||||
|
||||
## Conclusion
|
||||
|
||||
The cloud integration architecture is designed to be:
|
||||
|
||||
- **Modular**: Easy to extend and maintain
|
||||
- **Secure**: Multiple layers of protection
|
||||
- **Performant**: Optimized for responsiveness
|
||||
- **Reliable**: Graceful error handling
|
||||
- **Scalable**: Ready for growth
|
||||
|
||||
For implementation details, see the source code in:
|
||||
|
||||
- `/packages/cloud/src/`
|
||||
- `/src/core/webview/`
|
||||
- `/packages/types/src/`
|
||||
386
docs/CLOUD_INTEGRATION.md
Normal file
386
docs/CLOUD_INTEGRATION.md
Normal file
|
|
@ -0,0 +1,386 @@
|
|||
# Roo Code Cloud Integration
|
||||
|
||||
This document provides comprehensive information about Roo Code's cloud integration features, including cloud-synchronized provider profiles, task sharing, and enhanced task lifecycle events.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Cloud Authentication](#cloud-authentication)
|
||||
- [Cloud-Synchronized Provider Profiles](#cloud-synchronized-provider-profiles)
|
||||
- [Task Sharing](#task-sharing)
|
||||
- [Task Lifecycle Events](#task-lifecycle-events)
|
||||
- [Configuration](#configuration)
|
||||
- [API Reference](#api-reference)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
|
||||
## Overview
|
||||
|
||||
Roo Code's cloud integration enables teams to collaborate more effectively by providing:
|
||||
|
||||
1. **Cloud-Synchronized Provider Profiles** - Centralized management of API provider configurations across team members
|
||||
2. **Task Sharing** - Share tasks with your organization or publicly with configurable visibility
|
||||
3. **Enhanced Task Lifecycle Events** - Granular tracking of task states for analytics and monitoring
|
||||
4. **Organization Settings** - Centralized configuration management for teams
|
||||
|
||||
## Cloud Authentication
|
||||
|
||||
### Setting Up Authentication
|
||||
|
||||
Roo Code uses web-based authentication for cloud services. To authenticate:
|
||||
|
||||
1. Click on the account button in the Roo Code interface
|
||||
2. Select "Sign in with Roo Cloud"
|
||||
3. Complete the authentication flow in your browser
|
||||
4. Return to VS Code once authenticated
|
||||
|
||||
### Authentication States
|
||||
|
||||
The cloud service tracks several authentication states:
|
||||
|
||||
- **Authenticated** - User is signed in with valid credentials
|
||||
- **Has Active Session** - User has an active session token
|
||||
- **Organization Member** - User belongs to an organization with specific roles
|
||||
|
||||
### Environment Variables
|
||||
|
||||
For automated environments, you can use:
|
||||
|
||||
- `ROO_CODE_CLOUD_TOKEN` - Static authentication token
|
||||
- `ROO_CODE_CLOUD_ORG_SETTINGS` - Static organization settings (JSON format)
|
||||
|
||||
## Cloud-Synchronized Provider Profiles
|
||||
|
||||
### Overview
|
||||
|
||||
Provider profiles allow teams to share API configurations (models, endpoints, settings) across team members. When a profile is updated by an organization admin, all team members automatically receive the updates.
|
||||
|
||||
### How It Works
|
||||
|
||||
1. **Profile Sync on Login** - When you sign in to Roo Cloud, your provider profiles are automatically synchronized
|
||||
2. **Real-time Updates** - Profile changes are propagated to all team members in real-time
|
||||
3. **Local Override** - You can still create local profiles that won't be synchronized
|
||||
|
||||
### Managing Cloud Profiles
|
||||
|
||||
Cloud profiles are managed through the `CloudService` and `ProviderSettingsManager`:
|
||||
|
||||
```typescript
|
||||
// Sync cloud profiles
|
||||
await provider.syncCloudProfiles()
|
||||
|
||||
// The sync process:
|
||||
// 1. Fetches organization settings from cloud
|
||||
// 2. Compares with local profiles
|
||||
// 3. Updates local profiles with cloud changes
|
||||
// 4. Preserves local-only profiles
|
||||
```
|
||||
|
||||
### Profile Structure
|
||||
|
||||
Cloud-synchronized profiles include:
|
||||
|
||||
- API provider type (OpenAI, Anthropic, etc.)
|
||||
- Model configurations
|
||||
- Endpoint URLs
|
||||
- Rate limits and quotas
|
||||
- Custom headers and authentication
|
||||
|
||||
## Task Sharing
|
||||
|
||||
### Overview
|
||||
|
||||
Task sharing allows you to share your Roo Code conversations and results with your team or publicly. This is useful for:
|
||||
|
||||
- Knowledge sharing within teams
|
||||
- Getting help from colleagues
|
||||
- Creating reproducible examples
|
||||
- Building a knowledge base
|
||||
|
||||
### Sharing a Task
|
||||
|
||||
To share a task:
|
||||
|
||||
1. Click the share button in the task interface
|
||||
2. Choose visibility:
|
||||
- **Organization** - Only visible to your organization members
|
||||
- **Public** - Visible to anyone with the link
|
||||
3. The share URL is automatically copied to your clipboard
|
||||
|
||||
### Share Configuration
|
||||
|
||||
Organizations can configure sharing settings:
|
||||
|
||||
```typescript
|
||||
interface OrganizationCloudSettings {
|
||||
recordTaskMessages?: boolean // Enable message recording
|
||||
enableTaskSharing?: boolean // Enable sharing feature
|
||||
taskShareExpirationDays?: number // Auto-expire shared tasks
|
||||
allowMembersViewAllTasks?: boolean // Organization-wide visibility
|
||||
}
|
||||
```
|
||||
|
||||
### API Usage
|
||||
|
||||
```typescript
|
||||
// Share a task programmatically
|
||||
const result = await CloudService.instance.shareTask(
|
||||
taskId,
|
||||
"organization", // or "public"
|
||||
clineMessages, // Optional: backfill messages if needed
|
||||
)
|
||||
|
||||
// Check if sharing is enabled
|
||||
const canShare = await CloudService.instance.canShareTask()
|
||||
```
|
||||
|
||||
## Task Lifecycle Events
|
||||
|
||||
### Overview
|
||||
|
||||
Roo Code tracks detailed task lifecycle events for analytics, monitoring, and debugging purposes. These events provide insights into how tasks progress and where issues might occur.
|
||||
|
||||
### Event Types
|
||||
|
||||
#### Task Provider Lifecycle
|
||||
|
||||
- `taskCreated` - New task instance created
|
||||
|
||||
#### Task Lifecycle
|
||||
|
||||
- `taskStarted` - Task execution begins
|
||||
- `taskCompleted` - Task finishes successfully
|
||||
- `taskAborted` - Task is cancelled by user
|
||||
- `taskFocused` - Task gains focus in UI
|
||||
- `taskUnfocused` - Task loses focus
|
||||
- `taskActive` - Task is actively processing
|
||||
- `taskIdle` - Task is waiting for input
|
||||
|
||||
#### Subtask Lifecycle
|
||||
|
||||
- `taskPaused` - Parent task paused for subtask
|
||||
- `taskUnpaused` - Parent task resumes
|
||||
- `taskSpawned` - New subtask created
|
||||
|
||||
#### Task Execution
|
||||
|
||||
- `message` - New message in conversation
|
||||
- `taskModeSwitched` - Task switches mode (e.g., code to debug)
|
||||
- `taskAskResponded` - User responds to task question
|
||||
|
||||
#### Task Analytics
|
||||
|
||||
- `taskTokenUsageUpdated` - Token usage changes
|
||||
- `taskToolFailed` - Tool execution fails
|
||||
|
||||
### Event Handling
|
||||
|
||||
```typescript
|
||||
// Listen to task events
|
||||
provider.on(RooCodeEventName.TaskCompleted, (taskId, tokenUsage, toolUsage) => {
|
||||
console.log(`Task ${taskId} completed`)
|
||||
console.log(`Tokens used: ${tokenUsage.total}`)
|
||||
console.log(`Tools used: ${Object.keys(toolUsage).join(", ")}`)
|
||||
})
|
||||
|
||||
// Emit custom events
|
||||
task.emit(RooCodeEventName.TaskStarted)
|
||||
```
|
||||
|
||||
### Event Payloads
|
||||
|
||||
Each event includes relevant data:
|
||||
|
||||
```typescript
|
||||
interface TaskCompletedPayload {
|
||||
taskId: string
|
||||
tokenUsage: {
|
||||
input: number
|
||||
output: number
|
||||
total: number
|
||||
}
|
||||
toolUsage: Record<string, number>
|
||||
isSubtask: boolean
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Organization Settings
|
||||
|
||||
Organizations can configure default settings for all members:
|
||||
|
||||
```typescript
|
||||
interface OrganizationSettings {
|
||||
version: number
|
||||
cloudSettings?: OrganizationCloudSettings
|
||||
defaultSettings: OrganizationDefaultSettings
|
||||
allowList: OrganizationAllowList
|
||||
providerProfiles?: Record<string, ProviderSettings>
|
||||
}
|
||||
```
|
||||
|
||||
### Allow Lists
|
||||
|
||||
Control which models and providers team members can use:
|
||||
|
||||
```typescript
|
||||
interface OrganizationAllowList {
|
||||
allowAll: boolean
|
||||
providers: Record<
|
||||
string,
|
||||
{
|
||||
allowAll: boolean
|
||||
models?: string[]
|
||||
}
|
||||
>
|
||||
}
|
||||
```
|
||||
|
||||
### Settings Synchronization
|
||||
|
||||
Settings are synchronized in the following order:
|
||||
|
||||
1. Organization defaults (from cloud)
|
||||
2. User's cloud-synchronized settings
|
||||
3. Local workspace settings
|
||||
4. Local user preferences
|
||||
|
||||
## API Reference
|
||||
|
||||
### CloudService
|
||||
|
||||
The main service for cloud integration:
|
||||
|
||||
```typescript
|
||||
class CloudService {
|
||||
// Authentication
|
||||
async login(): Promise<void>
|
||||
async logout(): Promise<void>
|
||||
isAuthenticated(): boolean
|
||||
getUserInfo(): CloudUserInfo | null
|
||||
|
||||
// Organization
|
||||
getOrganizationId(): string | null
|
||||
getOrganizationName(): string | null
|
||||
getOrganizationRole(): string | null
|
||||
|
||||
// Settings
|
||||
getAllowList(): OrganizationAllowList
|
||||
getOrganizationSettings(): OrganizationSettings | undefined
|
||||
|
||||
// Task Sharing
|
||||
async shareTask(taskId: string, visibility?: ShareVisibility): Promise<ShareResponse>
|
||||
async canShareTask(): Promise<boolean>
|
||||
}
|
||||
```
|
||||
|
||||
### CloudShareService
|
||||
|
||||
Handles task sharing functionality:
|
||||
|
||||
```typescript
|
||||
class CloudShareService {
|
||||
async shareTask(taskId: string, visibility?: ShareVisibility): Promise<ShareResponse>
|
||||
async canShareTask(): Promise<boolean>
|
||||
}
|
||||
```
|
||||
|
||||
### CloudAPI
|
||||
|
||||
Low-level API client:
|
||||
|
||||
```typescript
|
||||
class CloudAPI {
|
||||
async shareTask(taskId: string, visibility?: ShareVisibility): Promise<ShareResponse>
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Authentication Failures
|
||||
|
||||
1. **Token Expired** - Sign out and sign in again
|
||||
2. **Network Issues** - Check your internet connection
|
||||
3. **Organization Not Found** - Verify your organization membership
|
||||
|
||||
#### Profile Sync Issues
|
||||
|
||||
1. **Profiles Not Updating** - Check cloud connection status
|
||||
2. **Conflicts** - Local changes may override cloud settings
|
||||
3. **Missing Profiles** - Ensure you have proper permissions
|
||||
|
||||
#### Task Sharing Problems
|
||||
|
||||
1. **Sharing Disabled** - Check organization settings
|
||||
2. **Task Not Found** - Ensure task was properly recorded
|
||||
3. **Permission Denied** - Verify your organization role
|
||||
|
||||
### Debug Mode
|
||||
|
||||
Enable debug logging for cloud services:
|
||||
|
||||
```typescript
|
||||
// In your VS Code settings
|
||||
{
|
||||
"rooCode.debug.cloudServices": true
|
||||
}
|
||||
```
|
||||
|
||||
### Error Handling
|
||||
|
||||
All cloud operations include proper error handling:
|
||||
|
||||
```typescript
|
||||
try {
|
||||
const result = await CloudService.instance.shareTask(taskId)
|
||||
if (result.success) {
|
||||
console.log("Shared at:", result.shareUrl)
|
||||
}
|
||||
} catch (error) {
|
||||
if (error instanceof AuthenticationError) {
|
||||
// Handle auth errors
|
||||
} else if (error instanceof TaskNotFoundError) {
|
||||
// Handle missing task
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **API Keys** - Never share provider API keys through cloud profiles
|
||||
2. **Sensitive Data** - Be cautious when sharing tasks containing sensitive information
|
||||
3. **Permissions** - Regularly review organization member permissions
|
||||
4. **Expiration** - Set appropriate expiration times for shared tasks
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Profile Management**
|
||||
|
||||
- Use descriptive names for profiles
|
||||
- Document profile purposes
|
||||
- Regularly review and update profiles
|
||||
|
||||
2. **Task Sharing**
|
||||
|
||||
- Review task content before sharing
|
||||
- Use organization visibility for internal discussions
|
||||
- Set expiration for temporary shares
|
||||
|
||||
3. **Event Tracking**
|
||||
- Monitor task completion rates
|
||||
- Track tool usage patterns
|
||||
- Identify common failure points
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
The cloud integration is continuously evolving. Planned features include:
|
||||
|
||||
- Enhanced collaboration tools
|
||||
- Real-time task collaboration
|
||||
- Advanced analytics dashboards
|
||||
- Custom organization workflows
|
||||
- Integration with external services
|
||||
|
||||
For the latest updates, check the [CHANGELOG](../CHANGELOG.md) and join our [Discord community](https://discord.gg/roocode).
|
||||
317
docs/CLOUD_QUICKSTART.md
Normal file
317
docs/CLOUD_QUICKSTART.md
Normal file
|
|
@ -0,0 +1,317 @@
|
|||
# Roo Code Cloud Integration Quick Start Guide
|
||||
|
||||
This guide will help you get started with Roo Code's cloud integration features in just a few minutes.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Roo Code extension installed in VS Code
|
||||
- An active Roo Code account (sign up at [roocode.com](https://roocode.com))
|
||||
- Organization membership (for team features)
|
||||
|
||||
## Step 1: Sign In to Roo Cloud
|
||||
|
||||
1. Open the Roo Code sidebar in VS Code
|
||||
2. Click the **Account** tab
|
||||
3. Click **Sign in with Roo Cloud**
|
||||
4. Complete authentication in your browser
|
||||
5. Return to VS Code when prompted
|
||||
|
||||
You should now see your user information in the Account tab.
|
||||
|
||||
## Step 2: Enable Cloud Features
|
||||
|
||||
Cloud features are enabled by default once you're signed in. You can verify this by checking:
|
||||
|
||||
```json
|
||||
// In VS Code settings (settings.json)
|
||||
{
|
||||
"rooCode.cloud.enabled": true,
|
||||
"rooCode.cloud.syncProfiles": true,
|
||||
"rooCode.cloud.enableSharing": true
|
||||
}
|
||||
```
|
||||
|
||||
## Step 3: Using Cloud-Synchronized Profiles
|
||||
|
||||
### View Available Profiles
|
||||
|
||||
1. Go to the **Settings** tab in Roo Code
|
||||
2. Look for the **API Configuration** section
|
||||
3. Cloud-synchronized profiles will have a cloud icon ☁️
|
||||
|
||||
### Switch Between Profiles
|
||||
|
||||
```typescript
|
||||
// Profiles are automatically synchronized
|
||||
// Just select from the dropdown in Settings
|
||||
```
|
||||
|
||||
### Create a Team Profile (Admins Only)
|
||||
|
||||
1. Create a new profile in Settings
|
||||
2. Configure your API provider and model
|
||||
3. Save with a descriptive name
|
||||
4. It will automatically sync to team members
|
||||
|
||||
## Step 4: Sharing Tasks
|
||||
|
||||
### Share Your Current Task
|
||||
|
||||
1. Complete or pause your current task
|
||||
2. Click the **Share** button (↗️) in the task interface
|
||||
3. Choose visibility:
|
||||
- **Organization** - Only your team can access
|
||||
- **Public** - Anyone with the link can view
|
||||
|
||||
### What Gets Shared
|
||||
|
||||
- Complete conversation history
|
||||
- Code changes and outputs
|
||||
- Tool usage and results
|
||||
- Task metadata (duration, tokens used)
|
||||
|
||||
### Share Link Format
|
||||
|
||||
```
|
||||
https://share.roocode.com/task/[task-id]
|
||||
```
|
||||
|
||||
The link is automatically copied to your clipboard!
|
||||
|
||||
## Step 5: Monitoring Task Events
|
||||
|
||||
### View Task Analytics
|
||||
|
||||
Task events are automatically tracked. You can:
|
||||
|
||||
1. See task completion status
|
||||
2. Monitor token usage
|
||||
3. Track tool execution
|
||||
4. Identify performance patterns
|
||||
|
||||
### Common Events to Monitor
|
||||
|
||||
```typescript
|
||||
// Task started
|
||||
RooCodeEventName.TaskStarted
|
||||
|
||||
// Task completed with metrics
|
||||
RooCodeEventName.TaskCompleted
|
||||
// Payload: { taskId, tokenUsage, toolUsage }
|
||||
|
||||
// Mode switches
|
||||
RooCodeEventName.TaskModeSwitched
|
||||
// Payload: { taskId, newMode }
|
||||
|
||||
// Tool failures
|
||||
RooCodeEventName.TaskToolFailed
|
||||
// Payload: { taskId, tool, error }
|
||||
```
|
||||
|
||||
## Step 6: Organization Settings
|
||||
|
||||
### For Organization Admins
|
||||
|
||||
Configure team-wide settings:
|
||||
|
||||
```typescript
|
||||
{
|
||||
"cloudSettings": {
|
||||
"enableTaskSharing": true,
|
||||
"taskShareExpirationDays": 30,
|
||||
"allowMembersViewAllTasks": false
|
||||
},
|
||||
"allowList": {
|
||||
"allowAll": false,
|
||||
"providers": {
|
||||
"openai": {
|
||||
"allowAll": false,
|
||||
"models": ["gpt-4", "gpt-3.5-turbo"]
|
||||
},
|
||||
"anthropic": {
|
||||
"allowAll": true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### For Team Members
|
||||
|
||||
Your available models and features are controlled by your organization admin. Contact them if you need access to specific models or features.
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
### 1. Team Knowledge Sharing
|
||||
|
||||
Share successful task completions with your team:
|
||||
|
||||
```typescript
|
||||
// After completing a complex refactoring
|
||||
// Click Share → Organization
|
||||
// Post link in team chat with context
|
||||
```
|
||||
|
||||
### 2. Getting Help
|
||||
|
||||
Share a stuck task with colleagues:
|
||||
|
||||
```typescript
|
||||
// When encountering an issue
|
||||
// Click Share → Organization
|
||||
// Ask for help with the share link
|
||||
```
|
||||
|
||||
### 3. Building Examples
|
||||
|
||||
Create public examples for documentation:
|
||||
|
||||
```typescript
|
||||
// Complete a demonstration task
|
||||
// Click Share → Public
|
||||
// Include link in documentation
|
||||
```
|
||||
|
||||
### 4. Standardizing Configurations
|
||||
|
||||
Admins can create standard profiles:
|
||||
|
||||
- "Production API" - Rate-limited, specific models
|
||||
- "Development API" - More permissive settings
|
||||
- "Testing API" - Optimized for speed/cost
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Not Seeing Cloud Features?
|
||||
|
||||
1. Ensure you're signed in (check Account tab)
|
||||
2. Verify organization membership
|
||||
3. Check with your admin for permissions
|
||||
|
||||
### Profiles Not Syncing?
|
||||
|
||||
1. Sign out and sign back in
|
||||
2. Check internet connection
|
||||
3. Verify organization settings
|
||||
|
||||
### Can't Share Tasks?
|
||||
|
||||
1. Check if sharing is enabled by your org
|
||||
2. Ensure task has completed or paused
|
||||
3. Verify you have sharing permissions
|
||||
|
||||
### Getting Authentication Errors?
|
||||
|
||||
1. Your session may have expired
|
||||
2. Sign out completely
|
||||
3. Clear VS Code credentials
|
||||
4. Sign in again
|
||||
|
||||
## Best Practices
|
||||
|
||||
### For Individual Users
|
||||
|
||||
1. **Review Before Sharing** - Check for sensitive data
|
||||
2. **Use Descriptive Names** - Help others understand shared tasks
|
||||
3. **Set Context** - Add comments explaining your approach
|
||||
4. **Clean Up** - Delete old shared tasks periodically
|
||||
|
||||
### for Teams
|
||||
|
||||
1. **Standardize Profiles** - Use consistent naming
|
||||
2. **Document Profiles** - Explain when to use each
|
||||
3. **Monitor Usage** - Track token consumption
|
||||
4. **Regular Reviews** - Update allowed models
|
||||
|
||||
### For Admins
|
||||
|
||||
1. **Start Restrictive** - Add permissions as needed
|
||||
2. **Communicate Changes** - Notify team of updates
|
||||
3. **Monitor Costs** - Track API usage by profile
|
||||
4. **Security First** - Never share API keys
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Programmatic Access
|
||||
|
||||
```typescript
|
||||
import { CloudService } from "@roo-code/cloud"
|
||||
|
||||
// Check authentication
|
||||
if (CloudService.instance.isAuthenticated()) {
|
||||
// Get user info
|
||||
const user = CloudService.instance.getUserInfo()
|
||||
|
||||
// Share a task
|
||||
const result = await CloudService.instance.shareTask(taskId, "organization")
|
||||
|
||||
console.log("Shared at:", result.shareUrl)
|
||||
}
|
||||
```
|
||||
|
||||
### Event Subscriptions
|
||||
|
||||
```typescript
|
||||
// Subscribe to task events
|
||||
provider.on(RooCodeEventName.TaskCompleted, (taskId, usage) => {
|
||||
// Send to analytics
|
||||
analytics.track("task_completed", {
|
||||
taskId,
|
||||
tokens: usage.total,
|
||||
duration: Date.now() - startTime,
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
### Custom Integrations
|
||||
|
||||
```typescript
|
||||
// Integrate with your tools
|
||||
class CustomIntegration {
|
||||
async onTaskShared(shareUrl: string) {
|
||||
// Post to Slack
|
||||
await slack.postMessage({
|
||||
text: `New Roo Code task shared: ${shareUrl}`,
|
||||
})
|
||||
|
||||
// Log to internal system
|
||||
await internalApi.logShare({
|
||||
url: shareUrl,
|
||||
user: CloudService.instance.getUserInfo(),
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Security Notes
|
||||
|
||||
1. **Never share tasks containing**:
|
||||
|
||||
- API keys or secrets
|
||||
- Personal information
|
||||
- Proprietary code (unless intended)
|
||||
- Security vulnerabilities
|
||||
|
||||
2. **Always verify** share visibility before sharing
|
||||
|
||||
3. **Use organization sharing** for internal work
|
||||
|
||||
4. **Set expiration** for temporary shares
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Documentation**: [docs.roocode.com](https://docs.roocode.com)
|
||||
- **Discord Community**: [discord.gg/roocode](https://discord.gg/roocode)
|
||||
- **GitHub Issues**: [Report bugs or request features](https://github.com/RooCodeInc/Roo-Code/issues)
|
||||
- **Email Support**: support@roocode.com
|
||||
|
||||
## Next Steps
|
||||
|
||||
Now that you're set up with cloud features:
|
||||
|
||||
1. Try sharing your first task
|
||||
2. Explore different provider profiles
|
||||
3. Monitor your task analytics
|
||||
4. Join our Discord to share experiences
|
||||
|
||||
Happy coding with Roo Code Cloud! 🚀
|
||||
Loading…
Add table
Reference in a new issue