pikuri 0.0.1

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Agent
+    module Listener
+      # Abstract base for listeners that consume the +Agent+'s normalized
+      # event stream as {Message} value objects. Concrete subclasses
+      # override the single {#on_message} hook and pattern-match on the
+      # variant.
+      #
+      # +#attach(chat)+ wires the three +RubyLLM::Chat+ callbacks once,
+      # builds the appropriate {Message} variant from each payload, and
+      # forwards it into {#on_message}. Empty +thinking+ and +assistant+
+      # content is filtered here so subclasses never receive vacuous
+      # events.
+      #
+      # Provider-reported token usage is a separate channel: every
+      # assistant +after_message+ event (including pure tool-call turns
+      # with empty content) emits an {Agent::Tokens} through {#on_tokens}
+      # so listeners that track context-window growth see every round
+      # trip. {Message::User} is not a +Chat+ event — {Agent#run_loop}
+      # constructs it directly and calls {#on_message}.
+      class MessageListener
+        # Wire the receiver into +chat+'s callback API. After this
+        # returns, +chat+'s loop will build {Message} variants from each
+        # event and forward them into {#on_message} on this instance.
+        #
+        # @param chat [RubyLLM::Chat]
+        # @return [void]
+        def attach(chat)
+          chat.after_message     { |msg| dispatch_chat_message(msg) }
+          chat.before_tool_call  { |tc|  on_message(Message::ToolCall.new(name: tc.name, arguments: tc.arguments)) }
+          chat.after_tool_result { |r|   on_message(Message::ToolResult.new(content: r)) }
+        end
+
+        # Single entry point for every event in the normalized stream.
+        # Concrete subclasses override this and dispatch on the variant
+        # (typically with a +case msg in Message::X(...)+ pattern). The
+        # default implementation is a no-op so listeners that only care
+        # about a subset can pattern-match and let everything else fall
+        # through.
+        #
+        # @param message [Message::User, Message::Thinking,
+        #   Message::Assistant, Message::ToolCall, Message::ToolResult,
+        #   Message::FallbackNotice]
+        # @return [void]
+        def on_message(message); end
+
+        # Hook for provider-reported token usage. Fires once per
+        # assistant turn (including pure tool-call turns with empty
+        # content) from {#dispatch_chat_message}. Default is a no-op so
+        # listeners that don't care — {Terminal}, {InMemoryMessageList} —
+        # ignore it; {TokenLog} overrides this to log and accumulate.
+        #
+        # @param tokens [Agent::Tokens]
+        # @return [void]
+        def on_tokens(tokens); end
+
+        private
+
+        # Normalizes a +RubyLLM::Chat+ +after_message+ payload into the
+        # appropriate {Message} variants for {#on_message}, plus an
+        # {Agent::Tokens} for {#on_tokens}.
+        #
+        # +msg+ is a +RubyLLM::Message+. Beyond +role+, +content+,
+        # +thinking+, and +tokens+ used here, it also carries
+        # +msg.tool_calls+ on assistant turns that requested one and
+        # +msg.raw+ for the unparsed provider payload.
+        #
+        # @param msg [RubyLLM::Message]
+        # @return [void]
+        def dispatch_chat_message(msg)
+          return unless msg.role == :assistant
+
+          text = msg.thinking&.text
+          on_message(Message::Thinking.new(content: text)) if text && !text.empty?
+
+          content = msg.content
+          on_message(Message::Assistant.new(content: content)) if content.is_a?(String) && !content.empty?
+
+          on_tokens(Agent::Tokens.new(
+                      input: msg.input_tokens,
+                      output: msg.output_tokens,
+                      cached: msg.cached_tokens,
+                      cache_creation: msg.cache_creation_tokens,
+                      thinking: msg.thinking_tokens,
+                      model_id: msg.model_id
+                    ))
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Agent
+    module Listener
+      # Standalone listener that caps the number of tool calls per
+      # +Agent#run_loop+ invocation. Not a +MessageListener+ — its job is
+      # control flow (raising on overrun), not surfacing events.
+      #
+      # ruby_llm has no built-in step budget, so this listener counts
+      # +before_tool_call+ events on the underlying +RubyLLM::Chat+ and
+      # raises {Exceeded} once the cap is crossed. +Agent#run_loop+
+      # forwards that out of +Chat#ask+; the step-exhaustion synthesizer
+      # rescues it to salvage the run.
+      class StepLimit
+        # Raised by the +before_tool_call+ callback once tool-call count
+        # exceeds +max+. Carries the budget that was tripped so rescue
+        # clauses can include it in user-facing messages.
+        class Exceeded < StandardError
+          # @return [Integer]
+          attr_reader :max_steps
+
+          # @param max_steps [Integer]
+          def initialize(max_steps)
+            @max_steps = max_steps
+            super("Agent loop exceeded #{max_steps} steps")
+          end
+        end
+
+        # @param max [Integer] hard cap on tool-call rounds; must be
+        #   positive
+        # @raise [ArgumentError] if +max+ is zero or negative
+        def initialize(max:)
+          raise ArgumentError, "max must be positive, got #{max}" if max <= 0
+
+          @max = max
+          @step = 0
+        end
+
+        # Wire the receiver into +chat+'s +before_tool_call+ callback. The
+        # callback increments the counter on every tool call and raises
+        # {Exceeded} once it crosses the configured cap.
+        #
+        # @param chat [RubyLLM::Chat]
+        # @return [void]
+        def attach(chat)
+          chat.before_tool_call do |_|
+            @step += 1
+            raise Exceeded, @max if @step > @max
+          end
+        end
+
+        # Listener protocol hook. Resets the step counter on
+        # {Agent::Message::User} — the User message marks the start of a
+        # new turn by definition, so it doubles as the lifecycle signal.
+        # Every other variant is a no-op.
+        #
+        # @param message [Agent::Message]
+        # @return [void]
+        def on_message(message)
+          case message
+          in Agent::Message::User
+            @step = 0
+          else
+            # no-op
+          end
+        end
+
+        # Sub-agent variant: a fresh +StepLimit+ at the caller-supplied
+        # +max_steps:+, or — when the key is absent from the forwarded
+        # params — at the receiver's own cap. The mutable counter and
+        # the +before_tool_call+ registration are per-chat, so the
+        # parent's instance cannot govern a sub-agent's chat; every
+        # sub-agent needs its own.
+        #
+        # The +max_steps+ default to +@max+ makes the method safe to
+        # call with no arguments, which keeps
+        # {Agent::ListenerList#for_sub_agent} usable as a bare
+        # +.for_sub_agent+ — a caller that doesn't care about the cap
+        # gets a sensible inheritance instead of an exception.
+        #
+        # @param max_steps [Integer] positive step cap for the sub-agent;
+        #   defaults to the receiver's current cap
+        # @return [StepLimit]
+        # @raise [ArgumentError] if +max_steps+ is non-positive
+        def for_sub_agent(max_steps: @max, **)
+          self.class.new(max: max_steps)
+        end
+
+        # @return [String] short config dump for {Agent#to_s}
+        def to_s
+          "StepLimit(max=#{@max})"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,137 @@
+# 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. {Message::User} is intentionally silent —
+      # the user typed it, so re-rendering it adds nothing on the CLI.
+      # This is the default listener attached by {Agent#initialize}.
+      #
+      # Optionally prepends a fixed number of leading spaces to every
+      # rendered line via the +padding:+ kwarg. Sub-agents get a fresh
+      # padded instance through this listener's {#for_sub_agent} hook
+      # (dispatched by {Agent::ListenerList#for_sub_agent}) so their
+      # output is visually indented under the parent's stream.
+      class Terminal < MessageListener
+        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}.
+        def initialize(padding: 0)
+          super()
+          @padding = padding
+        end
+
+        # @return [Integer] current padding width; exposed so callers can
+        #   introspect it (and so tests can assert it).
+        attr_reader :padding
+
+        # Sub-agent variant: a fresh +Terminal+ at {SUB_AGENT_PADDING} so
+        # sub-agent output is visually indented under the parent's
+        # stream. Called by {Agent::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)
+        end
+
+        # @param message [Agent::Message] one of the {Agent::Message}
+        #   variants; see {Agent::Message} for the full list
+        # @return [void]
+        def on_message(message)
+          case message
+          in Message::Thinking(content:)
+            puts indent(Rainbow(content).color(85, 85, 85))
+          in Message::Assistant(content:)
+            puts indent(render_markdown(content))
+          in Message::ToolCall(name:, arguments:)
+            args = arguments.map { |k, v| "#{k}=#{v.inspect}" }.join(', ')
+            puts indent(Rainbow("→ #{name}(#{args})").cyan)
+          in Message::ToolResult(content:)
+            puts indent(Rainbow("= #{truncate_tool_result(content)}").cyan)
+          in Message::FallbackNotice(reason:)
+            puts indent(Rainbow("! #{reason}").yellow)
+          in Message::User
+            # No-op: the user just typed this; echoing it back is noise.
+          end
+        end
+
+        # @return [String] short label for {Agent#to_s}; includes the
+        #   padding suffix only when non-zero so the default form stays
+        #   +"Terminal"+
+        def to_s
+          @padding.zero? ? 'Terminal' : "Terminal(padding=#{@padding})"
+        end
+
+        private
+
+        # 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,166 @@
+# 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')+. Overrides
+      # {MessageListener#on_tokens} and emits one +INFO+ line per turn.
+      #
+      # 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 keeps using the parent's
+      # instance because synth turns extend the same conversation.
+      #
+      # == Log line shape
+      #
+      # Without a cap (no detection source — see {Agent::ContextWindowDetector}):
+      #
+      #   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 (set by {Agent#initialize} after detection):
+      #
+      #   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 {Agent::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 < MessageListener
+        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
+        # {#on_tokens}. Zero until the first {#on_tokens} fires.
+        #
+        # @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} pushes the detected value here via
+        # {ListenerList#context_window_cap=} once it has run the detector,
+        # so an instance constructed bare (e.g. by callers, 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
+
+        # @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
+        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} pushes the resolved cap onto every
+        # +TokenLog+ in its list via {ListenerList#context_window_cap=}
+        # immediately after construction.
+        #
+        # @param name [String] sub-agent's identifier
+        # @return [TokenLog]
+        def for_sub_agent(name: '', **)
+          self.class.new(name: name)
+        end
+
+        # Update the context-window snapshot, then log one +INFO+ line.
+        #
+        # @param tokens [Agent::Tokens]
+        # @return [void]
+        def on_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
+
+          LOGGER.info(format_line(input_now, tokens.output.to_i, delta))
+        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
+
+        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

