pikuri-core 0.0.7 → 0.1.0

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

@@ -4,70 +4,48 @@ module Pikuri
   class Agent
     module Listener
       # Decorator that coalesces high-frequency streaming deltas
-      # ({Event::AssistantDelta}, {Event::ThinkingDelta}) into at most
-      # +fps+ events per second before handing them off to an inner
-      # listener. Non-delta events flow through unmodified, with any
-      # pending coalesced content either emitted ahead of them
-      # (default) or dropped silently — see
-      # +flush_pending_on_non_delta:+.
+      # ({Event::AssistantDelta}, {Event::ThinkingDelta}) into at most +fps+
+      # events/sec before forwarding to an inner listener. Non-delta events flow
+      # through unmodified, with any pending coalesced content emitted ahead of
+      # them (default) or dropped — see +flush_pending_on_non_delta:+.
       #
-      # Useful for renderers whose per-delta repaint cost is higher
-      # than the wire-arrival rate of provider chunks: a fast provider
-      # can emit dozens of deltas per second, and a Markdown-rendering
-      # UI doesn't need every one of them on-screen. +fps: 15+ is a
-      # reasonable starting point for a TUI.
+      # For renderers whose per-delta repaint costs more than provider chunks
+      # arrive: a fast provider emits dozens of deltas/sec, and a
+      # Markdown-rendering UI doesn't need every one. +fps: 15+ suits a TUI.
       #
       # == Tick alignment
       #
-      # The first flush is anchored to a monotonic-clock reference
-      # taken at construction, not to the arrival of the first delta.
-      # This keeps stream-startup latency from leaking into the
-      # cadence: with +fps: 1+, if the first delta arrives 0.9s after
-      # construction, it flushes immediately (the construction-time
-      # tick has already passed) and the next tick fires 0.1s later
-      # — preserving the configured rate. After a flush, the schedule
-      # advances by exactly +1/fps+ per missed tick; a long-idle
-      # stream doesn't backlog ticks against itself.
+      # The first flush is anchored to a monotonic-clock reference taken at
+      # construction, not the first delta's arrival — so stream-startup latency
+      # doesn't leak into the cadence. After a flush the schedule advances by
+      # exactly +1/fps+ per missed tick, so a long-idle stream doesn't backlog
+      # ticks against itself.
       #
       # == Per-stream buffering
       #
-      # Assistant and thinking deltas are buffered independently. A
-      # tick flushes whichever buffers are non-empty as separate
-      # coalesced delta events; providers practically don't interleave
-      # the two modalities within a single tick, but the
-      # implementation doesn't rely on that.
+      # Assistant and thinking deltas buffer independently; a tick flushes
+      # whichever are non-empty as separate events.
       #
       # == Non-delta handling
       #
-      # +flush_pending_on_non_delta: true+ (default) emits any pending
-      # coalesced content as a delta event ahead of the non-delta
-      # event so the inner listener sees the complete stream — the
-      # lossless choice. +false+ drops the pending buffers silently:
-      # appropriate for inner listeners that re-render the
-      # authoritative final content on a bookend ({Event::Assistant} /
-      # {Event::Thinking}), where rendering the trailing 0–66 ms of
-      # deltas would be wasted CPU before the redraw.
+      # +flush_pending_on_non_delta: true+ (default) emits pending content ahead
+      # of the non-delta event — lossless. +false+ drops it silently:
+      # appropriate for inner listeners that re-render the authoritative final
+      # content on a bookend ({Event::Assistant}/{Event::Thinking}), where the
+      # trailing 0–66 ms of deltas would be wasted CPU before the redraw.
       #
-      # == Threading
-      #
-      # No threads, no timers. The decorator advances its tick state
-      # only when an event arrives, so it's safe to install on any
-      # listener regardless of which thread the agent emits on, as
-      # long as delivery is sequential (which the {ListenerList}
-      # contract guarantees).
+      # No threads or timers: tick state advances only when an event arrives, so
+      # it's safe on any thread as long as delivery is sequential (the
+      # {ListenerList} contract).
       class RateLimited < Base
