pikuri-core 0.0.3 → 0.0.5

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

@@ -41,10 +41,10 @@ module Pikuri
       #
       #   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] +:
+      # When the owning {Agent} has a non-empty {Agent#id} (i.e. a
+      # sub-agent), the line is prefixed with +[id] +:
       #
-      #   [sub_agent 0] msg #1: ctx=4.2k  Δ+4.2k  ↑4.2k  ↓0.0k
+      #   [researcher 0] msg #1: ctx=4.2k  Δ+4.2k  ↑4.2k  ↓0.0k
       #
       # +ctx+ is the snapshot
       # (+input + cached + cache_creation + output+; see
@@ -89,16 +89,15 @@ module Pikuri
         # @return [Integer, nil]
         attr_accessor :context_window_cap
 
-        # @return [String] owning agent's identifier. Empty by
+        # @return [String] owning agent's id ({Agent#id}). 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
+        #   sub-agent's generated id so the log lines can be
+        #   prefixed with +[<id>] +. Read-only — for a sub-agent's
+        #   listener you get a fresh instance via {#for_sub_agent}.
+        attr_reader :id
 
         # The most recent log line, in the exact format written to
-        # {LOGGER} (including any +[<name>] + prefix). Empty until
+        # {LOGGER} (including any +[<id>] + 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
@@ -113,12 +112,12 @@ module Pikuri
         # @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: '')
+        # @param id [String] owning agent's id, prepended to each
+        #   log line as +[<id>] + when non-empty. Defaults to +""+
+        #   for the main agent.
+        def initialize(id: '')
           super()
-          @name = name
+          @id = id
           @msg = 0
           @context_window_size = 0
           @context_window_cap = nil
@@ -128,17 +127,17 @@ module Pikuri
         # 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>] +
+        # parent's. Picks the sub-agent's +id:+ out of the
+        # forwarded params so its log lines carry the +[<id>] +
         # 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
+        # @param id [String] sub-agent's id
         # @return [TokenLog]
-        def for_sub_agent(name: '', **)
-          self.class.new(name: name)
+        def for_sub_agent(id: '', **)
+          self.class.new(id: id)
         end
 
         # @param event [Agent::Event]
@@ -184,7 +183,7 @@ module Pikuri
 
         def format_line(input, output, delta)
           sign = delta.negative? ? '-' : '+'
-          prefix = @name.empty? ? '' : "[#{@name}] "
+          prefix = @id.empty? ? '' : "[#{@id}] "
           "#{prefix}msg ##{@msg}: ctx=#{format_ctx}  Δ#{sign}#{format_k(delta.abs)}  ↑#{format_k(input)}  ↓#{format_k(output)}"
         end
 

data/lib/pikuri/agent/listener_list.rb

@@ -35,8 +35,9 @@ module Pikuri
 
       # Iterate over the wrapped listeners in registration order. The
       # method exists so a ListenerList can be passed directly to
-      # {Configurator#add_listeners} (used by {Tool::SubAgent} when
-      # seeding a sub-agent's Configurator from the parent's list).
+      # {Configurator#add_listeners} (used by the +agent+ tool from
+      # +pikuri-subagents+ when seeding a sub-agent's Configurator
+      # from the parent's list).
       #
       # @yield [listener]
       # @yieldparam listener [Listener::Base]
@@ -59,13 +60,14 @@ module Pikuri
       # change this class — see {Listener::Terminal#for_sub_agent}
       # (fresh padded instance) and
       # {Listener::TokenLog#for_sub_agent} (fresh, zeroed snapshot
-      # with the forwarded +name:+).
+      # with the forwarded +id:+).
       #
       # +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 only key currently consumed by
-      # bundled listeners is +name:+ (used by {Listener::TokenLog}).
-      # Calling with no params is always valid.
+      # bundled listeners is +id:+ (used by {Listener::TokenLog} to
+      # prefix its log lines with the sub-agent's id). Calling with
+      # no params is always valid.
       #
       # @param params [Hash{Symbol => Object}]
       # @return [ListenerList]

data/lib/pikuri/agent/synthesizer.rb

@@ -45,7 +45,7 @@ module Pikuri
       # reasoning and answer flow through the same listener
       # surface the parent agent uses — terminal renders them
       # inline (padded under sub-agent), an in-memory recorder
-      # picks them up, a TokenLog tags them with the synth name.
+      # picks them up, a TokenLog tags them with the synth id.
       #
       # @param chat [RubyLLM::Chat] a *fresh* chat with no tools.
       #   The caller is responsible for constructing it with the
@@ -58,7 +58,7 @@ module Pikuri
       # @param listeners [Agent::ListenerList] listeners to wire
       #   the synth chat into. Typically the parent agent's list
       #   run through {ListenerList#for_sub_agent} with the
-      #   synth's +name:+ so any +TokenLog+ tags its lines with
+      #   synth's +id:+ so any +TokenLog+ tags its lines with
       #   the synth bracket and any +Terminal+ pads its output.
       # @param step_limit [Control::StepLimit, nil] defensive
       #   step budget. The synth has no tools so it should never