@aiwayds/dsh-tui-pi 2.5.0 → 2.7.0

package/lib/history.d.ts

@@ -0,0 +1,268 @@
+/**
+ * /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;
+    /**
+     * Show the fork-at-turn confirmation over the open browser; resolves true
+     * = fork now. `turnLabel` is the selected turn's number (as displayed),
+     * `totalTurns` the session's listed turn count; `cold` is true when the
+     * browsed session is not the live one — the fork then detaches the LIVE
+     * session, and the dialog must say so instead of hiding it.
+     */
+    confirmForkAtTurn(turnLabel: string, totalTurns: number, cold: boolean): Promise<boolean>;
+    /**
+     * Fork-and-switch at the turn boundary: start a new session on the CURRENT
+     * preset selection seeded with `seed` (the browsed session's prefix), and
+     * switch to it. Resolves when the new session is live; a rejection leaves
+     * every existing binding untouched (the browser stays open).
+     */
+    forkAtTurn(seed: readonly SessionEvent[], parentSessionId: string): Promise<unknown>;
+    /** Buffered channel for fork failures (a transcript notice). */
+    reportError(message: 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;
+    /** The browsed session's raw events — the fork-at-turn slice source. */
+    private events;
+    private query;
+    private rows;
+    private status;
+    private closed;
+    private pickerLoading;
+    private forkInProgress;
+    /**
+     * 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>;
+    /**
+     * Fork at the selected turn (`f`): confirm over the open browser, then
+     * hand the turn-bounded seed to the fork-and-switch seam. The browsed
+     * session's events are the slice source — live snapshots and cold-read
+     * (`inspect`) events fork alike. Cancel or an empty slice (nothing
+     * completed to carry) changes nothing; a failed fork keeps the browser
+     * open with the failure on the status line plus a buffered notice.
+     */
+    private forkAtSelectedTurn;
+    /** 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 {};