-        # @param inner [Listener::Base] the listener to forward
-        #   (possibly coalesced) events to.
-        # @param fps [Integer, Float] frames-per-second cap on the
-        #   coalesced delta stream. Must be positive.
-        # @param flush_pending_on_non_delta [Boolean] +true+
-        #   (default) emits any pending coalesced content as a delta
-        #   before forwarding the non-delta event; +false+ drops the
-        #   pending buffers silently.
-        # @param clock [Proc] zero-arg returning monotonic
-        #   seconds-since-some-epoch as a +Float+. Injection seam for
-        #   deterministic specs; production uses
-        #   +Process.clock_gettime(Process::CLOCK_MONOTONIC)+.
+        # @param inner [Listener::Base] the listener to forward (coalesced) events to.
+        # @param fps [Integer, Float] frames-per-second cap on the coalesced
+        #   delta stream. Must be positive.
+        # @param flush_pending_on_non_delta [Boolean] +true+ (default) emits
+        #   pending content as a delta before a non-delta event; +false+ drops it.
+        # @param clock [Proc] zero-arg → monotonic seconds as a +Float+;
+        #   injection seam for specs (production uses
+        #   +Process.clock_gettime(Process::CLOCK_MONOTONIC)+).
         # @raise [ArgumentError] if +fps+ is not positive.
         def initialize(inner, fps:, flush_pending_on_non_delta: true,
                        clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
@@ -107,15 +85,13 @@ module Pikuri
           end
         end
 
-        # Sub-agent variant: wraps the inner listener's sub-agent
-        # variant (or the inner listener itself when it doesn't define
-        # +for_sub_agent+) in a fresh +RateLimited+ with the same
-        # knobs. Returns +nil+ when the inner's +for_sub_agent+
-        # returned +nil+ — there's nothing to wrap.
+        # Sub-agent variant: wraps the inner listener's sub-agent variant (or
+        # the inner itself when it has no +for_sub_agent+) in a fresh
+        # +RateLimited+ with the same knobs. +nil+ when the inner's returned
+        # +nil+.
         #
-        # @param params [Hash{Symbol => Object}] forwarded to the
-        #   inner listener's +for_sub_agent+, same protocol as
-        #   {ListenerList#for_sub_agent}
+        # @param params [Hash{Symbol => Object}] forwarded to the inner's
+        #   +for_sub_agent+ (same protocol as {ListenerList#for_sub_agent})
         # @return [RateLimited, nil]
         def for_sub_agent(**params)
           inner_sub = @inner.respond_to?(:for_sub_agent) ? @inner.for_sub_agent(**params) : @inner
@@ -126,9 +102,8 @@ module Pikuri
                                     clock: @clock)
         end
 
-        # @return [String] short label for {Agent#to_s}; embeds the
-        #   inner listener's label so the chain reads end-to-end in
-        #   {ListenerList#to_s}
+        # @return [String] short label for {Agent#to_s}, embedding the inner
+        #   listener's so the chain reads end-to-end.
         def to_s
           policy = @flush_on_non_delta ? 'flush' : 'drop'
           "RateLimited(#{@fps}fps, #{policy}, #{@inner})"
@@ -136,9 +111,8 @@ module Pikuri
 
         private
 
-        # Advance to the next tick strictly after +now+, in one shot.
-        # Handles the case where deltas paused for several periods —
-        # a long-idle stream doesn't backlog ticks against the next
+        # Advance to the next tick strictly after +now+, in one shot — a stream
+        # idle for several periods doesn't backlog ticks against the next
         # stream's first delta.
         # @return [void]
         def tick

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

@@ -1,103 +1,72 @@
 # frozen_string_literal: true
 
 require 'rainbow'
+require 'io/console'
 
 module Pikuri
   class Agent
     module Listener
