pikuri-core 0.0.6 → 0.1.0

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

@@ -3,115 +3,86 @@
 module Pikuri
   class Agent
     module Listener
-      # Logs the conversation's context-window consumption per
-      # assistant turn via +Pikuri.logger_for('Tokens')+. Consumes
-      # {Event::Tokens} (one log line per emission) and
-      # {Event::ContextCap} (one-shot cap, picked off and cached);
-      # every other event variant is a no-op.
-      #
-      # Existence rationale: catch context-window growth before the
-      # provider raises +RubyLLM::ContextLengthExceededError+.
-      # +ctx+ is the headline number — tokens consumed by the
-      # conversation *through* this turn: this turn's prompt plus
-      # its reply, both of which the model will re-process on the
-      # next turn. The +Δ+ field shows the climb between turns;
-      # +↑+ / +↓+ are the per-turn input / output sizes that drove
-      # it (matching Claude Code's convention: +↑+ is what's sent
-      # to the model, +↓+ is what comes back).
-      #
-      # == State and scope
-      #
-      # The latest snapshot lives on the instance, so one
-      # +TokenLog+ is per-conversation. Sub-agents (with their own
-      # +RubyLLM::Chat+) get a fresh instance via {#for_sub_agent}
-      # (dispatched by {ListenerList#for_sub_agent}) so their
-      # counts log against their own chat. The synthesizer rescue
-      # gets a derived list via the same hook because its synth
-      # chat is also fresh.
+      # Logs the conversation's context-window consumption per assistant
+      # turn via +Pikuri.logger_for('Tokens')+ — a running headline to catch
+      # growth before the provider raises
+      # +RubyLLM::ContextLengthExceededError+. Consumes {Event::Tokens} (one
+      # line each), {Event::ContextCap} (caches the cap, refreshed on a model
+      # switch), and {Event::Reset} (zero the snapshot, see {#reset_snapshot});
+      # every other variant is a no-op.
       #
       # == Log line shape
       #
-      # Without a cap (no {Event::ContextCap} carrying a value):
-      #
-      #   msg #1: ctx=6.8k  Δ+6.8k  ↑6.8k  ↓0.0k
-      #   msg #2: ctx=8.4k  Δ+1.6k  ↑1.0k  ↓0.6k
-      #
-      # With a cap of e.g. 32k (an {Event::ContextCap} with
-      # +cap: 32_768+ was emitted at {Agent#initialize}):
-      #
-      #   msg #1: ctx=6.8k/32.0k  Δ+6.8k  ↑6.8k  ↓0.0k
+      #   msg #1: ctx=6.8k  Δ+6.8k  ↑6.8k  ↓0.0k          # no cap
+      #   msg #2: ctx=8.4k/32.0k  Δ+1.6k  ↑1.0k  ↓0.6k    # cap 32k
+      #   [researcher 0] msg #1: ctx=4.2k  ...            # sub-agent (Agent#id)
       #
-      # When the owning {Agent} has a non-empty {Agent#id} (i.e. a
-      # sub-agent), the line is prefixed with +[id] +:
+      # +ctx+ is the through-this-turn snapshot (+input + cached +
+      # cache_creation + output+; see {Event::Tokens}), suffixed +/<cap>+ when
+      # {#context_window_cap} is set. +Δ+ is the signed climb between turns
+      # (equal to +ctx+ on msg #1); +↑+/+↓+ are this turn's input/output
+      # (Claude Code's convention). Sizes are 1024-scaled with a +k+ suffix.
       #
-      #   [researcher 0] msg #1: ctx=4.2k  Δ+4.2k  ↑4.2k  ↓0.0k
-      #
-      # +ctx+ is the snapshot
-      # (+input + cached + cache_creation + output+; see
-      # {Event::Tokens}), optionally suffixed with +/<cap>+ when
-      # {#context_window_cap} is set so the operator can see how
-      # close the conversation is to the limit. Including +output+
-      # makes this turn's reply visible immediately — leaving it
-      # out would hide a long reply in the +ctx=+ headline until
-      # the next turn pulled it in as cached prompt. +Δ+ is
-      # signed: +Δ+X+ for growth, +Δ-X+ for shrinkage (legitimate
-      # if ruby_llm ever prunes between turns). On the first
-      # message the baseline is implicitly zero, so +Δ+ equals
-      # +ctx+. Sizes are scaled by 1024 and shown with one
-      # decimal + a +k+ suffix.
+      # One instance per conversation (the snapshot is instance state);
+      # sub-agents and the synthesizer get a fresh zeroed one via
+      # {#for_sub_agent}.
       class TokenLog < Base
