🏗️ Architecture: How to enable native WebSocket connectivity for Chrome MV3 a...

Date: 2026-01-30
Time: 13:06:37 UTC
Session: editor2-75.2
Agent: backend
Confidence: 90%
Status: ✅ Documented

📋 Decision Context

Question:

How to enable native WebSocket connectivity for Chrome MV3 and VSCode extensions that cannot use socket.io-client?

Task: Not specified

🎯 Decision Made

Chosen:

WebSocket Protocol Adapter (Option E) - Created native-ws.gateway.ts that runs alongside Socket.io on /ws endpoint

Options Considered:

1. Option A: Add native WS alongside Socket.io (duplication)
2. Option B: HTTP long-polling fallback (poor UX)
3. Option C: Replace Socket.io everywhere (risky rewrite)
4. Option D: Socket.io + EventSource hybrid (inconsistent)
5. Option E: WebSocket Protocol Adapter (CHOSEN)

💭 Reasoning

Session 74 used Socket.io (/mcp-stream) which works great for Angular apps but Chrome MV3 service workers and VSCode extensions cannot use socket.io-client due to platform limitations. Rather than replacing Socket.io (risky rewrite) or duplicating all logic, we created a Protocol Adapter that: 1) Accepts native WebSocket connections on /ws path with query-param auth, 2) Translates JSON messages to the same internal event handlers, 3) Bridges events to/from Socket.io gateway, 4) Shares AgentService for single source of truth in MongoDB. Angular/Flutter can continue using Socket.io for its superior features (auto-reconnect, rooms, fallback), while Chrome/VSCode/CLI tools use /ws.

📁 Files Involved

• apis/backend-ai-api/src/app/mcp-gateway/native-ws.gateway.ts
• apis/backend-ai-api/src/app/mcp-gateway/mcp-gateway.module.ts
• apis/backend-ai-api/src/main.ts
• apps/gograb-ai-extension/background/mcp-connector.js
• apps/vscode-gograb-ai/src/agent-status.ts

🔗 Related

• Decision ID: dev_1769778397254_5hc3ewc
• Session: 75
• Workspace: editor2

Auto-generated by MCP Smart Consolidation