global-notifications

Global notifications (cross-surface / cross-tab alerts)

Echo has two kinds of alerts that must reach the user even when they are NOT looking at the affected chat tab or surface. Session-scoped session_events (tool_call with status: awaiting_input, etc.) are only broadcast to clients subscribed to that workspace+surface+active tab, so they CANNOT be used for global alerts. Instead Echo uses global Hub broadcasts + frontend listener modules.

The chat-completion pattern (model to copy)

• Backend (internal/server/chat_sessions.go): on turn finish with status == "done", call s.manager.server.hub.Broadcast(chatCompletedMessage{...}) with type: "chat_completed", workspaceId, workspaceName, surface (chat|code), chatId, turnId, preview. Hub.Broadcast (in ws.go) fans out to all clients (no subscription needed).
• Frontend (web/src/completionNotifications.ts, started in web/js/app.js bootstrap via startCompletionNotifications()): listens ws.on("chat_completed", ...), plays notification-1.wav sound, and shows a browser Notification. Clicking it does window.location.hash = chatCompletionRouteHash({workspaceId, chatId, surface}), which deep-links to the exact chat tab. Tab activation is already handled: home.js (chat surface) and codeView.ts (code surface, ?chat=open) read chatCompletionTargetFromHash and call activateChatTab/expectedChatId + onExpectedChatResolved.
• chatCompletionRouteHash/chatCompletionTargetFromHash live in web/src/navigation.ts.

Plan-question notifications (mirrors the completion pattern)

When a Plan-mode ask_user_questions call starts awaiting input:

• Backend chat_sessions.go (~line 2103) broadcasts planQuestionsMessage with type: "plan_questions_awaiting" + the same target metadata (workspaceId, workspaceName, surface, chatId, turnId, callId) plus questions (array of {id, question, options}). This is additive; the session-scoped tool_call event remains for the active-view rendering.
• Frontend web/src/planQuestionNotifications.ts (started via startPlanQuestionNotifications() in app.js) listens ws.on("plan_questions_awaiting", ...), plays the question sound (delegated to playPlanQuestionSound()), and shows a notification. Clicking deep-links via chatCompletionRouteHash like completions.