-        # Subsystem logger; the per-turn context-window line is
-        # emitted at +INFO+ level. Set its level with
-        # +PIKURI_LOG_TOKENS+ or the global +PIKURI_LOG+.
+        # Subsystem logger; the per-turn line is +INFO+. Level via
+        # +PIKURI_LOG_TOKENS+ or +PIKURI_LOG+.
         #
         # @return [Logger]
         LOGGER = Pikuri.logger_for('Tokens')
 
-        # Tokens consumed by the conversation through the most
-        # recent turn — this turn's prompt plus its reply, which
-        # together make up the bulk of what the next turn will
-        # re-process. Equals +input + cached + cache_creation +
-        # output+ from the latest {Event::Tokens}. Zero until the
-        # first {Event::Tokens} arrives.
+        # Tokens consumed by the conversation through the most recent turn
+        # (+input + cached + cache_creation + output+ from the latest
+        # {Event::Tokens}). Zero until the first arrives.
         #
         # @return [Integer]
         attr_reader :context_window_size
 
-        # Model's context-window cap, or +nil+ if no source could
-        # supply one (see {Agent::ContextWindowDetector}). When
-        # set, the +ctx=+ field renders as +ctx=<used>/<cap>+
-        # instead of just +ctx=<used>+. {Agent#initialize} emits a
-        # one-shot {Event::ContextCap} at construction; this
-        # listener picks the value off it and caches it here. An
-        # instance constructed bare (e.g. in tests, or by
-        # {#for_sub_agent}) defaults to +nil+.
+        # Model's context-window cap, or +nil+ if no source supplied one (see
+        # {Agent::ContextWindowDetector}). When set, +ctx+ renders as
+        # +<used>/<cap>+. Picked off the one-shot {Event::ContextCap}; a bare
+        # instance (tests, {#for_sub_agent}) defaults to +nil+.
         #
         # @return [Integer, nil]
         attr_accessor :context_window_cap
 
-        # @return [String] owning agent's id ({Agent#id}). Empty by
-        #   default (main agent); set by {#for_sub_agent} from the
-        #   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}.
+        # @return [String] owning agent's id ({Agent#id}); empty for the main
+        #   agent, set by {#for_sub_agent} so log lines get an +[<id>] + prefix.
         attr_reader :id
 
-        # The most recent log line, in the exact format written to
-        # {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
-        # instead of re-implementing the formatting.
+        # The most recent status line, *without* the +[<id>] + prefix (the
+        # prefix is {LOGGER}'s concern; consumers get the id separately via
+        # {#id} / {#on_status_line} and choose their own presentation). Empty
+        # until the first {Event::Tokens}. Hosts surfacing the snapshot in
+        # their own UI (a TUI footer) read this; hosts wanting to be pushed set
+        # {#on_status_line}.
         #
-        # Thread safety: a single instance-variable read of a
-        # +String+ — safe to read from any thread; readers may
-        # briefly see the previous turn's line during an in-flight
-        # {#on_event} call, which is acceptable for a status
-        # display.
+        # Safe to read from any thread (a single +String+ ivar read); a reader
+        # may briefly see the previous turn's line mid-{#on_event}, acceptable
+        # for a status display.
         #
         # @return [String]
         attr_reader :status_line
 
+        # Optional status-line observer, +nil+ by default. When callable, it's
+        # invoked with the owning agent's {#id} and the freshly formatted
+        # {#status_line} after every {Event::Tokens} — the push counterpart to
+        # polling {#status_line}. Fires on the agent's loop thread, so the
+        # callable must hand off to its sink thread-safely; it sits on the
+        # loop's path, so an exception it raises propagates into the
+        # conversation (handle dead connections inside it).
+        #
+        # {#for_sub_agent} copies the observer by reference, so one callable
+        # receives parent and sub-agent lines alike — the +id+ parameter routes
+        # each to the right row. An observer assigned *after* a sub-agent
+        # spawned doesn't reach that sub-agent's instance.
+        #
+        # @return [Proc, nil] called with +(id, status_line)+ — the agent's id
+        #   and the unprefixed {#status_line}
+        attr_accessor :on_status_line
+
         # @param id [String] owning agent's id, prepended to each
         #   log line as +[<id>] + when non-empty. Defaults to +""+
         #   for the main agent.
