pikuri 0.0.1 → 0.0.4

data/lib/pikuri/agent/listener_list.rb

@@ -1,113 +0,0 @@
-# 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

@@ -1,61 +0,0 @@
-# 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

data/lib/pikuri/agent/synthesizer.rb

@@ -1,120 +0,0 @@
-# frozen_string_literal: true
-
-module Pikuri
-  class Agent
-    # Step-exhaustion rescue. When an +Agent+'s {Listener::StepLimit}
-    # trips, +Agent#run_loop+ catches the +Exceeded+ exception and hands
-    # off to {Synthesizer.run} so the run still produces something useful
-    # — a tools-free assistant turn that answers the user's question
-    # from whatever evidence the failed agent collected before running
-    # out of budget.
-    #
-    # == Why this exists
-    #
-    # Without a rescue, a step-exhausted run just raises a stack trace
-    # past +bin/pikuri-chat+ and the user gets nothing despite the agent
-    # having gathered useful information in the first N-1 steps. The
-    # observed failure mode is the "wait, but what about X?" death-loop:
-    # the agent collects sound evidence in the first few rounds, then
-    # spends the rest of the budget second-guessing. By the time the cap
-    # trips, the answer is largely in the messages — it just needs a
-    # tools-free pass to synthesize.
-    #
-    # == Seam discipline
-    #
-    # {Synthesizer.run} does not reference +RubyLLM::*+. +Agent+
-    # constructs the synth chat itself (the one +RubyLLM.chat+ call lives
-    # in +lib/agent.rb+, same as the parent chat) and passes it in.
-    # +Synthesizer+ only calls instance methods on whatever +chat+ it
-    # receives — +#with_instructions+ and +#ask+ — so the seam stays at
-    # three files.
-    module Synthesizer
-      # The synthesizer's system prompt. Strict and short: use the
-      # evidence, don't apologize, admit gaps when present.
-      SYSTEM_PROMPT = <<~PROMPT
-        You are given evidence another agent collected before running out of steps. Answer the user's question using only this evidence. You have no tools. If the evidence is insufficient, state plainly what's missing and what partial answer you can give. Do not apologize or comment on the previous agent.
-      PROMPT
-
-      # Configure +chat+ for synthesis, run one turn against it, and
-      # return the final assistant content. Listeners are attached so
-      # the synth's reasoning and answer flow through the same surface
-      # the parent agent uses — terminal renders them inline, an
-      # in-memory recorder picks them up, and a future web sink sees
-      # them as normal +Message+ variants.
-      #
-      # @param chat [RubyLLM::Chat] a *fresh* chat with no tools. The
-      #   caller is responsible for constructing it with the same
-      #   model/provider configuration the parent used.
-      # @param parent_messages [Array<RubyLLM::Message>] the parent
-      #   chat's full message history at the moment of step exhaustion.
-      #   Used to build the evidence transcript.
-      # @param user_message [String] the user's original question from
-      #   the parent turn that exhausted.
-      # @param listeners [Agent::ListenerList] listeners to attach to
-      #   the synth chat. Typically the parent agent's list run through
-      #   {ListenerList#for_sub_agent} with +max_steps: 1+ — same
-      #   transformation a sub-agent invocation gets, since the synth
-      #   runs on a fresh +RubyLLM::Chat+: +TokenLog+ zeroed, +Terminal+
-      #   padded, +StepLimit+ at the defensive cap (the synth has no
-      #   tools so it should never trip), shared listeners (e.g.
-      #   +InMemoryMessageList+) kept by reference.
-      # @return [String, nil] the synth's final assistant content, or
-      #   +nil+ if the synth somehow produced no assistant message
-      def self.run(chat:, parent_messages:, user_message:, listeners:)
-        chat.with_instructions(SYSTEM_PROMPT)
-        listeners.attach(chat)
-        chat.ask(build_prompt(parent_messages: parent_messages, user_message: user_message))
-        chat.messages.reverse.find { |m| m.role == :assistant }&.content
-      end
-
-      # Render the user's question plus an "Evidence gathered" section
-      # built from +parent_messages+ as a single prompt string. Pure
-      # function — no I/O, safe to test directly with fixture messages.
-      #
-      # @param parent_messages [Array<RubyLLM::Message>]
-      # @param user_message [String]
-      # @return [String]
-      def self.build_prompt(parent_messages:, user_message:)
-        transcript = format_evidence(parent_messages)
-        "Question: #{user_message}\n\nEvidence gathered:\n#{transcript}"
-      end
-
-      # Walk the parent's message history and produce a paired
-      # "Tool call:" / "Tool result:" log, preserving order. Tool calls
-      # that have no matching +:tool+ message are dropped — the call
-      # that tripped the step limit never executed, so including it
-      # would mislead the synth into citing nonexistent results.
-      # Non-empty assistant text content is preserved as a "Note:" line,
-      # since the parent may have summarized progress between tool
-      # calls.
-      #
-      # @param messages [Array<RubyLLM::Message>]
-      # @return [String]
-      def self.format_evidence(messages)
-        results_by_id = messages
-                        .select { |m| m.role == :tool }
-                        .to_h { |m| [m.tool_call_id, m.content] }
-
-        lines = []
-        messages.each do |msg|
-          next unless msg.role == :assistant
-
-          text = msg.content
-          lines << "Note: #{text}" if text.is_a?(String) && !text.empty?
-
-          msg.tool_calls&.each_value do |tc|
-            result = results_by_id[tc.id]
-            next unless result
-
-            args = tc.arguments.map { |k, v| "#{k}=#{v.inspect}" }.join(', ')
-            lines << "Tool call: #{tc.name}(#{args})"
-            lines << "Tool result: #{result}"
-            lines << ''
-          end
-        end
-        lines.join("\n").rstrip
-      end
-      private_class_method :format_evidence
-    end
-  end
-end

