pikuri-core 0.0.3

data/lib/pikuri/agent/control/interloper.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Agent
+    module Control
+      # Mid-loop user-input queue. A host (TUI, web client)
+      # constructs an +Interloper+, hands it to {Agent#initialize}
+      # via the +interloper:+ kwarg, and calls
+      # {#inject_user_message} from any thread while the agent
+      # is running. The +Agent+ drains the queue at the next
+      # +after_tool_result+ boundary — the only point inside
+      # ruby_llm's loop where the conversation state is
+      # consistent — and emits each item into the chat history
+      # plus the listener stream. The agent's next round-trip
+      # then sees the injected user message and reacts to it on
+      # its own.
+      #
+      # +Interloper+ is groundwork for downstream TUI/web hosts;
+      # the bundled +bin/pikuri-*+ entry-point scripts do *not*
+      # wire one up, since they keep stdin synchronous and have
+      # no way for a user to type while a turn is in flight.
+      # Downstream hosts that *do* run the agent on a worker
+      # thread can wire one in with no other changes to pikuri.
+      #
+      # == Delivery boundary and side effects
+      #
+      # When the +Agent+'s +after_tool_result+ wiring fires, it
+      # calls {#drain!} on the interloper (if any) and, for each
+      # returned item:
+      #
+      # 1. Appends a +role: :user+ message to the chat history so
+      #    the next +complete+ round-trip's request includes it.
+      # 2. Emits +Event::UserTurn(content:, mid_loop: true)+
+      #    through the listener stream so other listeners
+      #    (Terminal renderer, in-memory recorder, future logging)
+      #    see the injection as a normal +UserTurn+ event with the
+      #    +mid_loop:+ flag set.
+      #
+      # Controls do not respond to events; the +Agent+ pokes
+      # {Control::StepLimit#reset!} and {Control::Cancellable#reset!}
+      # only at the start of each turn — never on a mid-loop
+      # injection — so the "cancel-then-inject" hazard and the
+      # "refresh-budget-by-injecting" hazard cannot arise.
+      #
+      # == Boundary caveats
+      #
+      # The delivery point is +after_tool_result+, *not* the LLM
+      # HTTP call. Injections placed while the model is
+      # mid-response take effect on the *next* round-trip — by
+      # the time the queue drains, the model has already
+      # committed to whichever tool calls were in that response.
+      # The agent therefore typically observes an injection at
+      # the tool-batch boundary *after* the one during which the
+      # host called {#inject_user_message}. This is the same
+      # "gentle" semantic that {Control::Cancellable} promises
+      # and is the cleanest cross-provider point: no in-flight
+      # subprocess, no half-applied write, no half-built response.
+      #
+      # == Thread safety
+      #
+      # {#inject_user_message}, {#peek}, {#pending?}, and
+      # {#drain!} are safe to call from any thread; the internal
+      # queue is a +Mutex+-guarded +Array+. The +Agent+'s drain
+      # runs on the run thread (whatever thread invoked
+      # +Chat#ask+). +Mutex+ was chosen over +Thread::Queue+
+      # because +Thread::Queue+ exposes no snapshot read, and
+      # {#peek} is part of the surface (the host wants to render
+      # "feedback received, will deliver shortly" in its UI
+      # before the agent actually consumes the injection).
+      #
+      # == Sub-agent semantics
+      #
+      # {#for_sub_agent} returns +nil+. Sub-agents are private to
+      # the parent agent; the host has no handle to them, so a
+      # child +Interloper+ would be unreachable. The sub-agent's
+      # {Agent#initialize} simply receives +interloper: nil+ from
+      # {Tool::SubAgent}, which is its default. The behavior
+      # contrasts with {Control::Cancellable}, which shares its
+      # instance by reference so the parent's signal propagates
+      # to children — cancellation is a global "stop the whole
+      # tree" event, whereas injection is a directed "talk to the
+      # main agent" event.
+      class Interloper
+        def initialize
+          @mutex = Mutex.new
+          @items = []
+        end
+
+        # Push +content+ onto the delivery queue. Safe from any
+        # thread; the queue is +Mutex+-guarded.
+        #
+        # @param content [String] non-blank user-supplied text
+        # @raise [ArgumentError] if +content+ is +nil+, empty, or
+        #   whitespace-only — same rule as {Agent#run_loop}'s
+        #   +user_message:+ argument, since an empty injection
+        #   would poison the chat history just as a blank turn
+        #   would
+        # @return [void]
+        def inject_user_message(content)
+          raise ArgumentError, "content must not be blank, got #{content.inspect}" \
+            if content.nil? || content.to_s.strip.empty?
+
+          @mutex.synchronize { @items << content }
+          nil
+        end
+
+        # Non-destructive snapshot of the queue, in delivery
+        # order. Intended for hosts that want to render an
+        # "ongoing / pending" UI affordance ("3 messages waiting
+        # to deliver") in parallel with the agent's progress
+        # stream. Safe to call from any thread.
+        #
+        # @return [Array<String>] copy of the pending items;
+        #   never shares state with the internal buffer
+        def peek
+          @mutex.synchronize { @items.dup }
+        end
+
+        # @return [Boolean] whether the queue currently holds at
+        #   least one pending injection; observable from any
+        #   thread
+        def pending?
+          @mutex.synchronize { !@items.empty? }
+        end
+
+        # Atomically take and remove all pending items. Called by
+        # {Agent}'s +after_tool_result+ wiring; the +Agent+ then
+        # appends each item to the chat history and emits an
+        # {Event::UserTurn} with +mid_loop: true+ for each.
+        #
+        # Returns +[]+ when the queue is empty (the hot path —
+        # every +after_tool_result+ calls this).
+        #
+        # @return [Array<String>] items in delivery order; empty
+        #   when the queue is empty
+        def drain!
+          @mutex.synchronize do
+            next [] if @items.empty?
+
+            items = @items.dup
+            @items.clear
+            items
+          end
+        end
+
+        # Sub-agent variant: +nil+, signalling to {Agent} (and
+        # transitively to {Tool::SubAgent}) that no +Interloper+
+        # should be wired on a spawned sub-agent. See the class
+        # header for the "host has no handle to sub-agents"
+        # rationale.
+        #
+        # @return [nil]
+        def for_sub_agent(**)
+          nil
+        end
+
+        # @return [String] short label for {Agent#to_s}; reflects
+        #   the pending-count so a debug print or banner can tell
+        #   an idle interloper apart from one with queued items
+        def to_s
+          size = @mutex.synchronize { @items.size }
+          size.zero? ? 'Interloper' : "Interloper(#{size} pending)"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Agent
+    module Control
+      # Caps the number of tool calls per {Agent#run_loop}
+      # invocation. ruby_llm has no built-in step budget; the
+      # +Agent+ pokes {#tick!} on every +before_tool_call+
+      # callback and {#reset!} at the start of each turn. Once the
+      # counter exceeds the configured cap, {#tick!} raises
+      # {Exceeded}, the +Agent+ catches it, and the step-
+      # exhaustion synthesizer rescues to salvage a partial
+      # answer.
+      class StepLimit
+        # Raised by {#tick!} 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
+
+        # @return [Integer] the configured cap
+        attr_reader :max
+
+        # @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
+
+        # Increment the tool-call counter; raise {Exceeded} once
+        # it crosses {#max}. Called by {Agent} from its
+        # +before_tool_call+ wiring.
+        #
+        # @return [void]
+        # @raise [Exceeded] when the counter has now exceeded
+        #   {#max}
+        def tick!
+          @step += 1
+          raise Exceeded, @max if @step > @max
+        end
+
+        # Reset the counter back to zero. Called by {Agent} at the
+        # start of each turn (in {Agent#run_loop} before forwarding
+        # the user message to the chat) so the same instance can
+        # govern many turns across a long-running REPL. Mid-loop
+        # {Control::Interloper} injections deliberately do *not*
+        # trigger a reset — those are additional context for the
+        # same turn, not a fresh one, and a chatty user could
+        # otherwise refresh the budget forever by injecting.
+        #
+        # @return [void]
+        def reset!
+          @step = 0
+        end
+
+        # @return [Integer] current step count; exposed so callers
+        #   can introspect it (and so tests can assert it)
+        attr_reader :step
+
+        # Sub-agent variant: a fresh +StepLimit+ at the
+        # caller-supplied +max_steps:+, or — when the key is
+        # absent — at the receiver's own cap. The mutable counter
+        # is per-chat, so the parent's instance cannot govern a
+        # sub-agent's chat; every sub-agent needs its own.
+        #
+        # @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/control.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Agent
+    # Namespace for the +Agent+'s host-facing controls:
+    # {StepLimit}, {Cancellable}, and {Interloper}. Each is a small
+    # value-holder that the +Agent+ reads from (or pokes into the
+    # event stream from) at well-defined points in ruby_llm's
+    # chat-callback cycle. They are *not* listeners — they receive
+    # no events and never appear in a {ListenerList}.
+    #
+    # == Why they're separated
+    #
+    # Listeners are pure consumers of the event stream; controls
+    # are host-facing signal holders that the +Agent+ reads from.
+    # The +Agent+ is the only entity that emits events, the only
+    # entity that ticks the step counter, the only entity that
+    # checks the cancellation flag, and the only entity that drains
+    # the interloper queue. "What fires when" is a single grep for
+    # +@listeners.emit+ in +agent.rb+.
+    #
+    # == What each control does
+    #
+    # * {StepLimit} — caps the number of tool calls per
+    #   {Agent#run_loop}. The +Agent+ calls {StepLimit#tick!} on
+    #   every +before_tool_call+ (raising {StepLimit::Exceeded}
+    #   when over budget) and {StepLimit#reset!} at the start of
+    #   each turn. Sub-agents get their own counter.
+    # * {Cancellable} — cooperative cancellation flag. The host
+    #   calls {Cancellable#cancel!} from any thread; the +Agent+
+    #   calls {Cancellable#check!} at +before_tool_call+ (raising
+    #   {Cancellable::Cancelled} when the flag is set) and
+    #   {Cancellable#reset!} at the start of each turn. The same
+    #   instance is shared by reference across the parent, every
+    #   sub-agent, and the synthesizer rescue.
+    # * {Interloper} — mid-loop user-input queue. The host calls
+    #   {Interloper#inject_user_message} from any thread; the
+    #   +Agent+ drains the queue at +after_tool_result+,
+    #   appending each item as a user-role message and emitting
+    #   {Event::UserTurn} with +mid_loop: true+. Not propagated to
+    #   sub-agents (the host has no handle to them).
+    module Control
+    end
+  end
+end

