feat(cli): TUI complete overhaul — components, sidebar, search, branding (#157)

Co-authored-by: Jason Woltje <jason@diversecanvas.com>
Co-committed-by: Jason Woltje <jason@diversecanvas.com>

packages/cli/src/tui/app.tsx

@@ -1,16 +1,19 @@
-import React, { useState, useCallback, useEffect, useRef } from 'react';
-import { Box, Text, useInput, useApp } from 'ink';
-import TextInput from 'ink-text-input';
-import Spinner from 'ink-spinner';
-import { io, type Socket } from 'socket.io-client';
-import { fetchAvailableModels, type ModelInfo } from './gateway-api.js';
+import React, { useState, useCallback, useEffect, useMemo } from 'react';
+import { Box, useApp, useInput } from 'ink';
+import { TopBar } from './components/top-bar.js';
+import { BottomBar } from './components/bottom-bar.js';
+import { MessageList } from './components/message-list.js';
+import { InputBar } from './components/input-bar.js';
+import { Sidebar } from './components/sidebar.js';
+import { SearchBar } from './components/search-bar.js';
+import { useSocket } from './hooks/use-socket.js';
+import { useGitInfo } from './hooks/use-git-info.js';
+import { useViewport } from './hooks/use-viewport.js';
+import { useAppMode } from './hooks/use-app-mode.js';
+import { useConversations } from './hooks/use-conversations.js';
+import { useSearch } from './hooks/use-search.js';
 
-interface Message {
-  role: 'user' | 'assistant' | 'system';
-  content: string;
-}
-
-interface TuiAppProps {
+export interface TuiAppProps {
   gatewayUrl: string;
   conversationId?: string;
   sessionCookie?: string;
@@ -18,375 +21,230 @@ interface TuiAppProps {
   initialProvider?: string;
 }
 
-/**
- * Parse a slash command from user input.
- * Returns null if the input is not a slash command.
- */
-function parseSlashCommand(value: string): { command: string; args: string[] } | null {
-  const trimmed = value.trim();
-  if (!trimmed.startsWith('/')) return null;
-  const parts = trimmed.slice(1).split(/\s+/);
-  const command = parts[0]?.toLowerCase() ?? '';
-  const args = parts.slice(1);
-  return { command, args };
-}
-
 export function TuiApp({
   gatewayUrl,
-  conversationId: initialConversationId,
+  conversationId,
   sessionCookie,
   initialModel,
   initialProvider,
 }: TuiAppProps) {
   const { exit } = useApp();
-  const [messages, setMessages] = useState<Message[]>([]);
-  const [input, setInput] = useState('');
-  const [isStreaming, setIsStreaming] = useState(false);
-  const [connected, setConnected] = useState(false);
-  const [conversationId, setConversationId] = useState(initialConversationId);
-  const [currentStreamText, setCurrentStreamText] = useState('');
+  const gitInfo = useGitInfo();
+  const appMode = useAppMode();
 
-  // Model/provider state
-  const [currentModel, setCurrentModel] = useState<string | undefined>(initialModel);
-  const [currentProvider, setCurrentProvider] = useState<string | undefined>(initialProvider);
-  const [availableModels, setAvailableModels] = useState<ModelInfo[]>([]);
+  const socket = useSocket({
+    gatewayUrl,
+    sessionCookie,
+    initialConversationId: conversationId,
+    initialModel,
+    initialProvider,
+  });
 
-  const socketRef = useRef<Socket | null>(null);
-  const currentStreamTextRef = useRef('');
+  const conversations = useConversations({ gatewayUrl, sessionCookie });
 
-  // Fetch available models on mount
+  const viewport = useViewport({ totalItems: socket.messages.length });
+
+  const search = useSearch(socket.messages);
+
+  // Scroll to current match when it changes
+  const currentMatch = search.matches[search.currentMatchIndex];
   useEffect(() => {
-    fetchAvailableModels(gatewayUrl, sessionCookie)
-      .then((models) => {
-        setAvailableModels(models);
-        // If no model/provider specified and models are available, show the default
-        if (!initialModel && !initialProvider && models.length > 0) {
-          const first = models[0];
-          if (first) {
-            setCurrentModel(first.id);
-            setCurrentProvider(first.provider);
-          }
-        }
-      })
-      .catch(() => {
-        // Non-fatal: TUI works without model list
-      });
-  }, [gatewayUrl, sessionCookie, initialModel, initialProvider]);
+    if (currentMatch && appMode.mode === 'search') {
+      viewport.scrollTo(currentMatch.messageIndex);
+    }
+  }, [currentMatch, appMode.mode, viewport]);
 
-  useEffect(() => {
-    const socket = io(`${gatewayUrl}/chat`, {
-      transports: ['websocket'],
-      extraHeaders: sessionCookie ? { Cookie: sessionCookie } : undefined,
-    });
+  // Compute highlighted message indices for MessageList
+  const highlightedMessageIndices = useMemo(() => {
+    if (search.matches.length === 0) return undefined;
+    return new Set(search.matches.map((m) => m.messageIndex));
+  }, [search.matches]);
 
-    socketRef.current = socket;
+  const currentHighlightIndex = currentMatch?.messageIndex;
 
-    socket.on('connect', () => setConnected(true));
-    socket.on('disconnect', () => {
-      setConnected(false);
-      setIsStreaming(false);
-      setCurrentStreamText('');
-    });
-    socket.on('connect_error', (err: Error) => {
-      setMessages((msgs) => [
-        ...msgs,
-        {
-          role: 'assistant',
-          content: `Connection failed: ${err.message}. Check that the gateway is running at ${gatewayUrl}.`,
-        },
-      ]);
-    });
+  const [sidebarSelectedIndex, setSidebarSelectedIndex] = useState(0);
 
-    socket.on('message:ack', (data: { conversationId: string }) => {
-      setConversationId(data.conversationId);
-    });
-
-    socket.on('agent:start', () => {
-      setIsStreaming(true);
-      currentStreamTextRef.current = '';
-      setCurrentStreamText('');
-    });
-
-    socket.on('agent:text', (data: { text: string }) => {
-      currentStreamTextRef.current += data.text;
-      setCurrentStreamText(currentStreamTextRef.current);
-    });
-
-    socket.on('agent:end', () => {
-      const finalText = currentStreamTextRef.current;
-      currentStreamTextRef.current = '';
-      setCurrentStreamText('');
-      if (finalText) {
-        setMessages((msgs) => [...msgs, { role: 'assistant', content: finalText }]);
-      }
-      setIsStreaming(false);
-    });
-
-    socket.on('error', (data: { error: string }) => {
-      setMessages((msgs) => [...msgs, { role: 'assistant', content: `Error: ${data.error}` }]);
-      setIsStreaming(false);
-    });
-
-    return () => {
-      socket.disconnect();
-    };
-  }, [gatewayUrl]);
-
-  /**
-   * Handle /model and /provider slash commands.
-   * Returns true if the input was a handled slash command (should not be sent to gateway).
-   */
-  const handleSlashCommand = useCallback(
-    (value: string): boolean => {
-      const parsed = parseSlashCommand(value);
-      if (!parsed) return false;
-
-      const { command, args } = parsed;
-
-      if (command === 'model') {
-        if (args.length === 0) {
-          // List available models
-          if (availableModels.length === 0) {
-            setMessages((msgs) => [
-              ...msgs,
-              {
-                role: 'system',
-                content:
-                  'No models available (could not reach gateway). Use /model <modelId> to set one manually.',
-              },
-            ]);
-          } else {
-            const lines = availableModels.map(
-              (m) =>
-                `  ${m.provider}/${m.id}${m.id === currentModel && m.provider === currentProvider ? ' (active)' : ''}`,
-            );
-            setMessages((msgs) => [
-              ...msgs,
-              {
-                role: 'system',
-                content: `Available models:\n${lines.join('\n')}`,
-              },
-            ]);
-          }
-        } else {
-          // Switch model: /model <modelId> or /model <provider>/<modelId>
-          const arg = args[0]!;
-          const slashIdx = arg.indexOf('/');
-          let newProvider: string | undefined;
-          let newModelId: string;
-
-          if (slashIdx !== -1) {
-            newProvider = arg.slice(0, slashIdx);
-            newModelId = arg.slice(slashIdx + 1);
-          } else {
-            newModelId = arg;
-            // Try to find provider from available models list
-            const match = availableModels.find((m) => m.id === newModelId);
-            newProvider = match?.provider ?? currentProvider;
-          }
-
-          setCurrentModel(newModelId);
-          if (newProvider) setCurrentProvider(newProvider);
-
-          setMessages((msgs) => [
-            ...msgs,
-            {
-              role: 'system',
-              content: `Switched to model: ${newProvider ? `${newProvider}/` : ''}${newModelId}. Takes effect on next message.`,
-            },
-          ]);
-        }
-        return true;
-      }
-
-      if (command === 'provider') {
-        if (args.length === 0) {
-          // List providers from available models
-          const providers = [...new Set(availableModels.map((m) => m.provider))];
-          if (providers.length === 0) {
-            setMessages((msgs) => [
-              ...msgs,
-              {
-                role: 'system',
-                content:
-                  'No providers available (could not reach gateway). Use /provider <name> to set one manually.',
-              },
-            ]);
-          } else {
-            const lines = providers.map((p) => `  ${p}${p === currentProvider ? ' (active)' : ''}`);
-            setMessages((msgs) => [
-              ...msgs,
-              {
-                role: 'system',
-                content: `Available providers:\n${lines.join('\n')}`,
-              },
-            ]);
-          }
-        } else {
-          const newProvider = args[0]!;
-          setCurrentProvider(newProvider);
-          // If switching provider, auto-select first model for that provider
-          const providerModels = availableModels.filter((m) => m.provider === newProvider);
-          if (providerModels.length > 0 && providerModels[0]) {
-            setCurrentModel(providerModels[0].id);
-            setMessages((msgs) => [
-              ...msgs,
-              {
-                role: 'system',
-                content: `Switched to provider: ${newProvider} (model: ${providerModels[0]!.id}). Takes effect on next message.`,
-              },
-            ]);
-          } else {
-            setMessages((msgs) => [
-              ...msgs,
-              {
-                role: 'system',
-                content: `Switched to provider: ${newProvider}. Takes effect on next message.`,
-              },
-            ]);
-          }
-        }
-        return true;
-      }
-
-      if (command === 'help') {
-        setMessages((msgs) => [
-          ...msgs,
-          {
-            role: 'system',
-            content: [
-              'Available commands:',
-              '  /model              — list available models',
-              '  /model <id>         — switch model (e.g. /model gpt-4o)',
-              '  /model <p>/<id>     — switch model with provider (e.g. /model ollama/llama3.2)',
-              '  /provider           — list available providers',
-              '  /provider <name>    — switch provider (e.g. /provider ollama)',
-              '  /help               — show this help',
-            ].join('\n'),
-          },
-        ]);
-        return true;
-      }
-
-      // Unknown slash command — let the user know
-      setMessages((msgs) => [
-        ...msgs,
-        {
-          role: 'system',
-          content: `Unknown command: /${command}. Type /help for available commands.`,
-        },
-      ]);
-      return true;
+  const handleSwitchConversation = useCallback(
+    (id: string) => {
+      socket.switchConversation(id);
+      appMode.setMode('chat');
     },
-    [availableModels, currentModel, currentProvider],
+    [socket, appMode],
   );
 
-  const handleSubmit = useCallback(
-    (value: string) => {
-      if (!value.trim() || isStreaming) return;
-
-      setInput('');
-
-      // Handle slash commands first
-      if (handleSlashCommand(value)) return;
-
-      if (!socketRef.current?.connected) {
-        setMessages((msgs) => [
-          ...msgs,
-          { role: 'assistant', content: 'Not connected to gateway. Message not sent.' },
-        ]);
-        return;
-      }
-
-      setMessages((msgs) => [...msgs, { role: 'user', content: value }]);
-
-      socketRef.current.emit('message', {
-        conversationId,
-        content: value,
-        provider: currentProvider,
-        modelId: currentModel,
-      });
+  const handleDeleteConversation = useCallback(
+    (id: string) => {
+      void conversations
+        .deleteConversation(id)
+        .then((ok) => {
+          if (ok && id === socket.conversationId) {
+            socket.clearMessages();
+          }
+        })
+        .catch(() => {});
     },
-    [conversationId, isStreaming, currentModel, currentProvider, handleSlashCommand],
+    [conversations, socket],
   );
 
   useInput((ch, key) => {
     if (key.ctrl && ch === 'c') {
       exit();
     }
+    // Ctrl+L: toggle sidebar (refresh on open)
+    if (key.ctrl && ch === 'l') {
+      const willOpen = !appMode.sidebarOpen;
+      appMode.toggleSidebar();
+      if (willOpen) {
+        void conversations.refresh();
+      }
+    }
+    // Ctrl+N: create new conversation and switch to it
+    if (key.ctrl && ch === 'n') {
+      void conversations
+        .createConversation()
+        .then((conv) => {
+          if (conv) {
+            socket.switchConversation(conv.id);
+            appMode.setMode('chat');
+          }
+        })
+        .catch(() => {});
+    }
+    // Ctrl+K: toggle search mode
+    if (key.ctrl && ch === 'k') {
+      if (appMode.mode === 'search') {
+        search.clear();
+        appMode.setMode('chat');
+      } else {
+        appMode.setMode('search');
+      }
+    }
+    // Page Up / Page Down: scroll message history (only in chat mode)
+    if (appMode.mode === 'chat') {
+      if (key.pageUp) {
+        viewport.scrollBy(-viewport.viewportSize);
+      }
+      if (key.pageDown) {
+        viewport.scrollBy(viewport.viewportSize);
+      }
+    }
+    // Ctrl+T: cycle thinking level
+    if (key.ctrl && ch === 't') {
+      const levels = socket.availableThinkingLevels;
+      if (levels.length > 0) {
+        const currentIdx = levels.indexOf(socket.thinkingLevel);
+        const nextIdx = (currentIdx + 1) % levels.length;
+        const next = levels[nextIdx];
+        if (next) {
+          socket.setThinkingLevel(next);
+        }
+      }
+    }
+    // Escape: return to chat from sidebar/search; in chat, scroll to bottom
+    if (key.escape) {
+      if (appMode.mode === 'search') {
+        search.clear();
+        appMode.setMode('chat');
+      } else if (appMode.mode === 'sidebar') {
+        appMode.setMode('chat');
+      } else if (appMode.mode === 'chat') {
+        viewport.scrollToBottom();
+      }
+    }
   });
 
-  const modelLabel = currentModel
-    ? currentProvider
-      ? `${currentProvider}/${currentModel}`
-      : currentModel
-    : null;
+  const inputPlaceholder =
+    appMode.mode === 'sidebar'
+      ? 'focus is on sidebar… press Esc to return'
+      : appMode.mode === 'search'
+        ? 'search mode… press Esc to return'
+        : undefined;
+
+  const isSearchMode = appMode.mode === 'search';
+
+  const messageArea = (
+    <Box flexDirection="column" flexGrow={1}>
+      <MessageList
+        messages={socket.messages}
+        isStreaming={socket.isStreaming}
+        currentStreamText={socket.currentStreamText}
+        currentThinkingText={socket.currentThinkingText}
+        activeToolCalls={socket.activeToolCalls}
+        scrollOffset={viewport.scrollOffset}
+        viewportSize={viewport.viewportSize}
+        isScrolledUp={viewport.isScrolledUp}
+        highlightedMessageIndices={highlightedMessageIndices}
+        currentHighlightIndex={currentHighlightIndex}
+      />
+
+      {isSearchMode && (
+        <SearchBar
+          query={search.query}
+          onQueryChange={search.setQuery}
+          totalMatches={search.totalMatches}
+          currentMatch={search.currentMatchIndex}
+          onNext={search.nextMatch}
+          onPrev={search.prevMatch}
+          onClose={() => {
+            search.clear();
+            appMode.setMode('chat');
+          }}
+          focused={isSearchMode}
+        />
+      )}
+
+      <InputBar
+        onSubmit={socket.sendMessage}
+        isStreaming={socket.isStreaming}
+        connected={socket.connected}
+        placeholder={inputPlaceholder}
+      />
+    </Box>
+  );
 
   return (
-    <Box flexDirection="column" padding={1}>
-      <Box marginBottom={1}>
-        <Text bold color="blue">
-          Mosaic
-        </Text>
-        <Text> </Text>
-        <Text dimColor>{connected ? `connected` : 'connecting...'}</Text>
-        {conversationId && <Text dimColor> | {conversationId.slice(0, 8)}</Text>}
-        {modelLabel && (
-          <>
-            <Text dimColor> | </Text>
-            <Text color="yellow">{modelLabel}</Text>
-          </>
-        )}
-      </Box>
+    <Box flexDirection="column" height="100%">
+      <Box marginTop={1} />
+      <TopBar
+        gatewayUrl={gatewayUrl}
+        version="0.0.0"
+        modelName={socket.modelName}
+        thinkingLevel={socket.thinkingLevel}
+        contextWindow={socket.tokenUsage.contextWindow}
+        agentName="default"
+        connected={socket.connected}
+        connecting={socket.connecting}
+      />
 
-      <Box flexDirection="column" marginBottom={1}>
-        {messages.map((msg, i) => (
-          <Box key={i} marginBottom={1}>
-            {msg.role === 'system' ? (
-              <Text dimColor italic>
-                {msg.content}
-              </Text>
-            ) : (
-              <>
-                <Text bold color={msg.role === 'user' ? 'green' : 'cyan'}>
-                  {msg.role === 'user' ? '> ' : '  '}
-                </Text>
-                <Text wrap="wrap">{msg.content}</Text>
-              </>
-            )}
-          </Box>
-        ))}
+      {appMode.sidebarOpen ? (
+        <Box flexDirection="row" flexGrow={1}>
+          <Sidebar
+            conversations={conversations.conversations}
+            activeConversationId={socket.conversationId}
+            selectedIndex={sidebarSelectedIndex}
+            onSelectIndex={setSidebarSelectedIndex}
+            onSwitchConversation={handleSwitchConversation}
+            onDeleteConversation={handleDeleteConversation}
+            loading={conversations.loading}
+            focused={appMode.mode === 'sidebar'}
+            width={30}
+          />
+          {messageArea}
+        </Box>
+      ) : (
+        <Box flexGrow={1}>{messageArea}</Box>
+      )}
 
-        {isStreaming && currentStreamText && (
-          <Box marginBottom={1}>
-            <Text bold color="cyan">
-              {'  '}
-            </Text>
-            <Text wrap="wrap">{currentStreamText}</Text>
-          </Box>
-        )}
-
-        {isStreaming && !currentStreamText && (
-          <Box>
-            <Text color="cyan">
-              <Spinner type="dots" />
-            </Text>
-            <Text dimColor> thinking...</Text>
-          </Box>
-        )}
-      </Box>
-
-      <Box>
-        <Text bold color="green">
-          {'> '}
-        </Text>
-        <TextInput
-          value={input}
-          onChange={setInput}
-          onSubmit={handleSubmit}
-          placeholder={isStreaming ? 'waiting...' : 'type a message or /help'}
-        />
-      </Box>
+      <BottomBar
+        gitInfo={gitInfo}
+        tokenUsage={socket.tokenUsage}
+        connected={socket.connected}
+        connecting={socket.connecting}
+        modelName={socket.modelName}
+        providerName={socket.providerName}
+        thinkingLevel={socket.thinkingLevel}
+        conversationId={socket.conversationId}
+      />
     </Box>
   );
 }

packages/cli/src/tui/components/bottom-bar.tsx

@@ -0,0 +1,125 @@
+import React from 'react';
+import { Box, Text } from 'ink';
+import type { TokenUsage } from '../hooks/use-socket.js';
+import type { GitInfo } from '../hooks/use-git-info.js';
+
+export interface BottomBarProps {
+  gitInfo: GitInfo;
+  tokenUsage: TokenUsage;
+  connected: boolean;
+  connecting: boolean;
+  modelName: string | null;
+  providerName: string | null;
+  thinkingLevel: string;
+  conversationId: string | undefined;
+}
+
+function formatTokens(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(0)}k`;
+  return String(n);
+}
+
+/** Compact the cwd — replace home with ~ */
+function compactCwd(cwd: string): string {
+  const home = process.env['HOME'] ?? '';
+  if (home && cwd.startsWith(home)) {
+    return '~' + cwd.slice(home.length);
+  }
+  return cwd;
+}
+
+export function BottomBar({
+  gitInfo,
+  tokenUsage,
+  connected,
+  connecting,
+  modelName,
+  providerName,
+  thinkingLevel,
+  conversationId,
+}: BottomBarProps) {
+  const gatewayStatus = connected ? 'Connected' : connecting ? 'Connecting…' : 'Disconnected';
+  const gatewayColor = connected ? 'green' : connecting ? 'yellow' : 'red';
+
+  const hasTokens = tokenUsage.total > 0;
+
+  return (
+    <Box flexDirection="column" paddingX={0} marginTop={0}>
+      {/* Line 0: keybinding hints */}
+      <Box>
+        <Text dimColor>^L sidebar · ^N new · ^K search · ^T thinking · PgUp/Dn scroll</Text>
+      </Box>
+
+      {/* Line 1: blank  ·····  Gateway: Status */}
+      <Box justifyContent="space-between">
+        <Box />
+        <Box>
+          <Text dimColor>Gateway: </Text>
+          <Text color={gatewayColor}>{gatewayStatus}</Text>
+        </Box>
+      </Box>
+
+      {/* Line 2: cwd (branch)  ·····  Session: id */}
+      <Box justifyContent="space-between">
+        <Box>
+          <Text dimColor>{compactCwd(gitInfo.cwd)}</Text>
+          {gitInfo.branch && <Text dimColor> ({gitInfo.branch})</Text>}
+        </Box>
+        <Box>
+          <Text dimColor>
+            {conversationId ? `Session: ${conversationId.slice(0, 8)}` : 'No session'}
+          </Text>
+        </Box>
+      </Box>
+
+      {/* Line 3: token stats  ·····  (provider) model */}
+      <Box justifyContent="space-between" minHeight={1}>
+        <Box>
+          {hasTokens ? (
+            <>
+              <Text dimColor>↑{formatTokens(tokenUsage.input)}</Text>
+              <Text dimColor>{'  '}</Text>
+              <Text dimColor>↓{formatTokens(tokenUsage.output)}</Text>
+              {tokenUsage.cacheRead > 0 && (
+                <>
+                  <Text dimColor>{'  '}</Text>
+                  <Text dimColor>R{formatTokens(tokenUsage.cacheRead)}</Text>
+                </>
+              )}
+              {tokenUsage.cacheWrite > 0 && (
+                <>
+                  <Text dimColor>{'  '}</Text>
+                  <Text dimColor>W{formatTokens(tokenUsage.cacheWrite)}</Text>
+                </>
+              )}
+              {tokenUsage.cost > 0 && (
+                <>
+                  <Text dimColor>{'  '}</Text>
+                  <Text dimColor>${tokenUsage.cost.toFixed(3)}</Text>
+                </>
+              )}
+              {tokenUsage.contextPercent > 0 && (
+                <>
+                  <Text dimColor>{'  '}</Text>
+                  <Text dimColor>
+                    {tokenUsage.contextPercent.toFixed(1)}%/{formatTokens(tokenUsage.contextWindow)}
+                  </Text>
+                </>
+              )}
+            </>
+          ) : (
+            <Text dimColor>↑0 ↓0 $0.000</Text>
+          )}
+        </Box>
+        <Box>
+          <Text dimColor>
+            {providerName ? `(${providerName}) ` : ''}
+            {modelName ?? 'awaiting model'}
+            {thinkingLevel !== 'off' ? ` • ${thinkingLevel}` : ''}
+          </Text>
+        </Box>
+      </Box>
+    </Box>
+  );
+}

packages/cli/src/tui/components/input-bar.tsx

@@ -0,0 +1,50 @@
+import React, { useState, useCallback } from 'react';
+import { Box, Text } from 'ink';
+import TextInput from 'ink-text-input';
+
+export interface InputBarProps {
+  onSubmit: (value: string) => void;
+  isStreaming: boolean;
+  connected: boolean;
+  placeholder?: string;
+}
+
+export function InputBar({
+  onSubmit,
+  isStreaming,
+  connected,
+  placeholder: placeholderOverride,
+}: InputBarProps) {
+  const [input, setInput] = useState('');
+
+  const handleSubmit = useCallback(
+    (value: string) => {
+      if (!value.trim() || isStreaming || !connected) return;
+      onSubmit(value);
+      setInput('');
+    },
+    [onSubmit, isStreaming, connected],
+  );
+
+  const placeholder =
+    placeholderOverride ??
+    (!connected
+      ? 'disconnected — waiting for gateway…'
+      : isStreaming
+        ? 'waiting for response…'
+        : 'message mosaic…');
+
+  return (
+    <Box paddingX={1} borderStyle="single" borderColor="gray">
+      <Text bold color="green">
+        {'❯ '}
+      </Text>
+      <TextInput
+        value={input}
+        onChange={setInput}
+        onSubmit={handleSubmit}
+        placeholder={placeholder}
+      />
+    </Box>
+  );
+}

packages/cli/src/tui/components/message-list.tsx

@@ -0,0 +1,177 @@
+import React from 'react';
+import { Box, Text } from 'ink';
+import Spinner from 'ink-spinner';
+import type { Message, ToolCall } from '../hooks/use-socket.js';
+
+export interface MessageListProps {
+  messages: Message[];
+  isStreaming: boolean;
+  currentStreamText: string;
+  currentThinkingText: string;
+  activeToolCalls: ToolCall[];
+  scrollOffset?: number;
+  viewportSize?: number;
+  isScrolledUp?: boolean;
+  highlightedMessageIndices?: Set<number>;
+  currentHighlightIndex?: number;
+}
+
+function formatTime(date: Date): string {
+  return date.toLocaleTimeString('en-US', {
+    hour: '2-digit',
+    minute: '2-digit',
+    hour12: false,
+  });
+}
+
+function MessageBubble({
+  msg,
+  highlight,
+}: {
+  msg: Message;
+  highlight?: 'match' | 'current' | undefined;
+}) {
+  const isUser = msg.role === 'user';
+  const prefix = isUser ? '❯' : '◆';
+  const color = isUser ? 'green' : 'cyan';
+
+  const borderIndicator =
+    highlight === 'current' ? (
+      <Text color="yellowBright" bold>
+        ▌{' '}
+      </Text>
+    ) : highlight === 'match' ? (
+      <Text color="yellow">▌ </Text>
+    ) : null;
+
+  return (
+    <Box flexDirection="row" marginBottom={1}>
+      {borderIndicator}
+      <Box flexDirection="column">
+        <Box>
+          <Text bold color={color}>
+            {prefix}{' '}
+          </Text>
+          <Text bold color={color}>
+            {isUser ? 'you' : 'assistant'}
+          </Text>
+          <Text dimColor> {formatTime(msg.timestamp)}</Text>
+        </Box>
+        <Box marginLeft={2}>
+          <Text wrap="wrap">{msg.content}</Text>
+        </Box>
+      </Box>
+    </Box>
+  );
+}
+
+function ToolCallIndicator({ toolCall }: { toolCall: ToolCall }) {
+  const icon = toolCall.status === 'running' ? null : toolCall.status === 'success' ? '✓' : '✗';
+  const color =
+    toolCall.status === 'running' ? 'yellow' : toolCall.status === 'success' ? 'green' : 'red';
+
+  return (
+    <Box marginLeft={2}>
+      {toolCall.status === 'running' ? (
+        <Text color="yellow">
+          <Spinner type="dots" />
+        </Text>
+      ) : (
+        <Text color={color}>{icon}</Text>
+      )}
+      <Text dimColor> tool: </Text>
+      <Text color={color}>{toolCall.toolName}</Text>
+    </Box>
+  );
+}
+
+export function MessageList({
+  messages,
+  isStreaming,
+  currentStreamText,
+  currentThinkingText,
+  activeToolCalls,
+  scrollOffset,
+  viewportSize,
+  isScrolledUp,
+  highlightedMessageIndices,
+  currentHighlightIndex,
+}: MessageListProps) {
+  const useSlicing = scrollOffset != null && viewportSize != null;
+  const visibleMessages = useSlicing
+    ? messages.slice(scrollOffset, scrollOffset + viewportSize)
+    : messages;
+  const hiddenAbove = useSlicing ? scrollOffset : 0;
+
+  return (
+    <Box flexDirection="column" flexGrow={1} paddingX={1}>
+      {isScrolledUp && hiddenAbove > 0 && (
+        <Box justifyContent="center">
+          <Text dimColor>↑ {hiddenAbove} more messages ↑</Text>
+        </Box>
+      )}
+
+      {messages.length === 0 && !isStreaming && (
+        <Box justifyContent="center" marginY={1}>
+          <Text dimColor>No messages yet. Type below to start a conversation.</Text>
+        </Box>
+      )}
+
+      {visibleMessages.map((msg, i) => {
+        const globalIndex = hiddenAbove + i;
+        const highlight =
+          globalIndex === currentHighlightIndex
+            ? ('current' as const)
+            : highlightedMessageIndices?.has(globalIndex)
+              ? ('match' as const)
+              : undefined;
+        return <MessageBubble key={globalIndex} msg={msg} highlight={highlight} />;
+      })}
+
+      {/* Active thinking */}
+      {isStreaming && currentThinkingText && (
+        <Box flexDirection="column" marginBottom={1} marginLeft={2}>
+          <Text dimColor italic>
+            💭 {currentThinkingText}
+          </Text>
+        </Box>
+      )}
+
+      {/* Active tool calls */}
+      {activeToolCalls.length > 0 && (
+        <Box flexDirection="column" marginBottom={1}>
+          {activeToolCalls.map((tc) => (
+            <ToolCallIndicator key={tc.toolCallId} toolCall={tc} />
+          ))}
+        </Box>
+      )}
+
+      {/* Streaming response */}
+      {isStreaming && currentStreamText && (
+        <Box flexDirection="column" marginBottom={1}>
+          <Box>
+            <Text bold color="cyan">
+              ◆{' '}
+            </Text>
+            <Text bold color="cyan">
+              assistant
+            </Text>
+          </Box>
+          <Box marginLeft={2}>
+            <Text wrap="wrap">{currentStreamText}</Text>
+          </Box>
+        </Box>
+      )}
+
+      {/* Waiting spinner */}
+      {isStreaming && !currentStreamText && activeToolCalls.length === 0 && (
+        <Box marginLeft={2}>
+          <Text color="cyan">
+            <Spinner type="dots" />
+          </Text>
+          <Text dimColor> thinking…</Text>
+        </Box>
+      )}
+    </Box>
+  );
+}

packages/cli/src/tui/components/search-bar.tsx

@@ -0,0 +1,60 @@
+import React from 'react';
+import { Box, Text, useInput } from 'ink';
+import TextInput from 'ink-text-input';
+
+export interface SearchBarProps {
+  query: string;
+  onQueryChange: (q: string) => void;
+  totalMatches: number;
+  currentMatch: number;
+  onNext: () => void;
+  onPrev: () => void;
+  onClose: () => void;
+  focused: boolean;
+}
+
+export function SearchBar({
+  query,
+  onQueryChange,
+  totalMatches,
+  currentMatch,
+  onNext,
+  onPrev,
+  onClose,
+  focused,
+}: SearchBarProps) {
+  useInput(
+    (_input, key) => {
+      if (key.upArrow) {
+        onPrev();
+      }
+      if (key.downArrow) {
+        onNext();
+      }
+      if (key.escape) {
+        onClose();
+      }
+    },
+    { isActive: focused },
+  );
+
+  const borderColor = focused ? 'yellow' : 'gray';
+
+  const matchDisplay =
+    query.length >= 2
+      ? totalMatches > 0
+        ? `${String(currentMatch + 1)}/${String(totalMatches)}`
+        : 'no matches'
+      : '';
+
+  return (
+    <Box borderStyle="round" borderColor={borderColor} paddingX={1} flexDirection="row" gap={1}>
+      <Text>🔍</Text>
+      <Box flexGrow={1}>
+        <TextInput value={query} onChange={onQueryChange} focus={focused} />
+      </Box>
+      {matchDisplay && <Text dimColor>{matchDisplay}</Text>}
+      <Text dimColor>↑↓ navigate · Esc close</Text>
+    </Box>
+  );
+}

packages/cli/src/tui/components/sidebar.tsx

@@ -0,0 +1,143 @@
+import React from 'react';
+import { Box, Text, useInput } from 'ink';
+import type { ConversationSummary } from '../hooks/use-conversations.js';
+
+export interface SidebarProps {
+  conversations: ConversationSummary[];
+  activeConversationId: string | undefined;
+  selectedIndex: number;
+  onSelectIndex: (index: number) => void;
+  onSwitchConversation: (id: string) => void;
+  onDeleteConversation: (id: string) => void;
+  loading: boolean;
+  focused: boolean;
+  width: number;
+}
+
+function formatRelativeTime(dateStr: string): string {
+  const date = new Date(dateStr);
+  const now = new Date();
+  const diffMs = now.getTime() - date.getTime();
+  const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24));
+
+  if (diffDays === 0) {
+    const hh = String(date.getHours()).padStart(2, '0');
+    const mm = String(date.getMinutes()).padStart(2, '0');
+    return `${hh}:${mm}`;
+  }
+  if (diffDays < 7) {
+    return `${diffDays}d ago`;
+  }
+  const months = [
+    'Jan',
+    'Feb',
+    'Mar',
+    'Apr',
+    'May',
+    'Jun',
+    'Jul',
+    'Aug',
+    'Sep',
+    'Oct',
+    'Nov',
+    'Dec',
+  ];
+  const mon = months[date.getMonth()];
+  const dd = String(date.getDate()).padStart(2, '0');
+  return `${mon} ${dd}`;
+}
+
+function truncate(text: string, maxLen: number): string {
+  if (text.length <= maxLen) return text;
+  return text.slice(0, maxLen - 1) + '…';
+}
+
+export function Sidebar({
+  conversations,
+  activeConversationId,
+  selectedIndex,
+  onSelectIndex,
+  onSwitchConversation,
+  onDeleteConversation,
+  loading,
+  focused,
+  width,
+}: SidebarProps) {
+  useInput(
+    (_input, key) => {
+      if (key.upArrow) {
+        onSelectIndex(Math.max(0, selectedIndex - 1));
+      }
+      if (key.downArrow) {
+        onSelectIndex(Math.min(conversations.length - 1, selectedIndex + 1));
+      }
+      if (key.return) {
+        const conv = conversations[selectedIndex];
+        if (conv) {
+          onSwitchConversation(conv.id);
+        }
+      }
+      if (_input === 'd') {
+        const conv = conversations[selectedIndex];
+        if (conv) {
+          onDeleteConversation(conv.id);
+        }
+      }
+    },
+    { isActive: focused },
+  );
+
+  const borderColor = focused ? 'cyan' : 'gray';
+  // Available width for content inside border + padding
+  const innerWidth = width - 4; // 2 border + 2 padding
+
+  return (
+    <Box
+      flexDirection="column"
+      width={width}
+      borderStyle="single"
+      borderColor={borderColor}
+      paddingX={1}
+    >
+      <Text bold color="cyan">
+        Conversations
+      </Text>
+      <Box marginTop={0} flexDirection="column" flexGrow={1}>
+        {loading && conversations.length === 0 ? (
+          <Text dimColor>Loading…</Text>
+        ) : conversations.length === 0 ? (
+          <Text dimColor>No conversations</Text>
+        ) : (
+          conversations.map((conv, idx) => {
+            const isActive = conv.id === activeConversationId;
+            const isSelected = idx === selectedIndex && focused;
+            const marker = isActive ? '● ' : '  ';
+            const time = formatRelativeTime(conv.updatedAt);
+            const title = conv.title ?? 'Untitled';
+            // marker(2) + title + space(1) + time
+            const maxTitleLen = Math.max(4, innerWidth - marker.length - time.length - 1);
+            const displayTitle = truncate(title, maxTitleLen);
+
+            return (
+              <Box key={conv.id}>
+                <Text
+                  inverse={isSelected}
+                  color={isActive ? 'cyan' : undefined}
+                  dimColor={!isActive && !isSelected}
+                >
+                  {marker}
+                  {displayTitle}
+                  {' '.repeat(
+                    Math.max(0, innerWidth - marker.length - displayTitle.length - time.length),
+                  )}
+                  {time}
+                </Text>
+              </Box>
+            );
+          })
+        )}
+      </Box>
+      {focused && <Text dimColor>↑↓ navigate • enter switch • d delete</Text>}
+    </Box>
+  );
+}

packages/cli/src/tui/components/top-bar.tsx

@@ -0,0 +1,99 @@
+import React from 'react';
+import { Box, Text } from 'ink';
+
+export interface TopBarProps {
+  gatewayUrl: string;
+  version: string;
+  modelName: string | null;
+  thinkingLevel: string;
+  contextWindow: number;
+  agentName: string;
+  connected: boolean;
+  connecting: boolean;
+}
+
+/** Compact the URL — strip protocol */
+function compactHost(url: string): string {
+  return url.replace(/^https?:\/\//, '');
+}
+
+function formatContextWindow(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(0)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(0)}k`;
+  return String(n);
+}
+
+/**
+ * Mosaic 3×3 icon — brand tiles with black gaps (windmill cross pattern)
+ *
+ * Layout:
+ *   blue    ··    purple
+ *   ··      pink  ··
+ *   amber   ··    teal
+ */
+// Two-space gap between tiles (extracted to avoid prettier collapse)
+const GAP = '  ';
+
+function MosaicIcon() {
+  return (
+    <Box flexDirection="column" marginRight={2}>
+      <Text>
+        <Text color="#2f80ff">██</Text>
+        <Text>{GAP}</Text>
+        <Text color="#8b5cf6">██</Text>
+      </Text>
+      <Text>
+        <Text>{GAP}</Text>
+        <Text color="#ec4899">██</Text>
+      </Text>
+      <Text>
+        <Text color="#f59e0b">██</Text>
+        <Text>{GAP}</Text>
+        <Text color="#14b8a6">██</Text>
+      </Text>
+    </Box>
+  );
+}
+
+export function TopBar({
+  gatewayUrl,
+  version,
+  modelName,
+  thinkingLevel,
+  contextWindow,
+  agentName,
+  connected,
+  connecting,
+}: TopBarProps) {
+  const host = compactHost(gatewayUrl);
+  const connectionIndicator = connected ? '●' : '○';
+  const connectionColor = connected ? 'green' : connecting ? 'yellow' : 'red';
+
+  // Build model description line like: "claude-opus-4-6 (1M context) · default"
+  const modelDisplay = modelName ?? 'awaiting model';
+  const contextStr = contextWindow > 0 ? ` (${formatContextWindow(contextWindow)} context)` : '';
+  const thinkingStr = thinkingLevel !== 'off' ? ` · ${thinkingLevel}` : '';
+
+  return (
+    <Box paddingX={1} paddingY={0} marginBottom={1}>
+      <MosaicIcon />
+      <Box flexDirection="column" flexGrow={1}>
+        <Text>
+          <Text bold color="#56a0ff">
+            Mosaic Stack
+          </Text>
+          <Text dimColor> v{version}</Text>
+        </Text>
+        <Text dimColor>
+          {modelDisplay}
+          {contextStr}
+          {thinkingStr} · {agentName}
+        </Text>
+        <Text>
+          <Text color={connectionColor}>{connectionIndicator}</Text>
+          <Text dimColor> {host}</Text>
+        </Text>
+      </Box>
+    </Box>
+  );
+}

packages/cli/src/tui/hooks/use-app-mode.ts

@@ -0,0 +1,37 @@
+import { useState, useCallback } from 'react';
+
+export type AppMode = 'chat' | 'sidebar' | 'search';
+
+export interface UseAppModeReturn {
+  mode: AppMode;
+  setMode: (mode: AppMode) => void;
+  toggleSidebar: () => void;
+  sidebarOpen: boolean;
+}
+
+export function useAppMode(): UseAppModeReturn {
+  const [mode, setModeState] = useState<AppMode>('chat');
+  const [sidebarOpen, setSidebarOpen] = useState(false);
+
+  const setMode = useCallback((next: AppMode) => {
+    setModeState(next);
+    if (next === 'sidebar') {
+      setSidebarOpen(true);
+    }
+  }, []);
+
+  const toggleSidebar = useCallback(() => {
+    setSidebarOpen((prev) => {
+      if (prev) {
+        // Closing sidebar — return to chat
+        setModeState('chat');
+        return false;
+      }
+      // Opening sidebar — set mode to sidebar
+      setModeState('sidebar');
+      return true;
+    });
+  }, []);
+
+  return { mode, setMode, toggleSidebar, sidebarOpen };
+}

packages/cli/src/tui/hooks/use-conversations.ts

@@ -0,0 +1,139 @@
+import { useState, useEffect, useRef, useCallback } from 'react';
+
+export interface ConversationSummary {
+  id: string;
+  title: string | null;
+  archived: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface UseConversationsOptions {
+  gatewayUrl: string;
+  sessionCookie?: string;
+}
+
+export interface UseConversationsReturn {
+  conversations: ConversationSummary[];
+  loading: boolean;
+  error: string | null;
+  refresh: () => Promise<void>;
+  createConversation: (title?: string) => Promise<ConversationSummary | null>;
+  deleteConversation: (id: string) => Promise<boolean>;
+  renameConversation: (id: string, title: string) => Promise<boolean>;
+}
+
+export function useConversations(opts: UseConversationsOptions): UseConversationsReturn {
+  const { gatewayUrl, sessionCookie } = opts;
+
+  const [conversations, setConversations] = useState<ConversationSummary[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const mountedRef = useRef(true);
+
+  const headers = useCallback((): Record<string, string> => {
+    const h: Record<string, string> = { 'Content-Type': 'application/json' };
+    if (sessionCookie) h['Cookie'] = sessionCookie;
+    return h;
+  }, [sessionCookie]);
+
+  const refresh = useCallback(async () => {
+    if (!mountedRef.current) return;
+    setLoading(true);
+    setError(null);
+    try {
+      const res = await fetch(`${gatewayUrl}/api/conversations`, { headers: headers() });
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      const data = (await res.json()) as ConversationSummary[];
+      if (mountedRef.current) {
+        setConversations(data);
+      }
+    } catch (err) {
+      if (mountedRef.current) {
+        setError(err instanceof Error ? err.message : 'Unknown error');
+      }
+    } finally {
+      if (mountedRef.current) {
+        setLoading(false);
+      }
+    }
+  }, [gatewayUrl, headers]);
+
+  useEffect(() => {
+    mountedRef.current = true;
+    void refresh();
+    return () => {
+      mountedRef.current = false;
+    };
+  }, [refresh]);
+
+  const createConversation = useCallback(
+    async (title?: string): Promise<ConversationSummary | null> => {
+      try {
+        const res = await fetch(`${gatewayUrl}/api/conversations`, {
+          method: 'POST',
+          headers: headers(),
+          body: JSON.stringify({ title: title ?? null }),
+        });
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        const data = (await res.json()) as ConversationSummary;
+        if (mountedRef.current) {
+          setConversations((prev) => [data, ...prev]);
+        }
+        return data;
+      } catch {
+        return null;
+      }
+    },
+    [gatewayUrl, headers],
+  );
+
+  const deleteConversation = useCallback(
+    async (id: string): Promise<boolean> => {
+      try {
+        const res = await fetch(`${gatewayUrl}/api/conversations/${id}`, {
+          method: 'DELETE',
+          headers: headers(),
+        });
+        if (!res.ok) return false;
+        if (mountedRef.current) {
+          setConversations((prev) => prev.filter((c) => c.id !== id));
+        }
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    [gatewayUrl, headers],
+  );
+
+  const renameConversation = useCallback(
+    async (id: string, title: string): Promise<boolean> => {
+      try {
+        const res = await fetch(`${gatewayUrl}/api/conversations/${id}`, {
+          method: 'PATCH',
+          headers: headers(),
+          body: JSON.stringify({ title }),
+        });
+        if (!res.ok) return false;
+        if (mountedRef.current) {
+          setConversations((prev) => prev.map((c) => (c.id === id ? { ...c, title } : c)));
+        }
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    [gatewayUrl, headers],
+  );
+
+  return {
+    conversations,
+    loading,
+    error,
+    refresh,
+    createConversation,
+    deleteConversation,
+    renameConversation,
+  };
+}

packages/cli/src/tui/hooks/use-git-info.ts

@@ -0,0 +1,29 @@
+import { useState, useEffect } from 'react';
+import { execSync } from 'node:child_process';
+
+export interface GitInfo {
+  branch: string | null;
+  cwd: string;
+}
+
+export function useGitInfo(): GitInfo {
+  const [info, setInfo] = useState<GitInfo>({
+    branch: null,
+    cwd: process.cwd(),
+  });
+
+  useEffect(() => {
+    try {
+      const branch = execSync('git rev-parse --abbrev-ref HEAD', {
+        encoding: 'utf-8',
+        timeout: 3000,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      }).trim();
+      setInfo({ branch, cwd: process.cwd() });
+    } catch {
+      setInfo({ branch: null, cwd: process.cwd() });
+    }
+  }, []);
+
+  return info;
+}

packages/cli/src/tui/hooks/use-search.ts

@@ -0,0 +1,76 @@
+import { useState, useMemo, useCallback } from 'react';
+import type { Message } from './use-socket.js';
+
+export interface SearchMatch {
+  messageIndex: number;
+  charOffset: number;
+}
+
+export interface UseSearchReturn {
+  query: string;
+  setQuery: (q: string) => void;
+  matches: SearchMatch[];
+  currentMatchIndex: number;
+  nextMatch: () => void;
+  prevMatch: () => void;
+  clear: () => void;
+  totalMatches: number;
+}
+
+export function useSearch(messages: Message[]): UseSearchReturn {
+  const [query, setQuery] = useState('');
+  const [currentMatchIndex, setCurrentMatchIndex] = useState(0);
+
+  const matches = useMemo<SearchMatch[]>(() => {
+    if (query.length < 2) return [];
+
+    const lowerQuery = query.toLowerCase();
+    const result: SearchMatch[] = [];
+
+    for (let i = 0; i < messages.length; i++) {
+      const msg = messages[i];
+      if (!msg) continue;
+      const content = msg.content.toLowerCase();
+      let offset = 0;
+      while (true) {
+        const idx = content.indexOf(lowerQuery, offset);
+        if (idx === -1) break;
+        result.push({ messageIndex: i, charOffset: idx });
+        offset = idx + 1;
+      }
+    }
+
+    return result;
+  }, [query, messages]);
+
+  // Reset match index when matches change
+  useMemo(() => {
+    setCurrentMatchIndex(0);
+  }, [matches]);
+
+  const nextMatch = useCallback(() => {
+    if (matches.length === 0) return;
+    setCurrentMatchIndex((prev) => (prev + 1) % matches.length);
+  }, [matches.length]);
+
+  const prevMatch = useCallback(() => {
+    if (matches.length === 0) return;
+    setCurrentMatchIndex((prev) => (prev - 1 + matches.length) % matches.length);
+  }, [matches.length]);
+
+  const clear = useCallback(() => {
+    setQuery('');
+    setCurrentMatchIndex(0);
+  }, []);
+
+  return {
+    query,
+    setQuery,
+    matches,
+    currentMatchIndex,
+    nextMatch,
+    prevMatch,
+    clear,
+    totalMatches: matches.length,
+  };
+}

packages/cli/src/tui/hooks/use-socket.ts

@@ -0,0 +1,284 @@
+import { useState, useEffect, useRef, useCallback } from 'react';
+import { io, type Socket } from 'socket.io-client';
+import type {
+  ServerToClientEvents,
+  ClientToServerEvents,
+  MessageAckPayload,
+  AgentEndPayload,
+  AgentTextPayload,
+  AgentThinkingPayload,
+  ToolStartPayload,
+  ToolEndPayload,
+  SessionInfoPayload,
+  ErrorPayload,
+} from '@mosaic/types';
+
+export interface ToolCall {
+  toolCallId: string;
+  toolName: string;
+  status: 'running' | 'success' | 'error';
+}
+
+export interface Message {
+  role: 'user' | 'assistant' | 'thinking' | 'tool';
+  content: string;
+  timestamp: Date;
+  toolCalls?: ToolCall[];
+}
+
+export interface TokenUsage {
+  input: number;
+  output: number;
+  total: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cost: number;
+  contextPercent: number;
+  contextWindow: number;
+}
+
+export interface UseSocketOptions {
+  gatewayUrl: string;
+  sessionCookie?: string;
+  initialConversationId?: string;
+  initialModel?: string;
+  initialProvider?: string;
+}
+
+export interface UseSocketReturn {
+  connected: boolean;
+  connecting: boolean;
+  messages: Message[];
+  conversationId: string | undefined;
+  isStreaming: boolean;
+  currentStreamText: string;
+  currentThinkingText: string;
+  activeToolCalls: ToolCall[];
+  tokenUsage: TokenUsage;
+  modelName: string | null;
+  providerName: string | null;
+  thinkingLevel: string;
+  availableThinkingLevels: string[];
+  sendMessage: (content: string) => void;
+  setThinkingLevel: (level: string) => void;
+  switchConversation: (id: string) => void;
+  clearMessages: () => void;
+  connectionError: string | null;
+}
+
+type TypedSocket = Socket<ServerToClientEvents, ClientToServerEvents>;
+
+const EMPTY_USAGE: TokenUsage = {
+  input: 0,
+  output: 0,
+  total: 0,
+  cacheRead: 0,
+  cacheWrite: 0,
+  cost: 0,
+  contextPercent: 0,
+  contextWindow: 0,
+};
+
+export function useSocket(opts: UseSocketOptions): UseSocketReturn {
+  const { gatewayUrl, sessionCookie, initialConversationId, initialModel, initialProvider } = opts;
+
+  const [connected, setConnected] = useState(false);
+  const [connecting, setConnecting] = useState(true);
+  const [messages, setMessages] = useState<Message[]>([]);
+  const [conversationId, setConversationId] = useState(initialConversationId);
+  const [isStreaming, setIsStreaming] = useState(false);
+  const [currentStreamText, setCurrentStreamText] = useState('');
+  const [currentThinkingText, setCurrentThinkingText] = useState('');
+  const [activeToolCalls, setActiveToolCalls] = useState<ToolCall[]>([]);
+  const [tokenUsage, setTokenUsage] = useState<TokenUsage>(EMPTY_USAGE);
+  const [modelName, setModelName] = useState<string | null>(null);
+  const [providerName, setProviderName] = useState<string | null>(null);
+  const [thinkingLevel, setThinkingLevelState] = useState<string>('off');
+  const [availableThinkingLevels, setAvailableThinkingLevels] = useState<string[]>([]);
+  const [connectionError, setConnectionError] = useState<string | null>(null);
+
+  const socketRef = useRef<TypedSocket | null>(null);
+  const conversationIdRef = useRef(conversationId);
+  conversationIdRef.current = conversationId;
+
+  useEffect(() => {
+    const socket = io(`${gatewayUrl}/chat`, {
+      transports: ['websocket'],
+      extraHeaders: sessionCookie ? { Cookie: sessionCookie } : undefined,
+      reconnection: true,
+      reconnectionDelay: 2000,
+      reconnectionAttempts: Infinity,
+    }) as TypedSocket;
+
+    socketRef.current = socket;
+
+    socket.on('connect', () => {
+      setConnected(true);
+      setConnecting(false);
+      setConnectionError(null);
+    });
+
+    socket.on('disconnect', () => {
+      setConnected(false);
+      setIsStreaming(false);
+      setCurrentStreamText('');
+      setCurrentThinkingText('');
+      setActiveToolCalls([]);
+    });
+
+    socket.io.on('error', (err: Error) => {
+      setConnecting(false);
+      setConnectionError(err.message);
+    });
+
+    socket.on('message:ack', (data: MessageAckPayload) => {
+      setConversationId(data.conversationId);
+    });
+
+    socket.on('session:info', (data: SessionInfoPayload) => {
+      setProviderName(data.provider);
+      setModelName(data.modelId);
+      setThinkingLevelState(data.thinkingLevel);
+      setAvailableThinkingLevels(data.availableThinkingLevels);
+    });
+
+    socket.on('agent:start', () => {
+      setIsStreaming(true);
+      setCurrentStreamText('');
+      setCurrentThinkingText('');
+      setActiveToolCalls([]);
+    });
+
+    socket.on('agent:text', (data: AgentTextPayload) => {
+      setCurrentStreamText((prev) => prev + data.text);
+    });
+
+    socket.on('agent:thinking', (data: AgentThinkingPayload) => {
+      setCurrentThinkingText((prev) => prev + data.text);
+    });
+
+    socket.on('agent:tool:start', (data: ToolStartPayload) => {
+      setActiveToolCalls((prev) => [
+        ...prev,
+        { toolCallId: data.toolCallId, toolName: data.toolName, status: 'running' },
+      ]);
+    });
+
+    socket.on('agent:tool:end', (data: ToolEndPayload) => {
+      setActiveToolCalls((prev) =>
+        prev.map((tc) =>
+          tc.toolCallId === data.toolCallId
+            ? { ...tc, status: data.isError ? 'error' : 'success' }
+            : tc,
+        ),
+      );
+    });
+
+    socket.on('agent:end', (data: AgentEndPayload) => {
+      setCurrentStreamText((prev) => {
+        if (prev) {
+          setMessages((msgs) => [
+            ...msgs,
+            { role: 'assistant', content: prev, timestamp: new Date() },
+          ]);
+        }
+        return '';
+      });
+      setCurrentThinkingText('');
+      setActiveToolCalls([]);
+      setIsStreaming(false);
+
+      // Update usage from the payload
+      if (data.usage) {
+        setProviderName(data.usage.provider);
+        setModelName(data.usage.modelId);
+        setThinkingLevelState(data.usage.thinkingLevel);
+        setTokenUsage({
+          input: data.usage.tokens.input,
+          output: data.usage.tokens.output,
+          total: data.usage.tokens.total,
+          cacheRead: data.usage.tokens.cacheRead,
+          cacheWrite: data.usage.tokens.cacheWrite,
+          cost: data.usage.cost,
+          contextPercent: data.usage.context.percent ?? 0,
+          contextWindow: data.usage.context.window,
+        });
+      }
+    });
+
+    socket.on('error', (data: ErrorPayload) => {
+      setMessages((msgs) => [
+        ...msgs,
+        { role: 'assistant', content: `Error: ${data.error}`, timestamp: new Date() },
+      ]);
+      setIsStreaming(false);
+    });
+
+    return () => {
+      socket.disconnect();
+    };
+  }, [gatewayUrl, sessionCookie]);
+
+  const sendMessage = useCallback(
+    (content: string) => {
+      if (!content.trim() || isStreaming) return;
+      if (!socketRef.current?.connected) return;
+
+      setMessages((msgs) => [...msgs, { role: 'user', content, timestamp: new Date() }]);
+
+      socketRef.current.emit('message', {
+        conversationId,
+        content,
+        ...(initialProvider ? { provider: initialProvider } : {}),
+        ...(initialModel ? { modelId: initialModel } : {}),
+      });
+    },
+    [conversationId, isStreaming],
+  );
+
+  const setThinkingLevel = useCallback((level: string) => {
+    const cid = conversationIdRef.current;
+    if (!socketRef.current?.connected || !cid) return;
+    socketRef.current.emit('set:thinking', {
+      conversationId: cid,
+      level,
+    });
+  }, []);
+
+  const clearMessages = useCallback(() => {
+    setMessages([]);
+    setCurrentStreamText('');
+    setCurrentThinkingText('');
+    setActiveToolCalls([]);
+    setIsStreaming(false);
+  }, []);
+
+  const switchConversation = useCallback(
+    (id: string) => {
+      clearMessages();
+      setConversationId(id);
+    },
+    [clearMessages],
+  );
+
+  return {
+    connected,
+    connecting,
+    messages,
+    conversationId,
+    isStreaming,
+    currentStreamText,
+    currentThinkingText,
+    activeToolCalls,
+    tokenUsage,
+    modelName,
+    providerName,
+    thinkingLevel,
+    availableThinkingLevels,
+    sendMessage,
+    setThinkingLevel,
+    switchConversation,
+    clearMessages,
+    connectionError,
+  };
+}

packages/cli/src/tui/hooks/use-viewport.ts

@@ -0,0 +1,80 @@
+import { useState, useCallback, useEffect } from 'react';
+import { useStdout } from 'ink';
+
+export interface UseViewportOptions {
+  totalItems: number;
+  reservedLines?: number;
+}
+
+export interface UseViewportReturn {
+  scrollOffset: number;
+  viewportSize: number;
+  isScrolledUp: boolean;
+  scrollToBottom: () => void;
+  scrollBy: (delta: number) => void;
+  scrollTo: (offset: number) => void;
+  canScrollUp: boolean;
+  canScrollDown: boolean;
+}
+
+export function useViewport({
+  totalItems,
+  reservedLines = 10,
+}: UseViewportOptions): UseViewportReturn {
+  const { stdout } = useStdout();
+  const rows = stdout?.rows ?? 24;
+  const viewportSize = Math.max(1, rows - reservedLines);
+
+  const [scrollOffset, setScrollOffset] = useState(0);
+  const [autoFollow, setAutoFollow] = useState(true);
+
+  // Compute the maximum valid scroll offset
+  const maxOffset = Math.max(0, totalItems - viewportSize);
+
+  // Auto-follow: when new items arrive and auto-follow is on, snap to bottom
+  useEffect(() => {
+    if (autoFollow) {
+      setScrollOffset(maxOffset);
+    }
+  }, [autoFollow, maxOffset]);
+
+  const scrollTo = useCallback(
+    (offset: number) => {
+      const clamped = Math.max(0, Math.min(offset, maxOffset));
+      setScrollOffset(clamped);
+      setAutoFollow(clamped >= maxOffset);
+    },
+    [maxOffset],
+  );
+
+  const scrollBy = useCallback(
+    (delta: number) => {
+      setScrollOffset((prev) => {
+        const next = Math.max(0, Math.min(prev + delta, maxOffset));
+        setAutoFollow(next >= maxOffset);
+        return next;
+      });
+    },
+    [maxOffset],
+  );
+
+  const scrollToBottom = useCallback(() => {
+    setScrollOffset(maxOffset);
+    setAutoFollow(true);
+  }, [maxOffset]);
+
+  const isScrolledUp = scrollOffset < maxOffset;
+  const canScrollUp = scrollOffset > 0;
+  const canScrollDown = scrollOffset < maxOffset;
+
+  return {
+    scrollOffset,
+    viewportSize,
+    isScrolledUp,
+    scrollToBottom,
+    scrollBy,
+    scrollTo,
+    canScrollUp,
+    canScrollDown,
+  };
+}