🏗️ Architecture: How to fix agent visibility in VSCode extension and support ...

Date: 2026-02-05
Time: 13:21:47 UTC
Session: editor2-91.7
Agent: backend
Confidence: 92%
Status: ✅ Documented

📋 Decision Context

Question:

How to fix agent visibility in VSCode extension and support external connectors?

Task: Session 91.3 - Fix Agent Visibility & Superpower Infrastructure

🎯 Decision Made

Chosen:

6-phase approach: add vscode to platform enum, rewrite GET /ai-api/mcp/agents to query MongoDB for live agents + return static experts, add MCP JSON-RPC heartbeat refresh, update extension data flow for split agent types, build two-section Agents UI with YOU badge, and surface real-time WebSocket agent events

Options Considered:

• No alternatives documented

💭 Reasoning

Root cause was that GET /ai-api/mcp/agents returned 7 hardcoded expert agents instead of querying MongoDB for live agents. The unified endpoint now returns both liveAgents (from MongoDB) and expertAgents (static catalog). Added 'vscode' to platform enum since it was missing. MCP JSON-RPC clients (Claude Desktop) were going stale after 120s due to no heartbeat mechanism - added heartbeat refresh on tools/call and tools/list. WebSocket agent events were silently logged - now surfaced in real-time to the UI.

📁 Files Involved

• apis/backend-ai-api/src/app/schemas/agent-registry.schema.ts
• apis/backend-ai-api/src/app/infrastructure/services/agent.service.ts
• apis/backend-ai-api/src/app/mcp-gateway/mcp-gateway.controller.ts
• apis/backend-ai-api/src/app/mcp-gateway/mcp-jsonrpc.controller.ts
• apis/backend-ai-api/src/app/mcp-gateway/native-ws.gateway.ts
• apps/vscode-gograb-ai/src/services/mcp-client.service.ts
• apps/vscode-gograb-ai/src/panels/main-panel.ts
• apps/vscode-gograb-ai/src/panels/webview/types.ts
• apps/vscode-gograb-ai/src/panels/webview/state.ts
• apps/vscode-gograb-ai/src/panels/webview/api.ts
• apps/vscode-gograb-ai/src/panels/webview/components/agents/agents-view.ts
• apps/vscode-gograb-ai/src/services/websocket.service.ts
• apps/vscode-gograb-ai/src/services/types.ts

🔗 Related

• Decision ID: dev_1770297706951_mlvk58n
• Session: 91
• Workspace: editor2

Auto-generated by MCP Smart Consolidation