-      # Terminal renderer for the normalized event stream: dim grey
-      # reasoning, assistant content printed raw (Markdown as-is),
-      # cyan tool-call and tool-result lines, yellow fallback
-      # notice, red cancelled notice, magenta model-switch notice.
-      # An {Event::SystemInjected} block (recalled
-      # memory / context an extension injected) renders dim grey
-      # with a +⊕+ marker. {Event::UserTurn} is intentionally silent
-      # (the terminal user just typed the message, so re-rendering
-      # it adds nothing); {Event::Tokens} and {Event::ContextCap}
-      # are silent too (their consumer is {TokenLog}).
+      # Terminal renderer for the normalized event stream: dim grey reasoning,
+      # assistant Markdown printed raw, cyan tool-call/result lines, yellow
+      # fallback notice, red cancelled, magenta model-switch.
+      # {Event::UserTurn} / {Event::Tokens} / {Event::ContextCap} are silent
+      # (echo, or {TokenLog}'s business); {Event::SystemInjected} renders dim
+      # grey with a +⊕+ marker. Any unrecognized event — notably a gem
+      # *domain* event — renders generically via its +to_s+ (dim grey, +·+
+      # marker), so a new variant shows in the demo without a change here. An
+      # {Event::Transient} one instead rewrites a single line in place, and the
+      # text of every domain event is defanged through {Pikuri::Sanitizer} —
+      # a +to_s+ may carry a filename, a skill name or a server's own words.
       #
-      # Assistant Markdown deliberately prints raw, with no
-      # Markdown-to-ANSI rendering. A renderer (+tty-markdown+)
-      # used to sit on the non-streaming path; it was dropped:
-      # rendering can never apply to the streaming path anyway
-      # (half-finished Markdown — broken code fences, half-built
-      # tables — doesn't render), the gem hadn't shipped a release
-      # since 2023 (its known ANSI-in-table crashes forced a
-      # rescue-and-degrade carve-out here), and it pulled seven
-      # transitive gems into the audit surface. Raw Markdown is
-      # perfectly readable in a terminal; proper rendering belongs
-      # to a richer host (the planned pikuri-tui).
+      # Assistant Markdown prints raw, no Markdown-to-ANSI: rendering can't
+      # apply to the streaming path anyway (half-built fences/tables), and the
+      # one gem for it (tty-markdown) was unmaintained, crashed on
+      # ANSI-in-tables, and pulled seven transitive deps — proper rendering
+      # belongs to a richer host (the planned pikuri-tui).
       #
-      # Optionally prepends a fixed number of leading spaces to
-      # every rendered line via the +padding:+ kwarg. Sub-agents
-      # get a fresh padded instance through {#for_sub_agent}
-      # (dispatched by {ListenerList#for_sub_agent}) so their
-      # output is visually indented under the parent's stream.
+      # +padding:+ prepends a fixed number of leading spaces to every line;
+      # sub-agents get a fresh padded instance via {#for_sub_agent}.
       #
       # == Streaming mode
       #
-      # When constructed with +streaming: true+ (typically because
-      # the host's {Agent} was constructed with the matching flag):
-      #
-      # - {Event::ThinkingDelta} fragments print live in the same
-      #   dim grey as the non-streaming {Event::Thinking}, with no
-      #   trailing newline so the next fragment continues the line.
-      # - {Event::AssistantDelta} fragments print live the same
-      #   way, uncolored.
-      # - {Event::Thinking} and {Event::Assistant} bookends print
-      #   a single blank line as a stream terminator, not their
-      #   content (the content already landed via the deltas). The
-      #   terminator gives the next event (tool call, next round,
-      #   final REPL prompt) a clean line to start on.
-      #
-      # In non-streaming mode (+streaming: false+, the default),
-      # the deltas are silently ignored and the bookend events
-      # render the full text the way they always have.
+      # With +streaming: true+ (matching the {Agent}'s flag):
+      # {Event::ThinkingDelta} / {Event::AssistantDelta} print live (dim grey /
+      # uncolored, no trailing newline), and the {Event::Thinking} /
+      # {Event::Assistant} bookends print a single blank line as a terminator,
+      # not their content (already landed via deltas). With +streaming: false+
+      # (default) the deltas are ignored and the bookends render full text.
       class Terminal < Base
-        # 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.
+        # Char cap on tool-result content rendered to the terminal; longer is
+        # truncated with a marker reporting the original byte size (so a
+        # 200-char return is distinguishable from a 50KB 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.
+        # Padding for a sub-agent's stream. Absolute, not additive — sub-agent
+        # recursion is blocked (the sub-agent's toolset excludes +sub_agent+),
+        # so depth never exceeds 1 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}.
-        # @param streaming [Boolean] render the chunk-level delta
-        #   stream live. See the class header's "Streaming mode"
-        #   section for the behavior swap. Defaults to +false+.
+        # @param padding [Integer] non-negative leading spaces per line
+        #   (default 0; sub-agents get {SUB_AGENT_PADDING} via {#for_sub_agent}).
+        # @param streaming [Boolean] render the chunk-level delta stream live
+        #   (default +false+; see "Streaming mode").
         def initialize(padding: 0, streaming: false)
           super()
           @padding = padding
           @streaming = streaming
           @at_line_start = true
