dsh-code 0.3.0 → 0.4.0

package/lib/types/app.d.ts

@@ -59,31 +59,14 @@ export interface AppProps {
     selectModel(row: ModelRow): string;
     /** Cycle to the next permission preset (Shift+Tab); returns the new label. */
     cyclePermission(): string;
+    /** Export the transcript to a markdown file (/export [path]); reports via notices. */
+    exportTranscript(argument: string): Promise<void>;
+    /** Rename the session (/title <text>); returns the outcome line for the notice. */
+    renameTitle(argument: string): string;
     /** Registers the app's notice channel with the runner (called once on mount). */
     onBridgeReady(bridge: {
         notify(text: string): void;
     }): void;
 }
-/** One completion candidate row. */
-interface CompletionCandidate {
-    /** Insertion text for the command name (with leading slash). */
-    label: string;
-    /** Human-readable description shown beside the label. */
-    description: string;
-    /** Candidate origin; skills land the same literal text but route through the prompt. */
-    origin: 'command' | 'skill' | 'mention';
-}
-/** The completion menu snapshot the input editor publishes to the app. */
-export interface MenuState {
-    /** Whether the menu is on screen (slash or @mention). */
-    active: boolean;
-    /** Whether the menu is driven by an @mention token. */
-    mention: boolean;
-    /** Highlighted candidate index (wraps by row count). */
-    index: number;
-    /** Rendered rows in display order. */
-    rows: readonly CompletionCandidate[];
-}
 /** The whole terminal app; state arrives via the store, output via Ink. */
 export declare function App(props: AppProps): ReactElement;
-export {};

package/lib/types/render/export.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Markdown export of one transcript view: the /export command's pure
+ * formatter. Deterministic and side-effect free — the runner owns the file
+ * write, so tests drive the builder with folded views directly.
+ *
+ * @module @deepseek-ai/dsh-code/render/export
+ */
+import type { TranscriptView } from './projection.ts';
+/**
+ * Render the transcript as a standalone markdown document.
+ * @param view - the folded transcript view to export.
+ * @param sessionId - the full session identity for the header.
+ * @returns the complete markdown text.
+ */
+export declare function buildExportMarkdown(view: TranscriptView, sessionId: string): string;

package/lib/types/render/inspector.d.ts

@@ -0,0 +1,30 @@
+/** Pure viewport, selection, and scrolling rules for exclusive TUI panels. */
+/** Terminal-space allocation for the inspector's one dynamic screen. */
+export interface InspectorViewport {
+    /** Maximum dynamic rows, kept strictly below the terminal height. */
+    maxHeight: number;
+    /** Rows available to the selected entry after border, title, and footer. */
+    bodyRows: number;
+    /** Columns available inside the horizontal border and padding. */
+    contentColumns: number;
+    /** Tiny terminals use a borderless one-line close hint. */
+    compact: boolean;
+}
+/**
+ * Keep the inspector plus its persistent status/composer chrome below
+ * `stdout.rows`: at equality Ink clears the terminal and rewrites all
+ * accumulated `<Static>` output on every frame.
+ */
+export declare function panelViewport(columns: number, rows: number): InspectorViewport;
+/** Backward-compatible name for the Ctrl+O-specific caller and tests. */
+export declare function inspectorViewport(columns: number, rows: number): InspectorViewport;
+/** Clamp a first-visible row to the range representable by one viewport. */
+export declare function clampScroll(offset: number, totalRows: number, visibleRows: number): number;
+/** Move a viewport by a signed row delta without escaping its content. */
+export declare function moveScroll(offset: number, delta: number, totalRows: number, visibleRows: number): number;
+/** Keep one focused row visible while preserving the current window when possible. */
+export declare function revealRow(offset: number, row: number, totalRows: number, visibleRows: number): number;
+/** Center a selected list row where possible, clamped at both ends. */
+export declare function selectionWindow(cursor: number, totalRows: number, visibleRows: number): number;
+/** Follow appended history only while the inspector cursor was at the tail. */
+export declare function followInspectorCursor(cursor: number, previousLength: number, nextLength: number): number;

