botholomew 0.16.0 → 0.16.3

package/src/tui/hooks/useAppKeybindings.ts

@@ -0,0 +1,166 @@
+import { useInput } from "ink";
+import {
+  type Dispatch,
+  type MutableRefObject,
+  type SetStateAction,
+  useCallback,
+  useRef,
+} from "react";
+import { abortActiveStream, type ChatSession } from "../../chat/session.ts";
+import type { SlashCommand } from "../../skills/commands.ts";
+import type { TabId } from "../components/TabBar.tsx";
+import { TAB_BY_CTRL_KEY } from "../keys.ts";
+import { getSlashMatches } from "../slashCompletion.ts";
+import type { QueueEntry } from "./useMessageQueue.ts";
+
+interface UseAppKeybindingsParams {
+  activeTab: TabId;
+  setActiveTab: Dispatch<SetStateAction<TabId>>;
+  performShutdown: () => Promise<void>;
+  sessionRef: MutableRefObject<ChatSession | null>;
+  processingRef: MutableRefObject<boolean>;
+  queueRef: MutableRefObject<QueueEntry[]>;
+  queuedMessages: string[];
+  selectedQueueIndex: number;
+  setSelectedQueueIndex: Dispatch<SetStateAction<number>>;
+  setInputValue: Dispatch<SetStateAction<string>>;
+  syncQueue: () => void;
+  slashCommandsRef: MutableRefObject<SlashCommand[]>;
+  inputValueRef: MutableRefObject<string>;
+  markActivityRef: MutableRefObject<() => void>;
+}
+
+export function useAppKeybindings({
+  activeTab,
+  setActiveTab,
+  performShutdown,
+  sessionRef,
+  processingRef,
+  queueRef,
+  queuedMessages,
+  selectedQueueIndex,
+  setSelectedQueueIndex,
+  setInputValue,
+  syncQueue,
+  slashCommandsRef,
+  inputValueRef,
+  markActivityRef,
+}: UseAppKeybindingsParams): void {
+  // Stable refs for the input handler — same pattern as InputBar to prevent
+  // Ink's useInput from re-registering stdin listeners on every render.
+  const activeTabRef = useRef(activeTab);
+  const queuedMessagesRef = useRef(queuedMessages);
+  const selectedQueueIndexRef = useRef(selectedQueueIndex);
+  activeTabRef.current = activeTab;
+  queuedMessagesRef.current = queuedMessages;
+  selectedQueueIndexRef.current = selectedQueueIndex;
+
+  const handler = useCallback(
+    // biome-ignore lint/suspicious/noExplicitAny: Ink's Key type is not exported
+    (input: string, key: any) => {
+      markActivityRef.current();
+
+      // Ctrl+C exits. Routed through performShutdown so the in-flight LLM
+      // stream is aborted and mcpx is closed before we unmount Ink — without
+      // that, one Ctrl-C prints the goodbye but the process stays pinned by
+      // the open HTTPS socket and a second Ctrl-C is needed.
+      if (input === "c" && key.ctrl) {
+        void performShutdown();
+        return;
+      }
+
+      // Ctrl+<letter> jumps directly to a tab from any tab. On Chat, only
+      // suppress these if the slash-autocomplete popup needs the keystroke
+      // (Ctrl combos don't drive the popup, but keep the guard symmetric
+      // with the previous Tab-cycle behavior).
+      if (key.ctrl) {
+        const tabForKey = TAB_BY_CTRL_KEY[input];
+        if (tabForKey !== undefined) {
+          if (activeTabRef.current === 1) {
+            const popupOpen = getSlashMatches(
+              inputValueRef.current,
+              slashCommandsRef.current,
+            );
+            if (popupOpen) return;
+            // Ctrl+E edits a queued message when one is selected; only
+            // fall through to the Threads tab-jump when the queue is empty.
+            if (input === "e" && queuedMessagesRef.current.length > 0) {
+              // handled by the queue keybindings block below
+            } else {
+              setActiveTab(tabForKey);
+              return;
+            }
+          } else {
+            setActiveTab(tabForKey);
+            return;
+          }
+        }
+      }
+
+      const tab = activeTabRef.current;
+
+      // Esc on Chat tab while a turn is in flight: steer / interrupt.
+      // Calls MessageStream.abort() at the SDK layer; tools already running
+      // finish normally, but no further LLM turn is started.
+      if (key.escape && tab === 1 && processingRef.current) {
+        const session = sessionRef.current;
+        if (session) {
+          abortActiveStream(session);
+          return;
+        }
+      }
+
+      // Queue manipulation keybindings (only when queue has items on Chat tab)
+      const queue = queuedMessagesRef.current;
+      if (tab === 1 && queue.length > 0 && key.ctrl) {
+        if (input === "j") {
+          setSelectedQueueIndex((i) => Math.min(i + 1, queue.length - 1));
+          return;
+        }
+        if (input === "k") {
+          setSelectedQueueIndex((i) => Math.max(i - 1, 0));
+          return;
+        }
+        if (input === "x") {
+          queueRef.current.splice(selectedQueueIndexRef.current, 1);
+          syncQueue();
+          return;
+        }
+        if (input === "e") {
+          const [msg] = queueRef.current.splice(
+            selectedQueueIndexRef.current,
+            1,
+          );
+          syncQueue();
+          if (msg) {
+            setInputValue(msg.display);
+          }
+          return;
+        }
+      }
+
+      if (tab !== 1) {
+        // Escape returns to chat
+        if (key.escape) {
+          setActiveTab(1);
+          return;
+        }
+      }
+    },
+    [
+      performShutdown,
+      sessionRef,
+      processingRef,
+      queueRef,
+      setActiveTab,
+      setSelectedQueueIndex,
+      setInputValue,
+      syncQueue,
+      slashCommandsRef,
+      inputValueRef,
+      markActivityRef,
+    ],
+  );
+
+  useInput(handler);
+}

