dsh-code 0.2.0 → 0.4.0

package/lib/types/app.d.ts

@@ -18,13 +18,17 @@ import type { TranscriptStore } from './store.ts';
 import type { ApprovalStore } from './approval.ts';
 import type { CommandsView } from './commands.ts';
 import type { ModelDirectory, ModelRow } from './models.ts';
+import type { QuestionStore } from './questions.ts';
 import type { SkillsView } from './skills.ts';
+import type { MentionCandidate } from './mentions.ts';
 /** Props the runner hands the app; callbacks stay owned by the runner. */
 export interface AppProps {
     /** Event-fed transcript store for the live session. */
     store: TranscriptStore;
     /** Approval-question store fed by the answerer listener. */
     approval: ApprovalStore;
+    /** ask_user_question store fed by the single UI provider. */
+    questions: QuestionStore;
     /** Live slash-command descriptor list (completion candidates). */
     commands: CommandsView;
     /** Live user-invocable skill catalog (completion candidates). */
@@ -49,8 +53,16 @@ export interface AppProps {
     quit(): void;
     /** Load the selectable model directory (called when /model opens). */
     loadModels(): Promise<ModelDirectory>;
+    /** Load @mention candidates for the typed query (files + sessions). */
+    loadMentions(query: string, signal?: AbortSignal): Promise<readonly MentionCandidate[]>;
     /** Apply one /model selection; returns the display label. */
     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;

package/lib/types/mentions.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Workspace @mention support: file candidates from a bounded async scan of
+ * the session cwd, session candidates from the opt-in `sessionReferenceResolver`
+ * service, and submission preparation through its `prepare()` API. Picked
+ * session mentions land as canonical `@[label](dsh-session:…)` tokens; on
+ * submit the text is parsed back into readable `@label` text plus structured
+ * references, snapshots are injected via `agent.inject()` before the readable
+ * message wakes the driver (`followup` idle, `steer` running) — exactly the
+ * upstream README's wiring.
+ *
+ * @module @deepseek-ai/dsh-code/mentions
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import { parseSessionReferenceText, type SessionReferenceCandidate, type SessionReferenceInput } from '@deepseek-ai/dsh-session-reference';
+/** Parsed submission text: readable text plus structured references. */
+type ParsedSessionReferenceText = ReturnType<typeof parseSessionReferenceText>;
+/** One filesystem entry the @ menu can complete. */
+export interface FileCandidate {
+    /** Workspace-relative path with forward slashes. */
+    path: string;
+    /** Entry kind; directories insert with a trailing slash. */
+    kind: 'file' | 'directory';
+}
+/** One merged menu candidate (files and sessions, already ranked). */
+export interface MentionCandidate {
+    /** Text inserted after the `@` (directories carry a trailing slash). */
+    label: string;
+    /** Human-readable origin shown beside the label. */
+    description: string;
+    /** Origin kind for icon/coloring decisions. */
+    kind: 'file' | 'directory' | 'session';
+}
+/** Prepared submission: readable content plus optional injected context. */
+export interface PreparedMention {
+    /** Readable text with mention tokens normalized to `@label`. */
+    text: string;
+    /** Structured source sessions in appearance order (empty when none). */
+    references: SessionReferenceInput[];
+    /** Aggregated snapshot for `agent.inject()`, undefined without references. */
+    additionalContext?: import('@deepseek-ai/dsh-session').UserMessage;
+}
+/** Bounded async BFS scan of a workspace; unreadable entries are skipped. */
+export declare function scanWorkspaceFiles(root: string, signal?: AbortSignal): Promise<readonly FileCandidate[]>;
+/** The mention API the input editor and the runner share. */
+export interface MentionsApi {
+    /** Scanned workspace files, cached across one session. */
+    files(): Promise<readonly FileCandidate[]>;
+    /** Ranked menu candidates for the typed `@` query. */
+    candidates(query: string, signal?: AbortSignal): Promise<readonly MentionCandidate[]>;
+    /** Parse submission text into readable text plus structured references. */
+    parse(text: string): ParsedSessionReferenceText;
+    /**
+     * Snapshot references and build the injected context. Throws the service's
+     * typed error on failure — the caller restores the draft and notifies.
+     */
+    prepare(parsed: ParsedSessionReferenceText, signal?: AbortSignal): Promise<PreparedMention>;
+    /** Canonical mention token for a picked session candidate. */
+    sessionMention(candidate: SessionReferenceCandidate): string;
+}
+/**
+ * Create the mention API for one agent's workspace. A missing
+ * session-reference service degrades to file mentions only (the scan still
+ * works); `prepare` then passes text through untouched.
+ * @param ctx - context carrying the optional `sessionReferenceResolver`.
+ * @param agent - the session owner; excluded from its own candidates.
+ * @param cwd - workspace root to scan.
+ */
+export declare function createMentions(ctx: Context, agent: Agent, cwd: string): MentionsApi;
+export {};

package/lib/types/questions.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The terminal ask_user_question provider: registers the single UI provider
+ * on `ctx.userQuestions` and drives it with a FIFO queue — one question
+ * request on screen at a time, everything else waiting — then resolves the
+ * collected answers back into the tool's promise. The community TUI proved
+ * this exact pipeline shape; here the dialog is an Ink bar instead of a
+ * pi-tui inline modal.
+ *
+ * Plan reviews (`exit_plan_mode`) arrive through the same service with an
+ * `intent: { kind: 'plan-review' }` — the renderer highlights the approve
+ * option; the answer encoding is identical either way.
+ *
+ * @module @deepseek-ai/dsh-code/questions
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type AskUserQuestionAnswer, type AskUserQuestionRequest } from '@deepseek-ai/dsh-user-questions';
+/** One question request waiting on the human, with its settle channels. */
+export interface PendingQuestion {
+    /** The request the renderer walks through question by question. */
+    request: AskUserQuestionRequest;
+    /** Resolve the provider promise with the collected answers. */
+    resolve(answers: AskUserQuestionAnswer): void;
+    /** Reject the provider promise as aborted (also used for Esc cancel). */
+    reject(error: Error): void;
+}
+/** The pending-question snapshot the renderer subscribes to. */
+export interface QuestionSnapshot {
+    /** The active request, or undefined when nothing is being asked. */
+    pending: PendingQuestion | undefined;
+}
+/** Store the pending question lands in; the renderer reads, the provider writes. */
+export interface QuestionStore {
+    /** Subscribe to pending-state changes; returns the unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+    /** Read the current snapshot (identity-stable between changes). */
+    getSnapshot(): QuestionSnapshot;
+    /** Submit the collected answers for the active request and advance the queue. */
+    submit(pending: PendingQuestion, answers: AskUserQuestionAnswer): void;
+    /** Cancel the active request (Esc) — rejects ASK_ABORTED and advances the queue. */
+    cancel(pending: PendingQuestion): void;
+}
+/**
+ * Mount the single `ctx.userQuestions` UI provider over a FIFO queue.
+ * @param ctx - context carrying the `userQuestions` service (dsh-base).
+ * @returns the store the renderer subscribes to; a context without the
+ * service yields a permanently empty store.
+ */
+export declare function mountQuestionProvider(ctx: Context): QuestionStore;

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

@@ -0,0 +1,15 @@
+/**
+ * Terminal animation frame tables derived from the web design language:
+ * the StateDot "ongoing" pixel chase (3×3 ring, 125ms flat-hold brightness
+ * steps, 1s cycle) becomes the single-cell stepped pulse below, and the
+ * streaming caret blink is the Claude-Code convention. Pure functions only —
+ * the Ink layer owns timers and colors.
+ *
+ * @module @deepseek-ai/dsh-code/render/animations
+ */
+/** Single-cell stepped pulse: flat holds mirroring the web's 125ms keyframes. */
+export declare const PULSE_FRAMES: readonly ["█", "█", "▆", "▃", "▁", "▃", "▆", "█"];
+/** Pulse frame for a monotonic tick. */
+export declare function pulseFrame(tick: number): string;
+/** Caret visibility: half the ticks on, half off (530ms blink). */
+export declare function caretVisible(tick: number): boolean;

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/markdown.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Terminal markdown renderer for assistant replies: a pure GFM-subset
+ * block/inline parser producing styled line segments the Ink renderer maps
+ * to colored text. No ANSI here — the app owns color mapping, tests own the
+ * structure. The subset mirrors what agent replies actually emit: headings,
+ * emphasis, inline/fenced code, flat lists, blockquotes, links, rules, and
+ * wrapped paragraphs. Unknown syntax degrades to plain text (never throws).
+ *
+ * @module @deepseek-ai/dsh-code/render/markdown
+ */
+/** Style classes the renderer emits; the app maps them to colors/props. */
+export type MdStyle = 'plain' | 'bold' | 'italic' | 'boldItalic' | 'code' | 'accent' | 'dim' | 'strike';
+/** One styled run of text. */
+export interface MdSegment {
+    /** Visible text (no ANSI). */
+    text: string;
+    /** Presentation class for the app's color map. */
+    style: MdStyle;
+}
+/** One rendered line: a sequence of styled runs. */
+export interface MdLine {
+    segments: readonly MdSegment[];
+}
+/** Visible width of a run in columns (CJK counts double). */
+export declare function visibleColumns(text: string): number;
+/** Render markdown text into styled lines of at most `width` columns. */
+export declare function renderMarkdown(text: string, width: number): readonly MdLine[];

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

@@ -7,17 +7,23 @@
  * @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';
     /** Joined text blocks of the user message. */
     text: string;
+    /** True for collapsed injected context (plugin/continuation notices), which
+     * the renderer marks with a dim ↳ instead of the user ❯ prompt. */
+    notice: boolean;
 }
 /** One assembled assistant reply. */
 export interface AssistantEntry {
     kind: 'assistant';
     /** Joined text blocks of the assistant message. */
     text: string;
+    /** Joined reasoning blocks of the same message, empty when the model thought out loud. */
+    reasoning: string;
 }
 /** One model-requested tool invocation and its settled state. */
 export interface ToolEntry {
@@ -28,10 +34,18 @@ export interface ToolEntry {
     name: string;
     /** Raw arguments JSON string exactly as the model produced it. */
     arguments: string;
+    /** Bounded human-meaningful arguments preview for the tool card. */
+    preview: string;
     /** Execution state; `running` until the paired result lands. */
     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 {
@@ -53,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. */
@@ -76,17 +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;
+    /** 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;
     /**
@@ -96,6 +175,16 @@ export interface TranscriptView {
      * Empty before the session's first request.
      */
     model: string;
+    /** Plan mode state folded from the last `plan/mode` event. */
+    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
@@ -104,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. */
@@ -121,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,20 @@ 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. */
+    permission: string;
 }
 /**
  * Build the footer's display groups; a group with no data drops out whole.

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/render/tool-preview.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Bounded preview line for a tool invocation's raw JSON arguments: the first
+ * human-meaningful string among the well-known keys (command, path, query, …)
+ * with a fallback to the bounded raw JSON. Shared by the tool card in the
+ * transcript and the approval bar's command preview.
+ *
+ * @module @deepseek-ai/dsh-code/render/tool-preview
+ */
+/**
+ * Resolve one bounded preview for raw tool arguments.
+ * @param args - raw JSON arguments string as the model produced it.
+ * @param toolName - the tool the arguments belong to (fallback label).
+ * @returns the preview line; empty when nothing useful resolves.
+ */
+export declare function toolArgumentsPreview(args: string, toolName: string): string;

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/lib/types/theme.d.ts

@@ -25,6 +25,10 @@ export declare const TUI_RGB: {
     readonly error: readonly [239, 68, 68];
     /** Warning amber — `--dsw-static-amber-500`. */
     readonly warn: readonly [245, 158, 11];
+    /** Default foreground text — `--dsw-static-neutral-50`. */
+    readonly text: readonly [236, 240, 246];
+    /** Inline/fenced code — soft sky blue, distinct from brand accents. */
+    readonly code: readonly [125, 211, 252];
 };
 /** Paint with the primary brand blue: whale, wordmark, tool names, accents. */
 export declare function brand(text: string): string;