@aiwayds/dsh-tui-pi 2.4.0 → 2.6.0

package/README.md

@@ -4,7 +4,7 @@
 
 pi-style terminal UI for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh) — a plugin suite that turns dsh into a pi-like coding-agent experience: pi-tui look & feel, dsh slash commands, GitHub light/dark themes and a powerline footer.
 
-**Requires dsh >= 0.1.2-alpha.4** — the plugin tracks the rolling `@alpha` host line (currently **0.1.2-alpha.5**); the 0.1.1-rc stable line is not supported (see [ADR 0002](docs/adr/0002-target-dsh-0.1.2-alpha.3-single-target.md)). A startup guard logs a one-line warning and exits cleanly when the host is older than the floor (opt out with `DSH_TUI_SKIP_HOST_CHECK=1`). The support strategy will move to stable-only once dsh ships a stable line past the alpha era.
+**Requires dsh >= 0.1.2-rc.1** — this plugin targets the dsh RC/stable line only (CI and releases resolve the newest of the `latest`/`next` dist-tags at runtime). **The alpha line is no longer supported.** A startup guard logs a one-line warning and exits cleanly when the host is older than the floor (opt out with `DSH_TUI_SKIP_HOST_CHECK=1`). See [ADR 0002](docs/adr/0002-target-dsh-0.1.2-alpha.3-single-target.md) for the now-superseded alpha single-target decision.
 
 https://github.com/user-attachments/assets/6a7e00bb-1fd0-4bc5-9070-457f1e9fa54d
 
@@ -24,6 +24,7 @@ https://github.com/user-attachments/assets/6a7e00bb-1fd0-4bc5-9070-457f1e9fa54d
 - [**Model profiles & favorites**](docs/features/model-profiles.md) — switch a whole model setup per project and keep the picker small.
 - [**Agent preset switching**](docs/features/preset-switch.md) — `Tab` / `/preset` between the shipped agent compositions (`standard`, `minimal`, …); what a preset really gates, and exactly when a switch takes effect.
 - [**Sessions & resume**](docs/features/sessions-resume.md) — sessions stay tidy automatically and resume in a few keystrokes; a cross-process writer guard keeps the log single-writer.
+- [**History browser**](docs/features/history.md) — `/history` opens a fixed two-pane look-back over the session: completed turns on the left, the selected turn's replies on the right; copy a prompt back to the editor, or cold-read any stored session without resuming it (read-only, no writer lock).
 - [**Themes**](docs/features/themes.md) — GitHub light/dark palettes, hot-switchable; `auto` follows your terminal.
 - [**Search, selection & images**](docs/features/search-selection-images.md) — `Ctrl+Shift+F` over the whole transcript, drag-select copies to the OS clipboard, attachments from web/Feishu render inline, LaTeX replies draw as Unicode math.
 - [**Slash commands**](docs/features/slash-commands.md) — `/model`, `/resume`, `/btw`, `/profile-switch`, … plus everything dsh-native.
