dsh-ssh-tui 0.2.0 → 0.3.1

package/lib/types/index.d.ts

@@ -23,6 +23,8 @@ export interface Config {
     provider?: string;
     /** CLI-supplied model override; otherwise the saved default is used. */
     model?: string;
+    /** Minimum milliseconds between paints; see DSH_TUI_PAINT_MS. */
+    paintIntervalMs?: number;
 }
 /**
  * Mount the SSH TUI. The `main` agent is created here after the loader

package/lib/types/subagent-model.d.ts

@@ -4,15 +4,30 @@
  *
  * The provider is deliberately inherited from the running parent session:
  * the subagent selection only overrides the provider when the user stored an
- * explicit route. The model defaults to the lightweight `deepseek-v4-flash`.
+ * explicit route. When the parent provider changes, the TUI picks a
+ * same-family default (DeepSeek flash, Grok 4.5, otherwise the first listed
+ * lightweight model) unless `/submodel` stored an explicit model.
  */
 import z from '@deepseek-ai/schemastery';
 import type { Context } from '@deepseek-ai/cordis';
 import { type ReasoningEffortId as ReasoningEffort } from '@deepseek-ai/dsh-llm';
 /** Settings namespace carrying the TUI's subagent model selection. */
 export declare const SUBAGENT_SETTINGS_NAMESPACE: import("@deepseek-ai/dsh-settings").SettingsNamespace;
-/** Lightweight default model used for subagent children. */
+/** Lightweight default model used for DeepSeek-family subagent children. */
 export declare const DEFAULT_SUBAGENT_MODEL = "deepseek-v4-flash";