data/lib/pikuri/agent/event.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Agent
+    # Sealed value-object hierarchy describing a single event in the
+    # +Agent+'s normalized stream. Every listener consumes these through
+    # one {Listener::Base#on_event} entry point and pattern-matches on
+    # the variant.
+    #
+    # Each variant is a +Data.define+ with the minimal fields it needs;
+    # value equality and pattern-matching support come for free.
+    #
+    # == One stream, no side channels
+    #
+    # Provider-reported token usage rides as {Tokens}; the detected
+    # context-window cap rides as a one-shot {ContextCap} emitted by
+    # {Agent#initialize}; everything else maps to a turn-or-tool-call
+    # variant. Listeners override a single +on_event+ method and
+    # +case+-match on the variant they care about. The per-variant
+    # docs below name the emission site for each (which {Agent}
+    # callback wires it and what payload it carries).
+    module Event
+      # User's input for a turn (+mid_loop: false+, the default) or a
+      # host-supplied injection delivered while the loop is running
+      # (+mid_loop: true+, drained from {Control::Interloper}). The
+      # flag exists so listeners that treat the +UserTurn+ as a turn
+      # boundary can distinguish a fresh turn from an in-loop
+      # injection (additional context for the same turn, not a new
+      # one). Controls themselves no longer see this event — the
+      # +Agent+ pokes their +reset!+ / +tick!+ entry points directly
+      # at the right boundaries.
+      #
+      # Emitted in two places: by {Agent#run_loop} at the start of
+      # each turn (with +mid_loop: false+), and by {Agent}'s
+      # +after_tool_result+ wiring when a queued
+      # {Control::Interloper} item drains into the chat history
+      # (with +mid_loop: true+).
+      UserTurn = Data.define(:content, :mid_loop) do
+        # @param content [String] user-supplied text
+        # @param mid_loop [Boolean] +false+ for a turn-starting message
+        #   (the default); +true+ when drained from
+        #   {Control::Interloper}
+        def initialize(content:, mid_loop: false)
+          super
+        end
+      end
+
+      # Assistant reasoning ("thinking") block, extracted from the
+      # +thinking.text+ field on a +RubyLLM::Message+ with role
+      # +:assistant+. Emitted by {Agent}'s +after_message+ wiring;
+      # empty +thinking.text+ is filtered at the dispatch site so
+      # listeners never see vacuous events.
+      Thinking = Data.define(:content)
+
+      # Assistant Markdown content, extracted from a +RubyLLM::Message+
+      # with role +:assistant+. Emitted by {Agent}'s +after_message+
+      # wiring; empty +content+ is filtered at the dispatch site
+      # (pure tool-call turns surface {Tokens} only, no +Assistant+).
+      Assistant = Data.define(:content)
+
+      # Streaming fragment of an assistant reasoning block, pulled
+      # off a +RubyLLM::Chunk+ during a +Chat#ask+ stream. Emitted
+      # by the per-chunk streaming block {Agent.streaming_block}
+      # builds and {Agent#run_loop} / {Synthesizer.run} pass to
+      # +ask+; empty fragments are filtered at the dispatch site.
+      #
+      # Preview-only, not authoritative: the {Thinking} event
+      # emitted from +after_message+ at the end of the round-trip
+      # is the final reasoning text. Providers may normalize
+      # whitespace, and Anthropic thinking blocks include a
+      # signature that never appears in deltas, so
+      # +concat(deltas) == final.content+ is not guaranteed.
+      #
+      # == Ordering
+      #
+      # Per round-trip: all {ThinkingDelta}s (and {AssistantDelta}s)
+      # for a round arrive before that round's {Thinking} /
+      # {Assistant} / {Tokens} bookend, because the streaming block
+      # fires synchronously inside +Chat#ask+'s SSE read and
+      # +after_message+ fires once the message is complete. Within
+      # the delta stream itself, ordering between {ThinkingDelta}
+      # and {AssistantDelta} is provider-dependent (in practice
+      # non-interleaved on Anthropic and OpenAI reasoning models,
+      # but pikuri does not enforce it).
+      ThinkingDelta = Data.define(:content)
+
+      # Streaming fragment of an assistant Markdown content block,
+      # pulled off a +RubyLLM::Chunk+ during a +Chat#ask+ stream.
+      # Emitted by the per-chunk streaming block
+      # {Agent.streaming_block} builds and {Agent#run_loop} /
+      # {Synthesizer.run} pass to +ask+; empty fragments are
+      # filtered at the dispatch site.
+      #
+      # Preview-only, same semantics as {ThinkingDelta}: the
+      # {Assistant} event emitted from +after_message+ at the end
+      # of the round-trip is the authoritative final text;
+      # listeners that need an exact concat of fragments should
+      # consume {Assistant} instead. Per-round-trip ordering is
+      # guaranteed; per-modality ordering within the delta stream
+      # is best-effort.
+      AssistantDelta = 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. Emitted by
+      # {Agent}'s +before_tool_call+ wiring.
+      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.
+      # Emitted by {Agent}'s +after_tool_result+ wiring.
+      ToolResult = Data.define(:content)
+
+      # Provider-reported token usage for a single assistant turn,
+      # copied off a +RubyLLM::Message+'s +tokens+ block. Emitted by
+      # {Agent}'s +after_message+ wiring on every assistant turn,
+      # including pure tool-call turns where {Assistant} would have
+      # been filtered for empty content (those are exactly the turns
+      # where context-window growth matters most).
+      #
+      # All counts are +Integer, nil+. +nil+ means the provider did not
+      # report that field — common with local llama.cpp / Ollama
+      # servers that leave parts of the OpenAI +usage+ block empty.
+      # Listeners treat +nil+ as zero.
+      #
+      # The fields +input+, +cached+, and +cache_creation+ are
+      # **exclusive portions of this turn's full prompt** under the
+      # shape ruby_llm exposes for llama.cpp and Anthropic: they sum
+      # to the total prompt size processed on this request. OpenAI
+      # proper nests +cached_tokens+ inside its +prompt_tokens+
+      # instead — if pikuri ever talks there directly, the sum formula
+      # needs revisiting.
+      #
+      # - +input+ — newly-processed (uncached) prompt tokens this turn.
+      # - +output+ — tokens in this single assistant reply.
+      # - +cached+ — portion of this turn's prompt served from the
+      #   provider's prompt cache. Still counts against the context
+      #   window (caching is a speed/cost optimization, not a context-
+      #   savings mechanism).
+      # - +cache_creation+ — portion of this turn's prompt written
+      #   into the prompt cache. Anthropic-specific; usually +nil+ on
+      #   OpenAI-compatible local servers.
+      # - +thinking+ — extended-thinking (Anthropic) or reasoning
+      #   (OpenAI o-series) tokens produced on this turn. +nil+ on
+      #   providers without a reasoning channel.
+      # - +model_id+ — provider-side model name as reported on the
+      #   response; useful when a process targets multiple models.
+      #
+      # == Computing "current context window size"
+      #
+      # +input + cached + cache_creation+ is the size of the prompt
+      # processed on this turn. Add +output+ to get 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. That's what climbs toward
+      # +RubyLLM::ContextLengthExceededError+ and is the snapshot
+      # {Listener::TokenLog#context_window_size} tracks.
+      Tokens = Data.define(:input, :output, :cached, :cache_creation, :thinking, :model_id)
+
+      # Model's resolved context-window cap. Emitted once by
+      # {Agent#initialize} immediately after
+      # {Agent::ContextWindowDetector} runs. Carries +nil+ when no
+      # source produced a value (custom local model with no override
+      # and no reachable llama.cpp +/props+). Listeners that care —
+      # {Listener::TokenLog} renders +ctx=<used>/<cap>+ when set,
+      # +ctx=<used>+ when +nil+ — pick the value off this event and
+      # cache it; non-caring listeners ignore.
+      ContextCap = Data.define(:cap)
+
+      # Out-of-band notice that the agent had to take a rescue path.
+      # Emitted by {Agent#run_loop} when {Control::StepLimit} trips
+      # and the synthesizer fallback runs; carries the reason string
+      # the listener should surface. 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)
+
+      # Out-of-band notice that the user cancelled the in-flight turn
+      # via {Control::Cancellable}. Emitted by {Agent#run_loop} just
+      # before the +Cancellable::Cancelled+ exception re-raises out of
+      # the loop, so listeners (Terminal renderer, structured
+      # recorders) can mark the turn as user-aborted. Unlike
+      # {FallbackNotice}, no recovery follows — the exception is
+      # re-raised and the caller is expected to return control to the
+      # user (typically the REPL prompt).
+      Cancelled = Data.define
+    end
+  end
+end

