@aiwayds/dsh-tui-pi 0.3.0 → 0.4.2

package/lib/live-widgets.d.ts

@@ -1,57 +1,80 @@
 /**
- * Live widgets: the Todos boxed panel pinned ABOVE the chat input, and the
- * running-subagent activity merged into the last-request area BELOW the
- * editor. Two separate plain containers keep the two live surfaces apart:
+ * Live widgets — every fixed live surface around the chat window:
  *
- *  - `todosDoc` — the dock slot above the input (`ui.widgets`): a single
- *    bordered Todos panel (top border + header row + tree body rows + bottom
- *    border, same chrome as the thinking/tool panels). Auto height — it
- *    renders zero rows while empty and grows to its content while the model
- *    has todos.
- *  - `activityDoc` — the lastRequest container below the editor
- *    (`ui.lastRequest`): the ` ● <last request>` line (persisting across
- *    agent churn) followed by one compact line PER RUNNING agent. NO box
- *    chrome, NO `● Agents` header, NO provider — just
- *    `├─ ⠋ <name> · ↻N≤M · 21k/1m · 13.6s · <latest output>`, the `├─ ` /
- *    `└─ ` prefix in the same column as the todo rows and the request ` ● `
- *    (the last running agent closes the list with `└─ `). Auto height — it
- *    collapses to zero rows when both the last-request line is cleared and no
- *    agent runs.
+ *  - `todosDoc` (the widgets slot ABOVE the chat input) hosts THREE pinned
+ *    panels: the bordered Todos table, the ThinkPanel and the ToolPanel
+ *    (src/activity.ts). Think/tool activity NEVER creates transcript blocks
+ *    — one panel of each kind exists for the whole run, every event
+ *    refreshes it in place, and a panel with no content renders zero rows.
+ *  - `activityDoc` (the lastRequest container BELOW the editor): the
+ *    ` ● <last request>` line (persisting across agent churn) followed by one
+ *    compact line PER RUNNING agent — `├─ ⠋ <name> · ↻N≤M · 21k/1m · 13.6s ·
+ *    <content tail>`. The tail is the child's latest CONTENT line (assistant
+ *    text/reasoning, live-refreshed — never a tool name) and takes whatever
+ *    the row has left, truncated at the right edge: one row, no wrap.
  *
- * Show-when-content, clear-when-done: the Todos panel appears only while it
- * has content and disappears when it empties (an all-completed snapshot or
- * `/new`); an agent line renders only while its child RUNS (a settled child
- * drops off immediately). `clear()` (/new) drops the Todos panel and the
- * agent lines but preserves the last-request echo.
+ * Event flow: index.ts routes every parent-session event through
+ * `applyEvent` (think/tool phase machine) and todo/write snapshots through
+ * `renderTodos`; the bridge's onLive fold feeds `renderAgents`. Phase rules
+ * for the panels: a reasoning delta shows the think panel; a tool call
+ * refreshes the tool panel (pending); a matching result settles it (status
+ * icon, frozen time, result tail); a text delta / assembled message / user
+ * message / turn end hides the finished phases. `clear()` (/new, resume)
+ * hides both panels.
  *
- * Live refresh: `tickLive` (the AGENT_TICK_MS timer in index.ts) advances the
- * spinner and re-reads the elapsed clock; it is a no-op while nothing runs.
- * `setTheme` recolors in place on a theme hot-switch (no replay buffer — the
- * widget is live state, not transcript history).
+ * Live refresh: `tickLive` (the AGENT_TICK_MS timer in index.ts) advances
+ * the spinner and repaints while any agent runs OR either panel is visible
+ * (the elapsed columns re-read the clock each frame); no-op otherwise.
+ * `setTheme` recolors in place on a theme hot-switch (the panels re-render
+ * each frame through their theme getters — no replay buffer, they are live
+ * state, not transcript history).
  */
-import { Container } from '@earendil-works/pi-tui';
+import { Container, type Component } from '@earendil-works/pi-tui';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import type { PanelHeight } from './activity.ts';
 import type { AgentView } from './dsh-events.ts';
 import { type TuiTheme } from './theme/index.ts';