package/src/tui/hooks/useCaptureTabCycle.ts

@@ -0,0 +1,28 @@
+import { type Dispatch, type SetStateAction, useEffect } from "react";
+import type { TabId } from "../components/TabBar.tsx";
+
+// Capture-mode tab auto-cycle. Under VHS/ttyd the Tab key doesn't reliably
+// reach Ink, so a docs tape can't drive the tab tour by keystroke. When
+// BOTHOLOMEW_CAPTURE_TAB_CYCLE is set, schedule timers that walk through
+// every tab so a single recording can show all panels.
+//
+// Format: "dwellMs" or "dwellMs:startDelayMs". The optional start delay
+// lets a tape finish a streamed chat reply before the cycle kicks in.
+export function useCaptureTabCycle(
+  setActiveTab: Dispatch<SetStateAction<TabId>>,
+): void {
+  useEffect(() => {
+    const spec = process.env.BOTHOLOMEW_CAPTURE_TAB_CYCLE;
+    if (!spec) return;
+    const [dwellRaw, delayRaw] = spec.split(":");
+    const dwellMs = Number.parseInt(dwellRaw ?? "", 10) || 2500;
+    const startDelayMs = Number.parseInt(delayRaw ?? "", 10) || 0;
+    const sequence: TabId[] = [2, 3, 4, 5, 6, 7, 8, 1];
+    const timers = sequence.map((tab, i) =>
+      setTimeout(() => setActiveTab(tab), startDelayMs + dwellMs * (i + 1)),
+    );
+    return () => {
+      for (const t of timers) clearTimeout(t);
+    };
+  }, [setActiveTab]);
+}

package/src/tui/hooks/useChatSession.ts