data/lib/pikuri/agent/listener_list.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Agent
+    # Listener-list value object that an {Agent} owns. Implements the same
+    # +attach(chat)+ / +on_message(msg)+ protocol as an individual
+    # listener — every call is fanned out to the underlying list — so the
+    # +Agent+ never sees a raw +Array+ and never has to express
+    # "for each listener, do X" inline.
+    #
+    # == Why a class, not an Array
+    #
+    # Two operations want one home rather than scattered helpers:
+    #
+    # 1. {#for_sub_agent} produces a derived list for a sub-agent run by
+    #    forwarding to each listener's own +for_sub_agent(**params)+
+    #    hook (default identity for listeners that don't define one).
+    #    The dispatch lives on the listener — +Terminal+ swaps in a
+    #    padded fresh instance, +TokenLog+ resets its snapshot,
+    #    +StepLimit+ picks +max_steps+ out of the params hash — so this
+    #    class doesn't grow a method per new listener type. The
+    #    synthesizer rescue uses the same hook with +max_steps: 1+,
+    #    since a step-exhausted synth is just another fresh-context run.
+    #
+    # 2. {#attach} / {#on_message} replace +each { |l| l.attach(chat) }+
+    #    and +each { |l| l.on_message(msg) }+ at the call sites, which
+    #    makes the seam ("a listener list is a thing the agent owns")
+    #    more visible.
+    class ListenerList
+      # @param listeners [Array] listeners that respond to the duck-typed
+      #   +attach(chat)+ / +on_message(msg)+ protocol
+      def initialize(listeners)
+        @listeners = listeners.dup
+      end
+
+      # Wire every listener into +chat+'s callback API. Forwarded verbatim
+      # to each listener's +#attach+ — see {Listener::MessageListener#attach}
+      # and {Listener::StepLimit#attach} for what each one registers.
+      #
+      # @param chat [RubyLLM::Chat]
+      # @return [void]
+      def attach(chat)
+        @listeners.each { |l| l.attach(chat) }
+      end
+
+      # Dispatch one message to every listener.
+      #
+      # @param message [Agent::Message]
+      # @return [void]
+      def on_message(message)
+        @listeners.each { |l| l.on_message(message) }
+      end
+
+      # Return a new {ListenerList} in which every listener has been
+      # asked for its sub-agent variant. Each listener that defines
+      # +for_sub_agent(**params)+ receives the forwarded +params+ and
+      # returns either +self+ or a replacement; listeners that don't
+      # define the method are kept by reference (output, structured
+      # capture, and anything else stateful flow continuously into the
+      # parent's instances).
+      #
+      # The dispatch lives on the listener so adding a new listener type
+      # with sub-agent-specific behavior doesn't change this class — see
+      # {Listener::Terminal#for_sub_agent} (fresh padded instance),
+      # {Listener::TokenLog#for_sub_agent} (fresh, zeroed snapshot), and
+      # {Listener::StepLimit#for_sub_agent} (fresh cap from +max_steps:+).
+      #
+      # +params+ is a flat hash forwarded as kwargs to every listener's
+      # hook; each listener picks the keys it cares about and ignores
+      # the rest (the +**+ catch-all in their signatures). Calling with
+      # no params is always valid — every listener's +for_sub_agent+
+      # treats its consumed keys as optional (e.g. +StepLimit+ falls
+      # back to its own cap when +max_steps:+ is absent).
+      #
+      # @param params [Hash{Symbol => Object}] kwargs forwarded to each
+      #   listener's +for_sub_agent+. Currently +max_steps:+ is the only
+      #   key any listener consumes.
+      # @return [ListenerList]
+      def for_sub_agent(**params)
+        swapped = @listeners.map do |l|
+          l.respond_to?(:for_sub_agent) ? l.for_sub_agent(**params) : l
+        end
+        self.class.new(swapped)
+      end
+
+      # Set the context-window cap on every {Listener::TokenLog} in the
+      # list. Called by {Agent#initialize} once
+      # {Agent::ContextWindowDetector} has resolved a value, so the
+      # +ctx=<used>/<cap>+ form lights up across all token loggers without
+      # the caller having to know which listeners they registered.
+      #
+      # Non-+TokenLog+ listeners are left alone — they have no cap to
+      # carry.
+      #
+      # @param cap [Integer, nil] cap to apply; +nil+ is allowed (and
+      #   keeps the existing +ctx=<used>+ form)
+      # @return [void]
+      def context_window_cap=(cap)
+        @listeners.each do |l|
+          l.context_window_cap = cap if l.is_a?(Listener::TokenLog)
+        end
+      end
+
+      # @example
+      #   list.to_s # => "[Terminal, StepLimit(max=20)]"
+      #
+      # @return [String]
+      def to_s
+        "[#{@listeners.map(&:to_s).join(', ')}]"
+      end
+    end
+  end
+end

