pikuri-core 0.0.7 → 0.1.0

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

@@ -3,161 +3,183 @@
 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.
+      # Mid-loop host→agent injection queue. A host (TUI, web client)
+      # constructs an +Interloper+, passes it to {Agent#initialize} via
+      # +interloper:+, and enqueues from any thread while the agent runs. The
+      # +Agent+ drains it once the running tool batch is answered — the only
+      # point in ruby_llm's loop where conversation state is consistent — and
+      # the next round-trip reacts to what was injected.
       #
-      # +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.
+      # == Two kinds
       #
-      # == Delivery boundary and side effects
+      # Each item carries a {Item#kind}, driving how {Agent#drain_interloper}
+      # lands it:
       #
-      # When the +Agent+'s +after_tool_result+ wiring fires, it
-      # calls {#drain!} on the interloper (if any) and, for each
-      # returned item:
+      # - +:user+ ({#inject_user_message}) — a mid-loop user turn: appended
+      #   verbatim, emits +Event::UserTurn(mid_loop: true)+, and runs the
+      #   {Extension#on_user_message} dispatch (prefetch/record like an initial
+      #   turn).
+      # - +:system+ ({#inject_system_message}) — host-supplied reference text
+      #   (a loaded skill, retrieved context): appended wrapped in
+      #   +<system-reminder>+, emits +Event::SystemInjected+, and runs *no*
+      #   +on_user_message+ dispatch and no +UserTurn+ (it's not a user turn).
       #
-      # 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.
+      # Both reach the wire as +role: :user+ — the kinds differ in dispatch and
+      # envelope, not in role. +:system+ names the *role the text plays*, and
+      # {Agent#append_reference_block} says why the wire role can't match it.
       #
-      # 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.
+      # Groundwork for downstream TUI/web hosts: the bundled +bin/pikuri-*+ do
+      # not wire one (stdin is synchronous). A host running the agent on a
+      # worker thread wires one in with no other changes.
       #
-      # == Boundary caveats
+      # == Delivery boundary
       #
-      # 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.
+      # Delivery is at the end of a tool batch, *not* the LLM HTTP call: an
+      # injection made mid-response takes effect on the *next* round-trip, once
+      # the model has committed to the current response's tool calls. Never
+      # *inside* a batch — an assistant message carrying tool_calls and the
+      # +:tool+ messages answering it are one unit on the wire, and a message
+      # appended between them is rejected or mangled (see
+      # {Agent#tool_batch_complete?}). Same
+      # "gentle" semantic {Control::Cancellable} promises — the cleanest
+      # cross-provider point (no in-flight subprocess, no half-built response).
+      # Controls are reset only at turn start, never on a mid-loop injection,
+      # so "cancel-then-inject" and "refresh-budget-by-injecting" can't arise.
       #
-      # == Thread safety
+      # == Change notification
       #
-      # {#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).
+      # A host rendering the pending count reactively (a "3 waiting" badge)
+      # sets {#on_change} instead of polling {#size}. It fires whenever the
+      # count changes — once per {#inject_user_message}, once per {#drain!}
+      # that empties a non-empty queue (an empty-queue drain, the hot path,
+      # stays silent) — with the new count, outside the lock. A host-side hook,
+      # not an {Agent} listener event: the count changes on the injecting
+      # thread, off the agent-thread-confined stream. Mirrors
+      # {Pikuri::Tasks::List#on_change} but pushes the count (the interloper
+      # exposes no race-free snapshot to re-read).
       #
       # == Sub-agent semantics
       #
-      # Sub-agents are private to the parent agent; the host has
-      # no handle to them, so a child +Interloper+ would be
-      # unreachable. The +agent+ tool from +pikuri-subagents+
-      # therefore omits the kwarg when spawning a child, leaving
-      # the sub-agent's +interloper+ at its default +nil+. The
-      # behavior contrasts with {Control::Cancellable}, which is
-      # shared 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.
+      # Sub-agents are private to the parent; the host has no handle to them,
+      # so the +agent+ tool omits the kwarg, leaving a child's +interloper+
+      # +nil+. Contrast {Control::Cancellable}, shared by reference so the
+      # parent's stop propagates to the whole tree — cancellation is global,
+      # injection is directed at the main agent.
+      #
+      # Thread-safe: {#inject_user_message}, {#inject_system_message}, {#peek},
+      # {#pending?}, {#size}, and {#drain!} are a +Mutex+-guarded +Array+
+      # (chosen over +Thread::Queue+, which exposes no snapshot for {#peek}).
+      # {#on_change} fires outside the lock so a re-entrant or blocking callback
+      # can't deadlock.
       class Interloper