@@ -38,7 +39,7 @@ dsh plugin --profile tui add @aiwayds/dsh-tui-pi
 dsh --profile tui          # launch (or: dsh-tui-pi)
 ```
 
-Legacy `session_projcache` records (missing `identity.isSeeded`/`identity.inheritedEventCount`, written before dsh 0.1.2-alpha.4) are migrated at the profile layer: the bundle patch replaces the stock `session-projection-cache` row with a wrapper (`@aiwayds/dsh-tui-pi/projcache`) that backfills the records while its module loads — strictly before the stock plugin could open the domain and crash the boot — so every `dsh --profile tui` start is covered, launcher or not. Migration is idempotent, backs up every rewritten file next to the original, and never blocks startup. The `dsh-tui-pi` launcher additionally runs the same migration as a CLI preflight before `exec dsh`.
+Legacy `session_projcache` records (missing `identity.isSeeded`/`identity.inheritedEventCount`, written before dsh 0.1.2-alpha.4 — predating the rc/stable floor of 0.1.2-rc.1 this plugin now targets) are migrated at the profile layer: the bundle patch replaces the stock `session-projection-cache` row with a wrapper (`@aiwayds/dsh-tui-pi/projcache`) that backfills the records while its module loads — strictly before the stock plugin could open the domain and crash the boot — so every `dsh --profile tui` start is covered, launcher or not. Migration is idempotent, backs up every rewritten file next to the original, and never blocks startup. The `dsh-tui-pi` launcher additionally runs the same migration as a CLI preflight before `exec dsh`.
 
 Everything that used to need manual patching — the canvas background, the `@deepseek-ai` module closure, the compaction backend — now happens automatically. Upgrade an existing profile after a release:
 
@@ -62,10 +63,10 @@ node scripts/dev-upgrade.mjs 1.0.5 --dry-run  # preview the plan first
 - [@aiwayds/dsh-subagent-registry](https://github.com/fan56/dsh-subagent-registry) — registers `~/.dsh/agents/*.md` as `use_agent` subagents.
 - [@aiwayds/dsh-web-search-anysearch](https://github.com/fan56/dsh-web-search-anysearch) — the AnySearch web search provider.
 
-**Recommended install** — [@aiwayds/dsh-llmwiki-memory](https://github.com/fan56/dsh-llmwiki-memory), OKF topic memory for dsh (zero-LLM hot-path injection + a local git-tracked bundle):
+**Recommended install** — [@aiwayds/dsh-topics-memory](https://github.com/fan56/dsh-topics-memory), OKF topic memory for dsh (zero-LLM hot-path injection + a local git-tracked bundle; formerly dsh-llmwiki-memory):
 
 ```sh
-dsh plugin --profile tui add @aiwayds/dsh-llmwiki-memory
+dsh plugin --profile tui add @aiwayds/dsh-topics-memory
 ```
 
 **Optional** — [@aiwayds/dsh-feishu](https://github.com/fan56/dsh-feishu) — drives the same dsh session from Feishu/Lark on your phone ([demo](docs/features/feishu-demo.md)).

package/README.zh-CN.md

@@ -4,7 +4,7 @@
 
 面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（dsh）的 pi 风格终端 UI——一套把 dsh 变成 pi 式编码代理体验的插件套件：pi-tui 的外观与交互、dsh 斜杠命令、GitHub 明/暗主题和 powerline 状态栏。
 
-**要求 dsh >= 0.1.2-alpha.4** —— 本插件跟随滚动的 `@alpha` 宿主线（当前为 **0.1.2-alpha.5**）；不支持 0.1.1-rc 稳定线（见 [ADR 0002](docs/adr/0002-target-dsh-0.1.2-alpha.3-single-target.md)）。宿主低于下限时，启动守卫会打一行 warning 并干净退出（可用 `DSH_TUI_SKIP_HOST_CHECK=1` 跳过）。待 dsh 发布越过 alpha 期的正式稳定版后，支持策略将调整为只支持稳定版。
+**要求 dsh >= 0.1.2-rc.1** —— 本插件只跟随 dsh RC/stable 线（CI 与发版在运行时解析 latest/next 中更新的 dist-tag）。**不再支持 alpha 线。**宿主低于下限时，启动守卫会打一行 warning 并干净退出（可用 `DSH_TUI_SKIP_HOST_CHECK=1` 跳过）。alpha 单目标决策的历史见 [ADR 0002](docs/adr/0002-target-dsh-0.1.2-alpha.3-single-target.md)（已被取代）。
 
 https://github.com/user-attachments/assets/6a7e00bb-1fd0-4bc5-9070-457f1e9fa54d
 
@@ -60,10 +60,10 @@ node scripts/dev-upgrade.mjs 1.0.5 --dry-run  # 先预览执行计划
 - [@aiwayds/dsh-subagent-registry](https://github.com/fan56/dsh-subagent-registry) —— 把 `~/.dsh/agents/*.md` 注册成 `use_agent` 子代理。
 - [@aiwayds/dsh-web-search-anysearch](https://github.com/fan56/dsh-web-search-anysearch) —— AnySearch web 搜索 provider。
 
-**推荐安装** —— [@aiwayds/dsh-llmwiki-memory](https://github.com/fan56/dsh-llmwiki-memory)，dsh 的 OKF topic 记忆插件（零 LLM 热路径注入 + 本地 git 可追溯 bundle）：
+**推荐安装** —— [@aiwayds/dsh-topics-memory](https://github.com/fan56/dsh-topics-memory)，dsh 的 OKF topic 记忆插件（零 LLM 热路径注入 + 本地 git 可追溯 bundle；原名 dsh-llmwiki-memory）：
 
 ```sh
-dsh plugin --profile tui add @aiwayds/dsh-llmwiki-memory
+dsh plugin --profile tui add @aiwayds/dsh-topics-memory
 ```
 
 **可选** —— [@aiwayds/dsh-feishu](https://github.com/fan56/dsh-feishu) —— 用手机上的飞书/Lark 驱动同一个 dsh session（[演示](docs/features/feishu-demo.md)）。

package/lib/history-turns.d.ts

@@ -0,0 +1,85 @@
+/**
+ * /history turn grouping — the pure `SessionEvent[] → HistoryTurn[]` fold
+ * behind the history browser (docs/features/history.md, ADR 0003).
+ *
+ * The session log is a linear seq-keyed append-only stream; turns are the
+ * `turn/start … turn/end` brackets over it. One completed bracket becomes one
+ * HistoryTurn carrying everything the browser's two panes need:
+ *
+ * - the turn's user prompts (`user/message`, seq order — claimed steer and
+ *   follow-up messages land here as ordinary kind-'user' messages; injected
+ *   context of other source kinds is NOT a prompt and is excluded, matching
+ *   the /resume preview's vocabulary);
+ * - the turn's assembled LLM replies (`assistant/message` text blocks, seq
+ *   order — a tool-using turn has one per step; the last is the final reply);
+ * - the tool-invocation names (`tool/call`, seq order) for the per-tool count
+ *   summary line.
+ *
+ * A `turn/start` whose `turn/end` never arrives (the currently streaming /
+ * running turn of a live session) is INCOMPLETE and never reaches the output —
+ * a cold-read log has every turn closed, a live snapshot legitimately drops
+ * its in-flight tail. Streaming chunks (`assistant/chunk`) are skipped
+ * outright: the replay-path rule (iron rule 9) — the assembled message carries
+ * the full text.
+ *
+ * Pure and dependency-free apart from the event types, so it is unit-testable
+ * without a terminal or a session store.
+ */
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+/** One completed `turn/start … turn/end` bracket of a session log. */
+export interface HistoryTurn {
+    /** The log's turn number (`turn/start` data). Display identity of the row. */
+    turn: number;
+    /** Seq of the `turn/start` event. */
+    seqStart: number;
+    /** Seq of the closing `turn/end` event. */
+    seqEnd: number;
+    /** Kind of the closing `turn/end` reason (`completed`, `aborted`, …). */
+    endReason: string;
+    /** Error message of an `error`-kind turn end, when the log carried one. */
+    endError: string | undefined;
+    /** True when any assembled message of the turn was flagged `interrupted`. */
+    interrupted: boolean;
+    /**
+     * Text of every human prompt in the turn, seq order — direct prompts and
+     * claimed steer/follow-up messages alike (all source kind 'user').
+     */
+    userTexts: string[];
+    /**
+     * One-line preview of the turn: the first human prompt's text, falling back
+     * to the first text of any user/message kind (an injected-only turn still
+     * gets a readable row). Whitespace as logged.
+     */
+    previewText: string;
+    /** Text-bearing assistant message bodies, seq order (one per step). */
+    assistantTexts: string[];
+    /** Tool invocation names, seq order (repeats included). */
+    toolCallNames: string[];
+}
+/**
+ * Fold a session event snapshot into the completed turns, in log order.
+ * Unclosed brackets (the live turn still streaming when the snapshot was
+ * taken) and events outside any bracket are dropped.
+ */
+export declare function groupHistoryTurns(events: readonly SessionEvent[]): HistoryTurn[];
+/**
+ * The user prompt text a `c`/Enter copy refills the editor with: the turn's
+ * first human prompt. `undefined` when the turn carries NO human prompt —
+ * an injected-only turn (file-change notices, skill content) must never be
+ * refillable into the editor, where one Enter would submit the notice as a
+ * prompt. The LEFT-LIST preview keeps its own fallback (`previewText`), so
+ * such turns still show a readable row; only the copy path declines.
+ */
+export declare function turnPrimaryUserText(turn: HistoryTurn): string | undefined;
+/**
+ * Case-insensitive substring filter over the row vocabulary: the preview text
+ * and the turn number (typing "3" narrows to turn 3xx too — a feature, the
+ * number is the row's identity). Empty query matches everything. Mirrors the
+ * /model filter's matching convention (matchesModelFilter).
+ */
+export declare function matchesTurnFilter(turn: HistoryTurn, query: string): boolean;
+/**
+ * The `⚙ N tool calls: read×2, edit×1` summary of one turn's tool/call names,
+ * in first-appearance order. Empty string for a tool-less turn.
+ */
+export declare function toolCallSummary(names: readonly string[]): string;

