feat: per-session WebSocket architecture for parallel chat sessions

Each session now owns its own useAgentChat + WebSocket transport instead
of sharing a single instance. Background sessions process all events
(including approval_required) continuously, fixing the bug where
approvals from non-active sessions were silently dropped.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

backend/models.py

@@ -61,6 +61,14 @@ class SessionResponse(BaseModel):
     ready: bool = True
 
 
+class PendingApprovalTool(BaseModel):
+    """A tool waiting for user approval."""
+
+    tool: str
+    tool_call_id: str
+    arguments: dict[str, Any] = {}
+
+
 class SessionInfo(BaseModel):
     """Session metadata."""
 
@@ -69,6 +77,7 @@ class SessionInfo(BaseModel):
     is_active: bool
     message_count: int
     user_id: str = "dev"
+    pending_approval: list[PendingApprovalTool] | None = None
 
 
 class HealthResponse(BaseModel):

backend/session_manager.py

@@ -344,12 +344,30 @@ class SessionManager:
         if not agent_session:
             return None
 
+        # Extract pending approval tools if any
+        pending_approval = None
+        pa = agent_session.session.pending_approval
+        if pa and pa.get("tool_calls"):
+            pending_approval = []
+            for tc in pa["tool_calls"]:
+                import json
+                try:
+                    args = json.loads(tc.function.arguments)
+                except (json.JSONDecodeError, AttributeError):
+                    args = {}
+                pending_approval.append({
+                    "tool": tc.function.name,
+                    "tool_call_id": tc.id,
+                    "arguments": args,
+                })
+
         return {
             "session_id": session_id,
             "created_at": agent_session.created_at.isoformat(),
             "is_active": agent_session.is_active,
             "message_count": len(agent_session.session.context_manager.items),
             "user_id": agent_session.user_id,
+            "pending_approval": pending_approval,
         }
 
     def list_sessions(self, user_id: str | None = None) -> list[dict[str, Any]]:

frontend/src/components/Layout/AppLayout.tsx

@@ -16,32 +16,29 @@ import ChevronLeftIcon from '@mui/icons-material/ChevronLeft';
 import DragIndicatorIcon from '@mui/icons-material/DragIndicator';
 import DarkModeOutlinedIcon from '@mui/icons-material/DarkModeOutlined';
 import LightModeOutlinedIcon from '@mui/icons-material/LightModeOutlined';
-import { logger } from '@/utils/logger';
 
 import { useSessionStore } from '@/store/sessionStore';
 import { useAgentStore } from '@/store/agentStore';
 import { useLayoutStore } from '@/store/layoutStore';
-import { useAgentChat } from '@/hooks/useAgentChat';
 import SessionSidebar from '@/components/SessionSidebar/SessionSidebar';
+import SessionChat from '@/components/SessionChat';
 import CodePanel from '@/components/CodePanel/CodePanel';
-import ChatInput from '@/components/Chat/ChatInput';
-import MessageList from '@/components/Chat/MessageList';
 import WelcomeScreen from '@/components/WelcomeScreen/WelcomeScreen';
 import { apiFetch } from '@/utils/api';
 
 const DRAWER_WIDTH = 260;
 
 export default function AppLayout() {
-  const { sessions, activeSessionId, deleteSession, updateSessionTitle } = useSessionStore();
-  const { isConnected, isProcessing, setProcessing, activityStatus, llmHealthError, setLlmHealthError, user } = useAgentStore();
-  const { 
-    isLeftSidebarOpen, 
-    isRightPanelOpen, 
+  const { sessions, activeSessionId, deleteSession } = useSessionStore();
+  const { isConnected, llmHealthError, setLlmHealthError, user } = useAgentStore();
+  const {
+    isLeftSidebarOpen,
+    isRightPanelOpen,
     rightPanelWidth,
     themeMode,
     setRightPanelWidth,
     setLeftSidebarOpen,
-    toggleLeftSidebar, 
+    toggleLeftSidebar,
     toggleTheme,
   } = useLayoutStore();
 
@@ -85,7 +82,7 @@ export default function AppLayout() {
     };
   }, [handleMouseMove, stopResizing]);
 
