dsh-code 0.3.0 → 0.5.0

package/lib/startup.mjs

@@ -3,7 +3,7 @@ import { parseCmdline } from "@deepseek-ai/dsh-cmdline";
 //#region src/startup.ts
 /**
 * The interactive terminal app's command-line provider: parses `--resume`,
-* `--continue`, `--session`, and `--help`, then publishes
+* `--continue`, `--session`, `--mode`, and `--help`, then publishes
 * {@link TUI_STARTUP_SERVICE} for the runner to consume lazily. Follows the
 * headless bundle's startup shape (a commander action publishing a service
 * through {@link parseCmdline}).
@@ -26,17 +26,41 @@ const name = "tui-startup";
 const inject = ["cmdlineArgs"];
 /** Service provided by this plugin and injected by the terminal runner. */
 const TUI_STARTUP_SERVICE = "tuiStartup";
+/** Pure option policy shared by Commander and tests. */
+function resolveTuiStartup(options) {
+	if ([
+		options.resume !== void 0,
+		options.continue === true,
+		options.session !== void 0
+	].filter(Boolean).length > 1) throw new Error("--resume, --continue, and --session are mutually exclusive");
+	if (options.session === "") throw new Error("--session needs an id");
+	if (options.resume === "") throw new Error("--resume needs a session id or id prefix");
+	if (options.mode === "") throw new Error("--mode needs a preset id");
+	if (options.mode !== void 0 && (options.resume !== void 0 || options.continue === true)) throw new Error("--mode applies only to a new session; it cannot be combined with --resume or --continue");
+	return options.resume !== void 0 ? {
+		kind: "resume",
+		sessionId: options.resume
+	} : options.continue === true ? { kind: "latest" } : options.session !== void 0 ? {
+		kind: "named",
+		sessionId: options.session,
+		...options.mode === void 0 ? {} : { mode: options.mode }
+	} : {
+		kind: "fresh",
+		...options.mode === void 0 ? {} : { mode: options.mode }
+	};
+}
 /**
 * This app's command: the launcher's flags this app owns, its description,
 * and its help text.
 * @returns a fresh program, so one process can parse more than once (tests).
 */
 function tuiCommand() {
-	return new Command().name("dsh --profile cli").description("Claude-Code-style interactive terminal for DeepSeek Harness.").helpOption("-h, --help", "show this help").option("-r, --resume <session>", "resume the persisted session with this id (or unique id prefix)").option("-c, --continue", "resume the most recent persisted session for this working directory").option("--session <id>", "create a new session under this explicit id").addHelpText("after", `
+	return new Command().name("dsh --profile cli").description("Claude-Code-style interactive terminal for DeepSeek Harness.").helpOption("-h, --help", "show this help").option("-r, --resume <session>", "resume the persisted session with this id (or unique id prefix)").option("-c, --continue", "resume the most recent persisted session for this working directory").option("--session <id>", "create a new session under this explicit id").option("--mode <preset>", "agent preset for a newly created session").addHelpText("after", `
 Examples:
   dsh --profile cli                       fresh session, minted id
   dsh --profile cli --resume abc123       resume session by id prefix
   dsh --profile cli --continue            resume the latest local session
+  dsh --profile cli --mode minimal        fresh session using the minimal preset
 `);
 }
 /**
@@ -48,23 +72,16 @@ function apply(ctx) {
 	const program = tuiCommand();
 	program.action(() => {
 		const options = program.opts();
-		if ([
-			options.resume !== void 0,
-			options.continue === true,
-			options.session !== void 0
-		].filter(Boolean).length > 1) program.error("error: --resume, --continue, and --session are mutually exclusive");
-		if (options.session !== void 0 && options.session === "") program.error("error: --session needs an id");
-		if (options.resume !== void 0 && options.resume === "") program.error("error: --resume needs a session id or id prefix");
-		const startup = options.resume !== void 0 ? {
-			kind: "resume",
-			sessionId: options.resume
-		} : options.continue === true ? { kind: "latest" } : options.session !== void 0 ? {
-			kind: "named",
-			sessionId: options.session
-		} : { kind: "fresh" };
+		let startup;
+		try {
+			startup = resolveTuiStartup(options);
+		} catch (error) {
+			program.error(`error: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		if (startup === void 0) return;
 		ctx.provide(TUI_STARTUP_SERVICE, { startup });
 	});
 	parseCmdline(ctx, program);
 }
 //#endregion
-export { TUI_STARTUP_SERVICE, apply, inject, name };
+export { TUI_STARTUP_SERVICE, apply, inject, name, resolveTuiStartup };

