Module: TUI::Formatting

Included in:
Decorators::BaseDecorator, Screens::Chat
Defined in:
lib/tui/formatting.rb

Overview

Shared formatting helpers for timestamps and token counts. Used by both the Chat screen and client-side decorators to avoid duplicating display logic.

Instance Method Summary collapse

Instance Method Details

#format_ns_timestamp(ns) ⇒ String

Converts nanosecond-precision timestamp to human-readable HH:MM:SS.

Parameters:

  • ns (Integer, nil) —

    nanosecond timestamp

Returns:

  • (String) —

    formatted time, or “–:–:–” when nil



44
45
46
47
48
 
# File 'lib/tui/formatting.rb', line 44

def format_ns_timestamp(ns)
  return "--:--:--" unless ns

  Time.at(ns / 1_000_000_000.0).strftime("%H:%M:%S")
end

#format_token_label(tokens, estimated) ⇒ String

Formats a token count for display, with tilde prefix for estimates.

Parameters:

  • tokens (Integer, nil) —

    token count

  • estimated (Boolean) —

    whether the count is an estimate

Returns:

  • (String) —

    formatted label, e.g. “[42 tok]” or “[~28 tok]”



12
13
14
15
16
17
 
# File 'lib/tui/formatting.rb', line 12

def format_token_label(tokens, estimated)
  return "" unless tokens

  label = estimated ? "~#{tokens}" : tokens.to_s
  "[#{label} tok]"
end

#token_count_color(tokens) ⇒ String, Integer

Returns a semantic color for token count display. Visually flags expensive messages so runaway tool calls or bloated responses jump out immediately in debug mode.

Thresholds (empirically tuned from real agent sessions):

< 1k  → dark_gray  (routine, ignorable)
< 3k  → white      (normal)
< 10k → yellow     (notable)
< 20k → 208/orange (expensive)
≥ 20k → red        (alarm — likely runaway)

Parameters:

  • tokens (Integer) —

    token count

Returns:

  • (String, Integer) —

    named color or 256-color index



32
33
34
35
36
37
38
39
 
# File 'lib/tui/formatting.rb', line 32

def token_count_color(tokens)
  return "dark_gray" if tokens < 1_000
  return "white" if tokens < 3_000
  return "yellow" if tokens < 10_000
  return 208 if tokens < 20_000 # orange (256-color)

  "red"
end