Review: fix(mcp): reliable MCP→Agent UI session activation + error normalization

Request changes. The SSE activation design is clean and the error-scrubbing intent is right, but two changes regress behavior the PR didn't exercise: the relaxed URL-nav guard in App.tsx looks like it will fight (and likely ping-pong) manual session switches, and the new error envelope silently breaks two internal callers in agent_ui_mcp.py that still key on "error". Both live on the exact untested path the PR's own "frontend switch note" flags. Worth fixing before merge; neither is large.

Issues

🟡 Relaxed nav guard fights manual session switches (App.tsx:295-320)

Removing if (currentSessionId) return makes this effect re-run on every currentSessionId change, and the replacement guard if (target === currentSessionId) return never short-circuits for the app's own URLs: the hash-update effect writes a 7-char short hash (getSessionHash, format.ts:32), so target is "a1b2c3d" while currentSessionId is the full UUID — never equal.

Because this effect is declared before the hash-update effect (App.tsx:362), on each switch it reads the stale window.location.hash (previous session) and schedules a 500ms setCurrentSession back to it. So switching A→B schedules a bounce to A; when that fires it reads B's now-stale hash and schedules back to B — a perpetual ~500ms ping-pong. I couldn't drive a real 2-session browser switch to confirm the loop vs. a single bounce, but the stale-read is certain. Fix the guard to compare on the same representation:

        const target = sessionParam || hashParam;
        if (!target) return;
        // Already on this session — hash is a short hash, not the full id
        if (target === currentSessionId || target === getSessionHash(currentSessionId)) return;

Please verify with an actual A→B sidebar switch (hash present) before merge.

🟡 New error envelope breaks two internal callers (agent_ui_mcp.py:296, 366)

_normalize_error returns {"status": "error", "detail": ...} — no "error" key — but callers still test the old shape:

• get_messages (:296): if "error" in data is now always false on a normalized error, so a 404 / backend-down falls through to data.get("messages", []) and returns {"messages": [], "total": 0}. That's a silent fallback (CLAUDE.md "No Silent Fallbacks") — an error reported as an empty session.
• index_document (:366): if "error" not in attach_result is now always true on a failed link, so it sets result["linked_to_session"] and reports success when the attach actually failed; the warning branch is dead.

        if data.get("status") == "error":
            return data

and at :366, switch to attach_result.get("status") != "error" (and log attach_result.get("detail")).

🟢 Envelope isn't actually unified — delete_session (:288), screenshot tools (:460, :521) still return {"error": ...}. The PR says "all tool errors share one structured envelope"; today it's mixed. Either route those through _normalize_error too, or narrow the claim.

🟢 emit_set_active_session has no caller (sse_handler.py:187) — dead shim. Fine to land if a follow-up uses it, but flag it as intentionally-unused or drop it.

🟢 App.test.tsx tests are tautological — expect('GAIA Agent UI').toBe('GAIA Agent UI') and string .toContain('#') checks never render App or exercise the nav guard / SSE handler, so they assert nothing about the code they're named for. A real render test of the guard would have caught the issue above. The Python TestNormalizeError cases, by contrast, are solid.

Strengths

• Clean SSE activation design: fan-out _SystemSseEmitter with bounded queues + drop-on-full, 30s keepalive against proxy timeouts, and exponential-backoff reconnect on the client. /api/sessions/events is correctly declared before /api/sessions/{session_id} so it isn't captured as a session id, and activate_session 404s on an unknown id rather than emitting blindly.
• Centralized error scrubbing removes internal-URL leaks from the HTTP/connection paths, with focused unit tests proving it.
• Honest docstring fix — send_message no longer overpromises real-time render and points callers at open_session_in_browser().

Verdict

Request changes — the two 🟡 items are on the primary MCP→UI flow this PR exists to make reliable, and both are small, well-scoped fixes. Re-verify the A→B session switch in a real browser once the guard is corrected.

🔴 App.tsx:295–320 — SSE activation causes infinite session oscillation