+          @transient = false
         end
 
-        # @return [Integer] current padding width; exposed so
-        #   callers can introspect it (and so tests can assert it).
+        # @return [Integer] current padding width.
         attr_reader :padding
 
-        # @return [Boolean] +true+ when this Terminal is in
-        #   streaming mode (deltas rendered live; bookends emit a
-        #   terminator newline only).
+        # @return [Boolean] +true+ in streaming mode.
         attr_reader :streaming
 
-        # Sub-agent variant: a fresh +Terminal+ at
-        # {SUB_AGENT_PADDING}, carrying the same +streaming+ flag
-        # the parent had, so sub-agent output is visually indented
-        # under the parent's stream and the stream mode stays
-        # consistent across the agent tree. Called by
-        # {ListenerList#for_sub_agent}; ignores any params it's
-        # handed (Terminal has no caller-provided knobs).
+        # Sub-agent variant: a fresh +Terminal+ at {SUB_AGENT_PADDING} carrying
+        # the parent's +streaming+ flag, so sub-agent output indents under the
+        # parent's stream. Ignores any params (Terminal has no caller knobs).
         #
         # @return [Terminal]
         def for_sub_agent(**)
@@ -138,11 +107,16 @@ module Pikuri
             println(indent(Rainbow("! #{reason}").yellow))
           in Event::Cancelled
             println(indent(Rainbow('! cancelled').red))
+          in Event::Reset
+            println(indent(Rainbow('— context cleared —').color(85, 85, 85)))
+          in Event::UserTurn | Event::Tokens | Event::ContextCap
+            # Silent: UserTurn echoes just-typed input; Tokens/ContextCap are
+            # TokenLog's. (Non-streaming deltas no-op in their branches above.)
           else
-            # UserTurn / Tokens / ContextCap silent on the terminal.
-            # In non-streaming mode the deltas fall through here
-            # too (the final Thinking / Assistant bookend already
-            # renders the full text).
+            # Any other event — notably a gem *domain* event — renders via its
+            # own to_s; core needs no knowledge of the type. A richer host
+            # pattern-matches the variants it styles.
+            domain_event(event)
           end
         end
 
@@ -158,47 +132,108 @@ module Pikuri
 
         private
 
-        # +puts+ wrapper that also resets the streaming line-state
-        # to "at line start" — every full-line print necessarily
-        # leaves the cursor at column 0, so the next fragment
-        # printed in streaming mode knows to insert padding before
-        # its first character. Used by every branch in
-        # {#on_event} except the delta branches.
+        # +puts+ wrapper that resets the streaming line-state to "at line
+        # start" (a full-line print leaves the cursor at column 0, so the next
+        # streamed fragment knows to insert padding first).
         #
         # @param text [String]
         # @return [void]
         def println(text)
+          clear_transient
           puts text
           @at_line_start = true
         end
 