data/lib/pikuri/agent/extension.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Agent
+    # The Extension protocol — how hosts bolt extra capabilities
+    # (system-prompt snippets, tools, lifecycle hooks) onto an
+    # {Agent}. Extensions are added via {Configurator#add_extension}
+    # inside the +Agent.new+ block; the Agent then drives two hooks
+    # on each — {#configure} during the block, {#bind} once the
+    # agent is fully constructed.
+    #
+    # Mix this module into an extension class to inherit empty
+    # default implementations of both hooks; override the ones you
+    # need. Extensions that don't +include+ this module still work
+    # if they define both methods themselves (the Agent and
+    # Configurator call them by name) — the module exists to make
+    # the protocol *explicit* and to give "I want to implement just
+    # +configure+" extensions a free no-op +bind+ (and vice versa).
+    #
+    # == Example
+    #
+    #   class MyExtension
+    #     include Pikuri::Agent::Extension
+    #
+    #     def configure(c)
+    #       c.append_system_prompt("Always be polite.")
+    #     end
+    #
+    #     # bind not overridden — inherits the empty default
+    #   end
+    #
+    # See +Pikuri::Mcp::Extension+ and +Pikuri::Skill::Extension+
+    # (once those land in Steps 2-3 of the gem-split refactor — see
+    # IDEAS.md §"Extension protocol design") for the canonical
+    # worked implementations.
+    module Extension
+      # Called immediately by {Configurator#add_extension} during the
+      # +Agent.new+ block, with the parent agent's {Configurator}.
+      # Runs exactly once per extension instance, on the parent agent
+      # only — sub-agents do not re-run +configure+. The default is a
+      # no-op; override when you need to install *agent-agnostic*
+      # state. Things you typically do here:
+      #
+      # * append snippets to the system prompt via
+      #   {Configurator#append_system_prompt}
+      # * register tools via {Configurator#add_tool}
+      # * register listeners via {Configurator#add_listener}
+      # * register parent-only +on_close+ handlers via
+      #   {Configurator#on_close} (for cleanup of resources the
+      #   extension created in +configure+)
+      # * read the agent's transport / cancellable / etc. via the
+      #   Configurator's +attr_reader+s
+      #
+      # @param c [Configurator] the parent agent's Configurator
+      # @return [void]
+      def configure(c); end
+
+      # Called by {Agent#initialize} after the block returns and the
+      # chat is fully wired, with the live {Agent} as the argument.
+      # Runs once per agent — on the parent during its construction,
+      # and once more on each sub-agent during the sub-agent's
+      # construction (same extension instance, multiple +bind+ calls
+      # — per-agent state lives in +bind+'s closures, not in
+      # extension instance state). The default is a no-op; override
+      # when you need to install *per-agent* state. Things you
+      # typically do here:
+      #
+      # * register per-agent dynamic tools via
+      #   {Agent#internal_add_tool}
+      # * register per-agent +on_close+ handlers via
+      #   {Agent#on_close}
+      # * stash an +@agent+ reference if the extension's tools need
+      #   to act on this specific agent later (e.g. when a tool
+      #   fires and wants to register more tools on its owning
+      #   chat)
+      #
+      # @param agent [Agent] the live agent, fully wired
+      # @return [void]
+      def bind(agent); end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Pikuri
+  class Agent
+    module Listener
+      # Recording listener that appends every {Event} the agent
+      # emits to an in-memory list. Used by specs to assert on
+      # emissions without parsing stdout, and as the rough shape a
+      # future structured consumer (web sink, telemetry pipe) would
+      # take.
+      class InMemoryEventList < Base
+        # @return [Array<Agent::Event>] every event the listener
+        #   has seen, in order; never nil
+        attr_reader :events
+
+        def initialize
+          super
+          @events = []
+        end
+
+        # @param event [Agent::Event]
+        # @return [void]
+        def on_event(event)
+          @events << event
+        end
+
+        # @return [String] short label for {Agent#to_s}
+        def to_s
+          'InMemoryEventList'
+        end
+      end
+    end
+  end
+end