data/lib/pikuri/agent/tokens.rb

@@ -1,56 +0,0 @@
-# frozen_string_literal: true
-
-module Pikuri
-  class Agent
-    # Provider-reported token usage for a single assistant turn, copied
-    # off a +RubyLLM::Message+'s +tokens+ block. Delivered to listeners
-    # through {Listener::MessageListener#on_tokens} rather than the
-    # {Message} stream — it's metadata about an exchange, not an event
-    # in it.
-    #
-    # Emitted by {Listener::MessageListener#dispatch_chat_message} on
-    # every assistant +after_message+ event, including pure tool-call
-    # turns where {Message::Assistant} would have been filtered out 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 (without the +output+ term, a long reply stays invisible
-    # in the headline until the next turn pulls it in as cached prompt).
-    Tokens = Data.define(:input, :output, :cached, :cache_creation, :thinking, :model_id)
-  end
-end

data/lib/pikuri/agent.rb

@@ -1,286 +0,0 @@
-# frozen_string_literal: true
-
-require 'ruby_llm'
-
-module Pikuri
-  # Thin wrapper around +RubyLLM::Chat+: pikuri owns the *extension surface*
-  # (the listener objects that consume normalized chat events) while
-  # ruby_llm owns the loop itself. The Thought / Tool-call / Observation
-  # iteration lives in +Chat#complete+; pikuri's job is just attaching
-  # listeners at construction time, forwarding the user turn, and
-  # notifying the listeners of the new {Message::User} so any that care
-  # about turn boundaries (notably {Listener::StepLimit}) can react.
-  #
-  # Listeners live in a {ListenerList} the caller supplies — duck-typed
-  # against a tiny +attach(chat)+ / +on_message(msg)+ protocol, with the
-  # list itself implementing the same protocol so +Agent+ never touches
-  # the underlying +Array+. There are no defaults for +tools:+ or
-  # +listeners:+ on {#initialize}: both are conscious decisions the
-  # caller must state every time.
-  #
-  # == Step-exhaustion rescue
-  #
-  # If a {Listener::StepLimit} in {#listeners} trips during +Chat#ask+,
-  # {#run_loop} catches the +Exceeded+ exception, emits a
-  # {Message::FallbackNotice} to every listener, and hands off to
-  # {Synthesizer.run} on a fresh +RubyLLM::Chat+. The synth reuses the
-  # parent's {ListenerList} via {ListenerList#for_sub_agent} with
-  # +max_steps: 1+ — same transformation a sub-agent invocation gets,
-  # since the synth is a fresh context: +TokenLog+ zeroed, +Terminal+
-  # padded, +StepLimit+ at the defensive cap (the synth has no tools so
-  # it should never trip), +InMemoryMessageList+ shared by reference. The
-  # listener +name:+ becomes +"<@name>_synthesizer"+ (or just
-  # +"synthesizer"+ for the main agent) so the synth turn is distinct
-  # from the parent's normal turns in any name-aware log line. The
-  # synth's answer becomes the value reported by
-  # {#last_assistant_content}, so callers (notably {Tool::SubAgent})
-  # still get a usable reply instead of raising past +bin/pikuri-chat+.
-  class Agent
-    # @param transport [ChatTransport] the model-resolution triple
-    #   (+model+ / +provider+ / +assume_model_exists+) forwarded to
-    #   +RubyLLM.chat+. Bundled into one value object so every
-    #   construction site — this constructor and the synthesizer rescue
-    #   below — can forward all three with one assignment instead of
-    #   three kwargs (where dropping one would silently route the chat
-    #   elsewhere or raise +RubyLLM::ModelNotFoundError+). If
-    #   +transport.model+ is +nil+, it's filled in from
-    #   +RubyLLM.config.default_model+.
-    # @param system_prompt [String] system message prepended to the chat
-    # @param tools [Array<Tool>] pikuri tools registered with the
-    #   underlying chat in declaration order. Each is converted to
-    #   ruby_llm's runtime shape via {Tool#to_ruby_llm_tool} when wired
-    #   in. Required — no default, because the tool set is a deliberate
-    #   per-call decision (pass +[]+ for a tools-free agent).
-    # @param listeners [ListenerList] the listener list whose +attach+
-    #   the constructor calls on the underlying chat. Required — no
-    #   default, because the renderer and step-budget choices are
-    #   deliberate per-call decisions. Typical CLI shape:
-    #   +ListenerList.new([Listener::Terminal.new, Listener::StepLimit.new(max: 20)])+.
-    # @param context_window [Integer, nil] explicit override for the
-    #   model's context-window cap. When set, it wins over ruby_llm's
-    #   reported value and the llama.cpp probe — see
-    #   {ContextWindowDetector} for precedence. Resolved cap is pushed to
-    #   every {Listener::TokenLog} so the +ctx=<used>/<cap>+ headline
-    #   lights up.
-    # @param llama_probe_url [String, nil] llama.cpp +/props+ URL used as
-    #   the third detection source. Only consulted when neither
-    #   +context_window+ nor ruby_llm's reported value is set. Typically
-    #   derived by +bin/pikuri-chat+ from its configured +openai_api_base+;
-    #   leave +nil+ when the configured server is anything other than
-    #   llama.cpp.
-    # @param name [String] identifier for this agent. Empty for the main
-    #   agent; sub-agents get monotonic hierarchical names like
-    #   +"sub_agent 0"+, +"sub_agent 1"+, +"sub_agent 0_0"+, ... generated
-    #   by {Tool::SubAgent} from the parent's name + a per-parent counter.
-    #   Forwarded to listeners through {ListenerList#for_sub_agent} so
-    #   name-aware ones (notably {Listener::TokenLog}) can tag their output.
-    # @param skill_catalog [Tool::SkillCatalog] catalog of on-disk skills
-    #   the agent may load on demand. Defaults to
-    #   +Tool::SkillCatalog::EMPTY+, which is a no-op singleton. When
-    #   non-empty: the catalog's prompt block ({Tool::SkillCatalog#format_for_prompt})
-    #   is appended to +system_prompt+ so the LLM can see what's available,
-    #   and a {Tool::Skill} bound to the catalog is appended to +tools+
-    #   so the LLM can actually load them. The two changes are coupled —
-    #   advertising skills without a loader (or vice versa) would be a
-    #   bug, so the catalog is the single source of truth for both.
-    # @return [Agent]
-    def initialize(transport:, system_prompt:, tools:, listeners:,
-                   context_window: nil, llama_probe_url: nil, name: '',
-                   skill_catalog: Tool::SkillCatalog::EMPTY)
-      @transport = transport.model ? transport : transport.with(model: RubyLLM.config.default_model)
-      @system_prompt = skill_catalog.empty? ? system_prompt : system_prompt + skill_catalog.format_for_prompt
-      @skill_catalog = skill_catalog
-      @tools = tools.dup
-      @listeners = listeners
-      @name = name
-      @synth_answer = nil
-
-      unless skill_catalog.empty?
-        raise 'Tool::Skill cannot be passed in tools: when skill_catalog is non-empty; ' \
-              'Agent auto-registers it from the catalog.' \
-          if @tools.any?(Tool::Skill)
-
-        @tools << Tool::Skill.new(catalog: skill_catalog)
-      end
-
-      @chat = RubyLLM.chat(**@transport.to_h)
-      @chat.with_instructions(@system_prompt)
-      @tools.each { |t| @chat.with_tool(t.to_ruby_llm_tool) }
-
-      @context_window_cap = ContextWindowDetector.new(
-        override: context_window,
-        ruby_llm_reported: @chat.model.context_window,
-        llama_probe_url: llama_probe_url
-      ).detect
-      @listeners.context_window_cap = @context_window_cap
-      @listeners.attach(@chat)
-    end
-
-    # @return [RubyLLM::Chat] underlying chat; the extension seam
-    attr_reader :chat
-
-    # @return [ChatTransport] the resolved transport bundle this agent
-    #   was constructed with — same model id / provider /
-    #   assume-model-exists flag passed to every +RubyLLM.chat+ call
-    #   originating from this agent (the main chat, the synthesizer
-    #   rescue, the sub-agent tool). Read by {Tool::SubAgent} so
-    #   spawned sub-agents reuse the same transport.
-    attr_reader :transport
-
-    # @return [Array<Tool>] this agent's tool list in declaration order.
-    #   Snapshotted by {Tool::SubAgent} so spawned sub-agents inherit
-    #   the parent's tools (minus the sub-agent tool itself, which
-    #   {#allow_sub_agent} appends to +@tools+ only after the snapshot
-    #   has been taken — recursion guard).
-    attr_reader :tools
-
-    # @return [String] resolved model id from {#transport}. Convenience
-    #   delegator for callers that don't need the full transport bundle.
-    def model
-      @transport.model
-    end
-
-    # @return [String] system prompt actually sent to the chat — equal to
-    #   the constructor's +system_prompt:+ argument plus, when a non-
-    #   empty +skill_catalog:+ was supplied, the catalog's
-    #   +<available_skills>+ block. {Tool::SubAgent} forwards this
-    #   already-augmented value to spawned sub-agents, so they see the
-    #   same catalog without needing the +skill_catalog:+ kwarg themselves.
-    attr_reader :system_prompt
-
-    # @return [Tool::SkillCatalog] catalog passed to the constructor;
-    #   +Tool::SkillCatalog::EMPTY+ if none was supplied. Read by callers
-    #   that want to inspect the loaded skills (e.g. for a startup banner).
-    attr_reader :skill_catalog
-
-    # @return [ListenerList] the listener list attached to this agent's
-    #   chat
-    attr_reader :listeners
-
-    # @return [String] this agent's identifier — empty for the main agent;
-    #   for sub-agents, the hierarchical id assigned by
-    #   {Tool::SubAgent} (e.g. +"sub_agent 0"+, +"sub_agent 1"+,
-    #   +"sub_agent 0_0"+). Read by the sub-agent tool so spawned
-    #   sub-agents prefix their own names with this one, and propagated
-    #   to listeners via {ListenerList#for_sub_agent} so name-aware ones
-    #   can tag output.
-    attr_reader :name
-
-    # @return [Integer, nil] context-window cap resolved by
-    #   {ContextWindowDetector} at construction time. +nil+ when no
-    #   source produced a value (custom local model with no override and
-    #   no reachable llama.cpp +/props+). Read by {Tool::SubAgent} so
-    #   spawned sub-agents inherit the same cap without re-probing.
-    attr_reader :context_window_cap
-
-    # Final assistant message content for the most recent {#run_loop}.
-    # When the synthesizer rescue fired, returns its answer; otherwise
-    # walks the underlying chat's history. Returns +nil+ if neither
-    # source has produced an assistant turn yet.
-    #
-    # @return [String, nil]
-    def last_assistant_content
-      return @synth_answer if @synth_answer
-
-      last = @chat.messages.reverse.find { |m| m.role == :assistant }
-      last&.content
-    end
-
-    # Run the agent loop for a single user turn. Notifies every listener of
-    # the {Message::User} — which is also how {Listener::StepLimit}
-    # learns to reset its counter — and forwards +user_message+ to
-    # {#chat} via +ask+. Returns nil; rendering and any other observable
-    # output is the listeners' responsibility.
-    #
-    # If a {Listener::StepLimit} trips during +ask+, the rescue branch
-    # emits a {Message::FallbackNotice} and runs {Synthesizer.run} on a
-    # fresh +RubyLLM::Chat+. The synth's answer is captured for
-    # {#last_assistant_content}; the exception does not bubble out.
-    #
-    # Subsequent calls keep building on the same chat history, so the
-    # model sees full multi-turn context.
-    #
-    # @param user_message [String] the user's request for this turn; must
-    #   not be +nil+, empty, or whitespace-only
-    # @raise [ArgumentError] if +user_message+ is +nil+, empty, or
-    #   contains only whitespace — an empty turn would poison the chat
-    #   history and burn a step budget on nothing
-    # @return [nil]
-    def run_loop(user_message:)
-      raise ArgumentError, "user_message must not be blank, got #{user_message.inspect}" \
-        if user_message.nil? || user_message.to_s.strip.empty?
-
-      @synth_answer = nil
-      @listeners.on_message(Message::User.new(content: user_message))
-      @chat.ask(user_message)
-      nil
-    rescue Listener::StepLimit::Exceeded => e
-      notice = Message::FallbackNotice.new(
-        reason: "agent exhausted #{e.max_steps} steps; synthesizing answer from gathered evidence"
-      )
-      @listeners.on_message(notice)
-
-      synth_chat = RubyLLM.chat(**@transport.to_h)
-      # Synth runs under this agent's identity but on a fresh chat with a
-      # different system prompt, so it gets a distinct +_synthesizer+
-      # suffix on the name — same +_+ separator the sub-agent generator
-      # uses, so main becomes +"synthesizer"+ and a sub-agent
-      # +"sub_agent 0"+ becomes +"sub_agent 0_synthesizer"+. Any
-      # +TokenLog+ in the list tags the synth's prompt under that bracket
-      # so it's obvious from the log which turns were the rescue rather
-      # than the original loop.
-      synth_name = @name.empty? ? 'synthesizer' : "#{@name}_synthesizer"
-      @synth_answer = Synthesizer.run(
-        chat: synth_chat,
-        parent_messages: @chat.messages,
-        user_message: user_message,
-        listeners: @listeners.for_sub_agent(max_steps: 1, name: synth_name)
-      )
-      nil
-    end
-
-    # Adds a +sub_agent+ tool that lets this agent spawn sub-agents which
-    # share the parent's model, system prompt, and current tool set (minus
-    # the sub-agent tool itself, so recursion is impossible).
-    #
-    # {Tool::SubAgent} snapshots +@tools+ during construction; we append
-    # the new sub-agent tool to +@tools+ only after that, so the
-    # sub-agent's tool list never contains itself.
-    #
-    # Each sub-agent run gets a derived {ListenerList} via
-    # {ListenerList#for_sub_agent} — listeners that define a sub-agent
-    # variant return a fresh instance (e.g. +StepLimit+ at the new cap,
-    # +Terminal+ with sub-agent padding, +TokenLog+ zeroed); listeners
-    # without the hook (+InMemoryMessageList+, ...) are shared by reference so
-    # the sub-agent's events render and capture continuously with the
-    # parent's.
-    #
-    # @param max_steps [Integer] step budget for each sub-agent run,
-    #   passed through to {Tool::SubAgent#initialize}
-    # @raise [RuntimeError] if a {Tool::SubAgent} is already registered
-    #   on this agent — calling twice would advertise two identically
-    #   named tools to ruby_llm and double the sub-agent's tool list
-    #   (the second snapshot would contain the first sub-agent tool).
-    # @return [void]
-    def allow_sub_agent(max_steps: 10)
-      raise "Tool::SubAgent already registered on this agent; allow_sub_agent may only be called once" \
-        if @tools.any?(Tool::SubAgent)
-
-      sub_tool = Tool::SubAgent.new(self, max_steps: max_steps)
-      @tools << sub_tool
-      @chat.with_tool(sub_tool.to_ruby_llm_tool)
-    end
-
-    # Short, single-line config dump suitable for a startup banner or a
-    # debug print. Delegates the listener rendering to {ListenerList#to_s}.
-    #
-    # @example
-    #   agent.to_s
-    #   # => "Agent(model=qwen3-35b, tools=4, listeners=[Terminal, StepLimit(max=20)])"
-    #
-    # @return [String]
-    def to_s
-      "Agent(model=#{model}, tools=#{@tools.size}, listeners=#{@listeners})"
-    end
-  end
-end