package/lib/history-turns.js

@@ -0,0 +1,170 @@
+/**
+ * /history turn grouping — the pure `SessionEvent[] → HistoryTurn[]` fold
+ * behind the history browser (docs/features/history.md, ADR 0003).
+ *
+ * The session log is a linear seq-keyed append-only stream; turns are the
+ * `turn/start … turn/end` brackets over it. One completed bracket becomes one
+ * HistoryTurn carrying everything the browser's two panes need:
+ *
+ * - the turn's user prompts (`user/message`, seq order — claimed steer and
+ *   follow-up messages land here as ordinary kind-'user' messages; injected
+ *   context of other source kinds is NOT a prompt and is excluded, matching
+ *   the /resume preview's vocabulary);
+ * - the turn's assembled LLM replies (`assistant/message` text blocks, seq
+ *   order — a tool-using turn has one per step; the last is the final reply);
+ * - the tool-invocation names (`tool/call`, seq order) for the per-tool count
+ *   summary line.
+ *
+ * A `turn/start` whose `turn/end` never arrives (the currently streaming /
+ * running turn of a live session) is INCOMPLETE and never reaches the output —
+ * a cold-read log has every turn closed, a live snapshot legitimately drops
+ * its in-flight tail. Streaming chunks (`assistant/chunk`) are skipped
+ * outright: the replay-path rule (iron rule 9) — the assembled message carries
+ * the full text.
+ *
+ * Pure and dependency-free apart from the event types, so it is unit-testable
+ * without a terminal or a session store.
+ */
+/**
+ * Join the `text` blocks of a message content array into one trimmed string
+ * (multi-block bodies join with newlines so copy stays faithful). Defensive
+ * over the erased shape — a malformed log row yields '' instead of throwing.
+ */
+function blocksText(content) {
+    if (!Array.isArray(content))
+        return '';
+    let text = '';
+    for (const block of content) {
+        const typed = block;
+        if (typed?.type === 'text' && typeof typed.text === 'string') {
+            text += (text === '' ? '' : '\n') + typed.text;
+        }
+    }
+    return text.trim();
+}
+/**
+ * Fold a session event snapshot into the completed turns, in log order.
+ * Unclosed brackets (the live turn still streaming when the snapshot was
+ * taken) and events outside any bracket are dropped.
+ */
+export function groupHistoryTurns(events) {
+    const turns = [];
+    let open;
+    const close = () => {
+        if (open === undefined)
+            return;
+        const userTexts = open.userEntries
+            .filter(entry => entry.kind === 'user' && entry.text !== '')
+            .map(entry => entry.text);
+        const anyText = open.userEntries.find(entry => entry.text !== '')?.text ?? '';
+        turns.push({
+            turn: open.turn,
+            seqStart: open.seqStart,
+            seqEnd: open.seqEnd,
+            endReason: open.endReason,
+            endError: open.endError,
+            interrupted: open.interrupted,
+            userTexts,
+            previewText: userTexts[0] ?? anyText,
+            assistantTexts: open.assistantTexts,
+            toolCallNames: open.toolCallNames,
+        });
+        open = undefined;
+    };
+    for (const event of events) {
+        if (event.type === 'turn/start') {
+            // A new bracket while one is open means the previous one never closed —
+            // drop it (incomplete) and start fresh; well-formed logs never hit this.
+            open = {
+                turn: Number(event.data.turn),
+                seqStart: Number(event.seq),
+                seqEnd: Number(event.seq),
+                endReason: 'completed',
+                endError: undefined,
+                interrupted: false,
+                userEntries: [],
+                assistantTexts: [],
+                toolCallNames: [],
+            };
+            continue;
+        }
+        if (open === undefined)
+            continue;
+        switch (event.type) {
+            case 'user/message': {
+                const message = event.data;
+                const kind = message.source?.kind ?? '';
+                const text = blocksText(message.content);
+                open.userEntries.push({ kind, text });
+                break;
+            }
+            case 'assistant/message': {
+                const message = event.data.message;
+                const text = blocksText(message.content);
+                if (text !== '')
+                    open.assistantTexts.push(text);
+                if (event.data.interrupted === true)
+                    open.interrupted = true;
+                break;
+            }
+            case 'tool/call':
+                open.toolCallNames.push(event.data.name);
+                break;
+            case 'turn/end': {
+                open.seqEnd = Number(event.seq);
+                open.endReason = event.data.reason.kind;
+                const error = event.data.reason;
+                open.endError = typeof error.error?.message === 'string' ? error.error.message : undefined;
+                close();
+                break;
+            }
+            default:
+                // assistant/chunk (iron rule 9: replay paths never consume chunks),
+                // step/start|end, request/*, command/*, todo/write, … — no turn pane
+                // needs them.
+                break;
+        }
+    }
+    // A trailing unclosed bracket (the live turn mid-flight) is dropped by
+    // never closing it.
+    return turns;
+}
+/**
+ * The user prompt text a `c`/Enter copy refills the editor with: the turn's
+ * first human prompt. `undefined` when the turn carries NO human prompt —
+ * an injected-only turn (file-change notices, skill content) must never be
+ * refillable into the editor, where one Enter would submit the notice as a
+ * prompt. The LEFT-LIST preview keeps its own fallback (`previewText`), so
+ * such turns still show a readable row; only the copy path declines.
+ */
+export function turnPrimaryUserText(turn) {
+    return turn.userTexts[0];
+}
+/**
+ * Case-insensitive substring filter over the row vocabulary: the preview text
+ * and the turn number (typing "3" narrows to turn 3xx too — a feature, the
+ * number is the row's identity). Empty query matches everything. Mirrors the
+ * /model filter's matching convention (matchesModelFilter).
+ */
+export function matchesTurnFilter(turn, query) {
+    const needle = query.trim().toLowerCase();
+    if (needle === '')
+        return true;
+    return turn.previewText.toLowerCase().includes(needle)
+        || String(turn.turn).includes(needle);
+}
+/**
+ * The `⚙ N tool calls: read×2, edit×1` summary of one turn's tool/call names,
+ * in first-appearance order. Empty string for a tool-less turn.
+ */
+export function toolCallSummary(names) {
+    if (names.length === 0)
+        return '';
+    const counts = new Map();
+    for (const name of names)
+        counts.set(name, (counts.get(name) ?? 0) + 1);
+    const parts = [...counts.entries()].map(([name, count]) => `${name}×${count}`);
+    const total = names.length;
+    return `${total} tool call${total === 1 ? '' : 's'}: ${parts.join(', ')}`;
+}
+//# sourceMappingURL=history-turns.js.map

