[backend] refactor: route web chat through GatewayRunner pipeline for parity with Telegram/Slack/Discord

[Interstellar-code]

Problem

The Web UI chat currently uses a separate, thin code path (ApiServerAdapter._handle_chat_completions() → _create_agent() → agent.run_conversation()) that bypasses the full gateway pipeline used by all messaging platforms (Telegram, Slack, Discord).

This means the Web UI is missing critical infrastructure that messaging platforms get for free:

Capability	Telegram	Slack/Discord	Web UI
Persistent sessions (auto-reset, expiry)	✅	✅	⚠️ opt-in only
Session context injection	✅ rich	✅ rich	❌ none
Session hygiene (auto-compress oversized transcripts)	✅	✅	❌
Plugin hooks (pre_gateway_dispatch)	✅	✅	❌
Auto-skills (topic/channel bindings)	✅	✅	❌
Command handling (/stop, /new, /steer, /queue)	✅	✅	❌
Interrupt support	✅	✅	❌
Agent caching (LRU + idle TTL warm starts)	✅	✅	❌ fresh per request
Provider routing (allow/ignore/order/sort)	✅	✅	⚠️ basic
Typing indicators	✅	✅	❌

Architecture

Current: Two Separate Paths

Web UI:
  POST /v1/chat/completions
    → ApiServerAdapter._handle_chat_completions()
      → _create_agent() [separate, thin]
      → _run_agent()
        → agent.run_conversation()
      ← JSON/SSE response

Telegram/Slack/Discord:
  Platform SDK event
    → PlatformAdapter._handle_*_message()
      → _build_message_event()
      → self.handle_message(event)
        → BasePlatformAdapter.handle_message()
          → _process_message_background()
            → GatewayRunner._handle_message()
              ┌─────────────────────────────────────────┐
              │ FULL GATEWAY PIPELINE                   │
              │ • Auth / pairing                        │
              │ • Session persistence                   │
              │ • build_session_context()               │
              │ • Plugin hooks                          │
              │ • Auto-skills                           │
              │ • Session hygiene (auto-compression)    │
              │ • Vision enrichment                     │
              │ • _run_agent() with agent caching       │
              │ • run_conversation()                    │
              └─────────────────────────────────────────┘
            ← agent_result
            → Response delivery (platform-specific)

Proposed: Shared Pipeline, Forked Delivery

All paths:
  → GatewayRunner._handle_message()
    → [full gateway pipeline]
    ← agent_result

Delivery (platform-specific):
  Telegram → MarkdownV2, chunking, typing, media extraction
  Slack    → Block Kit, threads, reactions
  Web UI   → SSE stream, JSON, no formatting/chunking

Implementation Plan

Phase 1: Route Web Chat Through Gateway Pipeline

File: hermes-agent/gateway/platforms/api_server.py

The /api/sessions/{id}/chat/stream endpoint should:

1. Build a MessageEvent from the web chat request (mapping session headers to SessionSource)
2. Route it through self.handle_message(event) like other platform adapters
3. Let the gateway pipeline handle session management, context injection, hygiene, etc.
4. Capture the agent result and stream it back as SSE

# Current (thin path):
agent = self._create_agent(ephemeral_system_prompt=system_prompt, session_id=session_id)
result = await self._run_agent(user_message=user_message, ...)

# Proposed (gateway path):
event = self._build_message_event(session_id, user_message, system_prompt, ...)
await self.handle_message(event)  # → full gateway pipeline
# → SSE events from streaming callbacks

Phase 2: SessionSource Mapping

Map web UI headers to SessionSource:

• X-Hermes-Session-Id → session_id
• X-Hermes-Session-Key → stable memory scope key
• Platform = "switchui" (new value) or reuse "api_server"

Phase 3: Platform Toolsets Config

Add platform_toolsets.switchui to config.yaml so the web chat has its own toolset configuration, matching the pattern used by platform_toolsets.telegram.

Phase 4: Streaming Callbacks Through Gateway Path

Ensure stream_delta_callback, tool_start_callback, and tool_complete_callback are wired into the agent when dispatched through handle_message(), so SSE events still flow to the Web UI.

Phase 5: Override Delivery Tail

The Web UI delivery differs from messaging platforms:

• No MarkdownV2 conversion (Web UI renders its own markdown)
• No message chunking
• No MEDIA:<path> extraction (handled differently)
• No typing indicators (Web UI has its own loading state)
• JSON/SSE response format

This can be achieved by:

• The web endpoint providing its own _message_handler callback
• Or by detecting platform="switchui" and skipping platform-specific formatting

Expected Benefits

After implementation, Web UI chat will immediately gain:

1. Warm agent starts — LRU cache with idle TTL (no cold start per request)
2. Session context — "You are on Switch UI. User: Rohit..." injected into system prompt
3. Auto-compression — sessions that grow too large get compressed at 85% threshold
4. Plugin hooks — full pre_gateway_dispatch plugin chain
5. Interrupt support — /stop and agent interruption work
6. Provider routing — per-session model/provider routing applies
7. Auto-skills — topic/channel skill bindings work if configured
8. Session hygiene — consistent with messaging platforms