-/** Refresh interval of the live running-agent lines (spinner + elapsed). */
+/** Refresh interval of the live surfaces (spinner + elapsed columns). */
 export declare const AGENT_TICK_MS = 100;
 /** Braille spinner cycle; the frame index advances once per tick. */
 export declare const AGENT_SPINNER_FRAMES: readonly ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 /**
- * Compact human-readable size: 1_500_000 → `1.5m`, 20_965 → `20k`, 999 → `999`.
+ * Compact human-readable size: 1_500_000 -> `1.5m`, 20_965 -> `20k`, 999 -> `999`.
  * Millions keep one decimal (a trailing `.0` dropped), thousands floor to `k`.
  */
 export declare function fmtCompact(n: number): string;
+/**
+ * The live Todos panel - a self-drawing table on the panel framework
+ * (padCell/columnWidths from panels.ts), rendered at the CURRENT width on
+ * every frame. pi-tui's Container calls `render(width)` per frame with no
+ * caching, so a terminal resize re-lays the table out (clip + column widths)
+ * automatically - no stale baked rows, no word-wrap. Renders zero rows while
+ * the list is empty or every todo is completed (clear-when-done).
+ */
+export declare class TodosPanel implements Component {
+    private todos;
+    private readonly getTheme;
+    constructor(getTheme: () => TuiTheme);
+    invalidate(): void;
+    /** Replace the todos snapshot (`todo/write` events, replay, /new). */
+    setTodos(todos: readonly {
+        content: string;
+        status: string;
+    }[]): void;
+    render(width: number): string[];
+}
 export declare class LiveWidgets {
     private readonly todosDoc;
     private readonly activityDoc;
     private theme;
     private readonly requestRender;
-    /** Latest todo list from `todo/write`, rendered while non-empty. */
-    private liveTodos;
+    /** The self-drawing Todos table, mounted once in `todosDoc`. */
+    private readonly todosPanel;
+    /** The fixed think/tool status panels, mounted once in `todosDoc`. */
+    private readonly thinkPanel;
+    private readonly toolPanel;
     /** Latest subagent views from the bridge's onLive fold. */
     private liveAgents;
-    /** The Todos panel Text in `todosDoc`, replaced on rebuild. */
-    private todosText;
     /** The merged running-agent Text in `activityDoc`, replaced on rebuild. */
     private agentsText;
     /** The ` ● <last request>` Text in `activityDoc` (persists across churn). */
@@ -61,12 +84,14 @@ export declare class LiveWidgets {
     /** Spinner frame counter, advanced by tickLive while any agent runs. */
     private spinnerFrame;
     /**
-     * @param todosDoc The dock slot ABOVE the chat input — the Todos boxed
-     *   panel lives here.
-     * @param activityDoc The lastRequest container BELOW the editor — the ` ● `
+     * @param todosDoc The dock slot ABOVE the chat input - the Todos table and
+     *   the think/tool status panels live here.
+     * @param activityDoc The lastRequest container BELOW the editor - the ` ● `
      *   last-request line plus the compact running-agent lines live here.
+     * @param panelHeight Configured think/tool panel height ('1' one row, or a
+     *   boxed budget - see activity.ts).
      */
-    constructor(todosDoc: Container, activityDoc: Container, theme: TuiTheme, requestRender: () => void);
+    constructor(todosDoc: Container, activityDoc: Container, theme: TuiTheme, requestRender: () => void, panelHeight?: PanelHeight);
     /**
      * Render the ` ● <text>` last-request line in `activityDoc`, UNDER which the
      * running-agent lines appear. `undefined` (or blank) removes the line. Same
@@ -80,59 +105,65 @@ export declare class LiveWidgets {
         content: string;
         status: string;
     }[]): void;
+    /**
+     * One parent-session session event, driving the think/tool phase machine:
+     * a reasoning delta opens/feeds the think panel; a tool call refreshes the
+     * tool panel (pending, replacing any tracked tool) — except delegation
+     * spawn tools (`use_agent`/`subagent`/`workflow`/`ralph`), whose children
+     * already render in the running-agent lines below the editor and never
+     * open a tool block; a matching result settles the tracked tool; a text
+     * delta, an assembled assistant message, a user message or a turn end
+     * hides the finished phases. Called for every event AND for replayed
+     * history (a resumed session replays its tool calls; its final turn/end
+     * leaves the panels hidden).
+     */
+    applyEvent(event: SessionEvent): void;
     /** Replace the subagent views (the bridge's onLive fold). */
     renderAgents(agents: readonly AgentView[]): void;
     /**
-     * Live refresh ~10x/sec while any subagent runs: advance the spinner and
-     * repaint (the elapsed column re-reads Date.now()). No-op when nothing runs
-     * — the activity area then holds its final (empty) state.
+     * Live refresh ~10x/sec while any subagent runs or either status panel is
+     * visible: advance the spinner and repaint (the elapsed columns re-read
+     * Date.now() each frame). No-op otherwise — the activity area then holds
+     * its final (empty) state.
      */
     tickLive(): void;
-    /** Recolor the widget (Todos panel, ● line and agent lines) under a theme
-     * hot-switch (no-op on the same bundle). */
+    /**
+     * Switch the configured think/tool panel height (the settings watch sink).
+     * The panels re-render at the new budget on the next frame — no rebuild
+     * wiring, they are self-drawing.
+     */
+    setPanelHeight(panelHeight: PanelHeight): void;
+    /** Recolor the widget (Todos panel, think/tool panels, ● line and agent
+     * lines) under a theme hot-switch (no-op on the same bundle). The panels
+     * read the theme through their getters, so the swap needs only a repaint. */
     setTheme(theme: TuiTheme): void;
     /**
      * Drop everything except the last-request echo (`/new`): clears the Todos
-     * panel and the running-agent lines, keeps the ` ● ` line. The bridge also
-     * fires `renderAgents([])`.
+     * panel, hides the think/tool panels and drops the running-agent lines,
+     * keeps the ` ● ` line. The bridge also fires `renderAgents([])`.
      */
     clear(): void;
     /**
-     * Rebuild the two live surfaces:
-     *  - `todosDoc`: one bordered Todos panel (or nothing when all completed).
-     *  - `activityDoc`: the ` ● ` line (managed separately, persists) followed
-     *    by ONE Text holding the compact running-agent lines joined by '\n'
-     *    (or nothing when no agent runs — the slot collapses to the ● line).
-     * Clear-when-done: the Todos panel hides once every todo is completed (the
-     * model writes the whole-list snapshot and rarely clears it — an
-     * all-completed list is the end-of-work signal); the agent lines hide once
-     * no child is running.
+     * Rebuild the running-agent surface of `activityDoc`: the ` ● ` line
+     * (managed separately, persists) followed by ONE Text holding the compact
+     * running-agent lines joined by '\n' (or nothing when no agent runs - the
+     * slot collapses to the ● line). The pinned panels are NOT rebuilt here -
+     * they are self-drawing components that re-render each frame.
+     * Clear-when-done: the agent lines hide once no child is running.
      */
     private rebuild;
-    /** One bordered panel: top border + header row + body rows + bottom border. */
-    private boxedPanel;
-    /** `● Todos (done/total)`, styled for the panel header row. */
-    private todosHeader;
-    /**
-     * Tree-style todo body lines: `├─`/`└─` connectors with `☐`/`◐`/`☑` status
-     * icons. Content is model-controlled: clipped BEFORE styling to the boxed
-     * row's inner budget minus the tree chrome (connector 3 cols + icon+space
-     * 2 cols) — see clipPanelLine's contract.
-     */
-    private todoLines;
     /**
      * One compact running-agent line for the last-request area, todo-style:
      * `├─ `/`└─ ` connector (same column as the todo rows and the request
-     * ` ● `) + spinner + the agent NAME (`view.label`, matching the boxed
-     * panel's main line) + the exact meta that main line showed (`↻retries≤max`,
-     * compact `tokens[/contextWindow]`, elapsed) + the child's latest output
-     * line when one exists (` · <tail>`, so the user sees it is alive). NO box
-     * chrome, NO provider — the name is the prominent element; the last running
-     * agent closes the list with `└─ `. The label is the only unbounded field;
-     * it is clipped against a budget measured from the terminal width so the
-     * whole plain line (prefix included) fits, then the assembled plain line is
-     * clipped to the terminal width BEFORE any ANSI is applied (clipToWidth
-     * counts SGR fragments as visible columns — style last).
+     * ` ● `) + spinner + the agent NAME (`view.label`) + the exact meta the
+     * boxed board showed (`↻retries≤max`, compact `tokens[/contextWindow]`,
+     * elapsed) + the child's latest CONTENT line — live-refreshed assistant
+     * text/reasoning, NEVER a tool name — as the ` · <tail>` suffix. NO box
+     * chrome, NO provider. Layout against the terminal width: the name caps at
+     * 40% of the space the meta leaves; the tail takes EVERYTHING else and is
+     * truncated at the right edge (single row, never wrapped). The assembled
+     * plain line is clipped to the terminal width BEFORE any ANSI is applied
+     * (clipToWidth counts SGR fragments as visible columns — style last).
      */
     private compactAgentLine;
 }