@@ -122,22 +93,21 @@ module Pikuri
           @context_window_size = 0
           @context_window_cap = nil
           @status_line = ''
+          @on_status_line = 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 +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.
+        # Sub-agent variant: a fresh +TokenLog+ with a zeroed snapshot so the
+        # sub-agent tracks its own +RubyLLM::Chat+, carrying the sub-agent's
+        # +id:+ (for the +[<id>] + prefix) and the {#on_status_line} observer
+        # by reference. The cap stays +nil+ — the sub-agent's own
+        # {Event::ContextCap} refills it.
         #
         # @param id [String] sub-agent's id
         # @return [TokenLog]
         def for_sub_agent(id: '', **)
-          self.class.new(id: id)
+          derived = self.class.new(id: id)
+          derived.on_status_line = @on_status_line
+          derived
         end
 
         # @param event [Agent::Event]
@@ -148,6 +118,10 @@ module Pikuri
             log_tokens(tokens)
           in Event::ContextCap(cap:)
             @context_window_cap = cap
+          in Event::Reset
+            reset_snapshot
+          in Event::HistoryLoaded(tokens:)
+            seed_snapshot(tokens)
           else
             # Every other variant: no-op.
           end
@@ -162,8 +136,46 @@ module Pikuri
 
         private
 
-        # Update the snapshot and write one +INFO+ line to the
-        # subsystem logger.
+        # Zero the running snapshot on {Event::Reset} (host cleared the
+        # conversation): message counter, running size, and status line reset;
+        # the cap stays (a property of the unchanged model). The blanked line
+        # is pushed to {#on_status_line} so a footer clears at once.
+        #
+        # @return [void]
+        def reset_snapshot
+          @msg = 0
+          @context_window_size = 0
+          @status_line = ''
+          @on_status_line&.call(@id, @status_line)
+          nil
+        end
+
+        # Restore the running size from a conversation just loaded off disk
+        # ({Event::HistoryLoaded}), which always arrives right after the
+        # {Event::Reset} that zeroed it. Without this the footer reads +0.0k+
+        # against 40k of restored history until the next reply corrects it.
+        #
+        # The message counter deliberately stays at zero: it counts replies
+        # *this* session, and restored turns did not happen here. A history
+        # exported without usage (+tokens+ +nil+) leaves the zeroed snapshot
+        # alone rather than inventing a number.
+        #
+        # @param tokens [Event::Tokens, nil] usage of the last restored
+        #   assistant message.
+        # @return [void]
+        def seed_snapshot(tokens)
+          return if tokens.nil?
+
+          @context_window_size = tokens.input.to_i + tokens.cached.to_i +
+                                 tokens.cache_creation.to_i + tokens.output.to_i
+          @status_line = "restored: ctx=#{format_ctx}"
+          @on_status_line&.call(@id, @status_line)
+          nil
+        end
+
+        # Update the snapshot, write one +INFO+ line to the
+        # subsystem logger, and push the line to the status-line
+        # observer (when one was given at construction).
         #
         # @param tokens [Event::Tokens]
         # @return [void]
@@ -178,19 +190,18 @@ module Pikuri
           delta = @context_window_size - prev_ctx
 
           @status_line = format_line(input_now, tokens.output.to_i, delta)
-          LOGGER.info(@status_line)
+          prefix = @id.empty? ? '' : "[#{@id}] "
+          LOGGER.info("#{prefix}#{@status_line}")
+          @on_status_line&.call(@id, @status_line)
         end
 
         def format_line(input, output, delta)
           sign = delta.negative? ? '-' : '+'
-          prefix = @id.empty? ? '' : "[#{@id}] "
-          "#{prefix}msg ##{@msg}: ctx=#{format_ctx}  Δ#{sign}#{format_k(delta.abs)}  ↑#{format_k(input)}  ↓#{format_k(output)}"
+          "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.
+        # +<used>+ with no cap, +<used>/<cap>+ with one. Shared by
+        # {#format_line} and {#to_s}.
         def format_ctx
           base = format_k(@context_window_size)
           return base if @context_window_cap.nil?
@@ -198,11 +209,8 @@ module Pikuri
           "#{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).
+        # Format a token count as a 1024-scaled +k+-suffixed string
+        # (+nil+/+0+ → +0.0k+, 12_453 → +12.2k+).
         #
         # @param n [Integer, nil]
         # @return [String]

data/lib/pikuri/agent/listener.rb

@@ -3,49 +3,36 @@
 module Pikuri
   class Agent
     # Namespace for the +Agent+'s pure event consumers — {Terminal},