@@ -0,0 +1,151 @@
+import { useApp } from "ink";
+import {
+  type Dispatch,
+  type MutableRefObject,
+  type SetStateAction,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+import {
+  abortActiveStream,
+  type ChatSession,
+  endChatSession,
+  startChatSession,
+} from "../../chat/session.ts";
+import { getThread } from "../../threads/store.ts";
+import type { ChatMessage } from "../components/MessageList.tsx";
+import { msgId } from "../messages.ts";
+import { restoreMessagesFromInteractions } from "../restoreMessages.ts";
+import { ansi } from "../theme.ts";
+
+interface UseChatSessionParams {
+  projectDir: string;
+  resumeThreadId: string | undefined;
+  initialPrompt: string | undefined;
+  setMessages: Dispatch<SetStateAction<ChatMessage[]>>;
+  setError: Dispatch<SetStateAction<string | null>>;
+}
+
+interface UseChatSessionResult {
+  sessionRef: MutableRefObject<ChatSession | null>;
+  ready: boolean;
+  splashDone: boolean;
+  performShutdown: () => Promise<void>;
+}
+
+export function useChatSession({
+  projectDir,
+  resumeThreadId,
+  initialPrompt,
+  setMessages,
+  setError,
+}: UseChatSessionParams): UseChatSessionResult {
+  const { exit } = useApp();
+  const [ready, setReady] = useState(false);
+  const skipSplash = !!(resumeThreadId || initialPrompt);
+  const [splashDone, setSplashDone] = useState(skipSplash);
+  const sessionRef = useRef<ChatSession | null>(null);
+  const shuttingDownRef = useRef(false);
+
+  // Initialize session
+  useEffect(() => {
+    let cancelled = false;
+
+    startChatSession(projectDir, resumeThreadId)
+      .then(async (session) => {
+        if (cancelled) {
+          endChatSession(session);
+          return;
+        }
+        sessionRef.current = session;
+
+        if (resumeThreadId) {
+          // Always hydrate on resume so the Tools tab and chat history
+          // pick up prior tool_use/tool_result rows from the CSV — even if
+          // the thread has no plain message-kind interactions yet.
+          const threadData = await getThread(
+            session.projectDir,
+            session.threadId,
+          );
+          if (threadData) {
+            setMessages(
+              restoreMessagesFromInteractions(threadData.interactions),
+            );
+          }
+        }
+
+        setMessages((prev) => [
+          ...prev,
+          {
+            id: msgId(),
+            role: "system" as const,
+            content:
+              "Switch panels with Ctrl+<letter> (^a chat · ^o tools · ^n context · ^t tasks · ^r threads · ^s schedules · ^w workers) — `?` for help. Type /help for commands.",
+            timestamp: new Date(),
+          },
+        ]);
+
+        setReady(true);
+      })
+      .catch((err) => {
+        setError(`Failed to start session: ${err}`);
+      });
+
+    return () => {
+      cancelled = true;
+      // Fire-and-forget safety net: only triggers when unmount happens via a
+      // path that didn't go through performShutdown (which nulls sessionRef
+      // first). React doesn't await unmount cleanups, so the goodbye lands
+      // before mcpx finishes closing — that's fine for non-Ctrl-C paths.
+      if (sessionRef.current) {
+        const session = sessionRef.current;
+        const threadId = session.threadId;
+        abortActiveStream(session);
+        void endChatSession(session);
+        process.stderr.write(
+          `\nThread: ${threadId}\nResume with: ${ansi.success}botholomew chat --thread-id ${threadId}${ansi.reset}\nBye!\n`,
+        );
+      }
+    };
+  }, [projectDir, resumeThreadId, setMessages, setError]);
+
+  const performShutdown = useCallback(async () => {
+    if (shuttingDownRef.current) {
+      // Second Ctrl-C while cleanup is in flight — give the user an escape
+      // hatch. 130 = standard SIGINT exit code.
+      process.exit(130);
+    }
+    shuttingDownRef.current = true;
+
+    const session = sessionRef.current;
+    // Null the ref so the useEffect cleanup that runs on Ink unmount becomes
+    // a no-op — otherwise it would double-print the goodbye and double-close
+    // the mcpx client.
+    sessionRef.current = null;
+
+    if (session) {
+      const threadId = session.threadId;
+      abortActiveStream(session);
+      try {
+        await endChatSession(session);
+      } catch {
+        // Best-effort: the user pressed Ctrl-C, surfacing a stack trace here
+        // would just hide the goodbye line.
+      }
+      process.stderr.write(
+        `\nThread: ${threadId}\nResume with: ${ansi.success}botholomew chat --thread-id ${threadId}${ansi.reset}\nBye!\n`,
+      );
+    }
+    exit();
+  }, [exit]);
+
+  // Minimum splash screen duration
+  useEffect(() => {
+    const timer = setTimeout(() => setSplashDone(true), 2000);
+    return () => clearTimeout(timer);
+  }, []);
+
+  return { sessionRef, ready, splashDone, performShutdown };
+}

package/src/tui/hooks/useChatTitlePolling.ts

@@ -0,0 +1,36 @@
+import { type MutableRefObject, useEffect, useState } from "react";
+import type { ChatSession } from "../../chat/session.ts";
+import { getThread } from "../../threads/store.ts";
+
+export function useChatTitlePolling(
+  ready: boolean,
+  sessionRef: MutableRefObject<ChatSession | null>,
+): {
+  chatTitle: string | undefined;
+  setChatTitle: (t: string | undefined) => void;
+} {
+  const [chatTitle, setChatTitle] = useState<string | undefined>(undefined);
+
+  useEffect(() => {
+    if (!ready || !sessionRef.current) return;
+    let mounted = true;
+
+    const refreshTitle = async () => {
+      const session = sessionRef.current;
+      if (!session) return;
+      const result = await getThread(session.projectDir, session.threadId);
+      if (mounted && result?.thread.title) {
+        setChatTitle(result.thread.title);
+      }
+    };
+
+    refreshTitle();
+    const interval = setInterval(refreshTitle, 5000);
+    return () => {
+      mounted = false;
+      clearInterval(interval);
+    };
+  }, [ready, sessionRef]);
+
+  return { chatTitle, setChatTitle };
+}

package/src/tui/hooks/useMessageQueue.ts

@@ -0,0 +1,254 @@
+import {
+  type Dispatch,
+  type MutableRefObject,
+  type SetStateAction,
+  useCallback,
+  useRef,
+  useState,
+} from "react";
+import { type ChatSession, sendMessage } from "../../chat/session.ts";
+import type { ContextUsage } from "../../chat/usage.ts";
+import type { ChatMessage } from "../components/MessageList.tsx";
+import type { ToolCallData } from "../components/ToolCall.tsx";
+import { msgId } from "../messages.ts";
+
+export interface QueueEntry {
+  display: string;
+  content: string;
+}
+
+interface UseMessageQueueParams {
+  sessionRef: MutableRefObject<ChatSession | null>;
+  setMessages: Dispatch<SetStateAction<ChatMessage[]>>;
+  markActivityRef: MutableRefObject<() => void>;
+}
+
+export interface UseMessageQueueResult {
+  queueRef: MutableRefObject<QueueEntry[]>;
+  processingRef: MutableRefObject<boolean>;
+  queuedMessages: string[];
+  selectedQueueIndex: number;
+  setSelectedQueueIndex: Dispatch<SetStateAction<number>>;
+  syncQueue: () => void;
+  processQueue: () => Promise<void>;
+  isLoading: boolean;
+  streamingText: string;
+  activeToolCalls: ToolCallData[];
+  preparingTool: { id: string; name: string } | null;
+  streamStartedAt: Date | null;
+  usage: ContextUsage | null;
+  setUsage: Dispatch<SetStateAction<ContextUsage | null>>;
+  clearStreamingState: () => void;
+}
+
+export function useMessageQueue({
+  sessionRef,
+  setMessages,
+  markActivityRef,
+}: UseMessageQueueParams): UseMessageQueueResult {
+  const queueRef = useRef<QueueEntry[]>([]);
+  const processingRef = useRef(false);
+  const [queuedMessages, setQueuedMessages] = useState<string[]>([]);
+  const [selectedQueueIndex, setSelectedQueueIndex] = useState(0);
+  const [isLoading, setIsLoading] = useState(false);
+  const [streamingText, setStreamingText] = useState("");
+  const [activeToolCalls, setActiveToolCalls] = useState<ToolCallData[]>([]);
+  const [streamStartedAt, setStreamStartedAt] = useState<Date | null>(null);
+  const [preparingTool, setPreparingTool] = useState<{
+    id: string;
+    name: string;
+  } | null>(null);
+  const [usage, setUsage] = useState<ContextUsage | null>(null);
+
+  const syncQueue = useCallback(() => {
+    const snapshot = queueRef.current.map((e) => e.display);
+    setQueuedMessages(snapshot);
+    setSelectedQueueIndex((prev) =>
+      snapshot.length === 0 ? 0 : Math.min(prev, snapshot.length - 1),
+    );
+  }, []);
+
+  const clearStreamingState = useCallback(() => {
+    setStreamingText("");
+    setActiveToolCalls([]);
+    setPreparingTool(null);
+    setStreamStartedAt(null);
+  }, []);
+
+  const processQueue = useCallback(async () => {
+    if (processingRef.current || !sessionRef.current) return;
+    processingRef.current = true;
+
+    while (queueRef.current.length > 0) {
+      const entry = queueRef.current.shift();
+      syncQueue();
+      if (!entry) break;
+      setIsLoading(true);
+      setStreamingText("");
+      setActiveToolCalls([]);
+      setPreparingTool(null);
+      setStreamStartedAt(new Date());
+
+      const userMsg: ChatMessage = {
+        id: msgId(),
+        role: "user",
+        content: entry.display,
+        timestamp: new Date(),
+      };
+      setMessages((prev) => [...prev, userMsg]);
+
+      let pendingToolCalls: ToolCallData[] = [];
+      let currentText = "";
+
+      const finalizeSegment = () => {
+        if (currentText || pendingToolCalls.length > 0) {
+          const assistantMsg: ChatMessage = {
+            id: msgId(),
+            role: "assistant",
+            content: currentText,
+            timestamp: new Date(),
+            toolCalls:
+              pendingToolCalls.length > 0 ? [...pendingToolCalls] : undefined,
+          };
+          setMessages((prev) => [...prev, assistantMsg]);
+          currentText = "";
+          pendingToolCalls = [];
+          setStreamingText("");
+          setActiveToolCalls([]);
+          setStreamStartedAt(new Date());
+        }
+      };
+
+      let lastStreamFlush = 0;
+      try {
+        await sendMessage(sessionRef.current, entry.content, {
+          onToken: (token) => {
+            currentText += token;
+            const now = Date.now();
+            if (now - lastStreamFlush >= 50) {
+              setStreamingText(currentText);
+              lastStreamFlush = now;
+              markActivityRef.current();
+            }
+          },
+          onToolPreparing: (id, name) => {
+            markActivityRef.current();
+            setPreparingTool({ id, name });
+          },
+          onToolStart: (id, name, input) => {
+            markActivityRef.current();
+            if (currentText) {
+              finalizeSegment();
+            }
+            const tc: ToolCallData = {
+              id,
+              name,
+              input,
+              running: true,
+              timestamp: new Date(),
+            };
+            pendingToolCalls = [...pendingToolCalls, tc];
+            setActiveToolCalls(pendingToolCalls);
+            setPreparingTool(null);
+          },
+          onToolEnd: (id, _name, output, isError, meta) => {
+            markActivityRef.current();
+            // Replace the matched entry with a new object so its identity
+            // changes (memoized ToolCall children rely on this); other entries
+            // keep their reference and skip re-render.
+            pendingToolCalls = pendingToolCalls.map((t) =>
+              t.id === id
+                ? {
+                    ...t,
+                    running: false,
+                    output,
+                    isError,
+                    ...(meta?.largeResult
+                      ? { largeResult: meta.largeResult }
+                      : {}),
+                  }
+                : t,
+            );
+            setActiveToolCalls(pendingToolCalls);
+          },
+          onToolNotify: (id, message) => {
+            markActivityRef.current();
+            let touched = false;
+            pendingToolCalls = pendingToolCalls.map((t) => {
+              if (t.id !== id) return t;
+              touched = true;
+              return { ...t, notes: [...(t.notes ?? []), message] };
+            });
+            if (touched) setActiveToolCalls(pendingToolCalls);
+          },
+          onUsage: (info) => {
+            setUsage(info);
+          },
+          takeInjections: () => {
+            // Drain queued messages into the running turn so the agent sees
+            // them on the next LLM call instead of after the whole tool loop.
+            // Finalize the in-flight assistant segment first so the new user
+            // bubbles render in the right order in the chat view.
+            if (queueRef.current.length === 0) return [];
+            if (currentText || pendingToolCalls.length > 0) {
+              finalizeSegment();
+            }
+            const drained = queueRef.current.splice(0);
+            syncQueue();
+            for (const e of drained) {
+              const userMsg: ChatMessage = {
+                id: msgId(),
+                role: "user",
+                content: e.display,
+                timestamp: new Date(),
+              };
+              setMessages((prev) => [...prev, userMsg]);
+            }
+            return drained.map((e) => e.content);
+          },
+        });
+
+        if (sessionRef.current?.aborted) {
+          currentText += currentText
+            ? "\n\n_(steered — response interrupted)_"
+            : "_(steered — no response)_";
+        }
+        finalizeSegment();
+      } catch (err) {
+        const errorMsg: ChatMessage = {
+          id: msgId(),
+          role: "system",
+          content: `Error: ${err}`,
+          timestamp: new Date(),
+        };
+        setMessages((prev) => [...prev, errorMsg]);
+      } finally {
+        setStreamingText("");
+        setActiveToolCalls([]);
+        setPreparingTool(null);
+        setStreamStartedAt(null);
+      }
+    }
+
+    setIsLoading(false);
+    processingRef.current = false;
+  }, [sessionRef, setMessages, markActivityRef, syncQueue]);
+
+  return {
+    queueRef,
+    processingRef,
+    queuedMessages,
+    selectedQueueIndex,
+    setSelectedQueueIndex,
+    syncQueue,
+    processQueue,
+    isLoading,
+    streamingText,
+    activeToolCalls,
+    preparingTool,
+    streamStartedAt,
+    usage,
+    setUsage,
+    clearStreamingState,
+  };
+}

package/src/tui/hooks/useTerminalRows.ts

@@ -0,0 +1,20 @@
+import { useStdout } from "ink";
+import { useEffect, useState } from "react";
+
+// Track the terminal's row count so the dynamic frame stays strictly below
+// fullscreen. Ink 7 wipes scrollback whenever the dynamic frame is overflowing
+// or transitions out of fullscreen — so as long as the rendered output height
+// stays < `rows` on every render, scrollback is preserved.
+export function useTerminalRows(): number {
+  const { stdout } = useStdout();
+  const [rows, setRows] = useState(stdout?.rows ?? 24);
+  useEffect(() => {
+    if (!stdout) return;
+    const onResize = () => setRows(stdout.rows ?? 24);
+    stdout.on("resize", onResize);
+    return () => {
+      stdout.off("resize", onResize);
+    };
+  }, [stdout]);
+  return rows;
+}

package/src/tui/keys.ts

@@ -0,0 +1,24 @@
+import type { TabId } from "./components/TabBar.tsx";
+
+// Tab routing: Ctrl+<letter> jumps to a tab. Chosen for memorability — first
+// available letter that doesn't collide with other Ctrl bindings (Ctrl+C exit,
+// Ctrl+J/K/X/E queue ops on Chat).
+//
+// Help is bound to Ctrl+G rather than Ctrl+H because most terminals deliver
+// Ctrl+H as ASCII 0x08 (backspace). Bonus: macOS Terminal.app and several
+// other terminals map Ctrl+/ to BEL (0x07), the same byte as Ctrl+G — so this
+// binding also catches the Ctrl+/ keystroke on those terminals "for free".
+// We also accept "/" and "_" as fallbacks for terminals that deliver Ctrl+/
+// as 0x1F or as the literal "/" with ctrl=true (Kitty keyboard protocol).
+export const TAB_BY_CTRL_KEY: Record<string, TabId> = {
+  a: 1, // ch[a]t
+  o: 2, // t[o]ols
+  n: 3, // co[n]text
+  t: 4, // [t]asks
+  e: 5, // thr[e]ads
+  s: 6, // [s]chedules
+  w: 7, // [w]orkers
+  g: 8, // help (also catches Ctrl+/ on terminals that map it to BEL)
+  "/": 8, // help (Kitty keyboard protocol)
+  _: 8, // help (terminals that send Ctrl+/ as 0x1F)
+};

package/src/tui/messages.ts

@@ -0,0 +1,11 @@
+// Conservative line reservation for the bottom chrome — StatusBar (1) +
+// bordered InputBar (3) + multiline hint (1) + TabBar (1) + slack for the
+// SlashCommandPopup or QueuePanel (~4). The chat-tab body's `maxHeight` and
+// the panel boxes' `height` both subtract this from `rows` so the dynamic
+// frame's total output stays strictly below the viewport.
+export const FOOTER_RESERVE = 10;
+
+let nextMsgId = 0;
+export function msgId(): string {
+  return `msg-${++nextMsgId}`;
+}