minimal-agent 0.10.0 → 0.12.0

package/src/ui/hooks/useInputHistory.ts

@@ -0,0 +1,235 @@
+/**
+ * ============================================================
+ *  src/ui/hooks/useInputHistory.ts —— 输入历史 ring buffer + 持久化
+ * ------------------------------------------------------------
+ *  - ring buffer 上限 50 条
+ *  - 持久化 ~/.minimal-agent/input-history.txt（一行一条 UTF-8）
+ *    转义 `\\` → `\\\\`，`\n` → `\\n`，避免多行输入被换行符撕碎
+ *  - API：push / prev / next / search / resetCursor
+ *  - 核心逻辑抽到 createInputHistoryStore，方便测试 DI 注入 fs
+ *    hook 自身只是 useRef + useEffect 包一下，渲染零依赖
+ * ============================================================
+ */
+
+import { useEffect, useMemo, useRef } from 'react';
+import { mkdir as fsMkdir, readFile as fsReadFile, writeFile as fsWriteFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+export interface InputHistoryHook {
+  /** 提交后追加；连续重复自动去重 */
+  push(text: string): void;
+  /** 向更老翻；到顶返 null */
+  prev(): string | null;
+  /** 向更新翻；到底返 null（UI 收到 null 自行决定是否清空显示） */
+  next(): string | null;
+  /** 反向匹配，最近优先 */
+  search(query: string): string[];
+  /** 提交后游标回到 length，下次按 ↑ 又从最新开始 */
+  resetCursor(): void;
+}
+
+const MAX_ITEMS = 50;
+const WRITE_DEBOUNCE_MS = 500;
+
+/* ------------------------------------------------------------ *
+ *  转义：换行 + 反斜杠
+ * ------------------------------------------------------------ */
+
+export function encodeHistoryLine(text: string): string {
+  return text.replace(/\\/g, '\\\\').replace(/\n/g, '\\n');
+}
+
+export function decodeHistoryLine(line: string): string {
+  // 状态机：遇到 \ 看下一个字符决定 \\ → \  或  \n → 真换行
+  let out = '';
+  let i = 0;
+  while (i < line.length) {
+    const ch = line[i];
+    if (ch === '\\' && i + 1 < line.length) {
+      const nxt = line[i + 1];
+      if (nxt === '\\') {
+        out += '\\';
+        i += 2;
+        continue;
+      }
+      if (nxt === 'n') {
+        out += '\n';
+        i += 2;
+        continue;
+      }
+    }
+    out += ch;
+    i += 1;
+  }
+  return out;
+}
+
+/* ------------------------------------------------------------ *
+ *  纯 store —— 不依赖 React，便于单测
+ * ------------------------------------------------------------ */
+
+export interface InputHistoryStoreOptions {
+  fs?: {
+    readFile: (path: string) => Promise<string>;
+    writeFile: (path: string, data: string) => Promise<void>;
+    mkdir: (path: string, opts: { recursive: boolean }) => Promise<void>;
+  };
+  historyPath?: string;
+  /** 测试可注入 0 关掉防抖 */
+  writeDebounceMs?: number;
+}
+
+export interface InputHistoryStore extends InputHistoryHook {
+  /** 异步从磁盘填充 buffer；测试可显式 await */
+  load(): Promise<void>;
+  /** 测试用：等待防抖写盘 flush */
+  flush(): Promise<void>;
+  /** 测试观察用 */
+  _snapshot(): { buffer: string[]; cursor: number };
+}
+
+export function createInputHistoryStore(
+  opts: InputHistoryStoreOptions = {},
+): InputHistoryStore {
+  const fs = opts.fs ?? {
+    readFile: (p: string) => fsReadFile(p, 'utf8'),
+    writeFile: (p: string, d: string) => fsWriteFile(p, d, 'utf8'),
+    mkdir: (p: string, o: { recursive: boolean }) => fsMkdir(p, o).then(() => undefined),
+  };
+  const historyPath =
+    opts.historyPath ?? join(homedir(), '.minimal-agent', 'input-history.txt');
+  const debounceMs = opts.writeDebounceMs ?? WRITE_DEBOUNCE_MS;
+
+  let buffer: string[] = [];
+  let cursor = 0;
+  let writeTimer: ReturnType<typeof setTimeout> | null = null;
+  let pendingWrite: Promise<void> | null = null;
+
+  async function doWrite(): Promise<void> {
+    try {
+      await fs.mkdir(dirname(historyPath), { recursive: true });
+      const data = buffer.map(encodeHistoryLine).join('\n');
+      await fs.writeFile(historyPath, data);
+    } catch {
+      // 持久化失败不影响 UI；下次 push 还会再试
+    }
+  }
+
+  function scheduleWrite(): void {
+    if (debounceMs <= 0) {
+      pendingWrite = doWrite();
+      return;
+    }
+    if (writeTimer) clearTimeout(writeTimer);
+    writeTimer = setTimeout(() => {
+      writeTimer = null;
+      pendingWrite = doWrite();
+    }, debounceMs);
+  }
+
+  return {
+    async load() {
+      try {
+        const raw = await fs.readFile(historyPath);
+        if (!raw) return;
+        const lines = raw.split('\n').filter((l) => l.length > 0);
+        buffer = lines.slice(-MAX_ITEMS).map(decodeHistoryLine);
+        cursor = buffer.length;
+      } catch {
+        // 文件不存在 / 读不出 → 用空 buffer 起步
+      }
+    },
+
+    push(text) {
+      if (!text) return;
+      // 连续重复去重：跟最后一条相同就忽略
+      if (buffer.length > 0 && buffer[buffer.length - 1] === text) {
+        cursor = buffer.length;
+        return;
+      }
+      buffer.push(text);
+      while (buffer.length > MAX_ITEMS) buffer.shift();
+      cursor = buffer.length;
+      scheduleWrite();
+    },
+
+    prev() {
+      if (buffer.length === 0) return null;
+      if (cursor <= 0) return null;
+      cursor -= 1;
+      return buffer[cursor] ?? null;
+    },
+
+    next() {
+      if (buffer.length === 0) return null;
+      if (cursor >= buffer.length) return null;
+      cursor += 1;
+      if (cursor >= buffer.length) {
+        // 已走到 "新输入" 位（buffer 之后），返 null 让 UI 清空
+        return null;
+      }
+      return buffer[cursor] ?? null;
+    },
+
+    search(query) {
+      if (!query) return [];
+      const hits: string[] = [];
+      // 反向遍历，最近优先；同字符串只收一次
+      const seen = new Set<string>();
+      for (let i = buffer.length - 1; i >= 0; i -= 1) {
+        const item = buffer[i];
+        if (item.includes(query) && !seen.has(item)) {
+          hits.push(item);
+          seen.add(item);
+        }
+      }
+      return hits;
+    },
+
+    resetCursor() {
+      cursor = buffer.length;
+    },
+
+    async flush() {
+      if (writeTimer) {
+        clearTimeout(writeTimer);
+        writeTimer = null;
+        pendingWrite = doWrite();
+      }
+      if (pendingWrite) await pendingWrite;
+    },
+
+    _snapshot() {
+      return { buffer: [...buffer], cursor };
+    },
+  };
+}
+
+/* ------------------------------------------------------------ *
+ *  React hook 门面：store 用 useRef 持有，启动时 useEffect 拉盘
+ * ------------------------------------------------------------ */
+
+export function useInputHistory(opts?: InputHistoryStoreOptions): InputHistoryHook {
+  // 同一组件实例共享同一 store；options 变化不重建（输入历史 hook 不需要重建语义）
+  const storeRef = useRef<InputHistoryStore | null>(null);
+  if (storeRef.current === null) {
+    storeRef.current = createInputHistoryStore(opts);
+  }
+
+  useEffect(() => {
+    // 异步拉盘，不 await；UI 在拉盘前按 ↑ 只是空操作
+    storeRef.current?.load();
+  }, []);
+
+  // 暴露稳定门面，绑定到内部 store
+  return useMemo<InputHistoryHook>(() => {
+    return {
+      push: (t) => storeRef.current!.push(t),
+      prev: () => storeRef.current!.prev(),
+      next: () => storeRef.current!.next(),
+      search: (q) => storeRef.current!.search(q),
+      resetCursor: () => storeRef.current!.resetCursor(),
+    };
+  }, []);
+}

package/src/ui/hooks/usePasteHandler.ts

@@ -0,0 +1,220 @@
+/**
+ * ============================================================
+ *  src/ui/hooks/usePasteHandler.ts —— 粘贴检测 Hook（v0.3 最终版）
+ * ------------------------------------------------------------
+ *  功能：
+ *    1. 检测粘贴输入（通过内容长度阈值）
+ *    2. 收集多 Chunk 粘贴内容（处理 stdin 分块到达）
+ *    3. ✨ 粘贴期间拦截所有 Enter（防止多行内容被误发送）
+ *    4. 跨平台兼容：Win / Mac / Linux
+ *
+ *  v0.3 核心设计原则（符合用户直觉）：
+ *    - Enter（单独按）：始终返回 'continue' → 调用方处理为**发送消息**
+ *    - Alt+Enter（Mac: Option+Enter）：返回 'enter-newline' → 调用方处理为**插入换行**
+ *    - Ctrl+Enter：返回 'continue' → 调用方处理为**强制发送**
+ *    - 粘贴期间 + 任何 Enter：返回 'enter-in-paste' → **忽略**（防止误触发发送）
+ *
+ *  工作原理：
+ *    当用户粘贴多行内容时，stdin 可能分多个 chunk 到达。
+ *    如果不处理，粘贴内容中的 \n 会被解析为 Enter 键，
+ *    导致只有最后一个换行之前的内容被保留，或者直接触发了发送。
+ * ============================================================
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+// 粘贴检测阈值：超过此长度视为粘贴输入
+const PASTE_THRESHOLD = 20;
+
+// 多 Chunk 等待超时：100ms 内收到的内容视为同一批粘贴
+const PASTE_TIMEOUT_MS = 100;
+
+interface PasteState {
+  chunks: string[];
+  timeoutId: ReturnType<typeof setTimeout> | null;
+}
+
+interface UsePasteHandlerOptions {
+  /** 粘贴完成时的回调（传入合并后的完整文本） */
+  onPasteComplete: (text: string) => void;
+  /** 是否启用多行模式（启用后支持 Alt+Enter 换行）默认 false */
+  multiline?: boolean;
+}
+
+interface UsePasteHandlerResult {
+  /**
+   * 处理输入的包装函数
+   * @returns 处理结果：
+   *   - 'paste': 已作为粘贴处理，不继续
+   *   - 'enter-in-paste': Enter 在粘贴期间被忽略，不提交也不换行
+   *   - 'enter-newline': Alt+Enter（Mac: Option+Enter）被转换为换行符（用于编辑时手动换行）
+   *   - 'continue': 继续普通输入处理（包括 Enter 发送、Ctrl+Enter 强制发送等）
+   */
+  handleInput: (
+    input: string,
+    key: {
+      return?: boolean;
+      ctrl?: boolean;
+      shift?: boolean;
+      meta?: boolean;
+      [key: string]: unknown;
+    }
+  ) => 'paste' | 'enter-in-paste' | 'enter-newline' | 'continue';
+  /** 当前是否处于粘贴状态 */
+  isPasting: boolean;
+}
+
+/**
+ * 粘贴检测 Hook（v0.3 最终版）
+ *
+ * @example
+ * ```tsx
+ * const { handleInput } = usePasteHandler({
+ *   onPasteComplete: (text) => {
+ *     buf.insert(text);
+ *     forceRefresh();
+ *   },
+ *   multiline: true,
+ * });
+ *
+ * useInput((input, key) => {
+ *   const result = handleInput(input, key);
+ *   if (result === 'paste') return;           // 粘贴已处理
+ *   if (result === 'enter-in-paste') return;  // 粘贴中的 Enter 忽略
+ *   if (result === 'enter-newline') {         // Alt+Enter → 换行
+ *     buf.insert('\n');
+ *     forceRefresh();
+ *     return;
+ *   }
+ *   // result === 'continue': 正常处理
+ *   // 包括：Enter 发送、Ctrl+Enter 发送、普通字符输入等
+ * });
+ * ```
+ */
+export function usePasteHandler({
+  onPasteComplete,
+  multiline = false,
+}: UsePasteHandlerOptions): UsePasteHandlerResult {
+  const [isPasting, setIsPasting] = useState(false);
+  const pasteStateRef = useRef<PasteState>({
+    chunks: [],
+    timeoutId: null,
+  });
+
+  // 卸载清理：粘贴中途组件被切走（SessionPicker/ConfigMenu/AskQuestion 顶替）时
+  // 取消挂起的 flush 定时器，防止回调打到已卸载组件。
+  useEffect(() => {
+    return () => {
+      if (pasteStateRef.current.timeoutId) {
+        clearTimeout(pasteStateRef.current.timeoutId);
+        pasteStateRef.current.timeoutId = null;
+      }
+    };
+  }, []);
+
+  /**
+   * 刷新 UI 的引用（避免闭包问题）
+   */
+  const onPasteCompleteRef = useRef(onPasteComplete);
+  onPasteCompleteRef.current = onPasteComplete;
+
+  /**
+   * 刷新 isPasting 状态的引用
+   */
+  const setIsPastingRef = useRef(setIsPasting);
+  setIsPastingRef.current = setIsPasting;
+
+  /**
+   * 将收集的 chunks 合并并触发回调
+   */
+  const flushPaste = useCallback(() => {
+    const { chunks } = pasteStateRef.current;
+    if (chunks.length === 0) return;
+
+    // 合并所有 chunks
+    const rawText = chunks.join('');
+
+    // 清理文本：
+    // 1. \r\n → \n（Windows 行尾）
+    // 2. 连续的 \n 压缩为最多两个（保持段落分隔）
+    const cleanedText = rawText
+      .replace(/\r\n/g, '\n')
+      .replace(/\r/g, '\n')
+      .replace(/\n{3,}/g, '\n\n');
+
+    // 清除状态
+    pasteStateRef.current = { chunks: [], timeoutId: null };
+    setIsPastingRef.current(false);
+
+    // 触发回调
+    onPasteCompleteRef.current(cleanedText);
+  }, []);
+
+  /**
+   * 处理输入（v0.3：Enter 始终发送，Alt+Enter 换行，粘贴期间拦截）
+   */
+  const handleInput = useCallback(
+    (
+      input: string,
+      key: {
+        return?: boolean;
+        ctrl?: boolean;
+        shift?: boolean;
+        meta?: boolean;
+        [key: string]: unknown;
+      }
+    ): 'paste' | 'enter-in-paste' | 'enter-newline' | 'continue' => {
+
+      // ---- 1. 粘贴期间的任何 Enter 键：全部拦截 ----
+      // 这是最关键的防御！防止多行粘贴内容中的 \n 触发发送
+      if (isPasting && key.return) {
+        return 'enter-in-paste';
+      }
+
+      // ---- 2. Alt+Enter（Mac: Option+Enter）：插入换行符（用于编辑时手动换行）----
+      // multiline=false 时不识别 Alt+Enter，让它走到下面的普通 Enter 分支（提交）
+      if (multiline && key.return && key.meta && !key.ctrl) {
+        return 'enter-newline';
+      }
+
+      // ---- 3. Enter（包括 Ctrl+Enter）：始终返回 continue → 让调用方处理为发送 ----
+      // 不管是单行还是多行内容，Enter 的默认行为都是发送
+      // 只有 Alt+Enter 才是换行
+      if (key.return) {
+        return 'continue'; // 调用方会执行 onSubmit()
+      }
+
+      // ---- 4. 检测是否为粘贴输入 ----
+      const isLongInput = input.length > PASTE_THRESHOLD;
+
+      if (isLongInput || isPasting) {
+        // 进入或继续粘贴状态
+        setIsPasting(true);
+
+        // 清除之前的超时
+        if (pasteStateRef.current.timeoutId) {
+          clearTimeout(pasteStateRef.current.timeoutId);
+        }
+
+        // 收集这个 chunk
+        pasteStateRef.current.chunks.push(input);
+
+        // 设置新的超时，超时后 flush
+        pasteStateRef.current.timeoutId = setTimeout(() => {
+          flushPaste();
+        }, PASTE_TIMEOUT_MS);
+
+        return 'paste';
+      }
+
+      // ---- 5. 普通输入，继续处理 ----
+      return 'continue';
+    },
+    [isPasting, multiline, flushPaste]
+  );
+
+  return {
+    handleInput,
+    isPasting,
+  };
+}

