🏗️ Architecture: How should the 5 critical UX/performance/session issues be s...

Date: 2026-03-28
Time: 16:14:34 UTC
Session: gspace1-284.5
Agent: backend
Confidence: 95%
Status: ✅ Documented

📋 Decision Context

Question:

How should the 5 critical UX/performance/session issues be solved in the VSCode extension?

Task: S284: Fix 5 critical UX/performance/session issues in VSCode extension

🎯 Decision Made

Chosen:

5 interconnected fixes: (1) retainContextWhenHidden: true — single line that prevents VS Code from destroying the webview DOM on tab switch. Root cause of both state loss and reload delays. (2) sendLightweightRefresh — only syncs connection status + IDE context when panel becomes visible again, instead of blasting empty arrays + 4 API calls. (3) Cloud session backed by existing backend conversation history — no new endpoints needed since agent-session already persists to MongoDB. Extension sends sessionId on every message, backend links history automatically. (4) Tool capabilities already correct — extension advertises 7 IDE tools for local execution, backend provides all 30+ tools server-side (web_search, browser_*, memory, etc.) via ToolRegistryService. No change needed. (5) Vitto personality via GET /engine/mind/brief/me + GET /engine/mood/me — parallel fetch on connect, populates personalized greeting, mood-aware avatar, and context-aware suggestions from user brief.

Options Considered:

1. Use VSCode setState/getState for manual serialization (rejected: retainContextWhenHidden is simpler and keeps live DOM state)
2. Build new session history GET endpoint (rejected: backend already persists via agentSessions)
3. Add server-side tools to extension's tools array (rejected: backend already provides them independently)
4. Inline personality data in system prompt only (rejected: user-facing greeting and suggestions need frontend integration too)

💭 Reasoning

Root cause analysis: The state loss (#1) and performance (#2) issues share a single root cause — missing retainContextWhenHidden. Without it, VS Code destroys and recreates the entire webview DOM on every tab switch. This is a documented VS Code API behavior, not a framework bug. The fix is one line. The sendInitialState method then compounds the problem by blasting the webview with empty state arrays and running 4 parallel API calls on every visibility change, causing visible loading delays. The lightweight refresh pattern (only push connection status + IDE context) is the correct optimization when the DOM is retained. For #3 (sessions), the backend already persists conversation history per sessionId — the extension just needs to maintain stable sessionIds. For #4 (tools), investigation revealed that the extension's tools array only controls IDE delegation; server-side tools are provided independently by ToolRegistryService. No change needed. For #5 (personality), the backend has established /engine/mind/brief/:userId and /engine/mood/:userId endpoints that return user context, mood, and recent topics — exactly what the empty state and suggestions need.

📁 Files Involved

• apps/vitto-vscode-extension/src/panels/main-panel.ts
• apps/vitto-vscode-extension/src/panels/webview/components/agent/agent-chat-view.ts
• apps/vitto-vscode-extension/src/panels/webview/types.ts

🔗 Related

• Decision ID: dev_1774714474270_va6m6kl
• Session: 284
• Workspace: gspace1

Auto-generated by MCP Smart Consolidation