-    # {InMemoryEventList}, {TokenLog}, and any host- or test-defined
-    # consumer. Each subclasses {Base} and overrides {Base#on_event}
-    # to pattern-match on the {Event} variants it cares about;
-    # everything else flows through unobserved.
+    # {InMemoryEventList}, {TokenLog}, and any host/test consumer. Each
+    # subclasses {Base} and overrides {Base#on_event} to pattern-match the
+    # {Event} variants it cares about; everything else flows through unobserved.
     #
-    # == What lives here, what doesn't
-    #
-    # The directory holds *pure consumers*: code whose only side
-    # effect is to react to events the +Agent+ has already emitted.
-    # No listener writes back into the stream — the +Agent+ is the
-    # only emitter — and no listener reaches into ruby_llm's chat
-    # callbacks. Both responsibilities live in {Agent}.
-    #
-    # Host-facing signal holders — step budget, cancellation flag,
-    # mid-loop user input queue — are *controls*, not listeners.
-    # They live under {Pikuri::Agent::Control} and reach {Agent}
-    # through dedicated kwargs on {Agent#initialize}; they never
-    # appear in the {ListenerList} and they never receive events.
+    # These are *pure consumers*: no listener writes back into the stream
+    # (emission is the +Agent+'s and {Agent::ExtensionContext#emit_event}'s job)
+    # or reaches into ruby_llm's callbacks (that's {Agent}'s). Host-facing signal
+    # holders (step budget, cancel flag, input queue) are *controls* under
+    # {Pikuri::Agent::Control}, not listeners — they never appear in a
+    # {ListenerList} or receive events.
     module Listener
-      # Abstract base for event-stream consumers. Subclasses override
-      # {#on_event} with a +case+ on the {Event} variant; the default
-      # implementation is a no-op so a listener that cares about a
-      # single variant doesn't have to enumerate the rest.
+      # Abstract base for event-stream consumers. Subclasses override {#on_event}
+      # with a +case+ on the {Event} variant; the default is a no-op so a
+      # listener caring about one variant needn't enumerate the rest.
       #
-      # Subclasses optionally define +for_sub_agent(**params)+ to
-      # return a variant suitable for a spawned sub-agent — a fresh
-      # zeroed instance, the same instance shared by reference, or
-      # +nil+ to opt out of propagation. See
-      # {ListenerList#for_sub_agent} for the dispatch and the
-      # per-listener semantics.
+      # Subclasses optionally define +for_sub_agent(**params)+ for a spawned
+      # sub-agent — a fresh instance, the same shared by reference, or +nil+ to
+      # opt out. See {ListenerList#for_sub_agent}.
       class Base
         # Single entry point for every event in the normalized stream.
-        # Concrete subclasses override this and dispatch on the
-        # variant (typically with a +case event in Event::X(...)+
-        # pattern). The default implementation is a no-op so a
-        # listener that only cares about a subset can match
-        # selectively and let everything else fall through.
+        # Subclasses override and dispatch on the variant (a +case event in
+        # Event::X(...)+); the default no-op lets a listener match a subset and
+        # ignore the rest.
         #
-        # @param event [Event::UserTurn, Event::Thinking,
-        #   Event::ThinkingDelta, Event::Assistant,
-        #   Event::AssistantDelta, Event::ToolCall,
+        # @param event [Event::UserTurn, Event::Thinking, Event::ThinkingDelta,
+        #   Event::Assistant, Event::AssistantDelta, Event::ToolCall,
         #   Event::ToolResult, Event::Tokens, Event::ContextCap,
-        #   Event::FallbackNotice, Event::Cancelled]
+        #   Event::FallbackNotice, Event::Cancelled, Object] a core
+        #   loop-narration variant, or a gem domain event via
+        #   {Agent::ExtensionContext#emit_event} (e.g. +Pikuri::Tasks::ListChanged+)
         # @return [void]
         def on_event(event); end
       end

data/lib/pikuri/agent/listener_list.rb

@@ -2,20 +2,14 @@
 
 module Pikuri
   class Agent
-    # Listener-list value object that an {Agent} owns. Wraps an
-    # +Array+ of {Listener::Base} instances and fans {#emit} out to
-    # each; {Agent#initialize} stores one of these and is the sole
-    # caller of {#emit}.
+    # Listener-list value object an {Agent} owns: wraps an +Array+ of
+    # {Listener::Base} and fans {#emit} out to each. {Agent#initialize} stores
+    # one and is the sole caller of {#emit}.
     #
