From b4a278eb1a924517cedd7264a1a2fc408ed02e2c Mon Sep 17 00:00:00 2001 From: Roo Code Date: Sat, 2 Aug 2025 23:45:58 +0000 Subject: [PATCH] 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. --- README.md | 11 + docs/CLOUD_ARCHITECTURE.md | 545 +++++++++++++++++++++++++++++++++++++ docs/CLOUD_INTEGRATION.md | 386 ++++++++++++++++++++++++++ docs/CLOUD_QUICKSTART.md | 317 +++++++++++++++++++++ 4 files changed, 1259 insertions(+) create mode 100644 docs/CLOUD_ARCHITECTURE.md create mode 100644 docs/CLOUD_INTEGRATION.md create mode 100644 docs/CLOUD_QUICKSTART.md diff --git a/README.md b/README.md index 08f8f81806..d8a9baa76e 100644 --- a/README.md +++ b/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: diff --git a/docs/CLOUD_ARCHITECTURE.md b/docs/CLOUD_ARCHITECTURE.md new file mode 100644 index 0000000000..7d08e36f4f --- /dev/null +++ b/docs/CLOUD_ARCHITECTURE.md @@ -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 { + 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 + 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 + login(): Promise + logout(): Promise + 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, + currentProfileName?: string, + ): Promise { + // 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 + authenticate(): Promise + refresh(): Promise +} +``` + +### 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/` diff --git a/docs/CLOUD_INTEGRATION.md b/docs/CLOUD_INTEGRATION.md new file mode 100644 index 0000000000..019b13d7b3 --- /dev/null +++ b/docs/CLOUD_INTEGRATION.md @@ -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 + 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 +} +``` + +### 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 + async logout(): Promise + 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 + async canShareTask(): Promise +} +``` + +### CloudShareService + +Handles task sharing functionality: + +```typescript +class CloudShareService { + async shareTask(taskId: string, visibility?: ShareVisibility): Promise + async canShareTask(): Promise +} +``` + +### CloudAPI + +Low-level API client: + +```typescript +class CloudAPI { + async shareTask(taskId: string, visibility?: ShareVisibility): Promise +} +``` + +## 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). diff --git a/docs/CLOUD_QUICKSTART.md b/docs/CLOUD_QUICKSTART.md new file mode 100644 index 0000000000..58ac02f8bd --- /dev/null +++ b/docs/CLOUD_QUICKSTART.md @@ -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! 🚀