+        # A queued injection: +kind+ (+:user+ or +:system+) selects the drain
+        # path; +content+ is the message text. Producers are the two
+        # +inject_*+ methods; the consumer is {Agent#drain_interloper}.
+        Item = Data.define(:kind, :content)
+
         def initialize
           @mutex = Mutex.new
           @items = []
+          @on_change = nil
         end
 
-        # Push +content+ onto the delivery queue. Safe from any
-        # thread; the queue is +Mutex+-guarded.
+        # Optional host callback invoked with the new pending count whenever it
+        # changes (after {#inject_user_message}, and after a {#drain!} that
+        # empties a non-empty queue). +nil+ (default) disables it. Runs
+        # *outside* the queue lock, on the mutating thread, so a callback
+        # feeding another thread should hand off only immutable data.
+        #
+        # @return [Proc, nil]
+        attr_accessor :on_change
+
+        # Enqueue a +:user+ mid-loop turn (any thread; +Mutex+-guarded). Fires
+        # {#on_change} with the new count, outside the lock.
         #
         # @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
+        # @raise [ArgumentError] if +content+ is +nil+/blank — a blank
+        #   injection would poison the chat history like a blank turn
         # @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?
+          enqueue(:user, content)
+        end
 
-          @mutex.synchronize { @items << content }
-          nil
+        # Enqueue a +:system+ reference block — host-loaded skill text or
+        # other retrieved context injected on the host's own initiative, not a
+        # user turn (any thread; +Mutex+-guarded). Fires {#on_change}.
+        #
+        # @param content [String] non-blank reference text (e.g. a rendered
+        #   skill block); an own semantic tag is kept, the +<system-reminder>+
+        #   envelope nests around it
+        # @raise [ArgumentError] if +content+ is +nil+/blank
+        # @return [void]
+        def inject_system_message(content)
+          enqueue(:system, content)
         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.
+        # Non-destructive snapshot of the queue in delivery order, for a host
+        # rendering a "pending" affordance. Safe from any thread.
         #
-        # @return [Array<String>] copy of the pending items;
-        #   never shares state with the internal buffer
+        # @return [Array<Item>] 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
+        # @return [Boolean] whether the queue holds a pending injection;
+        #   observable from any thread
         def pending?
           @mutex.synchronize { !@items.empty? }
         end
 
-        # @return [Integer] number of pending injections; like
-        #   {#pending?} and {#peek}, a snapshot observable from
-        #   any thread — by the time the caller reads it the
-        #   queue may already have drained
+        # @return [Integer] number of pending injections; a snapshot from any
+        #   thread (may have drained by the time the caller reads it)
         def size
           @mutex.synchronize { @items.size }
         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.
+        # Atomically take and remove all pending items. Called by {Agent}'s
+        # +after_message+ wiring, once a tool batch is complete. Returns +[]+ when empty (the hot path) —
+        # an empty drain does *not* fire {#on_change}; a drain that empties a
+        # non-empty queue fires it with +0+, outside the lock.
         #
-        # 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
+        # @return [Array<Item>] items in delivery order; empty when the queue
+        #   is empty
         def drain!
-          @mutex.synchronize do
+          items = @mutex.synchronize do
             next [] if @items.empty?
 
-            items = @items.dup
+            taken = @items.dup
             @items.clear
-            items
+            taken
           end
+          @on_change&.call(0) unless items.empty?
+          items
         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
+        # @return [String] short label for {Agent#to_s}, reflecting the
+        #   pending count.
         def to_s
           pending = size
           pending.zero? ? 'Interloper' : "Interloper(#{pending} pending)"
         end
+
+        private
+
+        # Shared enqueue for both +inject_*+ methods: validate, push a typed
+        # {Item}, fire {#on_change} outside the lock.
+        #
+        # @param kind [Symbol] +:user+ or +:system+
+        # @param content [String]
+        # @raise [ArgumentError] if +content+ is +nil+/blank
+        # @return [void]
+        def enqueue(kind, content)
+          raise ArgumentError, "content must not be blank, got #{content.inspect}" \
+            if content.nil? || content.to_s.strip.empty?
+
+          count = @mutex.synchronize { @items << Item.new(kind: kind, content: content); @items.size }
+          @on_change&.call(count)
+          nil
+        end
       end
     end
   end

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