data/lib/pikuri/agent/message.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Agent
+    # Sealed value-object hierarchy describing a single event in the
+    # +Agent+'s normalized stream. Listeners (Terminal renderer,
+    # in-memory recorder, future web sink) receive these through one
+    # +Listener::MessageListener#on_message+ entry point and dispatch on
+    # the variant's class.
+    #
+    # Each variant is a +Data.define+ with the minimal fields it needs;
+    # value equality and pattern-matching support come for free.
+    #
+    # == Where each variant comes from
+    #
+    # * {User} — synthesized by {Agent#run_loop} before forwarding the
+    #   turn to +Chat#ask+. Never appears in ruby_llm's listener stream.
+    # * {Thinking} / {Assistant} — extracted from a +Chat#after_message+
+    #   payload when the role is +:assistant+. Empty +thinking.text+ and
+    #   empty +content+ are filtered out at the dispatch site so
+    #   listeners never see vacuous events.
+    # * {ToolCall} — emitted on +Chat#before_tool_call+, carrying the
+    #   tool's name and the LLM-supplied argument hash.
+    # * {ToolResult} — emitted on +Chat#after_tool_result+, carrying the
+    #   observation string the tool produced.
+    #
+    # Provider-reported token usage is *not* a {Message} variant — it's
+    # metadata about an exchange, not an event in it. See {Agent::Tokens}
+    # and {Listener::MessageListener#on_tokens}.
+    module Message
+      # User's input for a turn, as passed to {Agent#run_loop}.
+      User = Data.define(:content)
+
+      # Assistant reasoning ("thinking") block, extracted from the
+      # +thinking.text+ field on a +RubyLLM::Message+ with role
+      # +:assistant+.
+      Thinking = Data.define(:content)
+
+      # Assistant Markdown content, extracted from a +RubyLLM::Message+
+      # with role +:assistant+.
+      Assistant = Data.define(:content)
+
+      # A tool invocation the LLM has requested but not yet observed.
+      # Arguments are the raw hash ruby_llm parsed from the model's
+      # +tool_calls+ JSON — no validation has run yet.
+      ToolCall = Data.define(:name, :arguments)
+
+      # The observation a tool produced, as returned by
+      # {Tool#run}. Recoverable failures arrive here as +"Error: ..."+
+      # strings (per the pikuri error convention), not as exceptions.
+      ToolResult = Data.define(:content)
+
+      # Out-of-band notice that the agent had to take a rescue path —
+      # currently emitted by {Agent#run_loop} when {Listener::StepLimit}
+      # trips and the synthesizer fallback runs. Lets listeners (Terminal,
+      # future web UI) surface the divergence to the user before the
+      # synthesizer's own assistant output flows through.
+      FallbackNotice = Data.define(:reason)
+    end
+  end
+end