+/** Preferred subagent default when the parent route is SuperGrok / xAI. */
+export declare const DEFAULT_XAI_SUBAGENT_MODEL = "grok-4.5";
+/**
+ * Choose the default subagent model for a parent provider, preferring a
+ * same-family listed model over a leftover DeepSeek flash id.
+ */
+export declare function defaultSubagentModelForProvider(provider: string, listed?: readonly string[]): string;
+/**
+ * True when the stored subagent model still belongs to the parent provider
+ * family. An explicit leftover DeepSeek flash id after switching to xAI is
+ * treated as stale so the TUI can pick a same-family default.
+ */
+export declare function subagentModelMatchesProvider(provider: string, model: string, listed?: readonly string[]): boolean;
 /** Raw settings document shape. */
 export interface SubagentSettings {
     /** Explicit provider override; omitted means "same provider as the parent". */

package/lib/types/tui.d.ts

@@ -5,9 +5,9 @@
  * `ask_user_question` prompts from the keyboard, and drives one configured
  * agent with followup/steer.
  *
- * The renderer uses plain ANSI and a throttled full repaint, which keeps it
- * predictable over slow SSH links and avoids terminal-library dependency
- * drift inside the plugin.
+ * The renderer uses plain ANSI and coalesces each frame into one stdout
+ * write of dirty rows only — jump-host / proxied SSH should see one packet
+ * per paint, not one per line. Cadence is DSH_TUI_PAINT_MS (default 120).
  */
 import type { Agent, ModelSelection, ModelSelectionRef } from '@deepseek-ai/dsh-agent';
 import type { Context } from '@deepseek-ai/cordis';
@@ -50,6 +50,12 @@ export interface TuiConfig {
     onSelectionChanged?: (selection: ModelSelection) => void;
     /** Open the history-session picker immediately after mounting (--resume). */
     resumePicker?: boolean;
+    /**
+     * Minimum milliseconds between paints while a turn is streaming.
+     * Jump-host / proxied SSH can raise this so token ticks do not flood the
+     * link. Defaults from `DSH_TUI_PAINT_MS` (120).
+     */
+    paintIntervalMs?: number;
 }
 type SubagentLogKind = 'user' | 'assistant' | 'tool' | 'result' | 'turn' | 'approval' | 'team' | 'system';
 /** One child-session event folded into a parent-side subagent card. */
@@ -111,7 +117,10 @@ type Row = {
     active: boolean;
     pending: boolean;
     todos: PlanTodoItem[];
+    planMarkdown?: string;
     expanded: boolean;
+    /** When true the plan stays in the scrolling transcript, not the dock. */
+    archived?: boolean;
 } | {
     kind: 'question';
     questionId: string;
@@ -135,7 +144,7 @@ type Row = {
     kind: 'error';
     text: string;
 };
-type DisplayKind = Row['kind'] | 'tool-result' | 'diff-add' | 'diff-del' | 'diff-path';
+type DisplayKind = Row['kind'] | 'tool-result' | 'diff-add' | 'diff-del' | 'diff-path' | 'todo-done' | 'todo-active' | 'todo-pending' | 'plan-dock';
 /** One file's change, matching the web diff-card contract (`card: 'diff'`). */
 interface ToolDiffHunk {
     path: string;
@@ -146,6 +155,55 @@ interface ToolDiffHunk {
 export interface TuiController {
     dispose(): Promise<void>;
 }
+/**
+ * Paint cadence for jump-host / proxied SSH. Token ticks coalesce into one
+ * frame; the default stays snappy, slower links raise `DSH_TUI_PAINT_MS`.
+ */
+export declare function resolvePaintIntervalMs(configured?: number, env?: NodeJS.ProcessEnv): number;
+/** One incremental paint as a single stdout write (one SSH packet when corked). */
+export declare function composePaintOutput(options: {
+    width: number;
+    height: number;
+    paintRows: readonly string[];
+    previousRows: readonly string[];
+    sizeChanged: boolean;
+    chromeChanged: boolean;
+    chromeStart: number;
+    cursorRow: number;
+    cursorColumn: number;
+}): string;
+/** Human-facing kind for a live LLM route. */
+export declare function describeProviderRoute(provider: string): {
+    kind: string;
+    short: string;
+};
+/** Routes that authenticate without a harness API-key credential. */
+export declare function providerUsesLocalOAuth(provider: string): boolean;
+/**
+ * Terminal cell width for one string.
+ *
+ * Match glibc wcwidth / typical UTF-8 SSH terminals: CJK ideographs and
+ * fullwidth forms occupy two cells; East-Asian Ambiguous box-drawing and
+ * ornaments (`─`, `●`, `·`, `▸`, `❯`, Braille spinners) occupy one. Counting
+ * those ambiguous glyphs as two made `repeatToWidth('─', cols)` paint a
+ * half-width rule and parked the input cursor half a cell past the text.
+ *
+ * Overflow into the input box is handled by clipping/padding painted rows to
+ * the measured column count, not by inflating glyph width.
+ */
+export declare function displayWidth(text: string): number;
+/** Pad or clip one already-sanitized line so it occupies exactly `width` cells. */
+export declare function padToWidth(text: string, width: number): string;
+/**
+ * Pad an already-styled ANSI line to `width` cells without resetting SGR.
+ * Diff add/del rows keep their background across the whole terminal row
+ * instead of only the glyphs.
+ */
+export declare function padAnsiToWidth(text: string, width: number): string;
+/** Visible width of an ANSI-styled line, ignoring CSI / OSC sequences. */
+export declare function visibleWidth(text: string): number;
+/** Repeat a glyph until it occupies exactly `width` cells. */
+export declare function repeatToWidth(glyph: string, width: number): string;
 /**
  * Render workspace markdown into width-bounded terminal rows. Assistant
  * replies get a bold-white base; code blocks, headings, quotes, lists, rules,
@@ -154,6 +212,12 @@ export interface TuiController {
 export declare function renderMarkdownLines(text: string, width: number, color: boolean): string[];
 /** Cut one line to fit a width, appending an ellipsis when truncated. */
 export declare function truncateToWidth(text: string, width: number): string;
+/**
+ * Clip an already-styled ANSI line to `width` terminal cells without dropping
+ * the reset/SGR sequences. Used by the incremental painter so a leftover wide
+ * glyph cannot wrap into the next row.
+ */
+export declare function clipAnsiToWidth(text: string, width: number): string;
 /** One renderable view of the input line: text plus the cursor's visual offset. */
 interface InputView {
     text: string;
@@ -185,6 +249,37 @@ export declare function openCodeSourceFor(provider: string, llmPiAiSection: unkn
 export declare function formatOpenCodeGoUsage(payload: unknown, source: OpenCodeSource): string;
 /** Whether `text` could still grow into a recognized escape sequence. */
 export declare function isEscapePrefix(text: string): boolean;
+/** True while a plan still belongs in the dock (latest incomplete work). */
+export declare function planIsLive(plan: {
+    active: boolean;
+    pending: boolean;
+    todos: readonly PlanTodoItem[];
+    planMarkdown?: string;
+    archived?: boolean;
+}): boolean;
+export type CardCategory = 'thinking' | 'plan' | 'subagent' | 'reply' | 'tool' | 'question' | 'goal';
+/** Category for jump / search. Assistant replies are not collapsible cards. */
+export declare function cardCategoryOf(row: {
+    kind: string;
+}): CardCategory | undefined;
+/** Split `/find thinking padAnsi` into an optional category and a query. */
+export declare function parseFindQuery(raw: string): {
+    category?: CardCategory;
+    query: string;
+};
+/** Transcript rows matching a `/find` query, newest last. */
+export declare function matchTranscriptRows(rows: readonly Row[], raw: string): Row[];
+/** One-line note under an expanded plan strip. */
+export declare function planDockNote(plan: {
+    active: boolean;
+    pending: boolean;
+    todos: readonly PlanTodoItem[];
+    planMarkdown?: string;
+}): string;
+/** Compact per-status counts matching the web plan strip. */
+export declare function todoProgressLabel(todos: readonly PlanTodoItem[]): string;
+/** First markdown heading of an exit_plan_mode plan body. */
+export declare function planTitleFromMarkdown(markdown: string): string | undefined;
 /** Parse a todo_write payload into displayable plan items. */
 export declare function parsePlanTodos(value: unknown): PlanTodoItem[];
 /** Compact todo-list summary: done/total plus the first in-progress task. */
@@ -216,6 +311,7 @@ export declare function renderToolDiff(diffs: ToolDiffHunk[], maxLines: number):
 export declare function friendlyJsonLines(value: unknown, depth?: number): string[];
 /** Minimal tool-row shape the expanded-body renderer reads. */
 interface ToolBodySource {
+    name?: string;
     diff?: ToolDiffHunk[];
     command?: string;
     status?: 'running' | 'ok' | 'error';
@@ -306,6 +402,12 @@ export declare class SshTui {
     private lastTitleUpdateAt;
     private lastPaintRows;
     private lastChromeKey;
+    private lastPaintWidth;
+    private lastPaintHeight;
+    private readonly paintIntervalMs;
+    private searchHits;
+    private searchIndex;
+    private searchQuery;
     constructor(ctx: Context, agent: Agent, config: TuiConfig);
     /** Enter raw mode, switch to the alternate screen, and start listening. */
     start(): void;
@@ -320,6 +422,8 @@ export declare class SshTui {
     dispose(): Promise<void>;
     /** Human-facing exit with goodbye and flush; called from key handling. */
     requestExit(code: number): Promise<void>;
+    /** Capture one painted frame. Used by README screenshot fixtures. */
+    captureFrame(columns?: number, rows?: number): string[];
     private write;
     private markDirty;
     /** Append one transcript row, bounding memory on long sessions. */
@@ -329,7 +433,13 @@ export declare class SshTui {
     private spinnerFrame;
     private findSubagentRow;
     private findLivePlanRow;
+    /** Older / finished plans stay in the scrolling transcript. */
+    private archiveStalePlans;
     private upsertPlanRow;
+    /** Whether the live plan strip should occupy the workspace footer. */
+    private shouldDockPlan;
+    /** Compact web-style plan strip pinned above the input, not in the transcript. */
+    private paintPlanDock;
     private paintCollapsibleHeader;
     /** Move the expand/collapse focus among reasoning and tool rows. */
     private moveCollapsibleFocus;
@@ -337,9 +447,16 @@ export declare class SshTui {
     private toggleCollapsible;
     /** Expand all collapsible blocks, or collapse them again when all are open. */
     private toggleAllCollapsible;
+    private focusCard;
+    /** Jump to the newest card in a category (thinking / plan / subagent / reply). */
+    private jumpToCategory;
+    private applySearchHits;
+    private runFindCommand;
+    private stepSearch;
     private paint;
     private buildSuggestions;
     private suggestionsVisible;
+    private currentProviderId;
     private currentSelectionLabel;
     /** Replace one step's usage sample so a repeated report never double counts. */
     private recordUsage;
@@ -412,10 +529,22 @@ export declare class SshTui {
      * dialog so an endpoint with dozens of models stays selectable.
      */
     private pickModelOption;
-    /** /model: pick a model and reasoning effort for the current provider. */
+    /** Live adapter routes the TUI can switch to, plus the current selection. */
+    private listSelectableProviders;
+    /** Built-in SuperGrok catalog used when the live adapter list is still warming up. */
+    private static readonly XAI_FALLBACK_MODELS;
+    /** /model: stay on the current provider by default; switching providers is opt-in. */
     private runModelCommand;
+    /** Persist a provider/model/effort choice and keep the subagent on the same family. */
+    private applyModelSelection;
     /** Provider route the next subagent request should use. */
     private effectiveSubagentProvider;
+    /**
+     * When the parent provider changes (OAuth or API key), keep the subagent
+     * on a same-family model. An explicit leftover DeepSeek flash id after
+     * switching to xAI is treated as stale.
+     */
+    private syncSubagentToProvider;
     /** Persist one subagent selection and publish it to the live request waterfall. */
     private saveSubagentSelection;
     /** Resolve the picker model list for one provider (endpoint first, then catalog). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-ssh-tui",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "SSH-friendly interactive terminal TUI plugin for DeepSeek Harness",
   "keywords": [
     "deepseek-harness",
@@ -42,6 +42,7 @@
     "cordis.patch.yml",
     "README.md",
     "README.en.md",
+    "docs/screenshots",
     "LICENSE"
   ],
   "license": "MIT",
@@ -61,7 +62,8 @@
     "install:dsh": "bash scripts/install.sh",
     "install:npm": "bash scripts/install-npm.sh",
     "uninstall:dsh": "bash scripts/uninstall.sh",
-    "verify:dsh": "bash scripts/verify.sh"
+    "verify:dsh": "bash scripts/verify.sh",
+    "screenshots": "npm run build && node scripts/capture-readme-frames.mjs"
   },
   "engines": {
     "node": ">=22.19"