Feat/observability

[JamesRobert20]

Description

This PR implements a comprehensive observability feature for Zoo Code, enabling authenticated users with active subscriptions to log LLM request telemetry to the Zoo Code backend. The implementation includes:

Key Implementation Details

1. Zoo Code Authentication Service (src/services/zoo-code-auth.ts)

• OAuth-style authentication flow with callback URI handling
• Secure token storage using VS Code's SecretStorage API
• In-memory caching for synchronous access in hot paths (avoiding async overhead during API requests)
• User profile storage (name, email, avatar image)
• Subscription status checking with 5-minute cache to minimize API calls
• Token validation and revocation endpoints

2. LLM Telemetry Service (src/services/zoo-telemetry.ts)

• Fire-and-forget telemetry that never impacts user experience
• Only sends data for authenticated users with active subscriptions
• Captures: task ID, provider, model, mode, token usage (input/output/cache), and cost
• Silently handles all errors to prevent disruption

3. Authentication UI Badge (webview-ui/src/components/chat/ZooCodeAuthBadge.tsx)

• Circular avatar button displayed in chat text area
• Shows user avatar image (with fallback to initials)
• Deterministic color generation based on email/name
• Popover with sign-in, dashboard link, and sign-out options
• VSCode-native styling with proper hover states

4. Type Extensions (packages/types/src/vscode-extension-host.ts)

• New ExtensionState fields: zooCodeIsAuthenticated, zooCodeUserName, zooCodeUserEmail, zooCodeUserImage
• New WebviewMessage type: zooCodeSignOut

Design Choices & Trade-offs

• In-memory Token Caching: The auth token is cached in memory after initialization to allow synchronous access in the Task class hot path, avoiding async overhead during LLM request processing
• 5-minute Subscription Cache: Balances API load reduction with reasonably fresh subscription status
• Dynamic Imports: Telemetry calls use import() to avoid loading unnecessary code paths for users who aren't authenticated
• Fire-and-Forget Pattern: Telemetry errors are silently caught to ensure observability never degrades user experience
• Token Prefix Validation: Tokens must start with zoo_ext_ to prevent accidental misuse of other credentials

Roadmap Alignment

This PR aligns with the Reliability First roadmap goal by:

• Enabling observability into LLM usage patterns for debugging and optimization
• Implementing robust error handling that never impacts user workflows
• Supporting the expansion of AI provider ecosystem through usage insights

Test Procedure

Unit Tests

The PR includes comprehensive unit tests in src/services/__tests__/zoo-code-auth.test.ts:

cd src && npx vitest run services/__tests__/zoo-code-auth.test.ts

Test Coverage:

• getCachedSubscriptionStatus - Initial state verification
• checkSubscriptionStatus - API responses (active/inactive/error/timeout)
• getCachedZooCodeToken - Token caching behavior
• setZooCodeToken - Subscription status reset on token change
• clearZooCodeToken - Cleanup and state reset
• getZooCodeBaseUrl - Configuration and environment variable handling

Manual Testing Steps

1. Authentication Flow:

   • Open Zoo Code extension
   • Click the person icon in the chat text area
   • Click "Sign in to Zoo Code"
   • Complete OAuth flow on zoocode.dev
   • Verify callback redirects back to VS Code
   • Confirm avatar/initials appear in the badge

2. Telemetry Verification:

   • Authenticate as a subscriber
   • Send a chat message to trigger LLM request
   • Check Zoo Code dashboard for telemetry events
   • Verify token usage and cost data accuracy

3. Sign Out Flow:

   • Click the auth badge
   • Select "Sign out"
   • Verify badge returns to unauthenticated state
   • Confirm telemetry stops being sent

4. Error Handling:

   • Test with invalid/expired token
   • Test with network disconnection
   • Verify no user-facing errors appear

Documentation Updates

• No documentation updates are required.
• Yes, documentation updates are required:
  • Update user guide to explain Zoo Code observability feature
  • Document the authentication flow and what data is collected
  • Add privacy notice about telemetry data handling

Additional Notes

Files Changed Summary

File	Changes
packages/types/src/vscode-extension-host.ts	+5 lines - New state types for Zoo Code auth
src/activate/handleUri.ts	+29 lines - Auth callback handler for /auth-callback path
src/core/task/Task.ts	+19 lines - Telemetry call after task completion
src/core/webview/ClineProvider.ts	+36 lines - Auth methods and state management
src/core/webview/webviewMessageHandler.ts	+12 lines - Sign out message handler
src/extension.ts	+4 lines - Initialize Zoo Code auth service
src/services/__tests__/zoo-code-auth.test.ts	+234 lines - Comprehensive unit tests
src/services/zoo-code-auth.ts	+273 lines - Core authentication service
src/services/zoo-telemetry.ts	+61 lines - Telemetry service
webview-ui/src/components/chat/ChatTextArea.tsx	+2 lines - Add auth badge to UI
webview-ui/src/components/chat/ZooCodeAuthBadge.tsx	+201 lines - Auth badge React component
webview-ui/src/oauth/urls.ts	+10 lines - Zoo Code auth URL generator

Total: 12 files changed, +887 lines

Security Considerations

• Tokens are stored in VS Code's encrypted SecretStorage API
• Token prefix validation (zoo_ext_) prevents credential misuse
• Token revocation on sign-out clears both local and server-side session
• No sensitive data logged to console or telemetry

API Endpoints Used

Endpoint	Purpose
GET /api/subscription/status	Check subscription status
POST /api/extension/auth/verify	Validate token authenticity
POST /api/extension/auth/revoke	Revoke token on sign-out
POST /api/observability/events	Submit telemetry data

Interactively review PR in Roo Code Cloud