dsh-ssh-tui 0.8.1 → 0.8.2

package/lib/types/stats.d.ts

@@ -14,12 +14,41 @@
  * - decode rate needs a finite, non-negative output token count.
  */
 import type { TokenUsage } from '@deepseek-ai/dsh-llm';
+import { type ThroughputView } from './throughput.js';
 export interface SessionUsage {
     inputTokens: number;
     outputTokens: number;
+    /** Sum of the full-call totals the harness itself reported, when it reported one. */
+    reportedTokens: number;
+    /** Steps whose usage carried a harness total. */
+    reportedSteps: number;
+    /** Steps whose usage carried none, so the billed parts had to stand in. */
+    unreportedSteps: number;
     cacheReadTokens: number;
     cacheWriteTokens: number;
 }
+/** The session-size number the second row shows, and how it was derived. */
+export interface SessionTokenTotal {
+    tokens: number;
+    /**
+     * `harness` when every usage sample carried the harness's own total; `sum`
+     * when some step's billed parts had to be added in instead.
+     */
+    basis: 'harness' | 'sum';
+}
+/**
+ * How many tokens this session has moved, on the accounting the harness
+ * published.
+ *
+ * The harness is the authority: a `totalTokens` it reports is a full-call total
+ * whose parts are defined provider by provider — pi-ai's own adapters build it
+ * as prompt + output + cache read + cache write — and re-deriving one from the
+ * three prompt counters plus output is exactly the arithmetic that
+ * double-counts on a provider that folds cache into its prompt count. So
+ * reported totals are summed, and only a step that reported none contributes
+ * its billed parts. The basis says which happened, and `/status` prints it.
+ */
+export declare function sessionTokenTotal(usage: SessionUsage): SessionTokenTotal | undefined;
 export interface SessionStatsSnapshot {
     turns: number;
     steps: number;
@@ -29,6 +58,12 @@ export interface SessionStatsSnapshot {
     ttftSteps: number;
     decodeMs: number;
     decodeTokens: number;
+    /** Tokens and milliseconds of the most recent settled step alone. */
+    lastDecodeMs: number;
+    lastDecodeTokens: number;
+    /** Decode totals excluding the step that is currently open. */
+    settledDecodeMs: number;
+    settledDecodeTokens: number;
     usage: SessionUsage;
 }
 /** Flat view of the same numbers, for the footer's stats line. */
@@ -45,6 +80,7 @@ export interface SessionStatsRow {
     outputTokens: number;
     cacheReadTokens: number;
     cacheWriteTokens: number;
+    totalTokens: number;
 }
 export interface OpenStep {
     turn: number;
@@ -52,7 +88,7 @@ export interface OpenStep {
 }
 export declare function emptySessionUsage(): SessionUsage;
 export declare function emptySessionStats(): SessionStatsSnapshot;
-/** Flatten a snapshot into the footer's row shape. */
+/** Flatten a snapshot into the legacy stats-row shape. */
 export declare function statsRowOf(stats: SessionStatsSnapshot): SessionStatsRow;
 /**
  * Accumulates the stats the footer and `/status` show as session events arrive.
@@ -65,10 +101,35 @@ export declare class SessionStatsTracker {
     private readonly usageByStep;
     private readonly pendingToolTimes;
     private lastTurn;
+    /** Live decode estimate for the step currently streaming. */
+    private readonly live;
     /** The step a live chunk belongs to when the host frame carried none. */
     currentStep(): OpenStep | undefined;
+    /**
+     * The open step's two clocks, for the status row's elapsed suffix.
+     *
+     * Both are host wall clocks, so a caller may subtract them from `Date.now()`
+     * without a translation. `firstTokenAt` is absent until the step's first
+     * delta, which is exactly the difference between "the request is out" and
+     * "the model is talking".
+     */
+    stepClocks(): {
+        startedAt?: number;
+        firstTokenAt?: number;
+    };
     /** `step/start`: opens the clock LLM time, TTFT and decode are measured from. */
     noteStepStart(turn: number, step: number, time: number): void;
+    /**
+     * A live fragment of model output, for the running throughput estimate.
+     *
+     * The text itself travels: the estimate is tokens per character, and how many
+     * tokens a character is worth depends on the script the fragment is written in.
+     * @param text - the fragment.
+     * @param time - wall clock the fragment arrived at.
+     */
+    noteDelta(text: string, time?: number): void;
+    /** The running throughput estimate, settled value included. */
+    throughput(now?: number): ThroughputView;
     /** The first token delta of the open step latches its TTFT clock. */
     noteFirstToken(turn: number, step: number, time: number): void;
     /** Replace one step's usage sample so a repeated report never double counts. */
@@ -87,6 +148,8 @@ export declare class SessionStatsTracker {
     }): void;
     /** `tool/call`: start the tool clock for this call. */
     noteToolStart(callId: string, time: number): void;
+    /** When a still-open tool call started, for the status row's elapsed suffix. */
+    toolStartedAt(callId: string): number | undefined;
     /** `tool/result`: add the elapsed tool time, once. */
     noteToolEnd(callId: string, time: number): void;
     /** `step/end`: count the step, and forget the step's usage dedupe key. */

package/lib/types/term-text.d.ts

@@ -40,6 +40,16 @@ export declare function waitCardCopy(input: {
 export declare function wrapWaitDetails(detail: string, width: number, maxLines?: number): string[];
 /** Forget the cached decision, so the next read re-consults the environment. */
 export declare function resetAsciiChrome(): void;
+/**
+ * Whether chrome is being drawn in ASCII, for renderers that pick the glyph run
+ * themselves.
+ *
+ * `pinEmojiCells` translates them anyway; asking is for the case where the
+ * *shape* differs rather than just the character — a metre whose filled cell is
+ * `#` reads as `##..`, not as `#..#`, so the renderer wants to know before it
+ * counts and pads.
+ */
+export declare function asciiChromeEnabled(): boolean;
 /**
  * Rewrite one string's chrome into ASCII when the terminal cannot decode UTF-8.
  *
@@ -112,6 +122,28 @@ export declare function ambiguousWidthMeasured(): boolean | undefined;
  * @returns true when those glyphs should be budgeted two cells.
  */
 export declare function ambiguousWidthIsTwo(env?: NodeJS.ProcessEnv, onTerminal?: boolean): boolean;
+/**
+ * Cells one *code unit* costs at its position, given a resolved policy.
+ *
+ * The per-character core of {@link displayWidth}, split out for the
+ * callers that walk a string themselves (clipping, truncation, wrapping): they
+ * resolve {@link ambiguousPolicy} once per string and then ask this per
+ * character, instead of paying `displayWidth`'s policy lookup and ASCII mapping
+ * for every character of every row. A profile of a window drag put 56% of the
+ * samples in that lookup, because the clipping loops are O(n²) in a way nothing
+ * about their shape advertises: `clipAnsiToWidth` calls this for each character,
+ * and `truncateToWidth` re-measures the whole remainder inside its loop.
+ *
+ * ASCII is answered from its code point before any table lookup: it is the
+ * overwhelming majority of every row, and it can never be ambiguous or wide.
+ * @param cp - the code point.
+ * @param policy - the resolved policy, as returned by {@link ambiguousPolicy}.
+ * @returns 0, 1 or 2 cells.
+ */
+export declare function charCellWidth(cp: number, policy: {
+    wide: boolean;
+    reserve: boolean;
+}): number;
 export declare function displayWidth(text: string): number;
 /**
  * Make a painted row spend the two cells {@link displayWidth} budgets for every
@@ -216,7 +248,19 @@ export declare function hrefAtColumn(hits: readonly PaintedLinkHit[], col: numbe
  * headings, quotes, lists, rules, links and inline spans keep their own ANSI.
  */
 export declare function renderMarkdownLines(text: string, width: number, color: boolean, hyperlinks?: boolean): string[];
-/** Cut one line to fit a width, appending an ellipsis when truncated. */
+/**
+ * Cut **one line** to fit a width, appending an ellipsis when truncated.
+ *
+ * A line break is not a character in a row: it moves the terminal to the next row,
+ * and a frame that addresses its rows absolutely (`ESC[row;1H`) then writes every
+ * following row one line off — content lands on the composer, on the footer, and on
+ * top of whatever was already there. `sanitizeTerminalText` keeps LF/CR on purpose
+ * (it also sanitizes multi-line bodies), so the collapse happens here, where the
+ * contract is "one row": each break becomes a single space, which keeps the string
+ * the same *length* — callers that pass this result into `paintSegmentedLine` rely
+ * on character offsets into the text they built, and a collapsing replacement would
+ * silently move every colour segment.
+ */
 export declare function truncateToWidth(text: string, width: number): string;
 /**
  * Clip an already-styled ANSI line to `width` terminal cells without dropping

package/lib/types/throughput.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Live decode throughput for the status row.
+ *
+ * The harness never publishes tokens per second. What it does publish, per
+ * step, is authoritative: `assistant/message` carries the step's output-token
+ * count and the packed stream's first-token time, so `decodeTokens / decodeMs`
+ * over settled steps is a real measurement. What it does *not* publish is any
+ * per-token count while a step is still streaming — adapters emit text deltas
+ * and only hand over `usage` as the stream closes (verified against
+ * `dsh-llm-deepseek` and `dsh-llm-pi-ai`).
+ *
+ * So there are exactly two honest numbers, and this module keeps them apart:
+ *
+ * 1. **Settled** — tokens and milliseconds of a completed step. Exact, and the
+ *    only number that is ever comparable across steps or sessions.
+ * 2. **Live** — characters per second while a step streams, converted with a
+ *    ratio calibrated from this session's own settled steps. It is an estimate,
+ *    it is labelled with `~`, and it exists so a long reply shows *something*
+ *    that moves instead of a number frozen at the previous step.
+ *
+ * There is deliberately no health grading here. Tokens per second is a property
+ * of the model, the provider, the reasoning effort and the prompt, not a signal
+ * that something is wrong: 20 tok/s from a reasoning model and 20 tok/s from a
+ * small fast one mean different things. The row paints it neutral.
+ *
+ * @module dsh-ssh-tui/throughput
+ */
+/** How much of the recent past the live rate is measured over. */
+export declare const THROUGHPUT_WINDOW_MS = 4000;
+/** Minimum span between the two samples a rate is taken from. */
+export declare const THROUGHPUT_MIN_SPAN_MS = 400;
+/** A live rate older than this describes a stream that stopped, not one running. */
+export declare const THROUGHPUT_FRESH_MS = 2500;
+/**
+ * Tokens per character, for the two ends of the script spectrum.
+ *
+ * Latin text averages roughly a third of a token per character; CJK is close to
+ * one, because a Chinese character is usually its own token and most words are one
+ * or two characters. Between those ends the estimate is interpolated by the
+ * *measured* script mix of the stream being estimated, continuously: a threshold
+ * ("30% CJK means Chinese") would put a mostly-English reply with one Chinese
+ * paragraph on the wrong side of a cliff, and the number it produces is shown to
+ * the reader.
+ */
+export declare const DEFAULT_TOKENS_PER_CHAR_LATIN = 0.32;
+export declare const DEFAULT_TOKENS_PER_CHAR_CJK = 0.85;
+/** The Latin end under its original name: the fallback for a stream with no text. */
+export declare const DEFAULT_TOKENS_PER_CHAR = 0.32;
+/** What the status row paints, and what `/status` reports. */
+export interface ThroughputView {
+    /** Exact tokens per second of the most recent settled step, when it had usage. */
+    settledRate?: number;
+    /** Characters the live estimate was built from, for the calibration report. */
+    liveChars: number;
+    /** Estimated tokens per second over the streaming window. */
+    liveRate?: number;
+    /** True when `liveRate` was measured recently enough to call it current. */
+    fresh: boolean;
+}
+/**
+ * Characters to tokens, bounded and finite.
+ *
+ * The default is an average over mixed prose and code; every settled step
+ * replaces half of it with this session's own measurement, which is what makes
+ * the live estimate usable on CJK output (where one character is close to one
+ * token) without hardcoding a language.
+ */
+export declare function boundTokensPerChar(value: number, fallback?: number): number;
+/**
+ * The median of up to the last three rates, or the newest one alone.
+ *
+ * A single frame in which the terminal coalesced a burst of tokens into one
+ * delta reads as a spike; a median of three ignores it, while a real change
+ * survives because two agreeing samples decide it. Same rule, and the same
+ * reasoning, as the link chip's RTT median.
+ */
+export declare function medianRate(values: readonly number[]): number | undefined;
+/**
+ * Tracks one step's live decode rate from character deltas.
+ *
+ * Sampling is the caller's job (`note` per fragment): the window's own
+ * minimum span is what keeps the number stable, so a burst of tiny deltas and
+ * one coalesced delta produce the same answer.
+ */
+/**
+ * Whether one code point is written in a script whose characters are close to one
+ * token each: CJK ideographs, kana, Hangul syllables, and the fullwidth or CJK
+ * punctuation that travels with them.
+ *
+ * Deliberately a property of the *text* rather than of the reader's locale: a
+ * Chinese reader's English reply is Latin text and costs Latin tokens per
+ * character, and `~tok/s` has to describe the tokens, not the person.
+ */
+export declare function isCjkCodePoint(codePoint: number): boolean;
+/**
+ * The starting ratio for a stream of a given script mix: `cjkShare` of the
+ * characters read as CJK, the rest as Latin. Continuous by construction, so a
+ * reply that is 70% English and 30% Chinese lands 30% of the way up the range
+ * instead of being classified as one or the other.
+ */
+export declare function scriptTokensPerChar(cjkShare: number): number;
+export declare class ThroughputTracker {
+    /** The session's own ratio, once a step has settled. */
+    private calibrated;
+    /** Characters and CJK characters seen in the step being estimated. */
+    private observedChars;
+    private observedCjk;
+    private samples;
+    private chars;
+    private baseAt;
+    private startedAt;
+    private lastDeltaAt;
+    private lastStepChars;
+    /** Rates already computed this step, kept for the median. */
+    private recentRates;
+    private lastRate;
+    private settledRate;
+    /**
+     * The ratio the estimate is using right now: this session's own measurement once
+     * a step has settled, and the script mix of the stream being estimated before
+     * that. `/status` and the tests read it.
+     */
+    tokensPerChar(): number;
+    /** Share of this step's characters that were CJK, 0 when none have arrived. */
+    cjkShare(): number;
+    /** Whether the ratio is a settled measurement rather than a script estimate. */
+    calibratedRatio(): boolean;
+    /** Drop a finished step's stream state, keeping calibration and last settle. */
+    reset(): void;
+    /**
+     * One observed fragment of model output.
+     *
+     * The fragment itself, not a count: the estimate is tokens per character, and
+     * how many tokens a character is worth depends on which characters they are, so
+     * the script mix has to be measured here rather than assumed once for the
+     * session. Code points rather than UTF-16 units, so an emoji or a rare ideograph
+     * outside the BMP counts as the one character the reader sees.
+     * @param text - the fragment; empty is ignored.
+     * @param time - wall clock the fragment arrived at, for tests and replay.
+     */
+    note(text: string, time?: number): void;
+    /**
+     * Settle a step: fold its exact decode rate into the calibration and into the
+     * number an idle row shows.
+     * @param outputTokens - the step's authoritative output tokens.
+     * @param decodeMs - milliseconds from first token to the settled message.
+     */
+    settle(outputTokens: number, decodeMs: number): void;
+    /** What the status row paints, and what `/status` reports. */
+    view(now?: number): ThroughputView;
+    /** Drop samples that fell out of the window, and keep the newest few. */
+    private trim;
+    /** Recompute the window's rate and fold it into the median buffer. */
+    private sampleRate;
+}
+/**
+ * A rate as the row paints it: whole numbers, `<1` rather than nothing.
+ *
+ * A slow step that decoded 3 tokens over 30 seconds is still decoding; rounding
+ * it to `0` reads as a stalled model. Above 1000 the number is compacted, since
+ * four digits is cells the quota and context meters want more.
+ */
+export declare function formatRate(tokensPerSecond: number): string;

package/lib/types/tool-present.d.ts

@@ -4,6 +4,7 @@
 import type { AskUserQuestionItem } from '@deepseek-ai/dsh-user-questions';
 import { type TextSegment } from './term-text.js';
 import type { DiffDisplayLine, Row, ToolDiffHunk } from './transcript-types.js';
+import { type ToolApproval } from './approval-state.js';
 export declare const SHELL_TOOL_NAMES: Set<string>;
 export declare const DIFF_TOOL_NAMES: Set<string>;
 export declare const JOB_TOOL_NAMES: Set<string>;
@@ -104,6 +105,26 @@ export declare const SUBAGENT_TOOL_NAMES: Set<string>;
  * just duplicates chrome.
  */
 export declare const HIDDEN_TOOL_NAMES: Set<string>;
+/**
+ * Tools whose card is the *question* they asked, not a generic tool card (B2.4).
+ *
+ * `ask_user_question` is the only one: its durable representation is the question
+ * card built from the call's arguments, and drawing both was the duplicate this
+ * round removes. It is a separate set from {@link HIDDEN_TOOL_NAMES} on purpose —
+ * hidden means "no representation at all" (`get_goal`), while this means "the
+ * representation is drawn by the question projection". A tool card that never
+ * appears is a *different* decision from one whose content is shown elsewhere, and
+ * the audit has to be able to tell them apart.
+ */
+export declare const QUESTION_TOOL_NAMES: Set<string>;
+/**
+ * Tools whose card is the *artifact* they act on, not a tool card of their own.
+ *
+ * `exit_plan_mode` is the plan review: the plan artifact carries the reviewed body,
+ * the review's outcome and the lifecycle lines, so a generic card beside all of that
+ * was a third representation of one event (B2.5 §15).
+ */
+export declare const PLAN_TOOL_NAMES: Set<string>;
 export declare function toolTitle(name: string): string;
 export declare function planReviewOf(question: AskUserQuestionItem): boolean;
 /** Derive the intended file change from a mutation tool's arguments. */
@@ -142,10 +163,30 @@ export declare function buildToolHeader(input: {
         add: number;
         del: number;
     };
+    /**
+     * The approval that guarded this call (B2.4), when one did.
+     *
+     * It rides on the title — right after the tool's own name — rather than at the
+     * end of the row: the tail is what a narrow terminal truncates first, and a card
+     * whose whole point is "this needed a decision" must not be the one card that
+     * loses it. It is also the only place the state is shown, since approval no
+     * longer writes a row of its own.
+     */
+    approval?: ToolApproval;
 }): {
     plain: string;
     segments: TextSegment[];
 };
+/**
+ * The title chip: the state, and — when the reader is being told something
+ * weaker — why they can trust it less.
+ *
+ * `live` and `durable` are the same fact at two moments (a person decided, and
+ * the log still says so), so they print the state alone. `policy` adds `auto`,
+ * and `inferred` says so: a resume that found only the Harness's refusal sentence
+ * in a tool result is a reading, and the card has to admit it.
+ */
+export declare function approvalChipText(approval: ToolApproval): string;
 /** How many terminal rows a tool body occupies after wrapping. */
 export declare function wrappedToolBodyLineCount(lines: readonly {
     text: string;

package/lib/types/transcript-types.d.ts

@@ -3,6 +3,10 @@
  * Kept free of the SshTui class so leaf modules can import them.
  */
 export type DisconnectPolicyName = 'pause' | 'continue';
+import type { AskUserQuestionOption } from '@deepseek-ai/dsh-user-questions';
+import type { ToolApproval } from './approval-state.js';
+import type { PlanProvenance, PlanState } from './plan-projection.js';
+import type { RepresentationMeta } from './representation.js';
 export type SubagentLogKind = 'user' | 'assistant' | 'tool' | 'result' | 'turn' | 'approval' | 'team' | 'system';
 /** One child-session event folded into a parent-side subagent card. */
 export interface SubagentLogEntry {
@@ -23,7 +27,19 @@ export interface PlanTodoItem {
      */
     status: 'pending' | 'in_progress' | 'completed' | 'failed' | 'skipped';
 }
-export type Row = {
+/**
+ * A transcript line, plus the policy that produced it.
+ *
+ * The metadata is attached by `pushRow` (the only entry), which is why it is
+ * optional in the *shape*: a creation site writes a plain row and names its source,
+ * and the audit reads the classification back off the row afterwards. It is
+ * deliberately not a field each site fills in by hand — one owner, one place to get
+ * it wrong.
+ */
+export type Row = RowShape & {
+    representation?: RepresentationMeta;
+};
+type RowShape = {
     kind: 'user';
     text: string;
 } | {
@@ -63,6 +79,14 @@ export type Row = {
     totalLines?: number;
     /** Flip-card animation until this timestamp (ms since epoch). */
     flipUntil?: number;
+    /**
+     * The approval that guarded this call, when one did (B2.4).
+     *
+     * A field of the tool card, not a row of its own: approval is a state of
+     * the call. `provenance` says how well it is known, so a resume can never
+     * dress an inference up as a decision — see `approval-state.ts`.
+     */
+    approval?: ToolApproval;
 } | {
     kind: 'subagent';
     sessionId: string;
@@ -96,6 +120,23 @@ export type Row = {
     expanded: boolean;
     /** When true the plan stays in the scrolling transcript, not the dock. */
     archived?: boolean;
+    /**
+     * The plan artifact this row stands for (B2.5).
+     *
+     * The row is a *reference*: its state, its steps and its lifecycle come from the
+     * projection of durable events, and the id is derived from the sequence that
+     * opened the artifact — so a replay finds the same row again instead of
+     * rebuilding "the newest live plan" from display order.
+     */
+    artifactId?: string;
+    /** The artifact's folded state. */
+    state?: PlanState;
+    /** How that state is known: an event said it, or it was read off the log. */
+    provenance?: PlanProvenance;
+    /** The reader's words when they refused a review with feedback. */
+    reviewFeedback?: string;
+    /** The revision the two display flags below were last computed for. */
+    lastRevisionId?: string;
     /**
      * Display-only: the last turn ended while todos were still open.
      * Does not rewrite the session log.
@@ -112,11 +153,30 @@ export type Row = {
 } | {
     kind: 'question';
     questionId: string;
+    /**
+     * The `ask_user_question` call this question came from, when the Session
+     * recorded one. It is what ties the card to the durable projection, so a
+     * timed question answered *after* its window closed can be settled from the
+     * log instead of from a request that no longer exists.
+     */
+    callId?: string;
     title: string;
     header?: string;
     detail?: string;
     intent: 'ask' | 'plan-review';
+    /**
+     * The choices the call offered, kept so a question the Session still holds
+     * can be answered *as the question it was*: without them a second answer is
+     * a free-text box, and `ctx.userQuestions.answer` is handed a batch that does
+     * not match the call's own shape.
+     */
+    options?: AskUserQuestionOption[];
+    multiSelect?: boolean;
     status: 'waiting' | 'answered' | 'cancelled';
+    /** True when the Session still accepts an answer for this call. */
+    continued?: boolean;
+    /** True once the durable projection, not a live request, owns this card. */
+    durable?: boolean;
     summary: string;
     expanded: boolean;
 } | {
@@ -197,7 +257,7 @@ export type CollapsibleBlock = Extract<Row, {
     kind: 'streaming-reasoning';
     expanded: boolean;
 };
-export type DisplayKind = Row['kind'] | 'tool-result' | 'diff-add' | 'diff-del' | 'diff-path' | 'todo-done' | 'todo-active' | 'todo-pending' | 'todo-failed' | 'todo-skipped' | 'plan-dock' | 'subagent-header';
+export type DisplayKind = Row['kind'] | 'tool-result' | 'diff-add' | 'diff-del' | 'diff-path' | 'todo-done' | 'todo-active' | 'todo-pending' | 'todo-failed' | 'todo-skipped' | 'plan-dock' | 'subagent-header' | 'setup-step' | 'setup-choice' | 'setup-field' | 'setup-step' | 'setup-choice' | 'setup-field';
 /** One rendered diff/inspect body line with its display role. */
 export interface DiffDisplayLine {
     kind: DisplayKind;
@@ -233,3 +293,4 @@ export interface ToolDiffHunk {
     oldText: string | null;
     newText: string;
 }
+export {};