dsh-code 0.3.0 → 0.4.0

package/src/render/projection.ts

@@ -9,13 +9,29 @@
 
 import { boundContextSummary, type ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { SessionEvent, TodoItem } from '@deepseek-ai/dsh-session'
-// Type-only imports merge the plugin-owned SessionEventMap variants (command/*
-// from dsh-commands, plan/mode, permission/preset) into the union this reducer
-// switches on.
+// Type-only imports merge the plugin-owned SessionEventMap variants
+// (command/*, compaction/*, goal/change, llm/retry*, plan/mode,
+// permission/preset, sandbox/mode, session/title) into the union this
+// reducer switches on.
 import type {} from '@deepseek-ai/dsh-commands'
+import type {} from '@deepseek-ai/dsh-compaction'
+import type {} from '@deepseek-ai/dsh-goal'
+import type {} from '@deepseek-ai/dsh-llm-retry'
 import type {} from '@deepseek-ai/dsh-plan-mode'
 import type {} from '@deepseek-ai/dsh-permission-presets'
+import type {} from '@deepseek-ai/dsh-sandbox-policy'
+import type {} from '@deepseek-ai/dsh-session-title'
 import { toolArgumentsPreview } from './tool-preview.ts'
+import { toolResultDetail, type ToolDetail } from './tool-detail.ts'
+
+/** In-flight UI buffers are tails; the assembled assistant message is authoritative. */
+const MAX_STREAMING_CHARS = 65_536
+
+/** Append one delta without retaining an unbounded duplicate of the live reply. */
+function appendStreamingTail(current: string, delta: string): string {
+  const next = current + delta
+  return next.length <= MAX_STREAMING_CHARS ? next : next.slice(-MAX_STREAMING_CHARS)
+}
 
 /** One user prompt line. */
 export interface UserEntry {
@@ -51,6 +67,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`. */
@@ -75,8 +97,62 @@ export interface ErrorEntry {
   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 {
@@ -100,20 +176,34 @@ 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
   /**
@@ -127,12 +217,18 @@ 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
    * against. Keyed `turn:step` and by call id.
    */
-  readonly anchors: { stepStart: Map<string, number>; toolStart: Map<string, number> }
+  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>> }
 }
 
 /** Join the text blocks of a content list; non-text blocks contribute nothing. */
@@ -153,11 +249,15 @@ export function createTranscriptView(): TranscriptView {
     streamingReasoning: '',
     todos: [],
     busy: false,
+    busySince: 0,
     model: '',
     plan: false,
     permission: '',
-    stats: { turns: 0, steps: 0, llmMs: 0, toolMs: 0, usage: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0 } },
-    anchors: { stepStart: new Map(), toolStart: new Map() },
+    title: '',
+    sandbox: '',
+    goal: undefined,
+    stats: { turns: 0, steps: 0, llmMs: 0, toolMs: 0, usage: { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0 }, lastPromptTokens: 0, contextWindow: 0, ttftMs: 0, ttftSteps: 0, decodeMs: 0, decodeTokens: 0 },
+    anchors: { stepStart: new Map(), toolStart: new Map(), firstChunkAt: new Map(), compactionTokens: new Map(), lastPruneTokens: 0, turnFiles: new Map() },
   }
 }
 
@@ -184,11 +284,27 @@ export function projectEvent(view: TranscriptView, event: SessionEvent): Transcr
     }
     case 'assistant/chunk': {
       const chunk = event.data.chunk
+      // First-token latency: the first non-empty delta of a step anchors the
+      // TTFT (empty keep-alive deltas do not count as tokens).
+      const key = `${event.data.turn}:${event.data.step}`
+      const delta = chunk.type === 'text-delta' || chunk.type === 'reasoning-delta' ? chunk.text : ''
+      let stats = view.stats
+      if (delta !== '' && !view.anchors.firstChunkAt.has(key)) {
+        view.anchors.firstChunkAt.set(key, event.time)
+        const started = view.anchors.stepStart.get(key)
+        if (started !== undefined) {
+          stats = {
+            ...stats,
+            ttftMs: stats.ttftMs + Math.max(0, event.time - started),
+            ttftSteps: stats.ttftSteps + 1,
+          }
+        }
+      }
       if (chunk.type === 'text-delta') {
-        return { ...view, streaming: view.streaming + chunk.text }
+        return { ...view, streaming: appendStreamingTail(view.streaming, chunk.text), stats }
       }
       if (chunk.type === 'reasoning-delta') {
-        return { ...view, streamingReasoning: view.streamingReasoning + chunk.text }
+        return { ...view, streamingReasoning: appendStreamingTail(view.streamingReasoning, chunk.text), stats }
       }
       return view
     }
@@ -197,6 +313,8 @@ export function projectEvent(view: TranscriptView, event: SessionEvent): Transcr
       const key = `${event.data.turn}:${event.data.step}`
       const started = view.anchors.stepStart.get(key)
       view.anchors.stepStart.delete(key)
+      const firstChunk = view.anchors.firstChunkAt.get(key)
+      view.anchors.firstChunkAt.delete(key)
       const usage = event.data.usage
       const totals = view.stats.usage
       return {
@@ -216,6 +334,12 @@ export function projectEvent(view: TranscriptView, event: SessionEvent): Transcr
             outputTokens: totals.outputTokens + usage.outputTokens,
             cacheReadTokens: totals.cacheReadTokens + (usage.cacheReadTokens ?? 0),
           },
+          lastPromptTokens: usage === undefined ? view.stats.lastPromptTokens
+            : usage.inputTokens + (usage.cacheReadTokens ?? 0) + (usage.cacheWriteTokens ?? 0),
+          // Decode span and its tokens pair up: an un-timed step (no first
+          // chunk landed) contributes neither, so the rate stays honest.
+          decodeMs: view.stats.decodeMs + (firstChunk === undefined ? 0 : Math.max(0, event.time - firstChunk)),
+          decodeTokens: view.stats.decodeTokens + (firstChunk === undefined || usage === undefined ? 0 : usage.outputTokens),
         },
       }
     }
@@ -232,6 +356,7 @@ export function projectEvent(view: TranscriptView, event: SessionEvent): Transcr
           preview: toolArgumentsPreview(data.arguments, data.name),
           state: 'running',
           summary: '',
+          detail: undefined,
         }],
       }
     }
@@ -239,10 +364,21 @@ export function projectEvent(view: TranscriptView, event: SessionEvent): Transcr
       const block = event.data.message.content[0]
       const started = view.anchors.toolStart.get(block.toolCallId)
       view.anchors.toolStart.delete(block.toolCallId)
-      const summary = boundContextSummary(textOf(block.content))
+      const rawText = textOf(block.content)
+      const summary = boundContextSummary(rawText)
+      // The verbose expansion self-serves from the persisted presentation
+      // metadata (diffs, read windows, web sources) with the bounded raw text
+      // as the universal fallback — the capable-UI degradation ladder.
+      const detail = toolResultDetail(event.data.meta, rawText)
+      // Turn-tail deliverables: a diff-bearing mutation records its paths.
+      if (detail?.kind === 'diff') {
+        const set = view.anchors.turnFiles.get(event.data.turn) ?? new Set<string>()
+        for (const diff of detail.diffs) set.add(diff.path)
+        view.anchors.turnFiles.set(event.data.turn, set)
+      }
       const entries = view.entries.map((entry) => {
         if (entry.kind !== 'tool' || entry.callId !== block.toolCallId) return entry
-        return { ...entry, state: block.isError === true ? 'error' as const : 'done' as const, summary }
+        return { ...entry, state: block.isError === true ? 'error' as const : 'done' as const, summary, detail }
       })
       return {
         ...view,
@@ -262,6 +398,7 @@ export function projectEvent(view: TranscriptView, event: SessionEvent): Transcr
       return {
         ...view,
         busy: true,
+        busySince: view.busy ? view.busySince : event.time,
         todos: [],
         stats: { ...view.stats, turns: view.stats.turns + 1 },
       }
@@ -270,13 +407,119 @@ export function projectEvent(view: TranscriptView, event: SessionEvent): Transcr
       return { ...view, stats: { ...view.stats, steps: view.stats.steps + 1 } }
     case 'turn/end': {
       const reason = event.data.reason
-      if (reason.kind !== 'error') return { ...view, busy: false }
+      const appended: TranscriptEntry[] = []
+      if (reason.kind === 'error') {
+        appended.push({ kind: 'error', text: `${reason.error.code}: ${reason.error.message}` })
+      } else {
+        // Non-error outcomes deserve their own durable row (the web renders
+        // distinct max-tokens / abort / interruption nodes); `completed` stays
+        // silent so an ordinary turn never grows a marker.
+        const marker = reason.kind === 'aborted'
+          ? reason.reason.kind === 'user' ? 'turn cancelled by the user' : `turn cancelled (${reason.reason.kind})`
+          : reason.kind === 'max-tokens'
+            ? 'turn hit the output-token ceiling (max-tokens)'
+            : reason.kind === 'blocked'
+              ? 'turn ended blocked'
+              : reason.kind === 'interrupted'
+                ? 'turn was interrupted by a restart'
+                : undefined
+        if (marker !== undefined) appended.push({ kind: 'turn-marker', text: marker })
+      }
+      // Deliverables ride the turn tail (the web's turnTail chips): the
+      // turn's mutated files flush as one bounded row, then the set resets.
+      const files = view.anchors.turnFiles.get(event.data.turn)
+      view.anchors.turnFiles.delete(event.data.turn)
+      if (files !== undefined && files.size > 0) appended.push({ kind: 'files', paths: [...files].slice(0, 12) })
+      if (appended.length === 0) return { ...view, busy: false, busySince: 0 }
+      return { ...view, busy: false, busySince: 0, entries: [...view.entries, ...appended] }
+    }
+    case 'llm/retry': {
+      const data = event.data
       return {
         ...view,
-        busy: false,
-        entries: [...view.entries, { kind: 'error', text: `${reason.error.code}: ${reason.error.message}` }],
+        entries: [...view.entries, {
+          kind: 'retry',
+          retryId: data.retryId,
+          attempt: data.retry,
+          max: 'maxRetries' in data ? data.maxRetries : data.retry,
+          code: data.failure.code,
+          delayMs: data.delayMs,
+          state: 'running',
+        }],
       }
     }
+    case 'llm/retry-started': {
+      const data = event.data
+      const entries = view.entries.map((entry) => {
+        if (entry.kind !== 'retry' || entry.retryId !== data.retryId) return entry
+        return { ...entry, state: 'done' as const }
+      })
+      return { ...view, entries }
+    }
+    case 'sandbox/mode':
+      // Log-only override switch; last write wins for the status badge.
+      return { ...view, sandbox: event.data.mode }
+    case 'goal/change': {
+      const data = event.data
+      const clip = (text: string): string => (text.length > 60 ? `${text.slice(0, 59)}…` : text)
+      if (data.operation === 'clear') {
+        return {
+          ...view,
+          goal: undefined,
+          entries: [...view.entries, { kind: 'turn-marker', text: '◎ goal cleared' }],
+        }
+      }
+      const goal: GoalFold = {
+        objective: data.goal.objective,
+        phase: data.goal.phase,
+        rounds: data.roundsStarted,
+        max: data.goal.maxGoalRounds,
+        blocked: data.goal.blockedReason?.message ?? '',
+      }
+      const line = data.operation === 'create'
+        ? `◎ goal: ${clip(data.goal.objective)}`
+        : data.operation === 'complete'
+          ? '◎ goal complete'
+          : data.operation === 'pause'
+            ? '◎ goal paused'
+            : data.operation === 'resume'
+              ? '◎ goal resumed'
+              : data.operation === 'block'
+                ? `◎ goal blocked: ${clip(goal.blocked)}`
+                : undefined
+      return {
+        ...view,
+        goal,
+        entries: line === undefined ? view.entries : [...view.entries, { kind: 'turn-marker', text: line }],
+      }
+    }
+    case 'session/title':
+      // Latest-wins title snapshot, log-only; the status line prefers it.
+      return { ...view, title: event.data.title }
+    case 'compaction/summary':
+      // Remember the shadow price so the matching `compaction/end` row can
+      // state what the compaction reclaimed.
+      view.anchors.compactionTokens.set(event.data.compactionId, event.data.shadowedTokenCount)
+      return view
+    case 'compaction/prune':
+      // A model-free prune carries no compaction id; its price serves the next
+      // `compaction/end` that cannot find a summary price.
+      return { ...view, anchors: { ...view.anchors, lastPruneTokens: event.data.shadowedTokenCount } }
+    case 'compaction/end': {
+      const ok = event.data.error === undefined
+      const tokens = view.anchors.compactionTokens.get(event.data.compactionId) ?? view.anchors.lastPruneTokens
+      view.anchors.compactionTokens.delete(event.data.compactionId)
+      return {
+        ...view,
+        entries: [...view.entries, { kind: 'compaction', ok, tokens, error: event.data.error ?? '' }],
+      }
+    }
+    case 'request/context':
+      // Route capacity, logged only when it changes; last one wins.
+      return {
+        ...view,
+        stats: { ...view.stats, contextWindow: event.data.contextWindow ?? view.stats.contextWindow },
+      }
     case 'request/header': {
       // The session's own model record: the latest snapshot's provider/model
       // pair, exactly what a resumed TUI restores as the selection.
@@ -327,3 +570,23 @@ export function projectEvent(view: TranscriptView, event: SessionEvent): Transcr
 export function projectEvents(events: readonly SessionEvent[]): TranscriptView {
   return events.reduce(projectEvent, createTranscriptView())
 }
+
+/**
+ * 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 function settledEntryCount(entries: readonly TranscriptEntry[]): number {
+  for (let index = 0; index < entries.length; index++) {
+    const entry = entries[index]
+    if (entry.kind === 'tool' && entry.state === 'running') return index
+    if (entry.kind === 'retry' && entry.state === 'running') return index
+  }
+  return entries.length
+}

package/src/render/status.ts

@@ -36,6 +36,18 @@ export function formatDuration(ms: number): string {
   return `${Math.floor(whole / 60)}m${whole % 60}s`
 }
 
+/**
+ * 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 function formatRate(n: number): string {
+  if (n < 100) return String(Math.round(n * 10) / 10)
+  if (n < 1_000) return String(Math.round(n))
+  return `${Math.round(n / 100) / 10}K`
+}
+
 /**
  * Cache-hit share of billed prompt-side input.
  * @param usage - cumulative token totals.
@@ -57,6 +69,12 @@ 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. */
@@ -82,18 +100,47 @@ export function buildStatusGroups(facts: StatusFacts, stats: TranscriptStats): s
     groups.push(`T${stats.turns} · S${stats.steps}`)
     const durations: string[] = []
     if (stats.llmMs > 0) durations.push(`llm ${formatDuration(stats.llmMs)}`)
+    // Decode latency figures (the web StatsLine's TTFT and throughput):
+    // average first-token wait and tokens per second over timed steps.
+    if (stats.ttftSteps > 0) durations.push(`ttft ${formatDuration(stats.ttftMs / stats.ttftSteps)}`)
+    if (stats.decodeMs > 0 && stats.decodeTokens > 0) {
+      durations.push(`${formatRate(stats.decodeTokens / (stats.decodeMs / 1_000))} tok/s`)
+    }
     if (stats.toolMs > 0) durations.push(`tool ${formatDuration(stats.toolMs)}`)
     if (durations.length > 0) groups.push(durations.join(' · '))
   }
   const cacheHit = cacheHitPercent(stats.usage)
   if (stats.usage.inputTokens > 0 || stats.usage.outputTokens > 0) {
     if (cacheHit !== null) groups.push(`cache ${cacheHit}%`)
+    // Context occupancy (the web StatsLine's meter): the most recent
+    // reported prompt size against the advertised route capacity.
+    if (stats.contextWindow > 0 && stats.lastPromptTokens > 0) {
+      groups.push(`ctx ${Math.min(999, Math.round(stats.lastPromptTokens / stats.contextWindow * 100))}%`)
+    }
     groups.push(`↑${formatTokens(stats.usage.inputTokens)} ↓${formatTokens(stats.usage.outputTokens)}`)
   }
-  if (facts.sessionId !== '') groups.push(facts.sessionId)
+  // The session title replaces the bare short id whenever one has landed
+  // (user rename or provider generation), bounded so a long title cannot
+  // crowd out the rest of the line.
+  const label = facts.title !== undefined && facts.title !== ''
+    ? (facts.title.length > 48 ? `${facts.title.slice(0, 47)}…` : facts.title)
+    : facts.sessionId
+  if (label !== '') groups.push(label)
   // The permission preset trails the line: switching it changes only the
   // tail, so the left-aligned bar never shifts its other groups. Plain text,
   // the Claude-Code permission-mode display (no glyphs).
   if (facts.permission !== undefined && facts.permission !== '') groups.push(facts.permission)
+  // The sandbox override stays implicit when it merely echoes the preset —
+  // the badge exists to surface a divergence, not to duplicate the label.
+  const sandbox = facts.sandbox ?? ''
+  if (sandbox !== '' && sandbox.toLowerCase() !== facts.permission.toLowerCase()) {
+    groups.push(`sandbox ${sandbox}`)
+  }
+  // Goal badge: round progress while active, the phase otherwise.
+  if (facts.goal !== undefined) {
+    groups.push(facts.goal.phase === 'active'
+      ? `◎ r${facts.goal.rounds}/${facts.goal.max}`
+      : `◎ ${facts.goal.phase}`)
+  }
   return groups
 }

package/src/render/text.ts

@@ -22,3 +22,82 @@ const CONTROL_ESCAPE = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/gu
 export function displayText(text: string): string {
   return text.replace(CONTROL_ESCAPE, char => `\\x${char.charCodeAt(0).toString(16).padStart(2, '0')}`)
 }
+
+/** 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
+}
+
+/** Terminal-cell width matching the TUI's existing CJK-aware wrapping rule. */
+function cellWidth(text: string): number {
+  let columns = 0
+  for (const char of text) {
+    columns += (char.codePointAt(0) ?? 0) > 0x2e7f ? 2 : 1
+  }
+  return columns
+}
+
+/** Read one Unicode character immediately before `end`. */
+function previousCharacter(text: string, end: number): { char: string; start: number } {
+  const last = text.charCodeAt(end - 1)
+  if (last >= 0xdc00 && last <= 0xdfff && end >= 2) {
+    const first = text.charCodeAt(end - 2)
+    if (first >= 0xd800 && first <= 0xdbff) {
+      return { char: text.slice(end - 2, end), start: end - 2 }
+    }
+  }
+  return { char: text.slice(end - 1, end), start: end - 1 }
+}
+
+/**
+ * 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 function displayTail(text: string, columns: number, rows: number): DisplayTail {
+  const columnLimit = Math.max(1, Math.floor(columns))
+  const rowLimit = Math.max(1, Math.floor(rows))
+  const reversed: string[] = []
+  let row = 1
+  let used = 0
+  let end = text.length
+
+  while (end > 0) {
+    const previous = previousCharacter(text, end)
+    if (previous.char === '\n') {
+      if (row >= rowLimit) break
+      reversed.push('\n')
+      row += 1
+      used = 0
+      end = previous.start
+      continue
+    }
+
+    const safe = displayText(previous.char)
+    const width = cellWidth(safe)
+    if (used > 0 && used + width > columnLimit) {
+      if (row >= rowLimit) break
+      // Materialize the soft wrap. Ink otherwise reflows at word boundaries
+      // and can turn a cell-counted two-row suffix into three rendered rows.
+      reversed.push('\n')
+      row += 1
+      used = 0
+    }
+    const extraRows = Math.floor(Math.max(0, width - 1) / columnLimit)
+    if (row + extraRows > rowLimit) break
+    row += extraRows
+    reversed.push(safe)
+    used = extraRows === 0 ? used + width : width - extraRows * columnLimit
+    end = previous.start
+  }
+
+  return { text: reversed.reverse().join(''), truncated: end > 0 }
+}