package/src/ui/hooks/useTerminalSize.ts

@@ -0,0 +1,41 @@
+/**
+ * ============================================================
+ *  src/ui/hooks/useTerminalSize.ts —— 终端尺寸感知
+ * ------------------------------------------------------------
+ *  返回当前终端的 rows / cols；监听 process.stdout 'resize' 事件，
+ *  resize 时刷新 state，触发依赖此 hook 的组件 re-render（如 MessageList
+ *  根据 rows < 28 决定是否折叠 reasoning）。
+ *
+ *  fallback 值：rows=24, cols=80（POSIX 终端历史默认）。
+ *  非 TTY 场景（pipe / 测试环境）下 process.stdout.rows 可能 undefined，
+ *  fallback 兜底保证 UI 不崩。
+ * ============================================================
+ */
+
+import { useEffect, useState } from 'react';
+
+export interface TerminalSize {
+  rows: number;
+  cols: number;
+}
+
+function readSize(): TerminalSize {
+  return {
+    rows: process.stdout.rows ?? 24,
+    cols: process.stdout.columns ?? 80,
+  };
+}
+
+export function useTerminalSize(): TerminalSize {
+  const [size, setSize] = useState<TerminalSize>(readSize);
+
+  useEffect(() => {
+    const update = () => setSize(readSize());
+    process.stdout.on('resize', update);
+    return () => {
+      process.stdout.off('resize', update);
+    };
+  }, []);
+
+  return size;
+}