package/lib/types/render/lines.d.ts

@@ -0,0 +1,31 @@
+/** Width-safe styled physical rows for bounded terminal panels. */
+import type { TranscriptEntry } from './projection.ts';
+import { type MdStyle } from './markdown.ts';
+/** Presentation classes mapped to Ink colors by the app boundary. */
+export type LineStyle = MdStyle | 'brand' | 'success' | 'error' | 'warn' | 'dimItalic';
+/** One styled run within a physical terminal row. */
+export interface StyledSegment {
+    text: string;
+    style: LineStyle;
+}
+/** One row guaranteed not to exceed the requested terminal width. */
+export interface StyledLine {
+    segments: readonly StyledSegment[];
+}
+/** Construct one segment without leaking mutable objects into cached rows. */
+export declare function lineSegment(text: string, style?: LineStyle): StyledSegment;
+/**
+ * Sanitize and hard-wrap styled content into exact physical rows.
+ * Tabs become two visible spaces because terminal tab stops are contextual
+ * and therefore cannot participate in a deterministic row budget.
+ */
+export declare function styledLines(segments: readonly StyledSegment[], columns: number): readonly StyledLine[];
+/** Plain/dim text convenience over {@link styledLines}. */
+export declare function textLines(text: string, columns: number, style?: LineStyle): readonly StyledLine[];
+/** Markdown rows re-hardened so a single long word cannot escape the budget. */
+export declare function markdownLines(text: string, columns: number): readonly StyledLine[];
+/**
+ * Convert one durable transcript entry to its complete scrollable row model.
+ * The source entry stays intact; only the caller's visible slice is rendered.
+ */
+export declare function transcriptEntryLines(entry: TranscriptEntry, columns: number): readonly StyledLine[];

package/lib/types/render/projection.d.ts

@@ -7,6 +7,7 @@
  * @module @deepseek-ai/dsh-tui/render/projection
  */
 import type { SessionEvent, TodoItem } from '@deepseek-ai/dsh-session';