-    # == What this is, what it isn't
-    #
-    # One job: fan out. The +Agent+ wires ruby_llm's callbacks
-    # itself, the context-window cap rides the event stream as a
-    # one-shot {Event::ContextCap}, and the sub-agent derivation
-    # rule lives in {#for_sub_agent}. Controls (step budget,
-    # cancellation flag, mid-loop input queue) are not listeners
-    # and do not appear in this list; their sub-agent derivation
-    # lives on each control class instead.
+    # One job: fan out. The +Agent+ wires ruby_llm's callbacks itself, the
+    # context cap rides the stream as a one-shot {Event::ContextCap}, and the
+    # sub-agent derivation rule lives in {#for_sub_agent}. Controls are not
+    # listeners and don't appear here.
     class ListenerList
       # @param listeners [Array<Listener::Base>] listeners that
       #   define +on_event(event)+
@@ -23,21 +17,21 @@ module Pikuri
         @listeners = listeners.dup
       end
 
-      # Dispatch one event to every listener, in registration order.
-      # Called exclusively by {Agent} — listeners themselves never
-      # call this; the stream is one-way.
+      # Dispatch one event to every listener, in registration order. Exactly two
+      # callers: {Agent} (loop-narration {Event}s) and
+      # {ExtensionContext#emit_event} (domain events); listeners never call it —
+      # the stream is one-way.
       #
-      # @param event [Agent::Event]
+      # @param event [Object] an {Agent::Event} variant or a gem domain event
+      #   (an immutable value, by convention a +Data+)
       # @return [void]
       def emit(event)
         @listeners.each { |l| l.on_event(event) }
       end
 
-      # Iterate over the wrapped listeners in registration order. The
-      # method exists so a ListenerList can be passed directly to
-      # {Configurator#add_listeners} (used by the +agent+ tool from
-      # +pikuri-subagents+ when seeding a sub-agent's Configurator
-      # from the parent's list).
+      # Iterate the wrapped listeners in registration order — so a ListenerList
+      # can be passed to {Configurator#add_listeners} (the +agent+ tool seeds a
+      # sub-agent's Configurator from the parent's list).
       #
       # @yield [listener]
       # @yieldparam listener [Listener::Base]
@@ -46,28 +40,17 @@ module Pikuri
         @listeners.each(&block)
       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+, a replacement instance, or +nil+
-      # to opt out of propagation entirely — the resulting list
-      # compacts +nil+ entries away. Listeners that don't define the
-      # method are kept by reference (structured capture and other
-      # stateful sinks continue to flow into the parent's instances).
-      #
-      # The dispatch lives on each 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) and
-      # {Listener::TokenLog#for_sub_agent} (fresh, zeroed snapshot
-      # with the forwarded +id:+).
+      # A new {ListenerList} where every listener has been asked for its
+      # sub-agent variant: a listener defining +for_sub_agent(**params)+ returns
+      # +self+, a replacement, or +nil+ to opt out (compacted away); listeners
+      # without the method are kept by reference (stateful sinks keep flowing
+      # into the parent's instances). The dispatch lives on each listener so a
+      # new listener type needs no change here — see
+      # {Listener::Terminal#for_sub_agent} / {Listener::TokenLog#for_sub_agent}.
       #
-      # +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 +id:+ (used by {Listener::TokenLog} to
-      # prefix its log lines with the sub-agent's id). Calling with
-      # no params is always valid.
+      # +params+ is forwarded as kwargs; each listener picks what it needs. The
+      # only key bundled listeners consume is +id:+ ({Listener::TokenLog}); no
+      # params is valid.
       #
       # @param params [Hash{Symbol => Object}]
       # @return [ListenerList]
@@ -78,20 +61,6 @@ module Pikuri
         self.class.new(swapped)
       end
 
-      # Return a new {ListenerList} containing this list's listeners
-      # plus the given extras, in order. Used by {Synthesizer} and
-      # other internal consumers to derive a list from an existing
-      # one. Returns +self+ when +extras+ is empty so the common
-      # no-op case allocates nothing.
-      #
-      # @param extras [Array<Listener::Base>] listeners to append
-      # @return [ListenerList]
-      def with(*extras)
-        return self if extras.empty?
-
-        self.class.new(@listeners + extras)
-      end
-
       # @example
       #   list.to_s # => "[Terminal, TokenLog(ctx=0.0k)]"
       #