package/src/ui/hooks/useTextBuffer.ts

@@ -0,0 +1,108 @@
+/**
+ * ============================================================
+ *  src/ui/hooks/useTextBuffer.ts —— 输入框文本缓冲（React 包装）
+ * ------------------------------------------------------------
+ *  把 textBuffer.ts 里的纯函数包成 React Hook：useState 持有 BufferState，
+ *  暴露一组 callback 给 InputBox 调用。callback 用 setState(prev => ...)
+ *  形式，避免 useInput handler 闭包看到旧 state 的问题。
+ * ============================================================
+ */
+
+import { useCallback, useMemo, useState } from 'react';
+
+import {
+  bufClear,
+  bufDeleteBefore,
+  bufDeleteWordBefore,
+  bufInsert,
+  bufKillToLineEnd,
+  bufKillToLineStart,
+  bufMoveBufferEnd,
+  bufMoveBufferStart,
+  bufMoveDown,
+  bufMoveLeft,
+  bufMoveLineEnd,
+  bufMoveLineStart,
+  bufMoveRight,
+  bufMoveUp,
+  bufMoveWordLeft,
+  bufMoveWordRight,
+  bufSetText,
+  EMPTY_BUFFER,
+  layoutBuffer,
+  type BufferLayout,
+  type BufferState,
+} from '../textBuffer.js';
+
+export interface UseTextBufferResult {
+  state: BufferState;
+  layout: BufferLayout;
+  // 插入 / 重置
+  insert: (s: string) => void;
+  setText: (s: string) => void;
+  clear: () => void;
+  // 删除
+  deleteBefore: () => void;
+  deleteWordBefore: () => void;
+  killToLineStart: () => void;
+  killToLineEnd: () => void;
+  // 移动
+  moveLeft: () => void;
+  moveRight: () => void;
+  moveWordLeft: () => void;
+  moveWordRight: () => void;
+  moveLineStart: () => void;
+  moveLineEnd: () => void;
+  moveBufferStart: () => void;
+  moveBufferEnd: () => void;
+  moveUp: () => void;
+  moveDown: () => void;
+}
+
+export function useTextBuffer(): UseTextBufferResult {
+  const [state, setState] = useState<BufferState>(EMPTY_BUFFER);
+
+  const insert = useCallback((s: string) => setState((p) => bufInsert(p, s)), []);
+  const setText = useCallback((s: string) => setState(bufSetText(s)), []);
+  const clear = useCallback(() => setState(bufClear()), []);
+
+  const deleteBefore = useCallback(() => setState(bufDeleteBefore), []);
+  const deleteWordBefore = useCallback(() => setState(bufDeleteWordBefore), []);
+  const killToLineStart = useCallback(() => setState(bufKillToLineStart), []);
+  const killToLineEnd = useCallback(() => setState(bufKillToLineEnd), []);
+
+  const moveLeft = useCallback(() => setState(bufMoveLeft), []);
+  const moveRight = useCallback(() => setState(bufMoveRight), []);
+  const moveWordLeft = useCallback(() => setState(bufMoveWordLeft), []);
+  const moveWordRight = useCallback(() => setState(bufMoveWordRight), []);
+  const moveLineStart = useCallback(() => setState(bufMoveLineStart), []);
+  const moveLineEnd = useCallback(() => setState(bufMoveLineEnd), []);
+  const moveBufferStart = useCallback(() => setState(bufMoveBufferStart), []);
+  const moveBufferEnd = useCallback(() => setState(bufMoveBufferEnd), []);
+  const moveUp = useCallback(() => setState(bufMoveUp), []);
+  const moveDown = useCallback(() => setState(bufMoveDown), []);
+
+  const layout = useMemo(() => layoutBuffer(state), [state]);
+
+  return {
+    state,
+    layout,
+    insert,
+    setText,
+    clear,
+    deleteBefore,
+    deleteWordBefore,
+    killToLineStart,
+    killToLineEnd,
+    moveLeft,
+    moveRight,
+    moveWordLeft,
+    moveWordRight,
+    moveLineStart,
+    moveLineEnd,
+    moveBufferStart,
+    moveBufferEnd,
+    moveUp,
+    moveDown,
+  };
+}