package/lib/types/app.d.ts

@@ -21,6 +21,11 @@ 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';
+import type { PresetRow } from './presets.ts';
+import type { PluginRow } from './plugin-inventory.ts';
+import type { SessionDirectoryOptions, SessionRow } from './session-directory.ts';
+/** Visual priority for one bounded local notice. */
+export type NoticeTone = 'info' | 'warning' | 'error';
 /** Props the runner hands the app; callbacks stay owned by the runner. */
 export interface AppProps {
     /** Event-fed transcript store for the live session. */
@@ -37,12 +42,16 @@ export interface AppProps {
     model: string;
     /** Working-directory basename the session serves. */
     cwd: string;
+    /** Absolute working directory used by session filters and references. */
+    workspaceRoot: string;
     /** Git branch name, empty outside a repository. */
     branch: string;
     /** Short session identifier. */
     sessionId: string;
     /** Whether this session was resumed from persistence. */
     resumed: boolean;
+    /** Agent preset currently composing the session. */
+    mode: string;
     /** Submit one line: slash commands to the registry, other text to the agent. */
     dispatch(text: string): void;
     /** Submit steering: consumed at the running turn's next step boundary. */
@@ -59,31 +68,23 @@ 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;
+    /** Preset/session/plugin kernel operations. */
+    loadPresets(): Promise<readonly PresetRow[]>;
+    switchMode(id: string): Promise<string>;
+    createSession(mode?: string): void;
+    loadSessions(options: SessionDirectoryOptions, signal?: AbortSignal): Promise<readonly SessionRow[]>;
+    loadSessionTranscript(id: string, signal?: AbortSignal): Promise<string>;
+    switchSession(row: SessionRow): void;
+    cancelSessionSwitch(): boolean;
+    loadPlugins(): readonly PluginRow[];
     /** Registers the app's notice channel with the runner (called once on mount). */
     onBridgeReady(bridge: {
-        notify(text: string): void;
+        notify(text: string, tone?: NoticeTone): 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/commands.d.ts

@@ -14,6 +14,8 @@ import type { CommandDescriptor } from '@deepseek-ai/dsh-commands';
 export interface CommandsView {
     /** Name-sorted descriptors after scoped shadowing. */
     readonly descriptors: readonly CommandDescriptor[];
+    /** Latest descriptor-read failure; the help panel exposes it in place. */
+    readonly error?: string;
     /** Subscribe to list changes (`commands/change`); returns the unsubscribe function. */
     subscribe(listener: () => void): () => void;
     /** Retarget the agent whose scoped view the list is read through. */

package/lib/types/index.d.ts

@@ -1,11 +1,10 @@
 /**
  * @deepseek-ai/dsh-code — the interactive terminal driver. The bundle patch
  * rides over dsh-base without Host, HTTP, or browser plugins; this runner
- * creates (or resumes) one Agent through the core registry, mounts the Ink
- * app (DeepSeek blue, whale wordmark), folds submitted prompts into the same
- * durable session, answers approval asks with a y/n bar, dispatches slash
- * commands through the shared registry, and on quit flushes and requests
- * process exit.
+ * creates or resumes preset-composed Agents through the core registry, keeps
+ * one Ink owner while the active session changes, folds submitted prompts
+ * into the selected durable session, answers approval asks with a y/n bar,
+ * dispatches slash commands, and on quit flushes and requests process exit.
  *
  * @module @deepseek-ai/dsh-code
  */
@@ -21,6 +20,7 @@ export interface Config {
     startup: {
         kind: string;
         sessionId?: string;
+        mode?: string;
     };
 }
 export declare const Config: z<Config>;

package/lib/types/internals.d.ts

@@ -8,6 +8,8 @@
 import type { ReactElement } from 'react';
 /** A mounted terminal app instance; the runner owns unmount ordering. */
 export interface TuiMount {
+    /** Replace the root element while preserving Ink's single terminal owner. */
+    rerender(element: ReactElement): void;
     /** Tear the terminal app down before flush and exit. */
     unmount(): void;
 }

package/lib/types/kernel-panels.d.ts

@@ -0,0 +1,23 @@
+/** Bounded, composer-safe panels for preset, session, and plugin kernel views. */
+import { type ReactElement } from 'react';
+import type { PresetRow } from './presets.ts';
+import type { PluginRow } from './plugin-inventory.ts';
+import type { SessionDirectoryOptions, SessionRow } from './session-directory.ts';
+export declare function ModePanel({ current, load, select, close }: {
+    current: string;
+    load(): Promise<readonly PresetRow[]>;
+    select(id: string): void;
+    close(): void;
+}): ReactElement;
+export declare function PluginPanel({ load, close, initialQuery }: {
+    load(): readonly PluginRow[];
+    close(): void;
+    initialQuery?: string;
+}): ReactElement;
+export declare function ResumePanel({ currentCwd, load, readTranscript, select, close }: {
+    currentCwd: string;
+    load(options: SessionDirectoryOptions, signal?: AbortSignal): Promise<readonly SessionRow[]>;
+    readTranscript(id: string, signal?: AbortSignal): Promise<string>;
+    select(row: SessionRow): void;
+    close(): void;
+}): ReactElement;

package/lib/types/plugin-inventory.d.ts

@@ -0,0 +1,11 @@
+/** Read-only projection of Cordis Loader entries for /plugin. */
+import type { Context } from '@deepseek-ai/cordis';
+export type PluginPhase = 'pending' | 'loading' | 'active' | 'failed' | 'unloading' | null;
+export interface PluginRow {
+    readonly entryId: string;
+    readonly moduleName: string;
+    readonly enabled: boolean;
+    readonly phase: PluginPhase;
+}
+/** Snapshot the live Loader; group-only rows are composition containers, not plugins. */
+export declare function listPluginRows(ctx: Context): PluginRow[];

package/lib/types/presets.d.ts

@@ -0,0 +1,32 @@
+/** Agent-preset policy kept independent from the Ink surface. */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent, AgentHandle } from '@deepseek-ai/dsh-agent';
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session';
+/** One discoverable agent composition. */
+export interface PresetRow {
+    readonly id: string;
+    readonly trust: 'system' | 'user';
+    readonly name?: string;
+    readonly description?: string;
+    readonly order?: number;
+    readonly broken?: string;
+}
+/** Structural boundary for the optional upstream AgentPresets service. */
+export interface AgentPresetsService {
+    readonly defaultId: string;
+    list(): Promise<PresetRow[]>;
+    resolve(id?: string): Promise<PresetRow>;
+    mount(agentCtx: Context, id?: string): Promise<PresetRow>;
+    recompose(agentCtx: Context, id: string): Promise<PresetRow>;
+    composedPreset(agentCtx: Context): string | undefined;
+}
+/** Read an optional Cordis service without requiring its package at build time. */
+export declare function agentPresetsFrom(ctx: Context): AgentPresetsService | undefined;
+/** A preset may change only before the first durable turn begins. */
+export declare function isBlankSession(events: readonly SessionEvent[]): boolean;
+/** Latest logged selection wins; legacy sessions deliberately fall back to standard. */
+export declare function resolvePreset(session: Pick<Session, 'header' | 'events'>): string;
+/** Recompose atomically from the caller's perspective, logging only success. */
+export declare function switchPreset(service: AgentPresetsService, agent: Agent, presetId: string): Promise<PresetRow>;
+/** Minimal handle shape used by lifecycle tests without exposing Agent internals. */
+export type OwnedAgent = Pick<AgentHandle, 'agent' | 'dispose'>;

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,34 @@
+/** 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;
+    /** Optional blank rows separating title/body/footer on roomy terminals. */
+    gapRows: 0 | 2;
+    /** Columns available inside the horizontal border and padding. */
+    contentColumns: number;
+    /** Tiny terminals use a borderless one-line close hint. */
+    compact: boolean;
+}
+/** One transcript-to-composer gutter, collapsed on short terminals. */
+export declare function layoutGutterRows(rows: number): 0 | 1;
+/**
+ * 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.
@@ -31,12 +38,24 @@ export declare function cacheHitPercent(usage: TranscriptStats['usage']): number
 export interface StatusFacts {
     /** `provider/model` selection serving this session. */
     model: string;
+    /** Agent preset composing this session. */
+    mode?: string;
     /** Working-directory basename the session serves. */
     cwd: string;
     /** Git branch name, empty outside a repository or on a detached HEAD file. */
     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,30 @@
  * as a literal `\xNN` escape.
  */
 export declare function displayText(text: string): string;
+/** Collapse external text to one terminal-safe logical row. */
+export declare function singleLineText(text: string): string;
+/**
+ * Truncate one display-safe row without ever exceeding its physical-column
+ * budget. The ellipsis is included inside the budget, matching Codex's popup
+ * truncation contract; the previous app-local helper appended it after the
+ * row was already full and could force an extra terminal wrap.
+ */
+export declare function truncateColumns(text: string, columns: number): 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;