-        # Emit a single newline as a stream terminator and reset
-        # the line-state. Called on {Event::Thinking} /
-        # {Event::Assistant} bookends in streaming mode, where the
-        # content has already been rendered via the delta stream
-        # and what's left to do is give the next event a clean
-        # line to start on.
+        # A gem domain event, defanged and dimmed — an {Event::Transient} one
+        # rewriting a single line rather than appending to the log.
+        #
+        # @param event [Object] any event variant this listener does not style.
+        # @return [void]
+        def domain_event(event)
+          text = Sanitizer.sanitize(event.to_s.gsub(/\s+/, ' ').strip).text
+          return dim_line(text) unless event.is_a?(Event::Transient)
+
+          transient(text, done: event.done)
+        end
+
+        # @param text [String] sanitized and flattened.
+        # @return [void]
+        def dim_line(text)
+          println(indent(Rainbow("· #{text}").color(85, 85, 85)))
+        end
+
+        # Rewrite the in-place line, or retire it.
+        #
+        # Off a terminal it degrades to the final state only, as an ordinary line:
+        # a stream of +\r+ into a file is one unreadable mega-line, and a cold
+        # index emits hundreds of updates.
+        #
+        # @param text [String] sanitized and flattened.
+        # @param done [Boolean] the sequence is over, so the line goes away.
+        # @return [void]
+        def transient(text, done:)
+          unless $stdout.tty?
+            dim_line(text) if done
+            return
+          end
+
+          clear_transient
+          return if done
+
+          print(Rainbow(cut(indent("· #{text}"))).color(85, 85, 85))
+          $stdout.flush
+          @transient = true
+          @at_line_start = false
+        end
+
+        # Erase the in-place line so ordinary output does not land mid-bar.
+        #
+        # @return [void]
+        def clear_transient
+          return unless @transient
+
+          print("\r\e[K")
+          @transient = false
+          @at_line_start = true
+        end
+
+        # Fit +text+ in one row, because a line that wraps leaves its tail behind
+        # the carriage return that was supposed to erase it.
+        #
+        # @param text [String]
+        # @return [String]
+        def cut(text)
+          width = begin
+            $stdout.winsize[1]
+          rescue StandardError
+            80
+          end
+          text.length < width ? text : "#{text[0, width - 2]}…"
+        end
+
+        # Emit a newline as a stream terminator and reset line-state — the
+        # {Event::Thinking}/{Event::Assistant} bookend in streaming mode, where
+        # the content already rendered via deltas.
         #
         # @return [void]
         def terminate_stream
+          clear_transient
           puts
           @at_line_start = true
         end
 
-        # Print one streaming fragment to stdout *without* a
-        # trailing newline (so the next fragment continues the
-        # line) and flush so the bytes actually reach the
-        # terminal. Threads padding through any mid-fragment
-        # newlines: a fragment that contains "foo\nbar" with
-        # padding 2 prints +"  foo\n  bar"+ when the cursor was
-        # at line start.
+        # Print one streaming fragment without a trailing newline (so the next
+        # continues the line) and flush. Threads padding through mid-fragment
+        # newlines: "foo\nbar" at padding 2 from line start prints
+        # +"  foo\n  bar"+.
         #
-        # @param text [String] the fragment to emit; +nil+ / empty
-        #   short-circuits
+        # @param text [String] the fragment; +nil+/empty short-circuits
         # @return [void]
         def stream_fragment(text)
           return if text.nil? || text.empty?
 
+          clear_transient
+
           if @padding.zero?
             print(text)
             @at_line_start = text.end_with?("\n")
@@ -215,11 +250,9 @@ module Pikuri
           $stdout.flush
         end
 
-        # 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.
+        # Prepend +@padding+ spaces to every line of +text+. Uses +each_line+,
+        # not a +gsub+, so a trailing newline doesn't produce a stray padded
+        # blank line.
         #
         # @param text [String]
         # @return [String]
@@ -230,24 +263,17 @@ module Pikuri
           text.to_s.each_line.map { |line| prefix + line }.join
         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."
+        # Flatten whitespace and cap to {MAX_TOOL_RESULT_CHARS}; a truncated
+        # result's byte-count suffix distinguishes "returned exactly this" from
+        # "returned much more, you're seeing a slice."
         #
-        # Whitespace is flattened *first* (collapsing real tabs, CRs and
-        # newlines into single spaces — fine here, since this passive
-        # echo is a status line, not an approval artifact), then the
-        # result runs through {Pikuri::Sanitizer} so a tool observation
-        # can't smuggle an ESC or other control byte into this cyan line.
-        # The sanitizer's warnings are dropped — they belong at a
-        # confirmation prompt, not the stream narration.
+        # Whitespace is flattened first (fine — this passive echo is a status
+        # line, not an approval artifact), then run through {Pikuri::Sanitizer}
+        # so a tool observation can't smuggle an ESC/control byte into this
+        # line. Its warnings are dropped (they belong at a confirmation prompt).
         #
         # @param content [String] tool observation
-        # @return [String] single-line display form, possibly
-        #   truncated
+        # @return [String] single-line display form, possibly truncated
         def truncate_tool_result(content)
           original_bytes = content.to_s.bytesize
           flattened = Sanitizer.sanitize(content.to_s.gsub(/\s+/, ' ').strip).text