package/src/ui/hooks/useTokenUsage.ts

@@ -0,0 +1,44 @@
+/**
+ * ============================================================
+ *  src/ui/hooks/useTokenUsage.ts —— token 用量计算
+ * ------------------------------------------------------------
+ *  纯函数 hook：根据当前 history 算 token 数 + 距离压缩阈值的百分比，
+ *  StatusLine 用它显示底部状态。
+ *
+ *  历史坑：曾经用 useMemo([messages, provider]) 缓存——但 useChat
+ *  里的 historyRef.current 跨渲染始终是同一个数组引用（runQuery
+ *  内部用 push() / length=0 直接 mutate），useMemo 缓存键永不失效，
+ *  导致 StatusLine 显示的 token 数从启动后就冻结。
+ *
+ *  修复：直接每渲染重算。countMessagesTokens 在百 KB 历史上 < 1ms，
+ *  仅状态栏一处调用，零负担。如果未来历史规模变大需要 memo，
+ *  再额外传入版本号 prop 配合依赖即可。
+ * ============================================================
+ */
+
+import { getCompactThreshold } from '../../context/compact.js';
+import { countMessagesTokens } from '../../context/tokenCounter.js';
+import type { Message, Provider } from '../../types.js';
+
+export interface TokenUsage {
+  /** 当前估算的 token 数 */
+  tokens: number;
+  /** 触发压缩的阈值 */
+  threshold: number;
+  /** Provider 的 contextWindow */
+  contextWindow: number;
+  /** 距离压缩阈值的剩余 token */
+  toThreshold: number;
+}
+
+export function useTokenUsage(messages: Message[], provider: Provider): TokenUsage {
+  const tokens = countMessagesTokens(messages);
+  // 与 loop 实际触发同源（getCompactThreshold：按 contextWindow × compactRatio 比例 + 8K 下限）
+  const threshold = getCompactThreshold(provider);
+  return {
+    tokens,
+    threshold,
+    contextWindow: provider.contextWindow,
+    toThreshold: threshold - tokens,
+  };
+}