package/lib/history-turns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-turns.js","sourceRoot":"","sources":["../src/history-turns.ts"],"names":[],"mappings":"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"}

package/lib/history.d.ts

@@ -0,0 +1,239 @@
+/**
+ * /history — the read-only two-pane history browser (CONTEXT.md "History
+ * browser", ADR 0003, docs/features/history.md).
+ *
+ * Left pane: a TablePanel listing the browsed session's COMPLETED turns
+ * (turn 序号 + user-message preview, seq order — a list, not a tree; the
+ * session log has no message-level branching). Right pane: the selected
+ * turn's content — the user prompts in the main transcript's bubble style,
+ * the assembled LLM replies as Markdown, and a per-tool call-count summary.
+ * View and copy only: Enter/`c` refills the editor with the turn's user
+ * prompt (a plain setText — never submitted), `s` swaps the browsed session
+ * through a /resume-style picker, Esc closes. No resend, no branch, no
+ * transcript jump.
+ *
+ * Snapshot semantics: the event list is read once per open / session switch
+ * (live session → `session.snapshotEvents()`, stored session →
+ * `sessionPersistence.inspect()` — a cold read, no writer lock, no agent
+ * activation). A session that keeps running while the viewer is open does
+ * NOT live-update; reopening refreshes.
+ *
+ * Layout: ≥100 terminal columns renders an HStack (list ≈40% with a 30-column
+ * floor, detail takes the remainder); narrower terminals stack the panes
+ * vertically (list on top). The container is chosen per render at the current
+ * width. The window itself is FIXED geometry: the panel renders exactly
+ * `overlayContentBudget()` lines (short content pads blank, long content
+ * lives in the detail scroll window), so picking another turn never changes
+ * the window size — only a terminal resize re-derives it (overlay mounted at
+ * '90%' width / '85%' height; the budget floors the same percentage pi-tui
+ * does).
+ *
+ * Focus model: the keyboard lives on the left list by default; `→` hands it
+ * to the detail pane (`↑`/`↓` line-scroll, PgUp/PgDn or `[`/`]` page, `←` or
+ * Esc steps back; every other key is inert there). Esc grades detail → list
+ * → filter-clear → close — it never skips a level. Focus is visible: the
+ * focused pane's cues are the list's ▸ cursor (demoted to `›` while the
+ * detail is keyed) versus the detail pane's accent-BOLD title and its
+ * `← list · ↑↓ scroll` footer hint.
+ *
+ * Scroll reality (documented deviation from the original sketch): pi-tui's
+ * overlay path composites `component.render(width)` lines directly — the
+ * layout engine never descends into overlays, so a ScrollView can never
+ * obtain a viewport there (the same limitation AGENTS.md documents for plain
+ * Containers). The detail pane therefore manages its own scroll window (the
+ * SubagentViewerPanel precedent): `[` / `]` page, selection change resets to
+ * the top. The content itself is built from the same pi-tui primitives the
+ * main transcript uses (Text bubbles / Markdown), so the look matches.
+ *
+ * Static rebuild mode (the setTheme/relayout snapshot pattern): switching the
+ * selected turn REBUILDS the detail container from the turn's events — the
+ * render() path only ever slices an already-built line list and never
+ * touches the event data (iron rule 1: render never re-scans). The one
+ * deliberate exception is the render-time resize check below: an O(1)
+ * budget comparison that may rebuild ALREADY-DERIVED display rows (never
+ * events) so the fixed geometry tracks terminal resizes without a resize
+ * listener. Unlike the transcript's event-driven relayout(), this runs
+ * inside render() by design — do not copy it as a default pattern.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type SessionEvent } from '@deepseek-ai/dsh-session';
+import { Container, type Component, type TUI } from '@earendil-works/pi-tui';
+import { type HistoryTurn } from './history-turns.ts';
+import { PanelHost, TablePanel } from './panels.ts';
+import { type TuiTheme } from './theme/index.ts';
+/** Terminal width at which the browser switches from stacked to side-by-side. */
+export declare const DUAL_PANE_MIN_COLUMNS = 100;
+/** Floor of the left list pane in dual-pane mode (spec: min 30 columns). */
+export declare const LEFT_PANE_MIN_COLUMNS = 30;
+/** Rendered-line cap of one user bubble in the detail pane (spec: truncated). */
+export declare const MAX_USER_BUBBLE_LINES = 40;
+/**
+ * Content-row budget inside the framed overlay: showOverlay slices the
+ * component's lines at maxHeight ('85%' of the terminal — pi-tui floors the
+ * percentage, and so do we, so the budget never exceeds the real slice),
+ * and the FramedOverlay adds 4 chrome rows (top/bottom border + a blank
+ * spacer each). The browser renders EXACTLY this many lines (pad or cap —
+ * fixed window geometry), and every inner budget derives from it so no
+ * footer is ever sliced off. Testable; `rows` injected.
+ */
+export declare function overlayContentBudget(rows?: number | undefined): number;
+/**
+ * Visible rows of the left list: the TablePanel chrome is 7 rows (title,
+ * ┬/header/┼/┴ rules, blank spacer, footer) and 2 more rows are reserved
+ * for the filter line and the status line — the two optional lines that can
+ * co-display with results (an applied filter plus a copy/load status), and
+ * under-reserving them slices the panel footers off the fixed budget; the
+ * stacked layout additionally owes the detail pane its own chrome + a living
+ * body (15 reserved rows), the side-by-side layout only the slice guard (9).
+ * Fixed at panel construction — a terminal resize mid-open keeps the stale
+ * budget until reopened (the accepted overlay behavior). Testable.
+ */
+export declare function listMaxVisible(rows?: number | undefined, columns?: number | undefined): number;
+/** One row of the left list: the turn plus its pre-clipped display cells. */
+export interface HistoryRow {
+    turn: HistoryTurn;
+    /** The log turn number, as displayed. */
+    turnLabel: string;
+    /** One-line preview (control chars folded, hard character cap). */
+    preview: string;
+}
+/**
+ * The left-list rows for a turn list under `query`: case-insensitive
+ * substring match on the preview text and the turn number, in seq order.
+ * Pure; the TablePanel clips `preview` to the cell width at render time.
+ */
+export declare function historyRows(turns: readonly HistoryTurn[], query: string): HistoryRow[];
+/**
+ * The detail pane's content for one turn, as a fresh Container of the same
+ * primitives the main transcript renders: user prompts as canvasSubtle
+ * bubbles (Text + bg), replies as Markdown parsed once per rebuild, then the
+ * `⚙` tool-count summary line and any turn-end notice. Exported for tests.
+ */
+export declare function buildTurnDetailContainer(turn: HistoryTurn, theme: TuiTheme): Container;
+/** Structural TUI/session seam of the browser — keeps the flow testable. */
+export interface HistoryBrowserDeps {
+    readonly ctx: Context;
+    readonly tui: TUI;
+    readonly theme: TuiTheme;
+    /** Current live session id, when one exists. */
+    getSessionId(): string | undefined;
+    /** Event snapshot of the live session (its agent's session.snapshotEvents()). */
+    getLiveEvents(): readonly SessionEvent[] | undefined;
+    /** Copy target: a plain editor setText (never submitted). */
+    copyToEditor(text: string): void;
+    restoreFocus(): void;
+    requestRender(): void;
+}
+/** Events + provenance of one browsed session. */
+interface LoadedSession {
+    sessionId: string;
+    live: boolean;
+    events: readonly SessionEvent[];
+}
+/**
+ * The user-facing failure line for a failed session load. Corrupt logs get
+ * the ⚠ + repair pointer (the /resume vocabulary — repair itself is an
+ * agent-side flow and stays out of this read-only browser).
+ */
+export declare function historyLoadErrorMessage(id: string, error: unknown): string;
+/** One row of the `s` session picker (the /resume picker's vocabulary). */
+export interface SessionPickRow {
+    id: string;
+    updated: string;
+    dir: string;
+    session: string;
+}
+/**
+ * Case-insensitive substring filter over the picker's display vocabulary:
+ * the session title (preview/label, the ⚠ and ● markers included), the
+ * directory, and the raw session id (paste-an-id narrowing). Empty query
+ * matches everything, order preserved. Pure; exported for tests.
+ */
+export declare function filterSessionPickRows(rows: readonly SessionPickRow[], query: string): SessionPickRow[];
+/**
+ * The browser overlay root: left TablePanel + right detail pane, arranged
+ * side-by-side (≥100 columns) or stacked (narrower), the container chosen
+ * per render at the current width. The keyboard stays with the left list
+ * (navigation, `/` filter, Enter/`c` copy, `s` session switch, Esc close);
+ * `[`/`]` page the detail pane; there is no focus management between panes.
+ */
+export declare class HistoryBrowserPanel implements Component {
+    private readonly deps;
+    private readonly host;
+    private listOptions;
+    private list;
+    private readonly detail;
+    private listMax;
+    private sessionId;
+    private live;
+    private turns;
+    private query;
+    private rows;
+    private status;
+    private closed;
+    private pickerLoading;
+    /**
+     * Where the keyboard lives: the left list (default) or the right detail
+     * pane. `→` hands focus to the detail pane, `←`/Esc step back; only the
+     * focused pane's keys act (detail focus makes ↑↓ scroll, list keys inert).
+     */
+    private focus;
+    /**
+     * The overlay budget the current list panel was built for (and its derived
+     * list height): a terminal resize re-derives both — the one explicit
+     * external change the fixed-geometry render is allowed to react to.
+     */
+    private builtBudget;
+    /** Set by openHistoryBrowser; delivers the closing echo text. */
+    onFinish: ((text: string) => void) | undefined;
+    constructor(deps: HistoryBrowserDeps, host: PanelHost, loaded: LoadedSession);
+    /**
+     * (Re)build the left TablePanel over the current rows — the subagent
+     * viewer's swap-the-panel pattern. Columns refit against the live rows
+     * (autoColumns scans every row), so a session whose turn numbers gain a
+     * digit gets a wider TURN column instead of a clipped one; the cursor
+     * lands on `preselect` (row 0 of a freshly loaded session). In-place row
+     * swaps (`setQuery`) keep using the retained options object.
+     */
+    private rebuildListPanel;
+    invalidate(): void;
+    render(width: number): string[];
+    handleInput(data: string): void;
+    /** Move the keyboard between the two panes and refresh the focus visuals. */
+    private setFocus;
+    /** Close the overlay and deliver the closing echo text (once). */
+    private finish;
+    /** Refill the editor with the turn's user prompt and close (never submit). */
+    private copyTurn;
+    private copySelected;
+    /** Swap the browsed session; failures surface on the browser's status line. */
+    private loadAndShow;
+    /**
+     * Build the `s` session picker over prepared rows. Public so tests can
+     * drive the real panel (it mounts as its own overlay through the
+     * PanelHost). The filter is the same caller-held-query contract as the
+     * main list: `/` engages the input, every keystroke rebuilds the rows
+     * (case-insensitive substring over session title, directory and session
+     * id — `filterSessionPickRows`) with the cursor following its session
+     * across the rebuild, Esc clears the query before popping. The query is
+     * picker-local — reset on every `s` (CONTEXT.md "Filter").
+     */
+    buildSessionPickerPanel(rows: readonly SessionPickRow[]): TablePanel<SessionPickRow>;
+    /** Open the session picker overlay (the browser stays mounted underneath). */
+    private openSessionPicker;
+    /** Live query swap: rebuild rows, keep the cursor on its turn when visible. */
+    private setQuery;
+}
+/** Outcome text of the /history command (the command echo line). */
+export interface HistoryOpenResult {
+    text: string;
+    error: boolean;
+}
+/**
+ * Open the history browser. `sessionIdArg` (from `/history <sessionId>`)
+ * cold-reads that session; without one the CURRENT live session is browsed
+ * and, when none exists, a hint line is returned instead. Resolves with the
+ * closing echo text once the overlay closes (Esc, or copy-to-editor).
+ */
+export declare function openHistoryBrowser(deps: HistoryBrowserDeps, sessionIdArg: string | undefined): Promise<HistoryOpenResult>;
+export {};