+import { type ToolDetail } from './tool-detail.ts';
 /** One user prompt line. */
 export interface UserEntry {
     kind: 'user';
@@ -39,6 +40,12 @@ export interface ToolEntry {
     state: 'running' | 'done' | 'error';
     /** Bounded first text block of the result, empty until it lands. */
     summary: string;
+    /**
+     * Bounded expansion payload for the verbose transcript (Ctrl+O), derived
+     * from the tool's persisted presentation metadata; undefined until the
+     * result lands and only when something renderable exists.
+     */
+    detail: ToolDetail | undefined;
 }
 /** One slash-command execution dispatched through `ctx.commands`. */
 export interface CommandEntry {
@@ -60,8 +67,57 @@ export interface ErrorEntry {
     /** `code: message` of the failure. */
     text: string;
 }
+/** One non-error turn outcome surfaced from `turn/end`. */
+export interface TurnMarkerEntry {
+    kind: 'turn-marker';
+    /** Human-readable outcome line, dim-rendered. */
+    text: string;
+}
+/** One completed compaction lifecycle surfaced from `compaction/end`. */
+export interface CompactionEntry {
+    kind: 'compaction';
+    /** True when the compaction completed, false when it failed. */
+    ok: boolean;
+    /** Heuristic tokens shadowed by the compaction (summary or prune price). */
+    tokens: number;
+    /** Failure text when `ok` is false, empty otherwise. */
+    error: string;
+}
+/** One provider-routed model-request retry (the `llm/retry` pair). */
+export interface RetryEntry {
+    kind: 'retry';
+    /** Correlation id shared with the matching `llm/retry-started`. */
+    retryId: string;
+    /** Attempt ordinal and its cap. */
+    attempt: number;
+    max: number;
+    /** Failure code that triggered the retry. */
+    code: string;
+    /** Backoff wait before the next attempt, in ms. */
+    delayMs: number;
+    /** `running` while the backoff waits, `done` once the attempt started. */
+    state: 'running' | 'done';
+}
+/** Turn-tail deliverables: files mutated by the turn's diff-bearing tools. */
+export interface FilesEntry {
+    kind: 'files';
+    /** Unique mutated paths in call order, bounded. */
+    paths: readonly string[];
+}
 /** Ordered transcript items the renderer draws. */
-export type TranscriptEntry = UserEntry | AssistantEntry | ToolEntry | CommandEntry | ErrorEntry;
+export type TranscriptEntry = UserEntry | AssistantEntry | ToolEntry | CommandEntry | ErrorEntry | TurnMarkerEntry | CompactionEntry | RetryEntry | FilesEntry;
+/** The live goal the status line badges, folded from `goal/change`. */
+export interface GoalFold {
+    /** Human-requested completion objective. */
+    objective: string;
+    /** Durable lifecycle phase. */
+    phase: 'active' | 'paused' | 'blocked' | 'complete';
+    /** Highest admitted continuation round and its cap. */
+    rounds: number;
+    max: number;
+    /** Blocked explanation, empty outside the blocked phase. */
+    blocked: string;
+}
 /** Cumulative token accounting folded from `assistant/message` usage reports. */
 export interface UsageTotals {
     /** Prompt-side billed tokens: `inputTokens` plus both cache buckets. */
@@ -83,19 +139,33 @@ export interface TranscriptStats {
     toolMs: number;
     /** Cumulative token accounting; input stays 0 until a report lands. */
     usage: UsageTotals;
+    /** Prompt-side size of the most recent reported request (context pressure). */
+    lastPromptTokens: number;
+    /** Newest advertised route capacity, 0 when no adapter ever advertised one. */
+    contextWindow: number;
+    /** Summed first-token waits: `step/start` → first non-empty chunk, in ms. */
+    ttftMs: number;
+    /** Steps that produced a first chunk (the TTFT average's denominator). */
+    ttftSteps: number;
+    /** Summed decode spans: first chunk → `assistant/message`, in ms. */
+    decodeMs: number;
+    /** Completion tokens over timed decode spans (the tok/s numerator). */
+    decodeTokens: number;
 }
 /** The complete TUI transcript view for one session. */
 export interface TranscriptView {
     /** Settled entries in log order. */
     entries: readonly TranscriptEntry[];
-    /** Text accumulated from `assistant/chunk` deltas since the last flush. */
+    /** Bounded text tail accumulated from `assistant/chunk` deltas since the last flush. */
     streaming: string;
-    /** Thinking accumulated from `assistant/chunk` reasoning deltas since the last flush. */
+    /** Bounded thinking tail accumulated from reasoning deltas since the last flush. */
     streamingReasoning: string;
     /** Latest whole-list todo snapshot from `todo/write`, empty when none. */
     todos: readonly TodoItem[];
     /** True while a durable turn is open (`turn/start` … `turn/end`). */
     busy: boolean;
+    /** `turn/start` time of the open turn (0 while idle) — the web TurnStatus clock anchor. */
+    busySince: number;
     /** Figures the status line renders. */
     stats: TranscriptStats;
     /**
@@ -109,6 +179,12 @@ export interface TranscriptView {
     plan: boolean;
     /** Active permission preset folded from the last `permission/preset` event, empty before one. */
     permission: string;
+    /** Latest session title folded from the last `session/title` event, empty before one. */
+    title: string;
+    /** Sandbox-mode override folded from the last `sandbox/mode` event, empty when never switched. */
+    sandbox: string;
+    /** Current long-running goal folded from the last `goal/change`, undefined when cleared. */
+    goal: GoalFold | undefined;
     /**
      * Fold-internal timing anchors, never rendered: open step and tool-call
      * start timestamps the next `assistant/message` / `tool/result` resolves
@@ -117,6 +193,10 @@ export interface TranscriptView {
     readonly anchors: {
         stepStart: Map<string, number>;
         toolStart: Map<string, number>;
+        firstChunkAt: Map<string, number>;
+        compactionTokens: Map<string, number>;
+        lastPruneTokens: number;
+        turnFiles: Map<number, Set<string>>;
     };
 }
 /** A fresh, empty transcript view. */
@@ -134,3 +214,15 @@ export declare function projectEvent(view: TranscriptView, event: SessionEvent):
  * @returns the folded view.
  */
 export declare function projectEvents(events: readonly SessionEvent[]): TranscriptView;
+/**
+ * How many leading transcript entries can never change again: only a
+ * `running` tool or retry can still mutate in place — everything before the
+ * first one (including a completed tail: later events only APPEND new rows)
+ * is final. The renderer currently draws the whole transcript dynamically
+ * (a `<Static>` flush proved unstable with CJK wrapping on real terminals);
+ * this boundary stays as the append-only contract for when flushing is
+ * reintroduced.
+ * @param entries - the view's transcript entries in order.
+ * @returns the count of entries safe to flush (0 for an empty transcript).
+ */
+export declare function settledEntryCount(entries: readonly TranscriptEntry[]): number;

package/lib/types/render/status.d.ts

@@ -21,6 +21,13 @@ export declare function formatTokens(n: number): string;
  * @returns display string.
  */
 export declare function formatDuration(ms: number): string;
+/**
+ * Compact decode rate: one decimal under a hundred, whole below a thousand,
+ * then thousands (15.3 / 124 / 1.2K).
+ * @param n - tokens per second.
+ * @returns display string.
+ */
+export declare function formatRate(n: number): string;
 /**
  * Cache-hit share of billed prompt-side input.
  * @param usage - cumulative token totals.
@@ -37,6 +44,16 @@ export interface StatusFacts {
     branch: string;
     /** Short session identifier (last dash-separated segment or tail). */
     sessionId: string;
+    /** Latest session title (folded from `session/title`); shown in place of the id. */
+    title: string;
+    /** Sandbox-mode override (folded from `sandbox/mode`), empty when never switched. */
+    sandbox: string;
+    /** Live goal summary (folded from `goal/change`), undefined when none. */
+    goal: {
+        phase: string;
+        rounds: number;
+        max: number;
+    } | undefined;
     /** Whether plan mode is active (folded from `plan/mode`). */
     plan: boolean;
     /** Active permission preset (folded from `permission/preset`), empty when unknown. */

package/lib/types/render/text.d.ts

@@ -16,3 +16,21 @@
  * as a literal `\xNN` escape.
  */
 export declare function displayText(text: string): string;
+/** A display-safe suffix bounded by terminal rows and columns. */
+export interface DisplayTail {
+    /** Sanitized suffix suitable for direct terminal rendering. */
+    text: string;
+    /** Whether content before the returned suffix was omitted. */
+    truncated: boolean;
+}
+/**
+ * Keep only the newest display-safe text that fits a terminal rectangle.
+ * The scan walks backward and stops as soon as the suffix is full, so a long
+ * reasoning stream does not rescan its entire accumulated prefix per chunk.
+ * Explicit newlines and terminal wrapping both consume rows.
+ * @param text - raw externally sourced text.
+ * @param columns - available terminal columns.
+ * @param rows - available terminal rows.
+ * @returns a sanitized bounded suffix and whether an earlier prefix was cut.
+ */
+export declare function displayTail(text: string, columns: number, rows: number): DisplayTail;

package/lib/types/render/tool-detail.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Expansion payloads for tool cards (the Ctrl+O verbose transcript): the
+ * TUI-side consumption of the harness presentation contract. Mutation and
+ * read tools persist a structured `tool/result.meta` (`diffs`, read
+ * windows, web sources) exactly so a capable UI can replay richer cards than
+ * the model-facing text; this module narrows that opaque JSON defensively —
+ * mirroring the upstream validators — and pre-formats bounded, render-ready
+ * rows. Malformed or absent metadata always degrades to the bounded raw
+ * result text, never throws during replay.
+ *
+ * @module @deepseek-ai/dsh-code/render/tool-detail
+ */
+/** One rendered diff row: removed, added, or shared context. */
+export interface DiffLine {
+    /** '-' removed, '+' added, ' ' context. */
+    mark: '-' | '+' | ' ';
+    /** The line text, truncated to the column budget. */
+    text: string;
+}
+/** One file's bounded inline diff. */
+export interface ToolDiff {
+    /** File path the change belongs to. */
+    path: string;
+    /** Rendered rows in order; '-' block before the '+' block. */
+    lines: readonly DiffLine[];
+    /** True when the line budget cut the hunk. */
+    truncated: boolean;
+}
+/** One numbered line of a read window. */
+export interface ToolReadLine {
+    /** 1-based file line number. */
+    number: number;
+    /** The line text, truncated to the column budget. */
+    text: string;
+}
+/** One web-search source row. */
+export interface ToolWebSource {
+    /** Source URL. */
+    url: string;
+    /** Source title, when the provider returned one. */
+    title: string | undefined;
+    /** Short excerpt, truncated to the column budget. */
+    snippet: string;
+}
+/** The expansion payload a verbose tool card renders; a discriminated union. */
+export type ToolDetail = {
+    kind: 'diff';
+    diffs: readonly ToolDiff[];
+} | {
+    kind: 'read';
+    path: string;
+    offset: number;
+    lines: readonly ToolReadLine[];
+    totalLines: number;
+    truncated: boolean;
+} | {
+    kind: 'web-search';
+    sources: readonly ToolWebSource[];
+    truncated: boolean;
+} | {
+    kind: 'web-fetch';
+    url: string;
+    statusCode: number;
+} | {
+    kind: 'raw';
+    text: string;
+    truncated: boolean;
+};
+/**
+ * Render one change as removed-then-added rows, hunked by common prefix and
+ * suffix. A null before-image (file create) renders as pure additions. The
+ * budget caps emitted rows and reports the cut, so a whole-file overwrite
+ * never floods the transcript.
+ * @param oldText - prior content, or null for a create.
+ * @param newText - content after the change.
+ * @param budget - maximum rows to emit.
+ * @returns the bounded rows and whether they were cut.
+ */
+export declare function diffRows(oldText: string | null, newText: string, budget: number): {
+    lines: readonly DiffLine[];
+    truncated: boolean;
+};
+/**
+ * Narrow the opaque `tool/result.meta` into one bounded expansion payload,
+ * mirroring the upstream presenters' degradation ladder: diffs (write/edit),
+ * read windows (read), sources (web_search), fetch summaries (web_fetch), and
+ * the bounded raw result text as the universal fallback.
+ * @param meta - the persisted presentation metadata, when the tool attached one.
+ * @param rawText - the joined text blocks of the result message.
+ * @returns the expansion payload, or undefined when nothing renderable exists.
+ */
+export declare function toolResultDetail(meta: unknown, rawText: string): ToolDetail | undefined;

package/lib/types/store.d.ts

@@ -16,6 +16,8 @@ export interface TranscriptStore {
     subscribe(listener: () => void): () => void;
     /** Fold one session event; ignored events change nothing and notify nobody. */
     apply(event: SessionEvent): void;
+    /** Drop the folded view entirely (/clear): the next event starts a fresh one. */
+    reset(): void;
 }
 /**
  * Create one transcript store, optionally seeded with replayed history. The

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-code",
   "description": "Claude-Code-style interactive TUI bundle for DeepSeek Harness (dsh): DeepSeek-blue whale banner, live session transcript, and a blended status line",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "main": "lib/index.mjs",
   "types": "lib/types/index.d.ts",
@@ -72,23 +72,33 @@
     "@deepseek-ai/dsh-cmdline": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-code-runtime-worker-thread": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-commands": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-compaction": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-goal": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-invariants": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm-retry": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-permission-presets": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-plan-mode": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-session-persistence": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-session-reference": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-session-title": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-skill": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-user-approval": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-user-questions": "^0.1.0-rc.6"
   },
   "devDependencies": {
+    "@deepseek-ai/dsh-compaction": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-commands": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-goal": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm-retry": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-permission-presets": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-plan-mode": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-session-persistence": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-session-reference": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-session-title": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-skill": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-user-approval": "^0.1.0-rc.6",
     "@deepseek-ai/dsh-user-questions": "^0.1.0-rc.6",