pikuri-core 0.0.3

data/lib/pikuri/agent/listener/rate_limited.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Agent
+    module Listener
+      # Decorator that coalesces high-frequency streaming deltas
+      # ({Event::AssistantDelta}, {Event::ThinkingDelta}) into at most
+      # +fps+ events per second before handing them off to an inner
+      # listener. Non-delta events flow through unmodified, with any
+      # pending coalesced content either emitted ahead of them
+      # (default) or dropped silently — see
+      # +flush_pending_on_non_delta:+.
+      #
+      # Useful for renderers whose per-delta repaint cost is higher
+      # than the wire-arrival rate of provider chunks: a fast provider
+      # can emit dozens of deltas per second, and a Markdown-rendering
+      # UI doesn't need every one of them on-screen. +fps: 15+ is a
+      # reasonable starting point for a TUI.
+      #
+      # == Tick alignment
+      #
+      # The first flush is anchored to a monotonic-clock reference
+      # taken at construction, not to the arrival of the first delta.
+      # This keeps stream-startup latency from leaking into the
+      # cadence: with +fps: 1+, if the first delta arrives 0.9s after
+      # construction, it flushes immediately (the construction-time
+      # tick has already passed) and the next tick fires 0.1s later
+      # — preserving the configured rate. After a flush, the schedule
+      # advances by exactly +1/fps+ per missed tick; a long-idle
+      # stream doesn't backlog ticks against itself.
+      #
+      # == Per-stream buffering
+      #
+      # Assistant and thinking deltas are buffered independently. A
+      # tick flushes whichever buffers are non-empty as separate
+      # coalesced delta events; providers practically don't interleave
+      # the two modalities within a single tick, but the
+      # implementation doesn't rely on that.
+      #
+      # == Non-delta handling
+      #
+      # +flush_pending_on_non_delta: true+ (default) emits any pending
+      # coalesced content as a delta event ahead of the non-delta
+      # event so the inner listener sees the complete stream — the
+      # lossless choice. +false+ drops the pending buffers silently:
+      # appropriate for inner listeners that re-render the
+      # authoritative final content on a bookend ({Event::Assistant} /
+      # {Event::Thinking}), where rendering the trailing 0–66 ms of
+      # deltas would be wasted CPU before the redraw.
+      #
+      # == Threading
+      #
+      # No threads, no timers. The decorator advances its tick state
+      # only when an event arrives, so it's safe to install on any
+      # listener regardless of which thread the agent emits on, as
+      # long as delivery is sequential (which the {ListenerList}
+      # contract guarantees).
+      class RateLimited < Base
+        # @param inner [Listener::Base] the listener to forward
+        #   (possibly coalesced) events to.
+        # @param fps [Integer, Float] frames-per-second cap on the
+        #   coalesced delta stream. Must be positive.
+        # @param flush_pending_on_non_delta [Boolean] +true+
+        #   (default) emits any pending coalesced content as a delta
+        #   before forwarding the non-delta event; +false+ drops the
+        #   pending buffers silently.
+        # @param clock [Proc] zero-arg returning monotonic
+        #   seconds-since-some-epoch as a +Float+. Injection seam for
+        #   deterministic specs; production uses
+        #   +Process.clock_gettime(Process::CLOCK_MONOTONIC)+.
+        # @raise [ArgumentError] if +fps+ is not positive.
+        def initialize(inner, fps:, flush_pending_on_non_delta: true,
+                       clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
+          super()
+          raise ArgumentError, "fps must be positive, got #{fps.inspect}" unless fps.positive?
+
+          @inner = inner
+          @fps = fps
+          @period = 1.0 / fps
+          @flush_on_non_delta = flush_pending_on_non_delta
+          @clock = clock
+          @next_tick_at = clock.call
+          @assistant_buffer = String.new
+          @thinking_buffer = String.new
+        end
+
+        # @param event [Agent::Event] one of the {Agent::Event}
+        #   variants; see {Agent::Event} for the full list
+        # @return [void]
+        def on_event(event)
+          case event
+          when Event::AssistantDelta
+            @assistant_buffer << event.content
+            tick
+          when Event::ThinkingDelta
+            @thinking_buffer << event.content
+            tick
+          else
+            if @flush_on_non_delta
+              flush_thinking
+              flush_assistant
+            else
+              @assistant_buffer.clear
+              @thinking_buffer.clear
+            end
+            @inner.on_event(event)
+          end
+        end
+
+        # Sub-agent variant: wraps the inner listener's sub-agent
+        # variant (or the inner listener itself when it doesn't define
+        # +for_sub_agent+) in a fresh +RateLimited+ with the same
+        # knobs. Returns +nil+ when the inner's +for_sub_agent+
+        # returned +nil+ — there's nothing to wrap.
+        #
+        # @param params [Hash{Symbol => Object}] forwarded to the
+        #   inner listener's +for_sub_agent+, same protocol as
+        #   {ListenerList#for_sub_agent}
+        # @return [RateLimited, nil]
+        def for_sub_agent(**params)
+          inner_sub = @inner.respond_to?(:for_sub_agent) ? @inner.for_sub_agent(**params) : @inner
+          return nil if inner_sub.nil?
+
+          self.class.new(inner_sub, fps: @fps,
+                                    flush_pending_on_non_delta: @flush_on_non_delta,
+                                    clock: @clock)
+        end
+
+        # @return [String] short label for {Agent#to_s}; embeds the
+        #   inner listener's label so the chain reads end-to-end in
+        #   {ListenerList#to_s}
+        def to_s
+          policy = @flush_on_non_delta ? 'flush' : 'drop'
+          "RateLimited(#{@fps}fps, #{policy}, #{@inner})"
+        end
+
+        private
+
+        # Advance to the next tick strictly after +now+, in one shot.
+        # Handles the case where deltas paused for several periods —
+        # a long-idle stream doesn't backlog ticks against the next
+        # stream's first delta.
+        # @return [void]
+        def tick
+          now = @clock.call
+          return if now < @next_tick_at
+
+          flush_thinking
+          flush_assistant
+          missed = ((now - @next_tick_at) / @period).floor + 1
+          @next_tick_at += missed * @period
+        end
+
+        # @return [void]
+        def flush_assistant
+          return if @assistant_buffer.empty?
+
+          @inner.on_event(Event::AssistantDelta.new(content: @assistant_buffer.dup))
+          @assistant_buffer.clear
+        end
+
+        # @return [void]
+        def flush_thinking
+          return if @thinking_buffer.empty?
+
+          @inner.on_event(Event::ThinkingDelta.new(content: @thinking_buffer.dup))
+          @thinking_buffer.clear
+        end
+      end
+    end
+  end
+end

data/lib/pikuri/agent/listener/terminal.rb

@@ -0,0 +1,264 @@
+# frozen_string_literal: true
+
+require 'rainbow'
+require 'tty-markdown'
+
+module Pikuri
+  class Agent
+    module Listener
+      # Terminal renderer for the normalized event stream: dim grey
+      # reasoning, Markdown-rendered assistant content, cyan tool-
+      # call and tool-result lines, yellow fallback notice, red
+      # cancelled notice. {Event::UserTurn} is intentionally silent
+      # (the terminal user just typed the message, so re-rendering
+      # it adds nothing); {Event::Tokens} and {Event::ContextCap}
+      # are silent too (their consumer is {TokenLog}).
+      #
+      # Optionally prepends a fixed number of leading spaces to
+      # every rendered line via the +padding:+ kwarg. Sub-agents
+      # get a fresh padded instance through {#for_sub_agent}
+      # (dispatched by {ListenerList#for_sub_agent}) so their
+      # output is visually indented under the parent's stream.
+      #
+      # == Streaming mode
+      #
+      # When constructed with +streaming: true+ (typically because
+      # the host's {Agent} was constructed with the matching flag):
+      #
+      # - {Event::ThinkingDelta} fragments print live in the same
+      #   dim grey as the non-streaming {Event::Thinking}, with no
+      #   trailing newline so the next fragment continues the line.
+      # - {Event::AssistantDelta} fragments print live, *raw* — no
+      #   Markdown render. tty-markdown can't render half-finished
+      #   Markdown (broken code blocks, half-rendered tables), so
+      #   the live stream gives up formatting in exchange for
+      #   liveness.
+      # - {Event::Thinking} and {Event::Assistant} bookends print
+      #   a single blank line as a stream terminator, not their
+      #   content (the content already landed via the deltas). The
+      #   terminator gives the next event (tool call, next round,
+      #   final REPL prompt) a clean line to start on.
+      #
+      # In non-streaming mode (+streaming: false+, the default),
+      # the deltas are silently ignored and the bookend events
+      # render the full text the way they always have.
+      class Terminal < Base
+        # Subsystem logger; set its level with +PIKURI_LOG_TERMINAL+
+        # or the global +PIKURI_LOG+. Used for the narrow rescue
+        # around third-party rendering (+tty-markdown+ choking on
+        # assistant output) — see the CLAUDE.md "secondary to the
+        # loop" carve-out.
+        #
+        # @return [Logger]
+        LOGGER = Pikuri.logger_for('Terminal')
+
+        # Cap, in characters, applied to tool-result content
+        # rendered to the terminal. Anything longer is truncated
+        # with a marker that reports the original byte size so the
+        # reader can tell a 200-char return apart from a 50KB HTML
+        # dump.
+        MAX_TOOL_RESULT_CHARS = 200
+
+        # Padding applied to a sub-agent's rendered stream.
+        # Absolute, not additive — sub-agent recursion is blocked
+        # (the sub-agent's tool set excludes +sub_agent+ itself),
+        # so the depth never exceeds 1 in practice and a fixed
+        # indent reads cleanly.
+        SUB_AGENT_PADDING = 2
+
+        # @param padding [Integer] non-negative number of leading
+        #   spaces prepended to every rendered line. Defaults to 0;
+        #   sub-agents get a fresh instance with
+        #   {SUB_AGENT_PADDING} via {#for_sub_agent}.
+        # @param streaming [Boolean] render the chunk-level delta
+        #   stream live. See the class header's "Streaming mode"
+        #   section for the behavior swap. Defaults to +false+.
+        def initialize(padding: 0, streaming: false)
+          super()
+          @padding = padding
+          @streaming = streaming
+          @at_line_start = true
+        end
+
+        # @return [Integer] current padding width; exposed so
+        #   callers can introspect it (and so tests can assert it).
+        attr_reader :padding
+
+        # @return [Boolean] +true+ when this Terminal is in
+        #   streaming mode (deltas rendered live; bookends emit a
+        #   terminator newline only).
+        attr_reader :streaming
+
+        # Sub-agent variant: a fresh +Terminal+ at
+        # {SUB_AGENT_PADDING}, carrying the same +streaming+ flag
+        # the parent had, so sub-agent output is visually indented
+        # under the parent's stream and the stream mode stays
+        # consistent across the agent tree. Called by
+        # {ListenerList#for_sub_agent}; ignores any params it's
+        # handed (Terminal has no caller-provided knobs).
+        #
+        # @return [Terminal]
+        def for_sub_agent(**)
+          self.class.new(padding: SUB_AGENT_PADDING, streaming: @streaming)
+        end
+
+        # @param event [Agent::Event] one of the {Agent::Event}
+        #   variants; see {Agent::Event} for the full list
+        # @return [void]
+        def on_event(event)
+          case event
+          in Event::Thinking(content:)
+            if @streaming
+              terminate_stream
+            else
+              println(indent(Rainbow(content).color(85, 85, 85)))
+            end
+          in Event::Assistant(content:)
+            if @streaming
+              terminate_stream
+            else
+              println(indent(render_markdown(content)))
+            end
+          in Event::ThinkingDelta(content:)
+            stream_fragment(Rainbow(content).color(85, 85, 85)) if @streaming
+          in Event::AssistantDelta(content:)
+            stream_fragment(content) if @streaming
+          in Event::ToolCall(name:, arguments:)
+            args = arguments.map { |k, v| "#{k}=#{v.inspect}" }.join(', ')
+            println(indent(Rainbow("→ #{name}(#{args})").cyan))
+          in Event::ToolResult(content:)
+            println(indent(Rainbow("= #{truncate_tool_result(content)}").cyan))
+          in Event::FallbackNotice(reason:)
+            println(indent(Rainbow("! #{reason}").yellow))
+          in Event::Cancelled
+            println(indent(Rainbow('! cancelled').red))
+          else
+            # UserTurn / Tokens / ContextCap silent on the terminal.
+            # In non-streaming mode the deltas fall through here
+            # too (the final Thinking / Assistant bookend already
+            # renders the full text).
+          end
+        end
+
+        # @return [String] short label for {Agent#to_s}; appends
+        #   each non-default knob (+padding+, +streaming+) so the
+        #   default form stays +"Terminal"+
+        def to_s
+          suffix = []
+          suffix << "padding=#{@padding}" unless @padding.zero?
+          suffix << 'streaming' if @streaming
+          suffix.empty? ? 'Terminal' : "Terminal(#{suffix.join(', ')})"
+        end
+
+        private
+
+        # +puts+ wrapper that also resets the streaming line-state
+        # to "at line start" — every full-line print necessarily
+        # leaves the cursor at column 0, so the next fragment
+        # printed in streaming mode knows to insert padding before
+        # its first character. Used by every branch in
+        # {#on_event} except the delta branches.
+        #
+        # @param text [String]
+        # @return [void]
+        def println(text)
+          puts text
+          @at_line_start = true
+        end
+
+        # Emit a single newline as a stream terminator and reset
+        # the line-state. Called on {Event::Thinking} /
+        # {Event::Assistant} bookends in streaming mode, where the
+        # content has already been rendered via the delta stream
+        # and what's left to do is give the next event a clean
+        # line to start on.
+        #
+        # @return [void]
+        def terminate_stream
+          puts
+          @at_line_start = true
+        end
+
+        # Print one streaming fragment to stdout *without* a
+        # trailing newline (so the next fragment continues the
+        # line) and flush so the bytes actually reach the
+        # terminal. Threads padding through any mid-fragment
+        # newlines: a fragment that contains "foo\nbar" with
+        # padding 2 prints +"  foo\n  bar"+ when the cursor was
+        # at line start.
+        #
+        # @param text [String] the fragment to emit; +nil+ / empty
+        #   short-circuits
+        # @return [void]
+        def stream_fragment(text)
+          return if text.nil? || text.empty?
+
+          if @padding.zero?
+            print(text)
+            @at_line_start = text.end_with?("\n")
+          else
+            buf = String.new
+            prefix = ' ' * @padding
+            text.each_char do |ch|
+              buf << prefix if @at_line_start
+              buf << ch
+              @at_line_start = (ch == "\n")
+            end
+            print(buf)
+          end
+          $stdout.flush
+        end
+
+        # Prepend +@padding+ spaces to every line of +text+. Splits
+        # on +each_line+ rather than a +gsub+ trick so a trailing
+        # newline in the input doesn't produce a stray padded blank
+        # line at the end — +puts+ adds the final newline if
+        # missing, same as before.
+        #
+        # @param text [String]
+        # @return [String]
+        def indent(text)
+          return text if @padding.zero?
+
+          prefix = ' ' * @padding
+          text.to_s.each_line.map { |line| prefix + line }.join
+        end
+
+        # Render assistant Markdown for the terminal, degrading to
+        # the raw string when the renderer raises. tty-markdown /
+        # strings have known bugs around ANSI inside tables (e.g.
+        # +Strings::Wrap.insert_ansi+ raising +IndexError+); we'd
+        # rather show ugly Markdown than abort an in-flight
+        # conversation.
+        #
+        # @param content [String] assistant Markdown
+        # @return [String] rendered ANSI text, or +content+
+        #   unchanged on render failure
+        def render_markdown(content)
+          TTY::Markdown.parse(content)
+        rescue StandardError => e
+          LOGGER.warn("TTY::Markdown render failed (#{e.class}: #{e.message}); falling back to raw text")
+          content
+        end
+
+        # Flatten whitespace and cap to {MAX_TOOL_RESULT_CHARS}. The
+        # cap keeps multi-screen dumps (rendered HTML, PDF text)
+        # from drowning the terminal stream; the byte-count suffix
+        # on a truncated result distinguishes "tool returned
+        # exactly this" from "tool returned much more, you're
+        # seeing a slice."
+        #
+        # @param content [String] tool observation
+        # @return [String] single-line display form, possibly
+        #   truncated
+        def truncate_tool_result(content)
+          original_bytes = content.to_s.bytesize
+          flattened = content.to_s.gsub(/\s+/, ' ').strip
+          return flattened if flattened.length <= MAX_TOOL_RESULT_CHARS
+
+          "#{flattened[0, MAX_TOOL_RESULT_CHARS]}… (#{original_bytes} bytes total)"
+        end
+      end
+    end
+  end
+end

data/lib/pikuri/agent/listener/token_log.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Agent
+    module Listener
+      # Logs the conversation's context-window consumption per
+      # assistant turn via +Pikuri.logger_for('Tokens')+. Consumes
+      # {Event::Tokens} (one log line per emission) and
+      # {Event::ContextCap} (one-shot cap, picked off and cached);
+      # every other event variant is a no-op.
+      #
+      # Existence rationale: catch context-window growth before the
+      # provider raises +RubyLLM::ContextLengthExceededError+.
+      # +ctx+ is the headline number — tokens consumed by the
+      # conversation *through* this turn: this turn's prompt plus
+      # its reply, both of which the model will re-process on the
+      # next turn. The +Δ+ field shows the climb between turns;
+      # +↑+ / +↓+ are the per-turn input / output sizes that drove
+      # it (matching Claude Code's convention: +↑+ is what's sent
+      # to the model, +↓+ is what comes back).
+      #
+      # == State and scope
+      #
+      # The latest snapshot lives on the instance, so one
+      # +TokenLog+ is per-conversation. Sub-agents (with their own
+      # +RubyLLM::Chat+) get a fresh instance via {#for_sub_agent}
+      # (dispatched by {ListenerList#for_sub_agent}) so their
+      # counts log against their own chat. The synthesizer rescue
+      # gets a derived list via the same hook because its synth
+      # chat is also fresh.
+      #
+      # == Log line shape
+      #
+      # Without a cap (no {Event::ContextCap} carrying a value):
+      #
+      #   msg #1: ctx=6.8k  Δ+6.8k  ↑6.8k  ↓0.0k
+      #   msg #2: ctx=8.4k  Δ+1.6k  ↑1.0k  ↓0.6k
+      #
+      # With a cap of e.g. 32k (an {Event::ContextCap} with
+      # +cap: 32_768+ was emitted at {Agent#initialize}):
+      #
+      #   msg #1: ctx=6.8k/32.0k  Δ+6.8k  ↑6.8k  ↓0.0k
+      #
+      # When the owning {Agent} has a non-empty {Agent#name} (i.e.
+      # a sub-agent), the line is prefixed with +[name] +:
+      #
+      #   [sub_agent 0] msg #1: ctx=4.2k  Δ+4.2k  ↑4.2k  ↓0.0k
+      #
+      # +ctx+ is the snapshot
+      # (+input + cached + cache_creation + output+; see
+      # {Event::Tokens}), optionally suffixed with +/<cap>+ when
+      # {#context_window_cap} is set so the operator can see how
+      # close the conversation is to the limit. Including +output+
+      # makes this turn's reply visible immediately — leaving it
+      # out would hide a long reply in the +ctx=+ headline until
+      # the next turn pulled it in as cached prompt. +Δ+ is
+      # signed: +Δ+X+ for growth, +Δ-X+ for shrinkage (legitimate
+      # if ruby_llm ever prunes between turns). On the first
+      # message the baseline is implicitly zero, so +Δ+ equals
+      # +ctx+. Sizes are scaled by 1024 and shown with one
+      # decimal + a +k+ suffix.
+      class TokenLog < Base
+        # Subsystem logger; the per-turn context-window line is
+        # emitted at +INFO+ level. Set its level with
+        # +PIKURI_LOG_TOKENS+ or the global +PIKURI_LOG+.
+        #
+        # @return [Logger]
+        LOGGER = Pikuri.logger_for('Tokens')
+
+        # Tokens consumed by the conversation through the most
+        # recent turn — this turn's prompt plus its reply, which
+        # together make up the bulk of what the next turn will
+        # re-process. Equals +input + cached + cache_creation +
+        # output+ from the latest {Event::Tokens}. Zero until the
+        # first {Event::Tokens} arrives.
+        #
+        # @return [Integer]
+        attr_reader :context_window_size
+
+        # Model's context-window cap, or +nil+ if no source could
+        # supply one (see {Agent::ContextWindowDetector}). When
+        # set, the +ctx=+ field renders as +ctx=<used>/<cap>+
+        # instead of just +ctx=<used>+. {Agent#initialize} emits a
+        # one-shot {Event::ContextCap} at construction; this
+        # listener picks the value off it and caches it here. An
+        # instance constructed bare (e.g. in tests, or by
+        # {#for_sub_agent}) defaults to +nil+.
+        #
+        # @return [Integer, nil]
+        attr_accessor :context_window_cap
+
+        # @return [String] owning agent's identifier. Empty by
+        #   default (main agent); set by {#for_sub_agent} from the
+        #   sub-agent's generated name so the log lines can be
+        #   prefixed with +[<name>] +. Read-only — for a
+        #   sub-agent's listener you get a fresh instance via
+        #   {#for_sub_agent}.
+        attr_reader :name
+
+        # The most recent log line, in the exact format written to
+        # {LOGGER} (including any +[<name>] + prefix). Empty until
+        # the first {Event::Tokens} has been processed. Hosts that
+        # want to surface the current context-window snapshot in
+        # their own UI (e.g. a TUI status footer) read this
+        # instead of re-implementing the formatting.
+        #
+        # Thread safety: a single instance-variable read of a
+        # +String+ — safe to read from any thread; readers may
+        # briefly see the previous turn's line during an in-flight
+        # {#on_event} call, which is acceptable for a status
+        # display.
+        #
+        # @return [String]
+        attr_reader :status_line
+
+        # @param name [String] agent identifier prepended to each
+        #   log line as +[<name>] + when non-empty. Defaults to
+        #   +""+ for the main agent.
+        def initialize(name: '')
+          super()
+          @name = name
+          @msg = 0
+          @context_window_size = 0
+          @context_window_cap = nil
+          @status_line = ''
+        end
+
+        # Sub-agent variant: a fresh +TokenLog+ with a zeroed
+        # snapshot so the sub-agent's context-window readings
+        # track its own +RubyLLM::Chat+ rather than continuing the
+        # parent's. Picks the sub-agent's +name:+ out of the
+        # forwarded params so its log lines carry the +[<name>] +
+        # prefix; defaults to +""+ when absent. The cap is left
+        # +nil+ here; the sub-agent's {Agent#initialize} emits a
+        # fresh {Event::ContextCap} immediately after construction
+        # and this listener picks it up off the stream.
+        #
+        # @param name [String] sub-agent's identifier
+        # @return [TokenLog]
+        def for_sub_agent(name: '', **)
+          self.class.new(name: name)
+        end
+
+        # @param event [Agent::Event]
+        # @return [void]
+        def on_event(event)
+          case event
+          in Event::Tokens => tokens
+            log_tokens(tokens)
+          in Event::ContextCap(cap:)
+            @context_window_cap = cap
+          else
+            # Every other variant: no-op.
+          end
+        end
+
+        # @return [String] short label for {Agent#to_s}, including
+        #   the current context-window size (with cap suffix when
+        #   set)
+        def to_s
+          "TokenLog(ctx=#{format_ctx})"
+        end
+
+        private
+
+        # Update the snapshot and write one +INFO+ line to the
+        # subsystem logger.
+        #
+        # @param tokens [Event::Tokens]
+        # @return [void]
+        def log_tokens(tokens)
+          @msg += 1
+          input_now          = tokens.input.to_i
+          cached_now         = tokens.cached.to_i
+          cache_creation_now = tokens.cache_creation.to_i
+
+          prev_ctx = @context_window_size
+          @context_window_size = input_now + cached_now + cache_creation_now + tokens.output.to_i
+          delta = @context_window_size - prev_ctx
+
+          @status_line = format_line(input_now, tokens.output.to_i, delta)
+          LOGGER.info(@status_line)
+        end
+
+        def format_line(input, output, delta)
+          sign = delta.negative? ? '-' : '+'
+          prefix = @name.empty? ? '' : "[#{@name}] "
+          "#{prefix}msg ##{@msg}: ctx=#{format_ctx}  Δ#{sign}#{format_k(delta.abs)}  ↑#{format_k(input)}  ↓#{format_k(output)}"
+        end
+
+        # +<used>+ when no cap is set, +<used>/<cap>+ when one is.
+        # Shared between {#format_line} and {#to_s} so the headline
+        # reads the same in the log stream and in {Agent#to_s}
+        # banners.
+        def format_ctx
+          base = format_k(@context_window_size)
+          return base if @context_window_cap.nil?
+
+          "#{base}/#{format_k(@context_window_cap)}"
+        end
+
+        # Format a token count as a 1024-scaled +k+-suffixed
+        # string. +nil+ → +0.0k+; +0+ → +0.0k+; 12_453 → +12.2k+.
+        # Uniform format keeps lines easy to scan at the cost of
+        # looking odd for very small per-turn outputs (+↓0.0k+ on
+        # tool-call acks).
+        #
+        # @param n [Integer, nil]
+        # @return [String]
+        def format_k(n)
+          format('%.1fk', n.to_i / 1024.0)
+        end
+      end
+    end
+  end
+end