pi-session-peek 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0
+
+First release.
+
+- Two-pane picker: session list on the left, full conversation preview on the right.
+- Live filtering by conversation text, session name and working directory. Space-separated keywords must all match; `@7d`, `@24h`, `@2w`, `@1m` limit results to recently active sessions.
+- Keyword highlighting, hit snippets in the list, Ctrl+N / Ctrl+P to jump between hits.
+- Enter resumes, Ctrl+O forks, Ctrl+R renames, Ctrl+D deletes (moves to trash when the `trash` CLI is available).
+- Tab toggles between the current directory tree and all projects.
+- `/peek [keyword]` command, `--rp` and `--peek=<keyword>` startup flags.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeffropz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# 🔍 pi-session-peek — Find That Old Conversation and Jump Back In
+
+[![npm](https://img.shields.io/npm/v/pi-session-peek)](https://www.npmjs.com/package/pi-session-peek) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
+
+[中文说明](https://github.com/Jeffropz/pi-session-peek/blob/main/README.zh-CN.md)
+
+Search your [pi](https://pi.dev) session history by what was actually said, read the whole conversation in a side pane, then resume it or fork it.
+
+![pi-session-peek screenshot](https://raw.githubusercontent.com/Jeffropz/pi-session-peek/main/docs/screenshot.png)
+
+## ✨ Features
+
+- Opens a two-pane picker with `/peek` or `/peek <keyword>`: sessions on the left, the full conversation on the right.
+- Filters as you type across conversation text, session name and working directory. Tool call arguments and results are excluded, so a keyword only matches sessions that actually discussed it.
+- Requires every space-separated keyword to match, and shows a snippet around the first hit in the list.
+- Limits results to recently active sessions with `@7d`, `@24h`, `@2w` or `@1m`.
+- Highlights every hit in the preview and jumps between them with `Ctrl+N` / `Ctrl+P`.
+- Resumes with `Enter`, forks into a new session with `Ctrl+O`, renames with `Ctrl+R`, deletes with `Ctrl+D`.
+- Toggles between the current directory tree and all projects with `Tab`.
+- Starts straight into the picker with `pi --rp` or `pi --peek=<keyword>`.
+- Parses each session file once and caches it by mtime, so reopening is instant.
+
+## 📦 Install
+
+```bash
+pi install npm:pi-session-peek
+```
+
+Try it without installing permanently:
+
+```bash
+pi -e npm:pi-session-peek
+```
+
+Install from GitHub instead of npm:
+
+```bash
+pi install git:github.com/Jeffropz/pi-session-peek
+```
+
+Pi extensions run with the Pi process's user permissions, so install only trusted packages.
+
+## 🚀 Quick start
+
+In TUI mode, run `/peek` and start typing. Press `Enter` on a session to continue it, or `Ctrl+O` to continue in a fresh fork and leave the original untouched.
+
+## 💬 Commands
+
+| Command | Purpose |
+| --- | --- |
+| `/peek` | Open the picker. The previous keyword is remembered for the process. |
+| `/peek <keyword>` | Open the picker with the keyword filled in. |
+| `pi --rp` | Start pi and open the picker. Takes no argument. |
+| `pi --peek=<keyword>` | Start pi and open the picker with the keyword filled in. `--peek` requires a value. |
+
+## ⌨️ Keys
+
+| Key | Action |
+| --- | --- |
+| type | Filter. Space-separated words must all match; `@7d` and friends limit by time. |
+| `Tab` | Current directory tree ↔ all projects |
+| `↑` `↓` | Select session |
+| `PgUp` `PgDn` | Scroll preview by a page |
+| `Ctrl+U` `Ctrl+F` | Scroll preview by half a page |
+| `Shift+↑` `Shift+↓` | Scroll preview by three lines |
+| `Ctrl+N` `Ctrl+P` | Next / previous hit |
+| `Enter` | Resume the session |
+| `Ctrl+O` | Fork the session and open the fork |
+| `Ctrl+R` | Rename. Writes the same `session_info` entry as `/name`. |
+| `Ctrl+D` | Delete, confirmed with `y` or `Enter`. Uses the `trash` CLI when available, otherwise deletes the file. |
+| `Esc` `Ctrl+C` | Close |
+
+## 🔎 Search syntax
+
+The filter is case-insensitive and matches anywhere in the text.
+
+| Input | Meaning |
+| --- | --- |
+| `token undefined` | Sessions containing both `token` and `undefined` |
+| `@7d` | Sessions active in the last 7 days. Units: `h`, `d`, `w`, `m` (30 days). |
+| `token @2w` | Both combined |
+
+The search index holds user and assistant messages, the session name and the working directory. It does not hold tool call arguments or tool results.
+
+## 🚧 Limitations
+
+- TUI mode only.
+- The interface text is Chinese.
+- No mouse support. Pi only enables mouse input in its experimental fullscreen mode, and this picker does not handle it yet.
+- The preview shows the last 500 messages of very long sessions. Hits in earlier messages are still counted and announced.
+- `pi --peek` without a value is rejected by pi at startup. Use `pi --rp` to open without a keyword.
+- Only sessions under `~/.pi/agent/sessions` (or `$PI_CODING_AGENT_DIR/sessions`) are scanned.
+
+## 🗂️ Package layout
+
+```text
+pi-session-peek/
+├── index.ts                 # Registers /peek and the startup flags, injects delete / rename / fork
+├── src/
+│   ├── peek-component.ts    # The two-pane TUI component
+│   ├── sessions.ts          # Scans and parses session JSONL, rename / delete helpers
+│   ├── query.ts             # Query parsing, highlighting, hit snippets
+│   └── text.ts              # Path, time and width helpers
+├── scripts/screenshot.mjs   # Optional: renders a synthetic screenshot from component output
+└── test/                    # node:test suites
+```
+
+## 🛠️ Development
+
+```bash
+npm install
+npm test               # node:test via tsx
+npm run typecheck      # tsc --noEmit
+npm run screenshot     # optional: overwrite docs/screenshot.png with a synthetic render (needs Chrome)
+```
+
+To load a local checkout, add its path under `extensions` in `~/.pi/agent/settings.json` or drop the folder into `~/.pi/agent/extensions/`, then `/reload`.
+
+## 📄 License
+
+MIT. See [`LICENSE`](./LICENSE).

package/README.zh-CN.md

@@ -0,0 +1,120 @@
+# 🔍 pi-session-peek — 找到那次对话，接着聊
+
+[![npm](https://img.shields.io/npm/v/pi-session-peek)](https://www.npmjs.com/package/pi-session-peek) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
+
+[English](https://github.com/Jeffropz/pi-session-peek/blob/main/README.md)
+
+按对话内容搜索 [pi](https://pi.dev) 的历史会话，右栏直接读完整对话，然后回到那个会话继续，或者分叉出一个新的。
+
+![pi-session-peek 截图](https://raw.githubusercontent.com/Jeffropz/pi-session-peek/main/docs/screenshot.png)
+
+## ✨ 功能
+
+- `/peek` 或 `/peek 关键词` 打开左右分栏的选择器：左边是会话列表，右边是完整对话。
+- 边打字边过滤，搜的是对话正文、会话名和工作目录。工具调用的参数和结果不进索引，所以只会命中真正讨论过这个词的会话。
+- 空格分隔多个关键词，全部命中才显示；列表里直接显示第一个命中处的片段。
+- `@7d`、`@24h`、`@2w`、`@1m` 只看最近活动过的会话。
+- 预览里所有命中都高亮，`Ctrl+N` / `Ctrl+P` 在命中间跳。
+- `Enter` 进入会话，`Ctrl+O` 分叉成新会话，`Ctrl+R` 重命名，`Ctrl+D` 删除。
+- `Tab` 在当前目录树和全部项目之间切换。
+- `pi --rp` 或 `pi --peek=关键词` 启动时直接打开。
+- 会话文件只解析一次，按修改时间缓存，再次打开不用等。
+
+## 📦 安装
+
+```bash
+pi install npm:pi-session-peek
+```
+
+不装、只试一次：
+
+```bash
+pi -e npm:pi-session-peek
+```
+
+从 GitHub 装：
+
+```bash
+pi install git:github.com/Jeffropz/pi-session-peek
+```
+
+pi 扩展以你的用户权限运行，只装信得过的包。
+
+## 🚀 快速开始
+
+在 TUI 模式下输入 `/peek`，直接打字过滤。选中后按 `Enter` 接着聊，或者按 `Ctrl+O` 在一个新分叉里聊，原会话不动。
+
+## 💬 命令
+
+| 命令 | 作用 |
+| --- | --- |
+| `/peek` | 打开选择器，本次进程内记住上次的关键词 |
+| `/peek 关键词` | 带关键词打开 |
+| `pi --rp` | 启动 pi 并打开选择器。不接受参数。 |
+| `pi --peek=关键词` | 启动 pi 并带关键词打开。`--peek` 必须带值。 |
+
+## ⌨️ 按键
+
+| 按键 | 作用 |
+| --- | --- |
+| 打字 | 过滤。空格分隔的词都要命中；`@7d` 等限定时间。 |
+| `Tab` | 当前目录树 ↔ 全部项目 |
+| `↑` `↓` | 选会话 |
+| `PgUp` `PgDn` | 预览翻页 |
+| `Ctrl+U` `Ctrl+F` | 预览翻半页 |
+| `Shift+↑` `Shift+↓` | 预览滚三行 |
+| `Ctrl+N` `Ctrl+P` | 下一个 / 上一个命中 |
+| `Enter` | 进入会话 |
+| `Ctrl+O` | 分叉出新会话并进入 |
+| `Ctrl+R` | 重命名，写入的记录和 `/name` 一样 |
+| `Ctrl+D` | 删除，按 `y` 或 `Enter` 确认。有 `trash` 命令就进回收站，否则直接删文件。 |
+| `Esc` `Ctrl+C` | 关闭 |
+
+## 🔎 搜索语法
+
+大小写不敏感，匹配文本中任意位置。
+
+| 输入 | 含义 |
+| --- | --- |
+| `token undefined` | 同时包含 `token` 和 `undefined` 的会话 |
+| `@7d` | 最近 7 天活动过的会话。单位：`h` 小时、`d` 天、`w` 周、`m` 月（按 30 天算） |
+| `token @2w` | 两者组合 |
+
+索引里有用户和助手的消息、会话名、工作目录。没有工具调用的参数和结果。
+
+## 🚧 限制
+
+- 只支持 TUI 模式。
+- 不支持鼠标。pi 只在实验性的全屏模式里开鼠标，这个选择器还没处理鼠标事件。
+- 特别长的会话预览只显示最后 500 条消息，更早的命中仍会计数并提示。
+- `pi --peek` 不带值会被 pi 在启动时拒绝，不带关键词请用 `pi --rp`。
+- 只扫描 `~/.pi/agent/sessions`（或 `$PI_CODING_AGENT_DIR/sessions`）下的会话。
+
+## 🗂️ 目录结构
+
+```text
+pi-session-peek/
+├── index.ts                 # 注册 /peek 和启动参数，注入删除 / 重命名 / 分叉
+├── src/
+│   ├── peek-component.ts    # 双栏 TUI 组件
+│   ├── sessions.ts          # 扫描解析会话 JSONL，重命名 / 删除
+│   ├── query.ts             # 查询解析、高亮、命中片段
+│   └── text.ts              # 路径、时间、宽度工具
+├── scripts/screenshot.mjs   # 可选：用组件渲染输出生成一张合成截图
+└── test/                    # node:test 测试
+```
+
+## 🛠️ 开发
+
+```bash
+npm install
+npm test               # node:test，通过 tsx 跑 TS
+npm run typecheck      # tsc --noEmit
+npm run screenshot     # 可选：用合成渲染覆盖 docs/screenshot.png，需要本机有 Chrome
+```
+
+本地开发时把目录路径加到 `~/.pi/agent/settings.json` 的 `extensions` 里，或者直接放进 `~/.pi/agent/extensions/`，然后 `/reload`。
+
+## 📄 许可证
+
+MIT，见 [`LICENSE`](./LICENSE)。

package/index.ts

@@ -0,0 +1,118 @@
+import { SessionManager, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { basename } from "node:path";
+import { PeekComponent } from "./src/peek-component.ts";
+import { deleteSession, renameSession, scanSessions, type PeekSession } from "./src/sessions.ts";
+
+// 这里只做注册：/peek 命令、--peek / --rp 启动参数，以及把删除 / 重命名 / 分叉注入给组件
+
+let lastQuery = ""; // 进程内记住上次搜索词
+
+export default function (pi: ExtensionAPI) {
+  // pi 会把 boolean flag 的值一律强转成 true，所以带关键词的形式只能是 string 类型
+  pi.registerFlag("peek", {
+    description: "启动时打开会话搜索预览并预填关键词（--peek=关键词）",
+    type: "string",
+  });
+  pi.registerFlag("rp", {
+    description: "启动时打开会话搜索预览（不带关键词）",
+    type: "boolean",
+  });
+
+  pi.on("session_start", async (event, ctx) => {
+    if (event.reason !== "startup") return; // 切换会话也会触发 session_start，只在进程启动时打开
+    const peek = pi.getFlag("peek");
+    const rp = pi.getFlag("rp");
+    if (!peek && !rp) return;
+    const kw = typeof peek === "string" ? peek.trim() : "";
+    const cmd = `/peek${kw ? ` ${kw}` : ""}`;
+
+    // 等 UI 空闲再弹；带了初始 prompt 时 agent 在忙，最后排队到它之后
+    const tryOpen = (attempt: number) => {
+      try {
+        if (ctx.isIdle()) {
+          pi.sendUserMessage(cmd, { expandPromptTemplates: true });
+        } else if (attempt < 20) {
+          setTimeout(() => tryOpen(attempt + 1), 150);
+        } else {
+          pi.sendUserMessage(cmd, { expandPromptTemplates: true, deliverAs: "followUp" });
+        }
+      } catch {
+        // 扩展已卸载时 API 会抛，忽略
+      }
+    };
+    setTimeout(() => tryOpen(0), 150);
+  });
+
+  pi.registerCommand("peek", {
+    description: "搜索历史会话：左右分栏预览、关键词高亮，Enter 进入对话",
+    handler: async (args, ctx) => {
+      if (ctx.mode !== "tui") {
+        ctx.ui.notify("/peek 需要在交互模式（TUI）下使用", "error");
+        return;
+      }
+
+      // 当前正在用的会话不列出来
+      const currentFile = ctx.sessionManager.getSessionFile();
+      const all = scanSessions().filter((s) => s.path !== currentFile);
+      if (!all.length) {
+        ctx.ui.notify("没有找到历史会话", "info");
+        return;
+      }
+
+      const initial = ((args ?? "").trim() || lastQuery) ?? "";
+      type Picked = { s: PeekSession; action: "resume" | "fork" } | null;
+      const picked = await ctx.ui.custom<Picked>((tui, theme, _kb, done) => {
+        const comp = new PeekComponent(all, ctx.cwd, theme, process.stdout.rows || 24, initial);
+        comp.requestRender = () => tui.requestRender();
+        comp.onResume = (s) => {
+          lastQuery = comp.getQuery();
+          done({ s, action: "resume" });
+        };
+        comp.onFork = (s) => {
+          lastQuery = comp.getQuery();
+          done({ s, action: "fork" });
+        };
+        comp.onCancel = () => {
+          lastQuery = comp.getQuery();
+          done(null);
+        };
+        comp.onDelete = async (s) => {
+          const ok = await deleteSession(s.path, (cmd, a) => pi.exec(cmd, a, { timeout: 4000 }));
+          ctx.ui.notify(ok ? `已删除会话 ${basename(s.path)}` : "删除会话失败", ok ? "info" : "error");
+          return ok;
+        };
+        comp.onRename = async (s, name) => {
+          let ok = true;
+          try {
+            renameSession(s.path, name);
+          } catch {
+            ok = false;
+          }
+          ctx.ui.notify(ok ? `已重命名为「${name}」` : "重命名失败", ok ? "info" : "error");
+          return ok;
+        };
+        return comp;
+      });
+
+      if (!picked) return;
+
+      let target = picked.s.path;
+      if (picked.action === "fork") {
+        // 和 pi --fork 一样：把全部记录复制到新文件，header 里记下 parentSession
+        try {
+          const forked = SessionManager.forkFrom(picked.s.path, ctx.cwd);
+          target = forked.getSessionFile() ?? target;
+          ctx.ui.notify(`已分叉为新会话 ${basename(target)}`, "info");
+        } catch (e) {
+          ctx.ui.notify(`分叉失败：${e instanceof Error ? e.message : String(e)}`, "error");
+          return;
+        }
+      }
+
+      const result = await ctx.switchSession(target);
+      if (result?.cancelled) {
+        ctx.ui.notify("切换会话已取消", "info");
+      }
+    },
+  });
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "pi-session-peek",
+  "version": "0.1.0",
+  "description": "Pi extension: search session history in a two-pane picker with full conversation preview, then resume or fork.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Jeffropz",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "pi-coding-agent",
+    "session",
+    "search",
+    "resume"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Jeffropz/pi-session-peek.git"
+  },
+  "homepage": "https://github.com/Jeffropz/pi-session-peek#readme",
+  "bugs": "https://github.com/Jeffropz/pi-session-peek/issues",
+  "files": [
+    "index.ts",
+    "src",
+    "docs/screenshot.png",
+    "README.md",
+    "README.zh-CN.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test \"test/**/*.test.ts\"",
+    "check": "npm run typecheck && npm test",
+    "screenshot": "node --import tsx scripts/screenshot.mjs",
+    "prepublishOnly": "npm run check"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@earendil-works/pi-tui": "0.85.1",
+    "@types/node": "^22",
+    "tsx": "^4",
+    "typescript": "^5"
+  }
+}

package/src/peek-component.ts

@@ -0,0 +1,464 @@
+import {
+  Input,
+  Key,
+  matchesKey,
+  truncateToWidth,
+  visibleWidth,
+  type Component,
+  type Focusable,
+} from "@earendil-works/pi-tui";
+import { anyKw, highlight, parseQuery, snippet, type ParsedQuery } from "./query.ts";
+import type { PeekSession } from "./sessions.ts";
+import { fmtTime, normPath, padEndVisible, wrapLines } from "./text.ts";
+
+// 双栏选择器。文件操作（删除 / 重命名 / 分叉）不在这里做，由 index.ts 通过回调注入
+
+export class PeekComponent implements Component, Focusable {
+  private input: Input;
+  private scope: "current" | "all";
+  private filtered: PeekSession[] = [];
+  private selected = 0;
+  private listOffset = 0;
+  private previewOffset = 0;
+  private previewKey = ""; // 预览缓存的键（会话 + 关键词 + 宽度），置空强制重建
+  private previewLines: string[] = [];
+  private matchLines: number[] = []; // 预览里命中消息所在的行，Ctrl+N / Ctrl+P 用
+  private confirmingDelete = false; // Ctrl+D 之后等待确认
+  private renaming = false; // Ctrl+R 之后正在输入名字
+  private renameInput: Input;
+  private cachedWidth = -1;
+  private cachedLines: string[] = [];
+  private _focused = false;
+
+  // 由 index.ts 注入
+  onResume?: (s: PeekSession) => void;
+  onFork?: (s: PeekSession) => void;
+  onCancel?: () => void;
+  onDelete?: (s: PeekSession) => Promise<boolean>;
+  onRename?: (s: PeekSession, name: string) => Promise<boolean>;
+  requestRender?: () => void; // 异步操作完成后让 TUI 重画
+
+  constructor(
+    private all: PeekSession[],
+    private currentCwd: string,
+    private theme: any,
+    private termRows: number,
+    initialQuery: string,
+  ) {
+    this.input = new Input({ placeholder: "关键词过滤（空格分隔=同时命中；@7d 限定近 7 天）" });
+    this.renameInput = new Input({ placeholder: "新会话名（Enter 确认 / Esc 取消，留空取消）" });
+    if (initialQuery) this.input.setValue(initialQuery);
+    // 当前目录树下有会话就默认当前目录，否则全局
+    this.scope = all.some((s) => this.inCurrentTree(s)) ? "current" : "all";
+    this.refilter();
+  }
+
+  // 焦点要落到真正在用的那个输入框上，否则 IME 候选框位置不对
+  get focused(): boolean {
+    return this._focused;
+  }
+  set focused(v: boolean) {
+    this._focused = v;
+    this.input.focused = v && !this.renaming;
+    this.renameInput.focused = v && this.renaming;
+  }
+
+  getQuery(): string {
+    return this.input.getValue().trim();
+  }
+
+  private query(): ParsedQuery {
+    return parseQuery(this.getQuery());
+  }
+
+  // 等于当前目录，或在它的子目录下
+  private inCurrentTree(s: PeekSession): boolean {
+    const cur = normPath(this.currentCwd);
+    const c = normPath(s.cwd);
+    return c === cur || c.startsWith(cur + "/");
+  }
+
+  // keepSelection：尽量保持原来选中的会话，重命名后用
+  private refilter(keepSelection = false): void {
+    const prev = keepSelection ? this.filtered[this.selected] : undefined;
+    const { kws, since } = this.query();
+    let out = this.all;
+    if (this.scope === "current") out = out.filter((s) => this.inCurrentTree(s));
+    if (since) out = out.filter((s) => s.mtime >= since);
+    if (kws.length) out = out.filter((s) => kws.every((k) => s.searchText.includes(k)));
+    this.filtered = out;
+    const idx = prev ? out.indexOf(prev) : -1;
+    this.selected = idx >= 0 ? idx : keepSelection ? Math.min(this.selected, Math.max(0, out.length - 1)) : 0;
+    if (!keepSelection) this.listOffset = 0;
+    this.previewKey = "";
+  }
+
+  private bodyHeight(): number {
+    const rows = process.stdout.rows || this.termRows || 24; // 每次都读，终端拉伸后布局跟着变
+    return Math.max(8, Math.min(rows - 12, 30));
+  }
+
+  handleInput(data: string): void {
+    // 重命名输入中：Enter 提交，Esc / Ctrl+C 取消，其他键交给输入框
+    if (this.renaming) {
+      if (matchesKey(data, Key.enter)) {
+        const s = this.filtered[this.selected];
+        const name = this.renameInput.getValue().trim();
+        this.renaming = false;
+        this.focused = this._focused;
+        this.invalidate();
+        if (s && name && this.onRename) {
+          void this.onRename(s, name).then((ok) => {
+            if (ok) {
+              s.name = name;
+              // 名字参与搜索，改完可能就不再匹配当前关键词了
+              s.searchText = (s.msgs.map((m) => m.text).join(" ") + " " + name + " " + s.cwd).toLowerCase();
+              this.refilter(true);
+            }
+            this.invalidate();
+            this.requestRender?.();
+          });
+        }
+        return;
+      }
+      if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) {
+        this.renaming = false;
+        this.focused = this._focused;
+        this.invalidate();
+        return;
+      }
+      this.renameInput.handleInput(data);
+      this.invalidate();
+      return;
+    }
+    // 删除确认中：y / Enter 执行，其他任何键取消
+    if (this.confirmingDelete) {
+      this.confirmingDelete = false;
+      this.invalidate();
+      if (data === "y" || data === "Y" || matchesKey(data, Key.enter)) {
+        const s = this.filtered[this.selected];
+        if (s && this.onDelete) {
+          void this.onDelete(s).then((ok) => {
+            if (ok) {
+              let i = this.all.indexOf(s);
+              if (i >= 0) this.all.splice(i, 1);
+              i = this.filtered.indexOf(s);
+              if (i >= 0) this.filtered.splice(i, 1);
+              // 选中位置留在原地
+              this.selected = Math.min(this.selected, Math.max(0, this.filtered.length - 1));
+              this.previewKey = "";
+            }
+            this.invalidate();
+            this.requestRender?.();
+          });
+        }
+      }
+      return;
+    }
+    if (matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) {
+      this.onCancel?.();
+      return;
+    }
+    if (matchesKey(data, Key.ctrl("d"))) {
+      if (this.filtered.length && this.onDelete) {
+        this.confirmingDelete = true;
+        this.invalidate();
+      }
+      return;
+    }
+    if (matchesKey(data, Key.ctrl("r"))) {
+      const s = this.filtered[this.selected];
+      if (s && this.onRename) {
+        this.renaming = true;
+        this.renameInput.setValue(s.name || "");
+        this.focused = this._focused;
+        this.invalidate();
+      }
+      return;
+    }
+    if (matchesKey(data, Key.tab)) {
+      this.scope = this.scope === "all" ? "current" : "all";
+      this.refilter();
+      this.invalidate();
+      return;
+    }
+    if (matchesKey(data, Key.up)) {
+      if (this.selected > 0) {
+        this.selected--;
+        this.previewKey = "";
+        this.invalidate();
+      }
+      return;
+    }
+    if (matchesKey(data, Key.down)) {
+      if (this.selected < this.filtered.length - 1) {
+        this.selected++;
+        this.previewKey = "";
+        this.invalidate();
+      }
+      return;
+    }
+    if (matchesKey(data, Key.pageUp) || matchesKey(data, Key.ctrl("u"))) {
+      const step = matchesKey(data, Key.pageUp) ? this.bodyHeight() : Math.max(1, this.bodyHeight() >> 1);
+      this.previewOffset = Math.max(0, this.previewOffset - step);
+      this.invalidate();
+      return;
+    }
+    if (matchesKey(data, Key.pageDown) || matchesKey(data, Key.ctrl("f"))) {
+      const step = matchesKey(data, Key.pageDown) ? this.bodyHeight() : Math.max(1, this.bodyHeight() >> 1);
+      this.previewOffset += step;
+      this.invalidate();
+      return;
+    }
+    if (matchesKey(data, Key.shift("up"))) {
+      this.previewOffset = Math.max(0, this.previewOffset - 3);
+      this.invalidate();
+      return;
+    }
+    if (matchesKey(data, Key.shift("down"))) {
+      this.previewOffset += 3;
+      this.invalidate();
+      return;
+    }
+    if (matchesKey(data, Key.ctrl("n"))) {
+      this.jumpMatch(1);
+      return;
+    }
+    if (matchesKey(data, Key.ctrl("p"))) {
+      this.jumpMatch(-1);
+      return;
+    }
+    if (matchesKey(data, Key.enter)) {
+      const s = this.filtered[this.selected];
+      if (s) this.onResume?.(s);
+      return;
+    }
+    if (matchesKey(data, Key.ctrl("o"))) {
+      const s = this.filtered[this.selected];
+      if (s) this.onFork?.(s);
+      return;
+    }
+    // 其余按键交给搜索框
+    const before = this.input.getValue();
+    this.input.handleInput(data);
+    if (this.input.getValue() !== before) this.refilter(); // 光标移动不算输入，别重置列表
+    this.invalidate();
+  }
+
+  // 预览里跳到下一个 / 上一个命中，到头了回绕
+  private jumpMatch(dir: 1 | -1): void {
+    if (!this.matchLines.length) return;
+    const cur = this.previewOffset + 2;
+    let target: number | undefined;
+    if (dir === 1) {
+      target = this.matchLines.find((l) => l > cur) ?? this.matchLines[0];
+    } else {
+      target = [...this.matchLines].reverse().find((l) => l < cur) ?? this.matchLines[this.matchLines.length - 1];
+    }
+    if (target !== undefined) {
+      this.previewOffset = Math.max(0, target - 2);
+      this.invalidate();
+    }
+  }
+
+  // 左栏，每个会话两行
+  private buildList(height: number, lw: number): string[] {
+    const t = this.theme;
+    const { kws } = this.query();
+    const visible = Math.max(1, Math.floor(height / 2));
+    if (this.selected < this.listOffset) this.listOffset = this.selected;
+    if (this.selected >= this.listOffset + visible) {
+      this.listOffset = this.selected - visible + 1;
+    }
+
+    const rows: string[] = [];
+    for (let i = 0; i < visible; i++) {
+      const idx = this.listOffset + i;
+      const s = this.filtered[idx];
+      if (!s) {
+        rows.push(" ".repeat(lw), " ".repeat(lw));
+        continue;
+      }
+      const sel = idx === this.selected;
+      const time = fmtTime(s.time);
+      const cwdTail = s.cwd.replace(/\\/g, "/").split("/").slice(-2).join("/");
+      // 有关键词时显示命中的消息数
+      const hitBadge = kws.length
+        ? ` ·${s.msgs.reduce((n, m) => n + (anyKw(m.text.toLowerCase(), kws) ? 1 : 0), 0)}`
+        : "";
+      const l1 = `${sel ? "›" : " "} ${time} ${cwdTail}${hitBadge}`;
+      // 第二行：有关键词时显示命中片段，否则显示首条消息
+      const snip = snippet(s.msgs, kws, lw);
+      const l2 = snip !== undefined
+        ? `  ${highlight(snip, kws, t)}`
+        : `  ${s.first}${s.name ? `  [${s.name}]` : ""}`;
+      if (sel) {
+        rows.push(t.bg("selectedBg", padEndVisible(t.fg("accent", truncateToWidth(l1, lw)), lw)));
+        rows.push(t.bg("selectedBg", padEndVisible(truncateToWidth(l2, lw), lw)));
+      } else {
+        rows.push(padEndVisible(l1, lw));
+        rows.push(padEndVisible(t.fg("dim", truncateToWidth(l2, lw)), lw));
+      }
+    }
+    return rows.slice(0, height);
+  }
+
+  // 右栏。有关键词时滚到第一个命中处，没有时滚到底部看最新消息
+  private buildPreview(rw: number): void {
+    const t = this.theme;
+    const s = this.filtered[this.selected];
+    const key = s ? `${s.path}|${this.getQuery()}|${rw}` : "none";
+    if (key === this.previewKey) return;
+    this.previewKey = key;
+    this.matchLines = [];
+
+    if (!s) {
+      this.previewLines = [t.fg("dim", "没有匹配的会话")];
+      this.previewOffset = 0;
+      return;
+    }
+
+    const lines: string[] = [];
+    lines.push(
+      truncateToWidth(
+        t.fg("dim", `${s.cwd} • ${s.msgs.length} 条消息${s.name ? " • " + s.name : ""}`),
+        rw,
+      ),
+    );
+    lines.push("");
+
+    const { kws } = this.query();
+    const MAX_MSGS = 500;
+    const truncated = s.msgs.length > MAX_MSGS;
+    const msgs = truncated ? s.msgs.slice(-MAX_MSGS) : s.msgs;
+    if (truncated) {
+      lines.push(t.fg("dim", `（会话过长，仅显示最后 ${MAX_MSGS} 条）`));
+      lines.push("");
+    }
+    if (kws.length && !msgs.some((m) => anyKw(m.text.toLowerCase(), kws))) {
+      const inTruncated = truncated && s.msgs.some((m) => anyKw(m.text.toLowerCase(), kws));
+      lines.push(
+        t.fg(
+          "warning",
+          inTruncated ? "关键词命中在未显示的更早消息中" : "关键词仅命中会话名或目录，对话正文无匹配",
+        ),
+      );
+      lines.push("");
+    }
+
+    // 用户消息整块背景色，AI 消息只有一条细线标签
+    const fillLabel = (label: string): string => {
+      const w = visibleWidth(label);
+      return truncateToWidth(label + " " + "─".repeat(Math.max(2, rw - w - 1)), rw);
+    };
+
+    for (const m of msgs) {
+      const isMatch = kws.length > 0 && anyKw(m.text.toLowerCase(), kws);
+      if (isMatch) this.matchLines.push(lines.length);
+      const body = isMatch ? highlight(m.text, kws, t) : m.text;
+
+      if (m.role === "user") {
+        lines.push(
+          t.bg("userMessageBg", padEndVisible(t.bold(t.fg("accent", fillLabel("👤 你"))), rw)),
+        );
+        for (const wl of wrapLines(body, rw - 2)) {
+          lines.push(t.bg("userMessageBg", padEndVisible(" " + wl, rw)));
+        }
+      } else {
+        lines.push(t.fg("muted", fillLabel("🤖 AI")));
+        for (const wl of wrapLines(body, rw - 2)) lines.push(" " + wl);
+      }
+      lines.push("");
+    }
+
+    this.previewLines = lines;
+
+    if (this.matchLines.length) {
+      this.previewOffset = Math.max(0, this.matchLines[0] - 2);
+    } else {
+      this.previewOffset = Math.max(0, lines.length - this.bodyHeight());
+    }
+  }
+
+  render(width: number): string[] {
+    const H = this.bodyHeight();
+    const cacheKey = width * 1000 + H; // 宽或高变了都要重画
+    if (this.cachedWidth === cacheKey) return this.cachedLines;
+    const t = this.theme;
+    const lw = Math.max(26, Math.min(56, Math.floor(width * 0.4)));
+    const rw = Math.max(20, width - lw - 3);
+
+    const out: string[] = [];
+
+    // 头部：标题、范围、时间过滤、匹配数，然后是搜索框
+    const scopeLabel = this.scope === "all" ? "全局" : "当前目录树";
+    const { sinceLabel } = this.query();
+    const head =
+      t.fg("accent", t.bold("🔍 会话搜索预览")) +
+      t.fg("dim", "  范围[Tab]: ") +
+      t.fg("warning", scopeLabel) +
+      (sinceLabel ? t.fg("dim", "  时间: ") + t.fg("warning", sinceLabel) : "") +
+      t.fg("dim", `  匹配 ${this.filtered.length}/${this.all.length}`);
+    out.push(truncateToWidth(head, width));
+    out.push(this.input.render(width)[0] ?? "");
+    out.push(t.fg("borderMuted", "─".repeat(width)));
+
+    // 双栏
+    this.buildPreview(rw);
+    const leftRows = this.buildList(H, lw);
+
+    const maxOff = Math.max(0, this.previewLines.length - H);
+    if (this.previewOffset > maxOff) this.previewOffset = maxOff;
+    const rightRows = this.previewLines.slice(this.previewOffset, this.previewOffset + H);
+    const scrollInfo =
+      this.previewLines.length > H
+        ? t.fg(
+            "dim",
+            ` (${this.previewOffset + 1}-${Math.min(this.previewOffset + H, this.previewLines.length)}/${this.previewLines.length})`,
+          )
+        : "";
+
+    for (let i = 0; i < H; i++) {
+      const l = leftRows[i] ?? "";
+      let r = rightRows[i] ?? "";
+      if (i === 0 && scrollInfo) {
+        r = truncateToWidth(r, Math.max(0, rw - visibleWidth(scrollInfo))) + scrollInfo;
+      }
+      // 左栏在 buildList 里已经 pad 到 lw，这里再 pad 会把带样式的行截坏
+      out.push(l + t.fg("borderMuted", " │ ") + padEndVisible(r, rw));
+    }
+
+    // 底部：重命名和删除确认时换成对应的操作行
+    out.push(t.fg("borderMuted", "─".repeat(width)));
+    if (this.renaming) {
+      const prefix = "✏ 重命名: ";
+      const inputLine = this.renameInput.render(Math.max(10, width - visibleWidth(prefix)))[0] ?? "";
+      out.push(truncateToWidth(t.fg("warning", prefix) + inputLine, width));
+    } else if (this.confirmingDelete) {
+      const s = this.filtered[this.selected];
+      const desc = s ? `${fmtTime(s.time, true)} ${s.first.slice(0, 30)}` : "";
+      out.push(
+        truncateToWidth(
+          t.fg("error", t.bold(`⚠ 删除会话 [${desc}]？按 y / Enter 确认，任意其他键取消`)),
+          width,
+        ),
+      );
+    } else {
+      out.push(
+        truncateToWidth(
+          t.fg("dim", "↑↓ 选择  PgUp/Dn·^U/^F·⇧↑↓ 滚动  ^N/^P 命中  Tab 范围  ^D 删除  ^R 改名  ^O 分叉  Enter 进入  Esc/^C 关闭"),
+          width,
+        ),
+      );
+    }
+
+    this.cachedWidth = cacheKey;
+    this.cachedLines = out;
+    return out;
+  }
+
+  invalidate(): void {
+    this.cachedWidth = -1;
+    this.input.invalidate();
+  }
+}

package/src/query.ts

@@ -0,0 +1,89 @@
+import type { PeekMsg } from "./sessions.ts";
+
+// 搜索框语法：空格分隔多个词，都要命中；@7d / @24h / @2w / @1m 限定最近活动时间
+
+export interface ParsedQuery {
+  kws: string[];
+  since: number; // 毫秒时间戳，0 表示不限
+  sinceLabel: string;
+}
+
+const TIME_UNIT_MS: Record<string, number> = { h: 3600e3, d: 86400e3, w: 7 * 86400e3, m: 30 * 86400e3 };
+const TIME_UNIT_LABEL: Record<string, string> = { h: "小时", d: "天", w: "周", m: "个月" };
+
+// "foo bar @7d" → kws = [foo, bar]，since = 7 天前
+export function parseQuery(q: string): ParsedQuery {
+  const kws: string[] = [];
+  let since = 0;
+  let sinceLabel = "";
+  for (const tok of q.toLowerCase().split(/\s+/)) {
+    if (!tok) continue;
+    const m = /^@(\d+)([hdwm])$/.exec(tok);
+    if (m) {
+      const n = Number(m[1]);
+      if (n > 0) {
+        since = Date.now() - n * TIME_UNIT_MS[m[2]];
+        sinceLabel = `近${n}${TIME_UNIT_LABEL[m[2]]}`;
+      }
+      continue;
+    }
+    if (!kws.includes(tok)) kws.push(tok);
+  }
+  return { kws, since, sinceLabel };
+}
+
+// 单条消息用：命中任意一个关键词就算
+export function anyKw(lower: string, kws: string[]): boolean {
+  for (const k of kws) if (lower.includes(k)) return true;
+  return false;
+}
+
+// 最早出现的关键词；同一位置取最长的那个
+function nextMatch(lower: string, kws: string[], i: number): [number, number] {
+  let best = -1;
+  let len = 0;
+  for (const k of kws) {
+    const j = lower.indexOf(k, i);
+    if (j !== -1 && (best === -1 || j < best || (j === best && k.length > len))) {
+      best = j;
+      len = k.length;
+    }
+  }
+  return [best, len];
+}
+
+// 在换行之前调用，返回带 ANSI 的字符串。
+// 不用主题自带的 searchMatchBg：dark/light 主题里它和 selectedBg 同色，看不出来
+export function highlight(text: string, kws: string[], theme: any): string {
+  if (!kws.length) return text;
+  const lower = text.toLowerCase();
+  let out = "";
+  let i = 0;
+  for (;;) {
+    const [j, len] = nextMatch(lower, kws, i);
+    if (j === -1) {
+      out += text.slice(i);
+      break;
+    }
+    out +=
+      text.slice(i, j) +
+      "\x1b[4m" +
+      theme.bold(theme.fg("warning", text.slice(j, j + len))) +
+      "\x1b[24m";
+    i = j + len;
+  }
+  return out;
+}
+
+// 左栏用：第一个命中处前后截一段。没有消息命中时返回 undefined，调用方退回首条消息
+export function snippet(msgs: PeekMsg[], kws: string[], width: number): string | undefined {
+  if (!kws.length) return undefined;
+  for (const m of msgs) {
+    const flat = m.text.replace(/\s+/g, " ");
+    const [j] = nextMatch(flat.toLowerCase(), kws, 0);
+    if (j === -1) continue;
+    const start = Math.max(0, j - Math.floor(width / 3));
+    return (start > 0 ? "…" : "") + flat.slice(start, start + width);
+  }
+  return undefined;
+}

package/src/sessions.ts

@@ -0,0 +1,186 @@
+import { appendFileSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// 读 ~/.pi/agent/sessions 下的会话 JSONL，按 mtime 缓存；重命名和删除也在这里
+
+export interface PeekMsg {
+  role: "user" | "assistant";
+  text: string;
+}
+
+export interface PeekSession {
+  path: string;
+  cwd: string;
+  time: string;
+  name: string; // 最后一条 session_info 里的名字，没有则为空
+  first: string; // 首条消息，列表里显示用
+  msgs: PeekMsg[];
+  searchText: string; // 正文 + 会话名 + cwd，已小写
+  mtime: number;
+}
+
+const sessionCache = new Map<string, PeekSession>();
+
+// 和 pi 一样认 PI_CODING_AGENT_DIR
+function sessionsDir(): string {
+  const env = process.env.PI_CODING_AGENT_DIR;
+  const agent = env ? (env.startsWith("~") ? join(homedir(), env.slice(1)) : env) : join(homedir(), ".pi", "agent");
+  return join(agent, "sessions");
+}
+
+function* walkJsonl(dir: string): Generator<string> {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) yield* walkJsonl(p);
+    else if (e.name.endsWith(".jsonl")) yield p;
+  }
+}
+
+function extractText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((c: any) => c?.type === "text" && typeof c.text === "string")
+    .map((c: any) => c.text)
+    .join("\n");
+}
+
+function parseSession(path: string, mtime: number): PeekSession | null {
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return null;
+  }
+  let cwd = "";
+  let time = "";
+  let name = "";
+  const msgs: PeekMsg[] = [];
+
+  for (const line of raw.split("\n")) {
+    if (!line) continue;
+    try {
+      if (line.includes('"type":"session"')) {
+        const o = JSON.parse(line);
+        cwd = o.cwd ?? cwd;
+        time = o.timestamp ?? time;
+        continue;
+      }
+      if (line.includes('"type":"session_info"')) {
+        const o = JSON.parse(line);
+        if (typeof o.name === "string" && o.name) name = o.name;
+        continue;
+      }
+      // 先用子串粗筛，省掉大部分行的 JSON.parse
+      if (!line.includes('"role":"user"') && !line.includes('"role":"assistant"')) continue;
+      const o = JSON.parse(line);
+      if (o.type !== "message") continue;
+      const role = o.message?.role;
+      if (role !== "user" && role !== "assistant") continue;
+      const text = extractText(o.message?.content).trim();
+      if (text) msgs.push({ role, text });
+    } catch {
+    }
+  }
+
+  if (!msgs.length) return null;
+
+  return {
+    path,
+    cwd,
+    time,
+    name,
+    msgs,
+    mtime,
+    first: msgs[0].text.replace(/\s+/g, " ").slice(0, 80),
+    searchText: (msgs.map((m) => m.text).join(" ") + " " + name + " " + cwd).toLowerCase(),
+  };
+}
+
+/** 全部会话，按最后修改时间倒序；文件没变的直接用缓存 */
+export function scanSessions(): PeekSession[] {
+  const seen = new Set<string>();
+  const out: PeekSession[] = [];
+
+  for (const file of walkJsonl(sessionsDir())) {
+    seen.add(file);
+    let mtime = 0;
+    try {
+      mtime = statSync(file).mtimeMs;
+    } catch {
+      continue;
+    }
+    const hit = sessionCache.get(file);
+    if (hit && hit.mtime === mtime) {
+      out.push(hit);
+      continue;
+    }
+    const parsed = parseSession(file, mtime);
+    if (parsed) {
+      sessionCache.set(file, parsed);
+      out.push(parsed);
+    }
+  }
+
+  // 文件已经不在了的，从缓存里去掉
+  for (const key of [...sessionCache.keys()]) {
+    if (!seen.has(key)) sessionCache.delete(key);
+  }
+
+  return out.sort((a, b) => b.mtime - a.mtime);
+}
+
+// 和 pi 自带的 /name 写同一种 session_info 记录，parentId 用文件里最后一条记录的 id
+export function renameSession(path: string, name: string): void {
+  const raw = readFileSync(path, "utf8");
+  const lines = raw.split("\n");
+  let parentId: string | null = null;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (!lines[i]) continue;
+    try {
+      const o = JSON.parse(lines[i]);
+      if (typeof o.id === "string") {
+        parentId = o.id;
+        break;
+      }
+    } catch {
+      // 末行可能只写了一半
+    }
+  }
+  const entry = {
+    type: "session_info",
+    id: randomBytes(4).toString("hex"),
+    parentId,
+    timestamp: new Date().toISOString(),
+    name,
+  };
+  // 末行没换行（写了一半）时先补一个，别和新记录粘在一起
+  const sep = raw === "" || raw.endsWith("\n") ? "" : "\n";
+  appendFileSync(path, sep + JSON.stringify(entry) + "\n", "utf8");
+}
+
+// 先试 trash（能恢复），不行再直接删。trashExec 由调用方传入，方便测试
+export async function deleteSession(
+  path: string,
+  trashExec: (cmd: string, args: string[]) => Promise<{ code: number }>,
+): Promise<boolean> {
+  try {
+    const r = await trashExec("trash", [path]);
+    if (r.code === 0) return true;
+  } catch {
+  }
+  try {
+    rmSync(path, { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/text.ts

@@ -0,0 +1,28 @@
+import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+
+// Windows 路径大小写不敏感，统一小写再比
+export const normPath = (p: string) => p.replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase();
+
+// 本地时间 "MM-DD HH:mm"；withYear 或不是今年时带年份
+export function fmtTime(iso: string, withYear = false): string {
+  const d = new Date(iso);
+  if (!iso || Number.isNaN(d.getTime())) return withYear ? "????-??-?? ??:??" : "??-?? ??:??";
+  const p = (n: number) => String(n).padStart(2, "0");
+  const md = `${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
+  return withYear || d.getFullYear() !== new Date().getFullYear() ? `${d.getFullYear()}-${md}` : md;
+}
+
+// 按显示宽度补齐到 w，中文和 ANSI 都算对
+export function padEndVisible(s: string, w: number): string {
+  const v = visibleWidth(s);
+  return v >= w ? truncateToWidth(s, w) : s + " ".repeat(w - v);
+}
+
+export function wrapLines(text: string, width: number): string[] {
+  const out: string[] = [];
+  for (const part of text.split("\n")) {
+    const wrapped = wrapTextWithAnsi(part, width);
+    out.push(...(wrapped.length ? wrapped : [""]));
+  }
+  return out;
+}