The navigation guard now has currentSessionId in its deps and the old short-circuit (if (currentSessionId) return) is gone. When the SSE handler fires setCurrentSession(B), the guard re-runs, reads window.location.hash (still #A — the hash-update effect hasn't run yet in the same batch), sees A ≠ B, and schedules a 500 ms timer to switch back to A. 500 ms later it switches to A; the guard re-runs, reads #B (set by the hash-update effect after the previous switch), schedules a switch to B — and the sessions oscillate forever. This directly breaks the MCP activation path this PR is trying to fix.

Fix: sync the hash before triggering the React re-render so the guard sees the new session ID on the next run:

                    if (data.type === 'set_active_session' && data.session_id) {
                        log.nav.info(`MCP activate session: ${data.session_id}`);
+                       window.history.replaceState(null, '', `#${data.session_id}`);
                        setCurrentSession(data.session_id);
                        setMessages([]);
                    }

window.history.replaceState is synchronous, so when the navigation guard re-runs after the render it reads the already-updated hash, finds target === currentSessionId, and exits immediately.

🟡 src/gaia/apps/webui/src/__tests__/App.test.tsx — every test checks only literal values; no App.tsx code is ever called.

// This will always pass regardless of what App.tsx does:
it('title is GAIA Agent UI', () => {
    const expectedTitle = 'GAIA Agent UI';
    expect(expectedTitle).toBe('GAIA Agent UI'); // literal == literal
});

// Same problem — creates a plain object, never imports App.tsx:
it('set_active_session event shape matches contract', () => {
    const event = { type: 'set_active_session', session_id: 'test-123' };
    expect(event.type).toBe('set_active_session'); // trivially true
});

The new useEffect SSE loop in App.tsx (EventSource setup, reconnect backoff, setCurrentSession/setMessages dispatch) has zero real test coverage. A regression there — wrong URL, missing session_id guard, backoff overflow — won't be caught. Consider a @testing-library/react test that mounts App with a mocked EventSource, fires a set_active_session message, and asserts setCurrentSession was called with the right ID.

Everything else in the diff (error normalisation, SSE emitter, hash URL routing, lazy FastMCP import) looks correct.

Fixed the failing Unit Tests (all 4 platforms) in 3f5edd6.

Root cause: the new tests/unit/test_agent_ui_mcp.py errored at import (ModuleNotFoundError: No module named 'mcp') because agent_ui_mcp imported FastMCP at module level, and the unit-test job does not install the optional mcp extra.

Fix: import FastMCP lazily inside create_agent_ui_mcp() so the pure helpers (_normalize_error/_api/_stream_chat) import without mcp, and guard the two server-constructing tests with pytest.importorskip("mcp"). CI-simulated locally with mcp blocked → 5 passed, 2 skipped, 0 failed.

🟡 agent_ui_mcp.py:768 — activate fires before the duplicate-tab guard, so repeated calls to open_session_in_browser for the same already-open session still emit the SSE event. In App.tsx the handler calls setMessages([]) unconditionally, which wipes visible messages with no guaranteed reload (because setCurrentSession to an already-current ID may not re-fetch).

# sessions.py – fire activate only when we're actually going to switch tabs
        # Skip opening a duplicate tab for the same URL.
        if _last_opened_url["url"] == target_url:
            return {"opened": False, "url": target_url, "note": "Already open in browser"}

        # Signal the frontend only when a real navigation is about to happen.
        _api(backend_url, "post", f"/sessions/{session_id}/activate")

Or guard in App.tsx before calling setMessages:

if (data.type === 'set_active_session' && data.session_id && data.session_id !== currentSessionId) {
    setCurrentSession(data.session_id);
    setMessages([]);
}

Either fix works; both together is safest.

🔴 agent_ui_mcp.py — error-key mismatch breaks get_messages and index_document

_normalize_error now returns {"status": "error", "detail": "..."}, but two callers still check for the old "error" key:

Line 299 — get_messages silently swallows backend errors:

data = _api(backend_url, "get", f"/sessions/{session_id}/messages")
if "error" in data:   # ← never true with the new shape
    return data
# falls through to data.get("messages", []) → returns [] on error

Lines 369/376 — index_document falsely reports success when attach_document fails:

if "error" not in attach_result:   # ← always True now
    result["linked_to_session"] = session_id  # set even on failure
else:
    logger.warning(..., attach_result.get("error"))  # dead branch

Fix — update both callers to the new key:

# line 299
if data.get("status") == "error":

# line 369
if attach_result.get("status") != "error":

# line 376
attach_result.get("detail")

Post-merge follow-up: this PR merged before the review feedback landed, so the findings are addressed in #1756 (→ #1755):

• 🔴 Session oscillation — the URL-nav guard now responds only to external navigation (initial load + hashchange/popstate), so it can no longer fight a programmatic switch. Verified live: manual A→B and MCP-activate switches both settle and stay put (no ping-pong).
• Silent fallback / false success — get_messages and index_document now read the {"status":"error"} envelope, so backend errors surface instead of returning an empty session / a false link-success.
• Envelope unified across delete_session + screenshot tools; open_session_in_browser activates only after the duplicate-tab guard and surfaces activate failures; dead emit_set_active_session shim dropped; App.test.tsx replaced with real resolveUrlNavTarget unit tests (incl. the short-hash same-session case that caused the bounce).

Thanks @kovtcharov-amd and the reviewer for the catches.