dsh-code 1.0.6 → 1.2.0

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

@@ -54,6 +54,19 @@ export declare function deepDivingGradientColor(index: number, tick: number, gra
 export declare function deepDivingSparkIntensity(tick: number): number;
 /** Blue RGB color for the breathing Deep diving sparkle. */
 export declare function deepDivingSparkColor(tick: number, base: RgbTriple, highlight: RgbTriple): RgbTriple;
+/** One full prismatic flow lap — lively: violet → fuchsia → cyan → violet in 2.4s. */
+export declare const FLOW_PERIOD_MS = 2400;
+/**
+ * The prismatic flow color at one elapsed-time sample: a smoothstep walk
+ * around the anchor triangle, one full lap per {@link FLOW_PERIOD_MS}. Pure —
+ * the Ink layer owns the timer and passes its tick scaled by its own cadence
+ * (tick × tickMs). Callers gate on the animations preference and fall back to
+ * a static palette color when animation is off.
+ * @param elapsedMs - milliseconds since the flow started (any sign or size).
+ * @param anchors - the colors to walk, in order (theme.ts FLOW_ANCHORS).
+ * @returns the interpolated anchor color at this instant.
+ */
+export declare function flowColor(elapsedMs: number, anchors: readonly RgbTriple[]): RgbTriple;
 /** Caret blink cadence: one blink step (on or off) per tick. */
 export declare const CARET_BLINK_TICK_MS = 530;
 /** Caret visibility: half the ticks on, half off (530ms blink). */
@@ -174,6 +187,35 @@ export declare function easeInOut(progress: number): number;
  * @returns the envelope value in 0..1.
  */
 export declare function envelope(elapsed: number, total: number, fadeIn: number, fadeOut: number): number;
+/**
+ * The /rainbow celebration on the three-row composer band: a FIXED
+ * seven-color spectrum (not the rolled palette) that slides across every
+ * row as one ribbon. Triggered when switching to rainbow or rerolling the
+ * seed; independent of RAINBOW_SEED so the burst always reads as a prism.
+ */
+export declare const RAINBOW_BURST_TICK_MS = 33;
+export declare const RAINBOW_BURST_DURATION_MS = 1800;
+export declare const RAINBOW_BURST_HUES: readonly RgbTriple[];
+/**
+ * Smoothstep in 0..1, then wrap-lerp around the seven burst hues.
+ * Position 0 is red, wrapping back toward red at 1. Shared by the
+ * composer burst and the static rainbow whale header.
+ */
+export declare function rainbowSpectrumHue(position: number): RgbTriple;
+/**
+ * Background tint for one composer-band cell during the rainbow burst.
+ * Every row of a column shares the same hue (a solid ribbon); edge rows
+ * are slightly dimmer so the middle editor row reads as the crest. The
+ * spectrum slides ~1.2 widths over the burst, then fades to the band base.
+ * @param tick - frame index at {@link RAINBOW_BURST_TICK_MS}.
+ * @param column - band column (0..width-1).
+ * @param width - band width in columns.
+ * @param base - the theme's composerBand color to blend toward.
+ * @param row - band row (0..rows-1).
+ * @param rows - band height (composer is three rows: pad, editor, pad).
+ * @returns the blended RGB, or null after the burst (or at zero alpha).
+ */
+export declare function rainbowBurstColumnBg(tick: number, column: number, width: number, base: RgbTriple, row?: number, rows?: number): RgbTriple | null;
 /**
  * The background color for one composer-band column at a tick — Codex
  * `paint_bands` + `Canvas::tint` for all three styles. Bands overlap with a

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

@@ -155,8 +155,9 @@ export declare function replaceRangePreservingCursor(value: string, cursor: numb
  */
 export declare function composerMaxRows(terminalRows: number): number;
 /**
- * History navigation starts with Up on an empty draft, or after visual
- * movement has reached the directional text edge of an unchanged recalled
- * entry. Every other position remains under textarea movement.
+ * History navigation starts with Up on an empty draft, or continues from an
+ * unchanged recalled entry whenever the caret sits on either text edge
+ * (start or end) - moving the caret into the interior returns the keys to
+ * ordinary editing until an edge is reached again.
  */
 export declare function shouldRecallNavigate(value: string, cursor: number, lastRecalled: string | null, direction: -1 | 1): boolean;

package/lib/types/render/ime-cursor.d.ts

@@ -0,0 +1,60 @@
+/**
+ * IME cursor anchoring for the composer.
+ *
+ * Ink keeps the real terminal cursor hidden and parks it just below the
+ * dynamic tree (after the status row). IME composition text and candidate
+ * windows anchor to that real cursor cell - VS Code's integrated terminal
+ * positions its hidden IME textarea there, and Windows consoles behave the
+ * same - so CJK input appeared at the bottom of the screen instead of at the
+ * caret. The anchor moves the real cursor onto the caret cell without
+ * touching Ink's relative erase ledger:
+ *
+ * - the displacement is owned: before any foreign write or re-anchor, the
+ *   wrapper cancels it (cursor down, column 1), so every writer - Ink's
+ *   log-update rewrites, the resize replay, protocol pushes - keeps seeing
+ *   the cursor exactly where it was left;
+ * - log-update frame chunks (which start with the erase-line sequence) get
+ *   the anchor re-appended inside the same write, so a repaint can never
+ *   leave the cursor behind - in particular the caret blink keeps the anchor
+ *   stable while an IME composition is open, because the terminal parses the
+ *   rewrite and the re-anchor as one atomic update.
+ *
+ * @module @deepseek-ai/dsh-code/render/ime-cursor
+ */
+/** Cancel `rows` of owned upward displacement and return to column 1. */
+export declare function imeCursorRestore(rows: number): string;
+/** Move onto the caret cell: `rows` up from Ink's parked row, 0-based column. */
+export declare function imeCursorMove(rows: number, column: number): string;
+/**
+ * Rows between the caret cell and Ink's parked cursor row: the band's bottom
+ * blank row, the editor window rows below the caret, the status footer, and
+ * Ink's own below-frame row. Rows above the composer (gutter, live content)
+ * never enter this distance.
+ */
+export declare function imeCursorRowsUp(input: {
+    editorWindowRows: number;
+    caretRowInWindow: number;
+    rowsBelowComposer: number;
+}): number;
+/** The installed anchor handle. */
+export interface ImeCursorAnchor {
+    /** Anchor on the caret cell: `rows` above Ink's parked row at the 0-based
+     * `column`; `rows <= 0` releases the anchor. */
+    anchor(rows: number, column: number): void;
+    /** Cancel the displacement, restore the original write path, and detach. */
+    release(): void;
+}
+/**
+ * Take over `stream.write` so the anchor displacement stays invisible to every
+ * other writer. Idempotent per stream: a second install returns the live
+ * handle. Returns `undefined` on non-TTY streams where anchoring is meaningless.
+ */
+export declare function installImeCursorAnchor(stream: NodeJS.WriteStream): ImeCursorAnchor | undefined;
+/**
+ * Keep the real terminal cursor on the composer's caret cell while `active`
+ * (the editable composer). The second effect runs after every commit without
+ * a dep list: frame rewrites restore the anchor themselves, but any other
+ * write (protocol push, resize replay) leaves the cursor at Ink's parked
+ * position, and the next commit re-anchors it.
+ */
+export declare function useImeCursorAnchor(active: boolean, rows: number, column: number): void;

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

@@ -16,6 +16,32 @@ export interface InspectorViewport {
 }
 /** One transcript-to-composer gutter, collapsed on short terminals. */
 export declare function layoutGutterRows(rows: number): 0 | 1;
+/** Measured chrome that sits below (or in) the live region. */
+export interface LiveRegionChrome {
+    /** Terminal rows. */
+    readonly terminalRows: number;
+    /** Editor rows inside the composer band (frozen reports 1). */
+    readonly composerRows: number;
+    /** Status footer rows. */
+    readonly statusBarRows: 1 | 2;
+    /** Completion menu rows (0 when closed). */
+    readonly menuRows: number;
+    /** Transcript-to-composer gutter. */
+    readonly gutterRows: 0 | 1;
+    /** Notice line present. */
+    readonly notice: boolean;
+    /** Todo summary line present. */
+    readonly todo: boolean;
+    /** Agents summary line present. */
+    readonly agents: boolean;
+}
+/**
+ * Rows left for live transcript and streaming after pinning the composer and
+ * status at the bottom. Variable chrome (menu, notice, todos, agents, extra
+ * status row, extra editor rows) is deducted here so those rows cover the
+ * live region instead of growing the tree and moving the bottom bar.
+ */
+export declare function liveRegionBudget(chrome: LiveRegionChrome): number;
 /**
  * Keep the inspector plus its persistent status/composer chrome below
  * `stdout.rows`: at equality Ink clears the terminal and rewrites all

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

@@ -2,7 +2,7 @@
 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';
+export type LineStyle = MdStyle | 'brand' | 'success' | 'error' | 'warn' | 'dimItalic' | 'diffAdd' | 'diffDel' | 'promptRow' | 'promptQueuedRow' | 'promptSteeredRow';
 /** One styled run within a physical terminal row. */
 export interface StyledSegment {
     text: string;
@@ -14,6 +14,18 @@ export interface StyledLine {
 }
 /** Construct one segment without leaking mutable objects into cached rows. */
 export declare function lineSegment(text: string, style?: LineStyle): StyledSegment;
+/**
+ * Classify one unified-diff row for coloring: additions and deletions carry
+ * the diff tint styles (background on rich terminals), hunk headers and file
+ * markers stay brand-blue, and everything else is dim context.
+ */
+export declare function diffLineStyle(line: string): LineStyle;
+/**
+ * Extend pure diff-tinted rows to the full width with same-styled padding so
+ * the tint reads as one unbroken bar (GitHub-style), including wrapped
+ * continuation rows; mixed or non-diff rows pass through untouched.
+ */
+export declare function fillDiffLineBars(lines: readonly StyledLine[], columns: number): readonly StyledLine[];
 /**
  * Sanitize and hard-wrap styled content into exact physical rows.
  * Tabs become two visible spaces because terminal tab stops are contextual
@@ -30,6 +42,14 @@ export declare function markdownLines(text: string, columns: number): readonly S
  * reasoning content and assistant Markdown share one left edge.
  */
 export declare function reasoningLines(text: string, columns: number): readonly StyledLine[];
+/**
+ * Style the lines of one user prompt for display: plain verbatim, except
+ * inside ```diff / ```patch fences where added and removed lines take the
+ * shared diff tints (the review prompt pastes its diff this way, and the
+ * user row does not go through the markdown renderer). The fence markers
+ * and file headers stay plain.
+ */
+export declare function userPromptSegments(text: string): readonly StyledSegment[];
 /**
  * Convert one durable transcript entry to its complete scrollable row model.
  * The source entry stays intact; only the caller's visible slice is rendered.

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

@@ -9,7 +9,7 @@
  * @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' | 'accentBold' | 'dim' | 'strike';
+export type MdStyle = 'plain' | 'bold' | 'italic' | 'boldItalic' | 'code' | 'accent' | 'accentBold' | 'dim' | 'strike' | 'diffAdd' | 'diffDel';
 /** One styled run of text. */
 export interface MdSegment {
     /** Visible text (no ANSI). */

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

@@ -23,6 +23,12 @@ export interface UserEntry {
     images?: readonly ImageBlock['attachment'][];
     /** Durable file references carried by this prompt (0.1.5 file blocks). */
     files?: readonly FileAttachmentRef[];
+    /**
+     * How the prompt reached the agent, when it did not arrive as an ordinary
+     * submission: `queued` waited for this turn, `steered` joined it mid-flight.
+     * Absent for a prompt typed straight into an idle composer.
+     */
+    delivery?: 'queued' | 'steered';
 }
 /** One user message waiting in the agent inbox (the web's queued-message row). */
 export interface PendingEntry {
@@ -79,6 +85,68 @@ export interface ToolEntry {
      * result lands and only when something renderable exists.
      */
     detail: ToolDetail | undefined;
+    /**
+     * Nested PTC sub-dispatches (`run_code`) in start order, bounded to the
+     * newest {@link MAX_TOOL_SUB_DISPATCHES} rows.
+     */
+    subs: readonly ToolSubDispatch[];
+    /** Sub-dispatches evicted from the bounded window. */
+    subsDropped: number;
+}
+/**
+ * One nested PTC sub-dispatch under a `run_code` parent call: the durable
+ * `tool/ptc-dispatch-start`/`tool/ptc-dispatch` pair folded to one bounded
+ * row (upstream contract: pair by `subCallId`, every start settles, and the
+ * settle carries `tool/result`'s own vocabulary).
+ */
+export interface ToolSubDispatch {
+    /** Opaque sub-call id pairing the start with its settle. */
+    subCallId: string;
+    /** Sub-call tool name. */
+    name: string;
+    /** Bounded arguments preview. */
+    preview: string;
+    /** Lifecycle; `running` until the paired settle lands. */
+    state: 'running' | 'done' | 'error';
+    /** Bounded first text block of the settle content, '' until it lands. */
+    summary: string;
+    /** Wall-clock duration (settle − start), 0 while running. */
+    durationMs: number;
+}
+/** Bounded sub-dispatch window per tool card (display budget only). */
+export declare const MAX_TOOL_SUB_DISPATCHES = 12;
+/** Bounded member window per workflow run card (display budget only). */
+export declare const MAX_WORKFLOW_MEMBERS = 12;
+/** One workflow member (an `agent()` call inside a `workflow` script). */
+export interface WorkflowMember {
+    /** Member sequence within the run (the agent-start/agent-end pairing key). */
+    seq: number;
+    /** Display label. */
+    label: string;
+    /** Declared phase title, '' when none. */
+    phase: string;
+    /** Child session id (cross-links the subagent feed's rows). */
+    childId: string;
+    /** Settlement; `running` until the paired `tool-workflow/agent-end`. */
+    outcome: 'running' | 'completed' | 'failed' | 'cancelled';
+}
+/**
+ * One durable workflow run (the `tool-workflow/*` record a `workflow` or
+ * `ralph` tool appends to the parent session): run identity plus its
+ * bounded member list, live until `tool-workflow/run-end` settles.
+ */
+export interface WorkflowEntry {
+    kind: 'workflow';
+    /** Stable run identity shared by every event of the run. */
+    runId: string;
+    /** Display name of the run. */
+    name: string;
+    /** Members in sequence order, bounded to the newest window. */
+    members: readonly WorkflowMember[];
+    /** Members evicted from the bounded window. */
+    membersDropped: number;
+    /** Run settlement; `running` until `tool-workflow/run-end`. */
+    state: 'running' | 'completed' | 'cancelled' | 'error';
 }
 /** One slash-command execution dispatched through `ctx.commands`. */
 export interface CommandEntry {
@@ -144,7 +212,7 @@ export interface FilesEntry {
     paths: readonly string[];
 }
 /** Ordered transcript items the renderer draws. */
-export type TranscriptEntry = UserEntry | PendingEntry | AssistantEntry | ToolEntry | CommandEntry | ErrorEntry | TurnMarkerEntry | CompactionEntry | RetryEntry | FilesEntry;
+export type TranscriptEntry = UserEntry | PendingEntry | AssistantEntry | ToolEntry | CommandEntry | ErrorEntry | TurnMarkerEntry | CompactionEntry | RetryEntry | FilesEntry | WorkflowEntry;
 /** The live goal the status line badges, folded from `goal/change`. */
 export interface GoalFold {
     /** Human-requested completion objective. */
@@ -157,14 +225,21 @@ export interface GoalFold {
     /** Blocked explanation, empty outside the blocked phase. */
     blocked: string;
 }
-/** Cumulative token accounting folded from `assistant/message` usage reports. */
+/**
+ * Cumulative token accounting folded from `assistant/message` usage reports.
+ * The buckets are disjoint and mirror the provider's report, so the prompt
+ * side is never double counted: reasoning tokens are already inside
+ * `outputTokens`, and cache reads are never folded into the uncached input.
+ */
 export interface UsageTotals {
-    /** Prompt-side billed tokens: `inputTokens` plus both cache buckets. */
-    inputTokens: number;
+    /** Prompt-side tokens billed outside the cache. */
+    uncachedInputTokens: number;
     /** Completion-side tokens over the whole log. */
     outputTokens: number;
     /** Cache-read tokens over the whole log (0 when the adapter reports none). */
     cacheReadTokens: number;
+    /** Cache-write tokens over the whole log (0 when the adapter reports none). */
+    cacheWriteTokens: number;
 }
 /**
  * Estimated used tokens per context content type, folded from transcript
@@ -219,6 +294,38 @@ export interface TranscriptStats {
      */
     reasoningEffort: string;
 }
+/** One active reminder folded from durable `schedule/change` events. */
+export interface ScheduleRow {
+    readonly id: string;
+    readonly kind: 'after' | 'at' | 'every';
+    readonly prompt: string;
+    /** Next due time (epoch ms); the /schedule panel derives overdue/relative labels. */
+    readonly targetAt: number;
+    /** Recurrence seconds for 'every' rows, undefined otherwise. */
+    readonly everySeconds?: number;
+}
+/**
+ * The durable `schedule/change` payload shape this fold consumes. Upstream
+ * strict-decodes the whole transition stream before appending, so unknown
+ * ids here are corrupt-input edges that degrade to a no-op.
+ */
+export interface ScheduleChangeLike {
+    readonly operation: 'create' | 'delete' | 'dispatch';
+    readonly schedule?: {
+        readonly id: string;
+        readonly kind: 'after' | 'at' | 'every';
+        readonly prompt: string;
+        readonly afterSeconds?: number;
+        readonly everySeconds?: number;
+        readonly scheduledAt: string;
+    };
+    readonly id?: string;
+    readonly acceptedAt?: string;
+}
+/** Fold one `schedule/change` into the active-reminder list (create/delete/dispatch). */
+export declare function applyScheduleChange(rows: readonly ScheduleRow[], data: ScheduleChangeLike): readonly ScheduleRow[];
+/** First anchor-aligned target after `acceptedAt`, stepping from the previous aligned target. */
+export declare function nextEveryTarget(previousTarget: number, acceptedAt: number, everySeconds: number): number;
 /** The complete TUI transcript view for one session. */
 export interface TranscriptView {
     /** Settled entries in log order. */
@@ -265,6 +372,8 @@ export interface TranscriptView {
     sandbox: string;
     /** Current long-running goal folded from the last `goal/change`, undefined when cleared. */
     goal: GoalFold | undefined;
+    /** Active reminders folded from `schedule/change` events, oldest target first at render. */
+    schedules: readonly ScheduleRow[];
     /**
      * Ordered live message ids per inbox target, mirrored from
      * `agent/inbox/spliced` exactly like the upstream Inbox projection — the
@@ -274,6 +383,14 @@ export interface TranscriptView {
         'next-turn': readonly string[];
         'next-step': readonly string[];
     };
+    /**
+     * In-flight inbox messages by the list they were inserted into, kept until
+     * the durable user message that claims them lands. The claim itself is a
+     * plain splice that empties the pending row first, so this map — not
+     * {@link pending} — is what lets a settled prompt say it was queued or
+     * steered rather than typed into an idle composer.
+     */
+    claimOrigin: ReadonlyMap<string, 'next-turn' | 'next-step'>;
     /**
      * Fold-internal timing anchors, never rendered: open step and tool-call
      * start timestamps the next `assistant/message` / `tool/result` resolves
@@ -285,6 +402,8 @@ export interface TranscriptView {
     readonly anchors: {
         stepStart: Map<string, number>;
         toolStart: Map<string, number>;
+        /** Open PTC sub-dispatch starts by `subCallId` (duration anchors). */
+        subStart: Map<string, number>;
         firstChunkAt: Map<string, number>;
         compactionTokens: Map<string, number>;
         lastPruneTokens: number;
@@ -341,11 +460,15 @@ export interface ReplayAccumulator {
     retryIndex: Map<string, number[]>;
     /** messageId → every index into `entries` holding a `pending` row with that id. */
     pendingIndex: Map<string, number[]>;
+    /** runId → every index into `entries` holding a `workflow` row with that id. */
+    workflowIndex: Map<string, number[]>;
     /** Tombstone count; zero means `entries` is already the final array. */
     removedCount: number;
     /** Mutable inbox id lists, mirroring `view.pending` order per target. */
     pendingTurn: string[];
     pendingStep: string[];
+    /** Mutable mirror of `view.claimOrigin` (see the reducer's field doc). */
+    claimOrigin: Map<string, 'next-turn' | 'next-step'>;
     streaming: string;
     streamingReasoning: string;
     todos: readonly TodoItem[];
@@ -360,9 +483,12 @@ export interface ReplayAccumulator {
     systemPrompt: string;
     sandbox: string;
     goal: GoalFold | undefined;
+    schedules: readonly ScheduleRow[];
     stats: TranscriptStats;
     stepStart: Map<string, number>;
     toolStart: Map<string, number>;
+    /** Open PTC sub-dispatch starts by `subCallId` (duration anchors). */
+    subStart: Map<string, number>;
     firstChunkAt: Map<string, number>;
     compactionTokens: Map<string, number>;
     lastPruneTokens: number;

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

@@ -10,13 +10,8 @@
  * @module @deepseek-ai/dsh-tui/render/status
  */
 import type { TranscriptStats } from './projection.ts';
-/**
- * Compact token count: 517 / 12.2K / 517K / 1.2M (one decimal under three
- * digits), mirroring the web composer's StatsLine format.
- * @param n - token count.
- * @returns display string.
- */
-export declare function formatTokens(n: number): string;
+import { formatTokens } from './text.ts';
+export { formatTokens };
 /**
  * Compact duration: 45.2s under a minute, 2m42s from there on.
  * @param ms - duration in milliseconds.
@@ -24,7 +19,9 @@ export declare function formatTokens(n: number): string;
  */
 export declare function formatDuration(ms: number): string;
 /**
- * Cache-hit share of billed prompt-side input.
+ * Cache-hit share of billed prompt-side input. The denominator is the same
+ * billed total the /usage panel shows (uncached input plus both cache
+ * buckets), so the two readouts can never disagree.
  * @param usage - cumulative token totals.
  * @returns percent rounded to one decimal place, or null when no input was billed.
  */
@@ -33,7 +30,7 @@ export declare function cacheHitPercent(usage: TranscriptStats['usage']): number
  * Presentation tones for status spans; the footer maps each to a theme color
  * (Codex status-line accents: model/path/branch/state/usage categories).
  */
-export type StatusTone = 'model' | 'live' | 'path' | 'branch' | 'value' | 'label' | 'meta' | 'accent' | 'success' | 'warn' | 'error' | 'ctxFill';
+export type StatusTone = 'model' | 'live' | 'path' | 'branch' | 'value' | 'label' | 'meta' | 'accent' | 'success' | 'plan' | 'warn' | 'error' | 'ctxFill';
 /** One colored run inside the status bar. */
 export interface StatusSpan {
     text: string;
@@ -70,7 +67,10 @@ export declare const STATUS_GROUP_SEPARATOR = " | ";
 /** Separator between trailing state spans. */
 export declare const STATUS_ITEM_SEPARATOR = " \u00B7 ";
 /** The Codex-style mode cycle hint appended to the permission badge. */
+/** English compatibility value for callers that only measure the default layout. */
 export declare const STATUS_CYCLE_HINT = " (shift+tab to cycle)";
+/** Localized mode-cycle hint used by the live layout. */
+export declare function statusCycleHint(): string;
 /**
  * Interior columns of the context bar. The layout starts every bar at this
  * width so the drop ladder can pre-measure the group, then degrades the

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

@@ -11,6 +11,12 @@
  *
  * @module @deepseek-ai/dsh-code/render/text
  */
+/**
+ * Compact token count: exact below 1K, then one-decimal-ish K/M.
+ * @param n - token count.
+ * @returns display string.
+ */
+export declare function formatTokens(n: number): string;
 /**
  * Escape control and deceptive characters so externally sourced text cannot
  * drive the terminal. C0/C1/DEL render as a literal `\xNN` escape; bidi,

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

@@ -0,0 +1,113 @@
+/**
+ * Session usage for the /usage panel: the provider-reported token totals, the
+ * context pressure and composition, and the exact per-turn accounting, folded
+ * into the styled rows the panel draws.
+ *
+ * Every figure comes from the harness token meter. The four token buckets are
+ * disjoint, so the prompt side is never double counted; the composition block
+ * is a density estimate and is labelled as one.
+ *
+ * @module @deepseek-ai/dsh-tui/render/usage
+ */
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import type { TokenUsageProjection, TurnTokenUsage } from '@deepseek-ai/dsh-token-meter/client';
+import { type StyledLine } from './lines.ts';
+/** One completed turn's exact provider-reported accounting. */
+export interface UsageTurn {
+    /** Durable turn number (`turn/start`). */
+    readonly turn: number;
+    readonly usage: TurnTokenUsage;
+    /**
+     * The model that billed this turn, or '' when nothing in the log names one.
+     * The meter's own `routes` is preferred; it is absent whenever ONE attempt
+     * went unattributed, so the turn's own assistant messages answer instead.
+     */
+    readonly model: string;
+}
+/**
+ * Everything the panel reads. The totals come from the mounted projection and
+ * the per-turn rows from the meter's own fold; a missing projection renders as
+ * explicitly unavailable rather than as zeros, because an unmounted deployment
+ * and a session with no traffic are different facts.
+ */
+export interface UsageView {
+    /** Provider-reported usage over the whole durable log. */
+    readonly totals?: TokenUsageProjection;
+    /** Completed turns, oldest first. */
+    readonly turns: readonly UsageTurn[];
+}
+/** Prompt-side tokens the provider billed: uncached input plus both cache buckets. */
+export declare function billedInputTokens(totals: TokenUsageProjection): number;
+/** Prompt plus completion tokens over the whole log. */
+export declare function usageTotalTokens(totals: TokenUsageProjection): number;
+/**
+ * Cache-hit share of billed prompt-side input.
+ * @param totals - cumulative provider-reported buckets.
+ * @returns percent rounded to one decimal place, or null when nothing was billed.
+ */
+export declare function usageCacheHitPercent(totals: TokenUsageProjection): number | null;
+/** One complete turn's durable events, in log order. */
+export interface TurnSlice {
+    readonly turn: number;
+    readonly events: readonly SessionEvent[];
+}
+/**
+ * Split a durable log into COMPLETE turns. A turn still running has no
+ * `turn/end` yet, and an unfinished attempt has no exact accounting, so the
+ * trailing slice is dropped rather than guessed at.
+ * @param events - the whole durable log, in log order.
+ * @returns one slice per `turn/start`…`turn/end` span, oldest first.
+ */
+export declare function completedTurns(events: readonly SessionEvent[]): readonly TurnSlice[];
+/**
+ * Exact usage for every completed turn that can be proven.
+ * @param events - the whole durable log, in log order.
+ * @param derive - the meter's per-turn fold, injected so this module stays pure.
+ * @returns one row per provable turn, oldest first; turns whose attempts did
+ *   not all report usage are omitted rather than estimated, and so is a turn
+ *   that billed nothing at all — an empty row is noise in a usage table.
+ */
+export declare function turnUsages(events: readonly SessionEvent[], derive: (events: readonly SessionEvent[]) => TurnTokenUsage | undefined): readonly UsageTurn[];
+/** A bucket some turn of a group did not report, leaving the group sum a floor. */
+export type PartialBucket = 'cacheReadTokens' | 'cacheWriteTokens' | 'reasoningTokens';
+/** One model's merged totals across every turn it billed. */
+export interface ModelUsage {
+    /** Model names joined with ` + ` (a turn that switched models lists both). */
+    readonly model: string;
+    /** Turns attributed to this model. */
+    readonly turns: number;
+    readonly uncachedInputTokens: number;
+    readonly outputTokens: number;
+    readonly totalTokens: number;
+    /** Summed over the turns that reported it; absent when none did. */
+    readonly cacheReadTokens?: number;
+    /** Summed over the turns that reported it; absent when none did. */
+    readonly cacheWriteTokens?: number;
+    /** Summed over the turns that reported it; absent when none did. */
+    readonly reasoningTokens?: number;
+    /**
+     * Buckets some turn of the group left unreported. The corresponding sum (and
+     * the hit share derived from it) counts only what WAS reported, so the
+     * display marks it as a floor rather than hiding the group's known traffic.
+     */
+    readonly partial: readonly PartialBucket[];
+}
+/**
+ * Merge the per-turn rows by the model that billed them, biggest spender
+ * first. A turn lands in exactly one group — the group named by every model it
+ * used — so the sums stay additive and a mid-turn model switch never counts
+ * the same tokens twice. Each bucket is merged over the turns that reported
+ * it, and {@link ModelUsage.partial} records the ones that stayed silent.
+ * @param turns - provable per-turn rows, oldest first.
+ * @returns one row per model group.
+ */
+export declare function modelTotals(turns: readonly UsageTurn[]): readonly ModelUsage[];
+/** The model attribution for one turn: the meter's routes, else its messages. */
+export declare function turnModel(slice: TurnSlice, usage: TurnTokenUsage): string;
+/**
+ * Render the panel body.
+ * @param view - the projection totals plus the derived per-turn rows.
+ * @param columns - usable content columns inside the panel border.
+ * @returns bounded, styled rows ready to draw.
+ */
+export declare function usageLines(view: UsageView, columns: number): readonly StyledLine[];

package/lib/types/session-directory.d.ts

@@ -24,6 +24,23 @@ export interface SessionQueryService {
     listSessions(signal?: AbortSignal): Promise<SessionRecord[]>;
     readTitleSnapshots(ids: readonly string[], signal?: AbortSignal): Promise<TitleObservationResult[]>;
     readSession(id: string, signal?: AbortSignal): Promise<SessionLogSnapshot>;
+    /** Cross-session full-text search (SQLite FTS engine; openAt may gate it). */
+    searchSessions(request: {
+        query: string;
+        limit?: number;
+    }, exec?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        items: readonly {
+            header: SessionHeader;
+            live: boolean;
+            persisted: boolean;
+            bestMatch: {
+                snippet: string;
+                time: number;
+            };
+        }[];
+    }>;
 }
 export type SessionScope = 'roots' | 'all';
 export type CwdScope = 'all' | 'current';