Acceptance Criteria

• Web chat routes through GatewayRunner._handle_message()
• Session context is injected (platform, user, workspace)
• Agent caching works (warm starts, not fresh per request)
• Session hygiene auto-compresses oversized transcripts
• SSE streaming still works for tool events and token deltas
• /stop and interrupt work from the Web UI
• No regression in existing Web UI functionality
• /v1/chat/completions (OpenAI-compatible) continues to work as-is for external clients

Notes

• The /v1/chat/completions endpoint (OpenAI-compatible API) should remain unchanged — it serves external clients that expect the OpenAI protocol
• The /api/sessions/{id}/chat/stream endpoint (used by Switch UI) is the one to refactor
• The gateway pipeline was designed to be platform-agnostic above the delivery layer; the API server just never connected to it
• This is primarily a gateway-side change; minimal changes needed in the Switch UI frontend

Related Code

• Thin path (to be replaced): hermes-agent/gateway/platforms/api_server.py → _handle_chat_completions(), _create_agent(), _run_agent()
• Full pipeline (to be reused): hermes-agent/gateway/run.py → _handle_message(), _handle_message_with_agent(), _run_agent()
• Base adapter (routing): hermes-agent/gateway/platforms/base.py → handle_message(), _process_message_background()
• Telegram adapter (reference): hermes-agent/gateway/platforms/telegram.py → _handle_text_message(), _build_message_event()

[Interstellar-code]

Investigation Update (2026-06-06) — SSE Stream & Dashboard Audit

Ran a focused study triggered by the dashboard embedded chat changes (commit 33ff71cdf, Jun 4: always-on PTY chat). Key findings that impact this refactor:

✅ SSE Stream Already Emits Tool Events Live

Tested against the live gateway (POST /api/sessions/{id}/chat/stream on :8642). The SSE stream now emits:

event: tool.started    ← tool_name, preview, args
event: tool.completed  ← tool_name, preview, args  
event: tool.progress   ← reasoning/thinking (tool_name="_thinking")

This is confirmed working on the current thin path (_handle_session_chat_stream → _tool_progress callback). The old "callback signature drift" comment in SwitchUI send-stream.ts is outdated — the drift has been fixed upstream.

Implication for Phase 4: The streaming callback wiring already works on the thin path. The tool_progress_callback parameter flows through _create_agent() → AIAgent() correctly. The question is whether it survives the transition through GatewayRunner._handle_message(). Verify during implementation — _run_agent() accepts the callback and GatewayRunner already passes it for other platforms.

🗑️ SwitchUI Can Remove 800ms Synthetic Tool Polling

send-stream.ts lines 897–975 maintain a background poller that queries GET /api/sessions/{id}/messages every 800ms and synthesizes tool events from message data. This was a workaround for missing live tool events (comment: "vanilla Hermes Agent currently does not emit tool.* SSE events live — callback signature drift").

Since the SSE stream now emits tool.started, tool.completed, tool.progress live, the polling loop is dead code. ~100–150 lines can be removed from send-stream.ts once this refactor is complete. The SSE event handler at lines 1114–1200+ already handles these exact event names and shapes — no frontend changes needed.

❌ Dashboard Does NOT Proxy Chat REST

Audited all routes on the dashboard (port 9119). It has session CRUD (GET/DELETE) but zero routes for /api/sessions/{id}/chat or /chat/stream. The dashboard chat mechanism is PTY-based terminal emulation (/api/pty WebSocket → spawns hermes --tui in xterm.js) — not a REST API the SwitchUI can piggyback on.

Current architecture is correct and should stay:

• CLAUDE_API → :8642 (gateway) — for streamChat() SSE
• CLAUDE_DASHBOARD_URL → :9119 (dashboard) — for sessions/config/skills/cron

No consolidation opportunity on the dashboard side. The refactor should remain focused on the gateway api_server.py side.

🔍 Event Payload Shapes (for Phase 4 reference)

Captured from live stream against current thin path:

// tool.started
{"message_id": "msg_...", "tool_name": "search_files",
 "preview": "*", "args": {"pattern": "*", "target": "files", ...},
 "session_id": "api_...", "run_id": "run_...", "seq": 3, "ts": 1780728157.0}

// tool.completed
{"message_id": "msg_...", "tool_name": "search_files",
 "preview": null, "args": null,
 "session_id": "api_...", "run_id": "run_...", "seq": 4, "ts": 1780728157.2}

// tool.progress (reasoning)
{"message_id": "msg_...", "tool_name": "_thinking",
 "delta": "Let me think about...",
 "session_id": "api_...", "run_id": "run_...", "seq": 5, "ts": 1780728157.5}

The SwitchUI send-stream.ts SSE handler (lines 1114–1200+) already parses these exact event names and shapes.