-  // ── LLM health check on mount ───────────────────────────────────
+  // -- LLM health check on mount -----------------------------------------
   useEffect(() => {
     let cancelled = false;
     (async () => {
@@ -102,7 +99,7 @@ export default function AppLayout() {
           setLlmHealthError(null);
         }
       } catch {
-        // Backend unreachable — not an LLM issue, ignore
+        // Backend unreachable -- not an LLM issue, ignore
       }
     })();
     return () => { cancelled = true; };
@@ -110,19 +107,9 @@ export default function AppLayout() {
 
   const hasAnySessions = sessions.length > 0;
 
-  const { messages, sendMessage, stop, undoLastTurn, approveTools, flushMessages } = useAgentChat({
-    sessionId: activeSessionId,
-    onReady: () => logger.log('Agent ready'),
-    onError: (error) => logger.error('Agent error:', error),
-    onSessionDead: (deadSessionId) => {
-      logger.log('Removing dead session:', deadSessionId);
-      deleteSession(deadSessionId);
-    },
-  });
-
-  // Debounced "session expired" toast — only fires after 2s of sustained disconnect
+  // Debounced "session expired" toast
   useEffect(() => {
-    if (!isConnected && messages.length > 0 && activeSessionId) {
+    if (!isConnected && activeSessionId) {
       disconnectTimer.current = setTimeout(() => setShowExpiredToast(true), 2000);
     } else {
       if (disconnectTimer.current) clearTimeout(disconnectTimer.current);
@@ -132,34 +119,13 @@ export default function AppLayout() {
     return () => {
       if (disconnectTimer.current) clearTimeout(disconnectTimer.current);
     };
-  }, [isConnected, messages.length, activeSessionId]);
-
-  const handleSendMessage = useCallback(
-    async (text: string) => {
-      if (!activeSessionId || !text.trim() || isProcessing) return;
-
-      setProcessing(true);
-      sendMessage({ text: text.trim(), metadata: { createdAt: new Date().toISOString() } });
+  }, [isConnected, activeSessionId]);
 
-      // Auto-title the session from the first user message (async, non-blocking)
-      const isFirstMessage = messages.filter((m) => m.role === 'user').length <= 1;
-      if (isFirstMessage) {
-        const sessionId = activeSessionId;
-        apiFetch('/api/title', {
-          method: 'POST',
-          body: JSON.stringify({ session_id: sessionId, text: text.trim() }),
-        })
-          .then((res) => res.json())
-          .then((data) => {
-            if (data.title) updateSessionTitle(sessionId, data.title);
-          })
-          .catch(() => {
-            const raw = text.trim();
-            updateSessionTitle(sessionId, raw.length > 40 ? raw.slice(0, 40) + '…' : raw);
-          });
-      }
+  const handleSessionDead = useCallback(
+    (deadSessionId: string) => {
+      deleteSession(deadSessionId);
     },
-    [activeSessionId, sendMessage, messages, updateSessionTitle, isProcessing, setProcessing],
+    [deleteSession],
   );
 
   // Close sidebar on mobile after selecting a session
@@ -167,7 +133,7 @@ export default function AppLayout() {
     if (isMobile) setLeftSidebarOpen(false);
   }, [isMobile, setLeftSidebarOpen]);
 
-  // ── LLM error toast helper ──────────────────────────────────────────
+  // -- LLM error toast helper --------------------------------------------
   const llmErrorTitle = llmHealthError
     ? llmHealthError.errorType === 'credits'
       ? 'API Credits Exhausted'
@@ -180,7 +146,7 @@ export default function AppLayout() {
       : 'LLM Error'
     : '';
 
-  // ── Welcome screen: no sessions at all ────────────────────────────
+  // -- Welcome screen: no sessions at all ---------------------------------
   if (!hasAnySessions) {
     return (
       <Box sx={{ width: '100%', height: '100%', display: 'flex', flexDirection: 'column' }}>
@@ -189,14 +155,14 @@ export default function AppLayout() {
     );
   }
 
-  // ── Sidebar drawer ────────────────────────────────────────────────
+  // -- Sidebar drawer -----------------------------------------------------
   const sidebarDrawer = (
     <Drawer
       variant={isMobile ? 'temporary' : 'persistent'}
       anchor="left"
       open={isLeftSidebarOpen}
       onClose={() => setLeftSidebarOpen(false)}
-      ModalProps={{ keepMounted: true }} // Better mobile perf
+      ModalProps={{ keepMounted: true }}
       sx={{
         '& .MuiDrawer-paper': {
           boxSizing: 'border-box',
@@ -209,19 +175,17 @@ export default function AppLayout() {
         },
       }}
     >
-      <SessionSidebar onClose={handleSidebarClose} onBeforeSwitch={flushMessages} />
+      <SessionSidebar onClose={handleSidebarClose} />
     </Drawer>
   );
 
-  // ── Main chat interface ───────────────────────────────────────────
+  // -- Main chat interface ------------------------------------------------
   return (
     <Box sx={{ display: 'flex', width: '100%', height: '100%' }}>
-      {/* ── Left Sidebar ─────────────────────────────────────────── */}
+      {/* -- Left Sidebar ------------------------------------------------- */}
       {isMobile ? (
-        // Mobile: temporary overlay drawer (no reserved width)
         sidebarDrawer
       ) : (
-        // Desktop: persistent drawer with reserved width
         <Box
           component="nav"
           sx={{
@@ -235,7 +199,7 @@ export default function AppLayout() {
         </Box>
       )}
 
-      {/* ── Main Content (header + chat + code panel) ────────────── */}
+      {/* -- Main Content (header + chat + code panel) -------------------- */}
       <Box
         sx={{
           flexGrow: 1,
@@ -247,13 +211,13 @@ export default function AppLayout() {
           minWidth: 0,
         }}
       >
-        {/* ── Top Header Bar ─────────────────────────────────────── */}
-        <Box sx={{ 
+        {/* -- Top Header Bar --------------------------------------------- */}
+        <Box sx={{
           height: { xs: 52, md: 60 },
-          px: { xs: 1, md: 2 }, 
-          display: 'flex', 
-          alignItems: 'center', 
-          borderBottom: 1, 
+          px: { xs: 1, md: 2 },
+          display: 'flex',
+          alignItems: 'center',
+          borderBottom: 1,
           borderColor: 'divider',
           bgcolor: 'background.default',
           zIndex: 1200,
@@ -262,7 +226,7 @@ export default function AppLayout() {
           <IconButton onClick={toggleLeftSidebar} size="small">
             {isLeftSidebarOpen && !isMobile ? <ChevronLeftIcon /> : <MenuIcon />}
           </IconButton>
-          
+
           <Box sx={{ flex: 1, display: 'flex', justifyContent: 'center', alignItems: 'center', gap: 0.75 }}>
             <Box
               component="img"
@@ -318,7 +282,7 @@ export default function AppLayout() {
           </Box>
         </Box>
 
-        {/* ── Chat + Code Panel ──────────────────────────────────── */}
+        {/* -- Chat + Code Panel ------------------------------------------ */}
         <Box
           sx={{
             flexGrow: 1,
@@ -341,16 +305,16 @@ export default function AppLayout() {
             }}
           >
             {activeSessionId ? (
-              <>
-                <MessageList messages={messages} isProcessing={isProcessing} approveTools={approveTools} onUndoLastTurn={undoLastTurn} />
-                <ChatInput
-                  onSend={handleSendMessage}
-                  onStop={stop}
-                  isProcessing={isProcessing}
-                  disabled={!isConnected || activityStatus.type === 'waiting-approval'}
-                  placeholder={activityStatus.type === 'waiting-approval' ? 'Approve or reject pending tools first...' : undefined}
+              // Render ALL sessions — each owns its own useAgentChat.
+              // Only the active one renders visible UI (others return null).
+              sessions.map((s) => (
+                <SessionChat
+                  key={s.id}
+                  sessionId={s.id}
+                  isActive={s.id === activeSessionId}
+                  onSessionDead={handleSessionDead}
                 />
-              </>
+              ))
             ) : (
               <Box
                 sx={{
@@ -373,7 +337,7 @@ export default function AppLayout() {
             )}
           </Box>
 
-          {/* Code panel — inline on desktop, overlay drawer on mobile */}
+          {/* Code panel -- inline on desktop, overlay drawer on mobile */}
           {isRightPanelOpen && !isMobile && (
             <>
               <Box
@@ -390,8 +354,8 @@ export default function AppLayout() {
                   '&:hover': { bgcolor: 'primary.main' },
                 }}
               >
-                <DragIndicatorIcon 
-                  sx={{ fontSize: '0.8rem', color: 'text.secondary', pointerEvents: 'none' }} 
+                <DragIndicatorIcon
+                  sx={{ fontSize: '0.8rem', color: 'text.secondary', pointerEvents: 'none' }}
                 />
               </Box>
               <Box
@@ -412,7 +376,7 @@ export default function AppLayout() {
         </Box>
       </Box>
 
-      {/* Code panel — drawer overlay on mobile */}
+      {/* Code panel -- drawer overlay on mobile */}
       {isMobile && (
         <Drawer
           anchor="bottom"

frontend/src/components/SessionChat.tsx

@@ -0,0 +1,140 @@
+/**
+ * Per-session chat component.
+ *
+ * Each session renders its own SessionChat. The hook (useAgentChat) always
+ * runs — keeping the WebSocket alive and processing events — but only the
+ * active session renders visible UI (MessageList + ChatInput).
+ */
+import { useCallback, useEffect, useRef } from 'react';
+import { useAgentChat } from '@/hooks/useAgentChat';
+import { useAgentStore } from '@/store/agentStore';
+import { useSessionStore } from '@/store/sessionStore';
+import { useLayoutStore } from '@/store/layoutStore';
+import MessageList from '@/components/Chat/MessageList';
+import ChatInput from '@/components/Chat/ChatInput';
+import { apiFetch } from '@/utils/api';
+import { logger } from '@/utils/logger';
+
+interface SessionChatProps {
+  sessionId: string;
+  isActive: boolean;
+  onSessionDead: (sessionId: string) => void;
+}
+
+export default function SessionChat({ sessionId, isActive, onSessionDead }: SessionChatProps) {
+  const { isConnected, isProcessing, setProcessing, activityStatus } = useAgentStore();
+  const { updateSessionTitle } = useSessionStore();
+
+  const { messages, sendMessage, stop, undoLastTurn, approveTools, transport } = useAgentChat({
+    sessionId,
+    isActive,
+    onReady: () => logger.log(`Session ${sessionId} ready`),
+    onError: (error) => logger.error(`Session ${sessionId} error:`, error),
+    onSessionDead,
+  });
+
+  // When this session becomes active, sync ALL global agentStore state
+  // so the UI correctly reflects this session's current state.
+  const prevActiveRef = useRef(isActive);
+  useEffect(() => {
+    if (isActive && !prevActiveRef.current) {
+      const store = useAgentStore.getState();
+
+      // Sync WebSocket connection state
+      const wsConnected = transport?.isWebSocketConnected() ?? false;
+      store.setConnected(wsConnected);
+
+      // Check if this session has pending approvals in its messages
+      const lastAssistant = [...messages].reverse().find(m => m.role === 'assistant');
+      const hasPendingApproval = lastAssistant?.parts.some(
+        (p) => p.type === 'dynamic-tool' && p.state === 'approval-requested'
+      ) ?? false;
+
+      if (hasPendingApproval) {
+        store.setActivityStatus({ type: 'waiting-approval' });
+        store.setProcessing(false);
+
+        // Restore panel for the first pending tool
+        const pendingTool = lastAssistant!.parts.find(
+          (p) => p.type === 'dynamic-tool' && p.state === 'approval-requested'
+        );
+        if (pendingTool && pendingTool.type === 'dynamic-tool') {
+          const args = pendingTool.input as Record<string, string | undefined>;
+          if (pendingTool.toolName === 'hf_jobs' && args?.script) {
+            store.setPanel(
+              { title: 'Script', script: { content: args.script, language: 'python' }, parameters: pendingTool.input as Record<string, unknown> },
+              'script',
+              true,
+            );
+          } else if (pendingTool.toolName === 'hf_repo_files' && args?.content) {
+            const filename = args.path || 'file';
+            store.setPanel({
+              title: filename.split('/').pop() || 'Content',
+              script: { content: args.content, language: filename.endsWith('.py') ? 'python' : 'text' },
+              parameters: pendingTool.input as Record<string, unknown>,
+            });
+          } else {
+            store.setPanel({
+              title: pendingTool.toolName,
+              output: { content: JSON.stringify(pendingTool.input, null, 2), language: 'json' },
+            }, 'output');
+          }
+          useLayoutStore.getState().setRightPanelOpen(true);
+        }
+      } else {
+        // No pending approval — reset to idle
+        store.setActivityStatus({ type: 'idle' });
+        store.setProcessing(false);
+      }
+    }
+    prevActiveRef.current = isActive;
+  }, [isActive, messages, transport]);
+
+  const handleSendMessage = useCallback(
+    async (text: string) => {
+      if (!text.trim() || isProcessing) return;
+
+      setProcessing(true);
+      sendMessage({ text: text.trim(), metadata: { createdAt: new Date().toISOString() } });
+
+      // Auto-title the session from the first user message
+      const isFirstMessage = messages.filter((m) => m.role === 'user').length <= 1;
+      if (isFirstMessage) {
+        apiFetch('/api/title', {
+          method: 'POST',
+          body: JSON.stringify({ session_id: sessionId, text: text.trim() }),
+        })
+          .then((res) => res.json())
+          .then((data) => {
+            if (data.title) updateSessionTitle(sessionId, data.title);
+          })
+          .catch(() => {
+            const raw = text.trim();
+            updateSessionTitle(sessionId, raw.length > 40 ? raw.slice(0, 40) + '\u2026' : raw);
+          });
+      }
+    },
+    [sessionId, sendMessage, messages, updateSessionTitle, isProcessing, setProcessing],
+  );
+
+  // Don't render UI for background sessions — hooks still run
+  if (!isActive) return null;
+
+  return (
+    <>
+      <MessageList
+        messages={messages}
+        isProcessing={isProcessing}
+        approveTools={approveTools}
+        onUndoLastTurn={undoLastTurn}
+      />
+      <ChatInput
+        onSend={handleSendMessage}
+        onStop={stop}
+        isProcessing={isProcessing}
+        disabled={!isConnected || activityStatus.type === 'waiting-approval'}
+        placeholder={activityStatus.type === 'waiting-approval' ? 'Approve or reject pending tools first...' : undefined}
+      />
+    </>
+  );
+}

frontend/src/components/SessionSidebar/SessionSidebar.tsx

@@ -16,7 +16,6 @@ import { apiFetch } from '@/utils/api';
 
 interface SessionSidebarProps {
   onClose?: () => void;
-  onBeforeSwitch?: () => void;
 }
 
 /** Small coloured dot for connection status */
@@ -33,7 +32,7 @@ const StatusDot = ({ connected }: { connected: boolean }) => (
   />
 );
 
-export default function SessionSidebar({ onClose, onBeforeSwitch }: SessionSidebarProps) {
+export default function SessionSidebar({ onClose }: SessionSidebarProps) {
   const { sessions, activeSessionId, createSession, deleteSession, switchSession } =
     useSessionStore();
   const { isConnected, setPlan, clearPanel } =
@@ -41,11 +40,10 @@ export default function SessionSidebar({ onClose, onBeforeSwitch }: SessionSideb
   const [isCreatingSession, setIsCreatingSession] = useState(false);
   const [capacityError, setCapacityError] = useState<string | null>(null);
 
-  // ── Handlers ──────────────────────────────────────────────────────
+  // -- Handlers -----------------------------------------------------------
 
   const handleNewSession = useCallback(async () => {
     if (isCreatingSession) return;
-    onBeforeSwitch?.();
     setIsCreatingSession(true);
     setCapacityError(null);
     try {
@@ -65,7 +63,7 @@ export default function SessionSidebar({ onClose, onBeforeSwitch }: SessionSideb
     } finally {
       setIsCreatingSession(false);
     }
-  }, [isCreatingSession, onBeforeSwitch, createSession, setPlan, clearPanel, onClose]);
+  }, [isCreatingSession, createSession, setPlan, clearPanel, onClose]);
 
   const handleDelete = useCallback(
     async (sessionId: string, e: React.MouseEvent) => {
@@ -74,7 +72,6 @@ export default function SessionSidebar({ onClose, onBeforeSwitch }: SessionSideb
         await apiFetch(`/api/session/${sessionId}`, { method: 'DELETE' });
         deleteSession(sessionId);
       } catch {
-        // Delete locally even if backend fails (session may already be gone)
         deleteSession(sessionId);
       }
     },
@@ -83,19 +80,18 @@ export default function SessionSidebar({ onClose, onBeforeSwitch }: SessionSideb
 
   const handleSelect = useCallback(
     (sessionId: string) => {
-      onBeforeSwitch?.();
       switchSession(sessionId);
       setPlan([]);
       clearPanel();
       onClose?.();
     },
-    [onBeforeSwitch, switchSession, setPlan, clearPanel, onClose],
+    [switchSession, setPlan, clearPanel, onClose],
   );
 
   const formatTime = (d: string) =>
     new Date(d).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' });
 
-  // ── Render ────────────────────────────────────────────────────────
+  // -- Render -------------------------------------------------------------
 
   return (
     <Box
@@ -106,7 +102,7 @@ export default function SessionSidebar({ onClose, onBeforeSwitch }: SessionSideb
         bgcolor: 'var(--panel)',
       }}
     >
-      {/* ── Header ─────────────────────────────────────────────────── */}
+      {/* -- Header -------------------------------------------------------- */}
       <Box sx={{ px: 1.75, pt: 2, pb: 0 }}>
         <Typography
           variant="caption"
@@ -122,7 +118,7 @@ export default function SessionSidebar({ onClose, onBeforeSwitch }: SessionSideb
         </Typography>
       </Box>
 
-      {/* ── Capacity error ─────────────────────────────────────────── */}
+      {/* -- Capacity error ------------------------------------------------ */}
       {capacityError && (
         <Alert
           severity="warning"
@@ -141,13 +137,12 @@ export default function SessionSidebar({ onClose, onBeforeSwitch }: SessionSideb
         </Alert>
       )}
 
-      {/* ── Session list ───────────────────────────────────────────── */}
+      {/* -- Session list -------------------------------------------------- */}
       <Box
         sx={{
           flex: 1,
           overflow: 'auto',
           py: 1,
-          // Thinner scrollbar
           '&::-webkit-scrollbar': { width: 4 },
           '&::-webkit-scrollbar-thumb': {
             bgcolor: 'var(--scrollbar-thumb)',
@@ -253,6 +248,24 @@ export default function SessionSidebar({ onClose, onBeforeSwitch }: SessionSideb
                   </Typography>
                 </Box>
 
+                {/* Attention badge — pulsing dot when background session needs approval */}
+                {session.needsAttention && !isSelected && (
+                  <Box
+                    sx={{
+                      width: 8,
+                      height: 8,
+                      borderRadius: '50%',
+                      bgcolor: 'var(--accent-yellow)',
+                      flexShrink: 0,
+                      animation: 'pulse 2s ease-in-out infinite',
+                      '@keyframes pulse': {
+                        '0%, 100%': { opacity: 1, transform: 'scale(1)' },
+                        '50%': { opacity: 0.5, transform: 'scale(0.8)' },
+                      },
+                    }}
+                  />
+                )}
+
                 <IconButton
                   className="delete-btn"
                   size="small"
@@ -273,7 +286,7 @@ export default function SessionSidebar({ onClose, onBeforeSwitch }: SessionSideb
         )}
       </Box>
 
-      {/* ── Footer: New Task + status ──────────────────────────── */}
+      {/* -- Footer: New Task + status ------------------------------------- */}
       <Divider sx={{ opacity: 0.5 }} />
       <Box
         sx={{

frontend/src/hooks/useAgentChat.ts

@@ -1,7 +1,11 @@
 /**
  * Central hook wiring the Vercel AI SDK's useChat with our custom
- * WebSocketChatTransport. Replaces the old useAgentWebSocket + agentStore
- * message management.
+ * WebSocketChatTransport.
+ *
+ * In the per-session architecture, each session mounts its own instance
+ * of this hook. The `isActive` flag controls whether side-channel
+ * callbacks update the global UI stores (agentStore / layoutStore) or
+ * only per-session metadata (sessionStore.needsAttention).
  */
 import { useCallback, useEffect, useMemo, useRef } from 'react';
 import { useChat } from '@ai-sdk/react';
@@ -16,16 +20,20 @@ import { useLayoutStore } from '@/store/layoutStore';
 import { logger } from '@/utils/logger';
 
 interface UseAgentChatOptions {
-  sessionId: string | null;
+  sessionId: string;
+  isActive: boolean;
   onReady?: () => void;
   onError?: (error: string) => void;
   onSessionDead?: (sessionId: string) => void;
 }
 
-export function useAgentChat({ sessionId, onReady, onError, onSessionDead }: UseAgentChatOptions) {
+export function useAgentChat({ sessionId, isActive, onReady, onError, onSessionDead }: UseAgentChatOptions) {
   const callbacksRef = useRef({ onReady, onError, onSessionDead });
   callbacksRef.current = { onReady, onError, onSessionDead };
 
+  const isActiveRef = useRef(isActive);
+  isActiveRef.current = isActive;
+
   const {
     setProcessing,
     setConnected,
@@ -36,35 +44,46 @@ export function useAgentChat({ sessionId, onReady, onError, onSessionDead }: Use
   } = useAgentStore();
 
   const { setRightPanelOpen, setLeftSidebarOpen } = useLayoutStore();
-  const { setSessionActive } = useSessionStore();
+  const { setSessionActive, setNeedsAttention } = useSessionStore();
 
-  // ── Build side-channel callbacks (stable ref) ────────────────────
+  // -- Build side-channel callbacks (stable ref) --------------------------
+  // These check isActiveRef to decide whether to update global UI state.
   const sideChannel = useMemo<SideChannelCallbacks>(
     () => ({
       onReady: () => {
-        setConnected(true);
-        setProcessing(false);
-        if (sessionId) setSessionActive(sessionId, true);
+        if (isActiveRef.current) {
+          setConnected(true);
+          setProcessing(false);
+        }
+        setSessionActive(sessionId, true);
         callbacksRef.current.onReady?.();
       },
       onShutdown: () => {
-        setConnected(false);
-        setProcessing(false);
+        if (isActiveRef.current) {
+          setConnected(false);
+          setProcessing(false);
+        }
       },
       onError: (error: string) => {
-        setError(error);
-        setProcessing(false);
+        if (isActiveRef.current) {
+          setError(error);
+          setProcessing(false);
+        }
         callbacksRef.current.onError?.(error);
       },
       onProcessing: () => {
-        setProcessing(true);
-        setActivityStatus({ type: 'thinking' });
+        if (isActiveRef.current) {
+          setProcessing(true);
+          setActivityStatus({ type: 'thinking' });
+        }
       },
       onProcessingDone: () => {
-        setProcessing(false);
+        if (isActiveRef.current) {
+          setProcessing(false);
+        }
       },
       onUndoComplete: () => {
-        setProcessing(false);
+        if (isActiveRef.current) setProcessing(false);
         // Remove the last turn (user msg + assistant response) from useChat state
         const setMsgs = chatActionsRef.current.setMessages;
         const msgs = chatActionsRef.current.messages;
@@ -75,19 +94,21 @@ export function useAgentChat({ sessionId, onReady, onError, onSessionDead }: Use
           }
           const updated = lastUserIdx > 0 ? msgs.slice(0, lastUserIdx) : [];
           setMsgs(updated);
-          if (sessionId) saveMessages(sessionId, updated);
+          saveMessages(sessionId, updated);
         }
       },
       onCompacted: (oldTokens: number, newTokens: number) => {
-        logger.log(`Context compacted: ${oldTokens} → ${newTokens} tokens`);
+        logger.log(`Context compacted: ${oldTokens} -> ${newTokens} tokens`);
       },
       onPlanUpdate: (plan) => {
+        if (!isActiveRef.current) return;
         useAgentStore.getState().setPlan(plan as Array<{ id: string; content: string; status: 'pending' | 'in_progress' | 'completed' }>);
         if (!useLayoutStore.getState().isRightPanelOpen) {
           setRightPanelOpen(true);
         }
       },
       onToolLog: (tool: string, log: string) => {
+        if (!isActiveRef.current) return;
         if (tool === 'hf_jobs') {
           const state = useAgentStore.getState();
           const existingOutput = state.panelData?.output?.content || '';
@@ -103,7 +124,7 @@ export function useAgentChat({ sessionId, onReady, onError, onSessionDead }: Use
         }
       },
       onConnectionChange: (connected: boolean) => {
-        setConnected(connected);
+        if (isActiveRef.current) setConnected(connected);
       },
       onSessionDead: (deadSessionId: string) => {
         logger.warn(`Session ${deadSessionId} dead, removing`);
@@ -111,6 +132,13 @@ export function useAgentChat({ sessionId, onReady, onError, onSessionDead }: Use
       },
       onApprovalRequired: (tools) => {
         if (!tools.length) return;
+
+        // Always mark the session as needing attention
+        setNeedsAttention(sessionId, true);
+
+        // Only update global UI if this is the active session
+        if (!isActiveRef.current) return;
+
         setActivityStatus({ type: 'waiting-approval' });
         const firstTool = tools[0];
         const args = firstTool.arguments as Record<string, string | undefined>;
@@ -139,6 +167,7 @@ export function useAgentChat({ sessionId, onReady, onError, onSessionDead }: Use
         setLeftSidebarOpen(false);
       },
       onToolCallPanel: (toolName: string, args: Record<string, unknown>) => {
+        if (!isActiveRef.current) return;
         if (toolName === 'hf_jobs' && args.operation && args.script) {
           setPanel(
             { title: 'Script', script: { content: String(args.script), language: 'python' }, parameters: args },
@@ -157,35 +186,36 @@ export function useAgentChat({ sessionId, onReady, onError, onSessionDead }: Use
         }
       },
       onToolOutputPanel: (toolName: string, _toolCallId: string, output: string, success: boolean) => {
+        if (!isActiveRef.current) return;
         if (toolName === 'hf_jobs' && output) {
           setPanelOutput({ content: output, language: 'markdown' });
           if (!success) useAgentStore.getState().setPanelView('output');
         }
       },
       onStreaming: () => {
-        setActivityStatus({ type: 'streaming' });
+        if (isActiveRef.current) setActivityStatus({ type: 'streaming' });
       },
       onToolRunning: (toolName: string) => {
-        setActivityStatus({ type: 'tool', toolName });
+        if (isActiveRef.current) setActivityStatus({ type: 'tool', toolName });
       },
     }),
-    // Zustand setters are stable
+    // sessionId is the only real dependency — Zustand setters are stable
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [sessionId],
   );
 
-  // ── Create transport (single stable instance for the lifetime of this hook) ──
+  // -- Create transport (one per session, stable for lifetime) ------------
   const transportRef = useRef<WebSocketChatTransport | null>(null);
   if (!transportRef.current) {
     transportRef.current = new WebSocketChatTransport({ sideChannel });
   }
 
-  // Keep side-channel callbacks in sync (they capture sessionId)
+  // Keep side-channel callbacks in sync (they capture isActiveRef)
   useEffect(() => {
     transportRef.current?.updateSideChannel(sideChannel);
   }, [sideChannel]);
 
-  // Connect / disconnect WebSocket when session changes
+  // Connect WebSocket on mount, disconnect on unmount
   useEffect(() => {
     transportRef.current?.connectToSession(sessionId);
     return () => {
@@ -193,28 +223,38 @@ export function useAgentChat({ sessionId, onReady, onError, onSessionDead }: Use
     };
   }, [sessionId]);
 
-  // ── Restore persisted messages for this session ─────────────────
+  // Destroy transport on unmount
+  useEffect(() => {
+    return () => {
+      transportRef.current?.destroy();
+      transportRef.current = null;
+    };
+  }, []);
+
+  // -- Restore persisted messages for this session ------------------------
   const initialMessages = useMemo(
-    () => (sessionId ? loadMessages(sessionId) : []),
+    () => loadMessages(sessionId),
     [sessionId],
   );
 
-  // ── Ref for chat actions (used by sideChannel callbacks created before chat) ──
+  // -- Ref for chat actions (used by sideChannel callbacks) ---------------
   const chatActionsRef = useRef<{
     setMessages: ((msgs: UIMessage[]) => void) | null;
     messages: UIMessage[];
   }>({ setMessages: null, messages: [] });
 
-  // ── useChat from Vercel AI SDK ───────────────────────────────────
+  // -- useChat from Vercel AI SDK -----------------------------------------
   const chat = useChat({
-    id: sessionId || '__no_session__',
+    id: sessionId,
     messages: initialMessages,
     transport: transportRef.current!,
     experimental_throttle: 80,
     onError: (error) => {
       logger.error('useChat error:', error);
-      setError(error.message);
-      setProcessing(false);
+      if (isActiveRef.current) {
+        setError(error.message);
+        setProcessing(false);
+      }
     },
   });
 
@@ -222,75 +262,87 @@ export function useAgentChat({ sessionId, onReady, onError, onSessionDead }: Use
   chatActionsRef.current.setMessages = chat.setMessages;
   chatActionsRef.current.messages = chat.messages;
 
-  // ── Hydrate from backend when switching to a session ──────────────
+  // -- Hydrate from backend on mount (page refresh recovery) --------------
   useEffect(() => {
-    if (!sessionId) return;
     let cancelled = false;
-    apiFetch(`/api/session/${sessionId}/messages`)
-      .then((res) => (res.ok ? res.json() : null))
-      .then((data) => {
-        if (cancelled || !data || !Array.isArray(data) || data.length === 0) return;
-        const uiMsgs = llmMessagesToUIMessages(data);
-        if (uiMsgs.length > 0) {
-          chat.setMessages(uiMsgs);
-          saveMessages(sessionId, uiMsgs);
+    (async () => {
+      try {
+        // Fetch messages and session info (for pending approval) in parallel
+        const [msgsRes, infoRes] = await Promise.all([
+          apiFetch(`/api/session/${sessionId}/messages`),
+          apiFetch(`/api/session/${sessionId}`),
+        ]);
+
+        if (cancelled) return;
+
+        // Extract pending approval tool IDs from session info
+        let pendingIds: Set<string> | undefined;
+        if (infoRes.ok) {
+          const info = await infoRes.json();
+          if (info.pending_approval && Array.isArray(info.pending_approval)) {
+            pendingIds = new Set(
+              info.pending_approval.map((t: { tool_call_id: string }) => t.tool_call_id)
+            );
+            if (pendingIds.size > 0) {
+              setNeedsAttention(sessionId, true);
+            }
+          }
         }
-      })
-      .catch(() => { /* backend unreachable — localStorage fallback is fine */ });
+
+        if (msgsRes.ok) {
+          const data = await msgsRes.json();
+          if (cancelled || !Array.isArray(data) || data.length === 0) return;
+          const uiMsgs = llmMessagesToUIMessages(data, pendingIds);
+          if (uiMsgs.length > 0) {
+            chat.setMessages(uiMsgs);
+            saveMessages(sessionId, uiMsgs);
+          }
+        }
+      } catch {
+        /* backend unreachable -- localStorage fallback is fine */
+      }
+    })();
     return () => { cancelled = true; };
   }, [sessionId]); // eslint-disable-line react-hooks/exhaustive-deps
 
-  // ── Persist messages ──────────────────────────────────────────────
-  const flushRef = useRef<{ sid: string | null; msgs: UIMessage[] }>({ sid: null, msgs: [] });
-  flushRef.current.sid = sessionId;
-  flushRef.current.msgs = chat.messages;
-
-  // Save whenever message count changes (covers user sends + new assistant msgs)
+  // -- Persist messages ---------------------------------------------------
   const prevLenRef = useRef(initialMessages.length);
   useEffect(() => {
-    if (!sessionId || chat.messages.length === 0) return;
+    if (chat.messages.length === 0) return;
     if (chat.messages.length !== prevLenRef.current) {
       prevLenRef.current = chat.messages.length;
       saveMessages(sessionId, chat.messages);
     }
   }, [sessionId, chat.messages]);
 
-  // ── Undo last turn (calls backend + syncs useChat + localStorage) ──
+  // -- Undo last turn -----------------------------------------------------
   const undoLastTurn = useCallback(async () => {
-    if (!sessionId) return;
     try {
       const res = await apiFetch(`/api/undo/${sessionId}`, { method: 'POST' });
       if (!res.ok) {
         logger.error('Undo API returned', res.status);
-        return;
       }
     } catch (e) {
       logger.error('Undo failed:', e);
     }
-    // Backend will also send undo_complete, but we apply optimistically
-    // so the UI updates immediately.
   }, [sessionId]);
 
-  // ── Convenience: approve tools via transport ─────────────────────
+  // -- Approve tools via transport ----------------------------------------
   const approveTools = useCallback(
     async (approvals: Array<{ tool_call_id: string; approved: boolean; feedback?: string | null; edited_script?: string | null }>) => {
-      if (!sessionId || !transportRef.current) return false;
+      if (!transportRef.current) return false;
       const ok = await transportRef.current.approveTools(sessionId, approvals);
       if (ok) {
+        // Clear needsAttention since user has responded
+        setNeedsAttention(sessionId, false);
         const hasApproved = approvals.some(a => a.approved);
-        if (hasApproved) setProcessing(true);
+        if (hasApproved && isActiveRef.current) setProcessing(true);
       }
       return ok;
     },
-    [sessionId, setProcessing],
+    [sessionId, setProcessing, setNeedsAttention],
   );
 
-  // ── Flush current messages to localStorage (call before switching sessions) ──
-  const flushMessages = useCallback(() => {
-    const { sid, msgs } = flushRef.current;
-    if (sid && msgs.length > 0) saveMessages(sid, msgs);
-  }, []);
-
   return {
     messages: chat.messages,
     sendMessage: chat.sendMessage,
@@ -298,7 +350,6 @@ export function useAgentChat({ sessionId, onReady, onError, onSessionDead }: Use
     status: chat.status,
     undoLastTurn,
     approveTools,
-    flushMessages,
     transport: transportRef.current,
   };
 }

frontend/src/lib/convert-llm-messages.ts

@@ -21,7 +21,15 @@ function nextId(): string {
   return `msg-${Date.now()}-${++idCounter}`;
 }
 
-export function llmMessagesToUIMessages(messages: LLMMessage[]): UIMessage[] {
+/**
+ * @param pendingApprovalIds - Set of tool_call_ids that are waiting for approval.
+ *   When provided, matching tool calls without results will get state
+ *   'approval-requested' instead of 'input-available'.
+ */
+export function llmMessagesToUIMessages(
+  messages: LLMMessage[],
+  pendingApprovalIds?: Set<string>,
+): UIMessage[] {
   // Build a map of tool_call_id -> tool result for pairing
   const toolResults = new Map<string, { output: string; isError: boolean }>();
   for (const msg of messages) {
@@ -72,6 +80,15 @@ export function llmMessagesToUIMessages(messages: LLMMessage[]): UIMessage[] {
               input,
               output: result.output,
             });
+          } else if (pendingApprovalIds?.has(tc.id)) {
+            parts.push({
+              type: 'dynamic-tool',
+              toolCallId: tc.id,
+              toolName: tc.function.name,
+              state: 'approval-requested',
+              input,
+              approval: { id: `approval-${tc.id}` },
+            });
           } else {
             parts.push({
               type: 'dynamic-tool',

frontend/src/lib/ws-chat-transport.ts

@@ -2,8 +2,8 @@
  * Custom ChatTransport that bridges our WebSocket-based backend protocol
  * to the Vercel AI SDK's UIMessageChunk streaming interface.
  *
- * The backend stays unchanged — this adapter translates WebSocket events
- * into the chunk types that useChat() expects.
+ * Each instance manages a single session's WebSocket connection.
+ * In the per-session architecture, every session owns its own transport.
  */
 import type { ChatTransport, UIMessage, UIMessageChunk, ChatRequestOptions } from 'ai';
 import { apiFetch, getWebSocketUrl } from '@/utils/api';
@@ -66,9 +66,6 @@ export class WebSocketChatTransport implements ChatTransport<UIMessage> {
   private currentSessionId: string | null = null;
   private sideChannel: SideChannelCallbacks;
 
-  /** Background WebSockets kept alive so the backend agent keeps running. */
-  private backgroundSockets: Map<string, WebSocket> = new Map();
-
   private streamController: ReadableStreamDefaultController<UIMessageChunk> | null = null;
   private streamGeneration = 0;
   private abortedGeneration = 0;
@@ -81,7 +78,6 @@ export class WebSocketChatTransport implements ChatTransport<UIMessage> {
   private retries = 0;
   private pingInterval: ReturnType<typeof setInterval> | null = null;
   private boundVisibilityHandler: (() => void) | null = null;
-  private wasHidden = false;
 
   constructor({ sideChannel }: WebSocketChatTransportOptions) {
     this.sideChannel = sideChannel;
@@ -91,7 +87,6 @@ export class WebSocketChatTransport implements ChatTransport<UIMessage> {
   private setupVisibilityHandler(): void {
     this.boundVisibilityHandler = () => {
       if (document.visibilityState === 'hidden') {
-        this.wasHidden = true;
         return;
       }
 
@@ -102,30 +97,25 @@ export class WebSocketChatTransport implements ChatTransport<UIMessage> {
           this.retries = 0;
           this.reconnectDelay = WS_RECONNECT_DELAY;
           this.createWebSocket(this.currentSessionId);
-
-          if (this.wasHidden) {
-            const store = useAgentStore.getState();
-            if (store.isProcessing) {
-              logger.log('Tab visible after WS drop: resetting stale processing state');
-              store.setProcessing(false);
-              this.closeActiveStream();
-            }
-          }
         } else if (wsState === WebSocket.OPEN) {
           this.ws!.send(JSON.stringify({ type: 'ping' }));
         }
-        this.wasHidden = false;
       }
     };
     document.addEventListener('visibilitychange', this.boundVisibilityHandler);
   }
 
-  /** Update side-channel callbacks (e.g. when sessionId changes). */
+  /** Update side-channel callbacks (e.g. when isActive changes). */
   updateSideChannel(sideChannel: SideChannelCallbacks): void {
     this.sideChannel = sideChannel;
   }
 
-  // ── Public API ──────────────────────────────────────────────────────
+  /** Check if the WebSocket is currently connected. */
+  isWebSocketConnected(): boolean {
+    return this.ws?.readyState === WebSocket.OPEN;
+  }
+
+  // -- Public API ----------------------------------------------------------
 
   /** Connect (or reconnect) to a session's WebSocket. */
   connectToSession(sessionId: string | null): void {
@@ -134,55 +124,15 @@ export class WebSocketChatTransport implements ChatTransport<UIMessage> {
       this.connectTimeout = null;
     }
 
-    // Move current WS to background instead of closing it
-    if (this.ws && this.currentSessionId && this.currentSessionId !== sessionId) {
-      const oldId = this.currentSessionId;
-      const oldWs = this.ws;
-      this.backgroundSockets.set(oldId, oldWs);
-      // Replace handler: background sockets only need ping/pong
-      oldWs.onmessage = (evt) => {
-        try {
-          const raw = JSON.parse(evt.data);
-          if (raw.type === 'pong') return;
-          // Silently discard — backend keeps running, we'll load results from localStorage
-        } catch { /* ignore */ }
-      };
-      oldWs.onclose = () => {
-        this.backgroundSockets.delete(oldId);
-      };
-      this.ws = null;
-      this.stopPing();
-    } else {
-      this.disconnectWebSocket();
+    // Same session — no-op
+    if (sessionId === this.currentSessionId && this.ws?.readyState === WebSocket.OPEN) {
+      return;
     }
 
+    this.disconnectWebSocket();
     this.currentSessionId = sessionId;
-    if (sessionId) {
-      // Promote background socket if one exists for this session
-      const bg = this.backgroundSockets.get(sessionId);
-      if (bg && (bg.readyState === WebSocket.OPEN || bg.readyState === WebSocket.CONNECTING)) {
-        this.backgroundSockets.delete(sessionId);
-        this.ws = bg;
-        // Restore full event handling
-        bg.onmessage = (evt) => {
-          try {
-            const raw = JSON.parse(evt.data);
-            if (raw.type === 'pong') return;
-            this.handleEvent(raw as AgentEvent);
-          } catch (e) {
-            logger.error('WS parse error:', e);
-          }
-        };
-        bg.onclose = (evt) => {
-          logger.log('WS closed', evt.code, evt.reason);
-          this.sideChannel.onConnectionChange(false);
-          this.stopPing();
-        };
-        this.sideChannel.onConnectionChange(true);
-        this.startPing();
-        return;
-      }
 
+    if (sessionId) {
       this.retries = 0;
       this.reconnectDelay = WS_RECONNECT_DELAY;
       this.connectTimeout = setTimeout(() => {
@@ -221,14 +171,11 @@ export class WebSocketChatTransport implements ChatTransport<UIMessage> {
       document.removeEventListener('visibilitychange', this.boundVisibilityHandler);
       this.boundVisibilityHandler = null;
     }
-    // Close all background sockets
-    for (const ws of this.backgroundSockets.values()) ws.close();
-    this.backgroundSockets.clear();
     this.disconnectWebSocket();
     this.closeActiveStream();
   }
 
-  // ── ChatTransport interface ─────────────────────────────────────────
+  // -- ChatTransport interface ---------------------------------------------
 
   async sendMessages(
     options: {
@@ -322,7 +269,7 @@ export class WebSocketChatTransport implements ChatTransport<UIMessage> {
     );
   }
 
-  // ── WebSocket lifecycle ─────────────────────────────────────────────
+  // -- WebSocket lifecycle -------------------------------------------------
 
   private createWebSocket(sessionId: string): void {
     if (this.ws?.readyState === WebSocket.OPEN || this.ws?.readyState === WebSocket.CONNECTING) {
@@ -409,7 +356,7 @@ export class WebSocketChatTransport implements ChatTransport<UIMessage> {
     }
   }
 
-  // ── Stream helpers ──────────────────────────────────────────────────
+  // -- Stream helpers ------------------------------------------------------
 
   private closeActiveStream(): void {
     if (this.streamController) {
@@ -438,7 +385,7 @@ export class WebSocketChatTransport implements ChatTransport<UIMessage> {
     }
   }
 
-  // ── Event → UIMessageChunk mapping ──────────────────────────────────
+  // -- Event -> UIMessageChunk mapping ------------------------------------
 
   private static readonly STREAM_EVENTS = new Set([
     'assistant_chunk', 'assistant_stream_end', 'assistant_message',
@@ -454,7 +401,7 @@ export class WebSocketChatTransport implements ChatTransport<UIMessage> {
     }
 
     switch (event.event_type) {
-      // ── Side-channel only events ────────────────────────────────
+      // -- Side-channel only events ----------------------------------------
       case 'ready':
         this.sideChannel.onReady();
         break;
@@ -465,10 +412,6 @@ export class WebSocketChatTransport implements ChatTransport<UIMessage> {
         break;
 
       case 'interrupted':
-        // Don't close the stream here — the abort handler already did, and
-        // a new stream for the next user message may already exist.
-        // Closing here would destroy the NEWER stream, causing the next
-        // response to be silently dropped.
         this.sideChannel.onProcessingDone();
         break;
 
@@ -498,7 +441,7 @@ export class WebSocketChatTransport implements ChatTransport<UIMessage> {
         );
         break;
 
-      // ── Chat stream events ──────────────────────────────────────
+      // -- Chat stream events ----------------------------------------------
       case 'processing':
         if (this.awaitingProcessing) {
           if (this.streamGeneration <= this.abortedGeneration) {

frontend/src/store/sessionStore.ts

@@ -13,6 +13,7 @@ interface SessionStore {
   switchSession: (id: string) => void;
   setSessionActive: (id: string, isActive: boolean) => void;
   updateSessionTitle: (id: string, title: string) => void;
+  setNeedsAttention: (id: string, needs: boolean) => void;
 }
 
 export const useSessionStore = create<SessionStore>()(
@@ -27,6 +28,7 @@ export const useSessionStore = create<SessionStore>()(
           title: `Chat ${get().sessions.length + 1}`,
           createdAt: new Date().toISOString(),
           isActive: true,
+          needsAttention: false,
         };
         set((state) => ({
           sessions: [...state.sessions, newSession],
@@ -50,7 +52,12 @@ export const useSessionStore = create<SessionStore>()(
       },
 
       switchSession: (id: string) => {
-        set({ activeSessionId: id });
+        set((state) => ({
+          activeSessionId: id,
+          sessions: state.sessions.map((s) =>
+            s.id === id ? { ...s, needsAttention: false } : s
+          ),
+        }));
       },
 
       setSessionActive: (id: string, isActive: boolean) => {
@@ -68,6 +75,14 @@ export const useSessionStore = create<SessionStore>()(
           ),
         }));
       },
+
+      setNeedsAttention: (id: string, needs: boolean) => {
+        set((state) => ({
+          sessions: state.sessions.map((s) =>
+            s.id === id ? { ...s, needsAttention: needs } : s
+          ),
+        }));
+      },
     }),
     {
       name: 'hf-agent-sessions',

frontend/src/types/agent.ts

@@ -15,6 +15,7 @@ export interface SessionMeta {
   title: string;
   createdAt: string;
   isActive: boolean;
+  needsAttention: boolean;
 }
 
 export interface ToolApproval {