@@ -3,35 +3,27 @@
 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} and the +Agent+ applies the {#on_exhausted}
-      # policy: re-raise to the host (the default), or run the
-      # step-exhaustion synthesizer to salvage a partial answer.
+      # Caps the number of tool calls per {Agent#run_loop}. ruby_llm has no
+      # step budget; the +Agent+ pokes {#tick!} on every +before_tool_call+ and
+      # {#reset!} at turn start. Once the count exceeds the cap, {#tick!} raises
+      # {Exceeded} and the +Agent+ applies {#on_exhausted}: re-raise to the host
+      # (default), or run the synthesizer to salvage a partial answer.
       #
       # == Why the policy lives here, not on +Agent+
       #
-      # Synthesis can only ever fire off a tripped step limit, so
-      # an +Agent.new(synthesize: ...)+ kwarg would be meaningless
-      # whenever +step_limit:+ is +nil+ — an invalid combination
-      # the API would have to document away. Attaching the policy
-      # to the budget makes "what happens when the budget runs
-      # out" travel with the budget, and the nonsense state is
-      # unrepresentable. The host picks per wiring: a Q&A REPL
-      # wants +:synthesize+ (salvage an answer from the evidence
-      # gathered so far); a coding agent wants the default
-      # +:raise+ (a tools-free pass can't finish writing code —
-      # stop, let the user say "continue"; {#reset!} at the next
-      # turn boundary refreshes the budget).
+      # Synthesis can only fire off a tripped step limit, so an
+      # +Agent.new(synthesize: ...)+ kwarg would be meaningless when
+      # +step_limit:+ is +nil+ — an invalid combination. Attaching the policy to
+      # the budget makes "what happens when it runs out" travel with the budget,
+      # and that nonsense state unrepresentable. Hosts pick per wiring: a Q&A
+      # REPL wants +:synthesize+ (salvage from evidence so far); a coding agent
+      # wants +:raise+ (a tools-free pass can't finish code — stop, let the user
+      # say "continue"; {#reset!} refreshes the budget next turn).
       class StepLimit
         # Valid {#on_exhausted} policies.
         ON_EXHAUSTED = %i[raise synthesize].freeze
-        # 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.
+        # Raised by {#tick!} once the tool-call count exceeds +max+; carries the
+        # tripped budget for user-facing messages.
         class Exceeded < StandardError
           # @return [Integer]
           attr_reader :max_steps
@@ -68,39 +60,31 @@ module Pikuri
           @step = 0
         end
 
-        # Increment the tool-call counter; raise {Exceeded} once
-        # it crosses {#max}. Called by {Agent} from its
-        # +before_tool_call+ wiring.
+        # Increment the counter; raise {Exceeded} once it crosses {#max}. Called
+        # from {Agent}'s +before_tool_call+ wiring.
         #
         # @return [void]
-        # @raise [Exceeded] when the counter has now exceeded
-        #   {#max}
+        # @raise [Exceeded] when the counter now exceeds {#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.
+        # Reset the counter to zero. Called by {Agent} at each turn start so one
+        # instance governs many turns. Mid-loop {Control::Interloper} injections
+        # deliberately do *not* reset — they're context for the same turn, 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)
+        # @return [Integer] current step count.
         attr_reader :step
 
-        # @return [String] short config dump for {Agent#to_s}.
-        #   The policy only renders when it's the non-default
-        #   +:synthesize+, so existing banner output is unchanged.
+        # @return [String] short config dump for {Agent#to_s}; the policy
+        #   renders only when the non-default +:synthesize+.
         def to_s
           policy = @on_exhausted == :raise ? '' : ", on_exhausted=#{@on_exhausted}"
           "StepLimit(max=#{@max}#{policy})"

data/lib/pikuri/agent/control.rb

@@ -2,43 +2,23 @@
 
 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}.
+    # Namespace for the +Agent+'s host-facing controls: {StepLimit},
+    # {Cancellable}, and {Interloper}. Each is a small value-holder the +Agent+
+    # reads from (or pokes into the event stream from) at fixed points in
+    # ruby_llm's 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
+    # The split: listeners are pure consumers of the event stream; controls are
+    # host-facing signal holders the +Agent+ reads. The +Agent+ is the only
+    # entity that emits events, ticks the step counter, checks the cancel flag,
+    # and drains the interloper queue — "what fires when" is one 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).
+    # * {StepLimit} — caps tool calls per {Agent#run_loop}; sub-agents get their
+    #   own counter.
+    # * {Cancellable} — cooperative cancel flag, shared by reference across the
+    #   parent, sub-agents, and the synthesizer.
+    # * {Interloper} — mid-loop user-input queue; not propagated to sub-agents.
     module Control
     end
   end