pikuri-core 0.0.4 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f26e9b56204d1fbbaf64390e643a26c4183b3c21d45e3dcc43984c677a09f400
-  data.tar.gz: e657171d9440ef19a53ae5ad9335c62ff34ea8db62c9753ce79352f699122f06
+  metadata.gz: ac822a7bd46228f2eea2994c2e1428e3aa90c269e6ebafd603474fb630ba34ee
+  data.tar.gz: 00c69d139bc38c1a881bf87980970672517db51f59469aef266009a803a874db
 SHA512:
-  metadata.gz: 4f53aef4566f6218750c58b0cac4d1015d9ae2d2a1d464481ff4eabae3d42eb560559517a105ccd6fb2128e0b8e1b9393fdea257757dd6c85af0dc7a47683ed3
-  data.tar.gz: ba4adbf32911a499111eaf26057622e94fa27511aaefb5f9fb705ac3471a20d860536d1717e6933ec3e2b55af152fbfb8b479f99e11e44ea9ad907dd1c666a66
+  metadata.gz: d148d78b2027d747ef10f4dd7a19252f66bb1b5f99e8eef763149bf3e93ae608a3f7cf739b02ed4d92ab3ab39d8fe6888615a5acaf90dcb44ca783058a95a716
+  data.tar.gz: 32ef75bbd6d825970e5a1e6b5e27cf0fc812980e87e5ddd59b14f2c10772c91cf93003c2ebe2c9501f5e9682e726f77c4c387c7c83b467b9aa57dc91a9a178f0

data/lib/pikuri/agent/configurator.rb

@@ -127,8 +127,15 @@ module Pikuri
       # @param step_limit [Control::StepLimit, nil]
       # @param cancellable [Control::Cancellable, nil]
       # @param interloper [Control::Interloper, nil]
+      # @param on_close_sink [Array<Proc>, nil] array that {#on_close}
+      #   appends to. {Agent#initialize} passes its own live
+      #   +@on_close_handlers+ so a handler an extension arms via
+      #   +c.on_close+ is reachable the instant it's registered — which
+      #   is what lets the constructor close a half-built agent if a
+      #   later extension's +configure+ raises. Defaults to a fresh
+      #   array for standalone use (e.g. specs).
       def initialize(transport:, system_prompt_base:, id:, streaming:,
-                     step_limit:, cancellable:, interloper:)
+                     step_limit:, cancellable:, interloper:, on_close_sink: nil)
         @transport = transport
         @system_prompt_base = system_prompt_base
         @id = id
@@ -141,7 +148,7 @@ module Pikuri
         @sub_agent_tools = []
         @listeners = []
         @system_prompt_additions = []
-        @on_close_handlers = []
+        @on_close_handlers = on_close_sink || []
         @extensions = []
       end
 

data/lib/pikuri/agent/context_window_detector.rb

@@ -2,6 +2,7 @@
 
 require 'faraday'
 require 'json'
+require 'cgi'
 
 module Pikuri
   class Agent
@@ -31,6 +32,20 @@ module Pikuri
     #    (typically +bin/pikuri-chat+) derives the right URL from its configured
     #    base.
     #
+    # == llama.cpp router mode
+    #
+    # A llama.cpp *router* (the multi-instance front that proxies to N
+    # on-demand model servers) answers a bare +/props+ with
+    # +{"role":"router", ..., "n_ctx":0}+ — there is no single loaded
+    # model at the router itself, so its top-level +n_ctx+ is +0+. The
+    # real per-model cap is one proxied hop away: +GET /props?model=<id>+
+    # routes the probe to that model's instance, whose +/props+ carries
+    # the launched +n_ctx+. So when the bare probe reports +role: router+
+    # and a +model_id+ is known, this re-probes with the model id before
+    # giving up. A plain single-model server is untouched: its bare
+    # +/props+ already carries a positive +n_ctx+, so the router branch
+    # never runs.
+    #
     # == Failure handling
     #
     # The probe is best-effort. HTTP error, timeout, non-JSON body, or a
@@ -64,10 +79,15 @@ module Pikuri
       #   +RubyLLM::Chat#model.context_window+
       # @param llama_probe_url [String, nil] full URL to llama.cpp +/props+;
       #   +nil+ or empty string skips the probe
-      def initialize(override:, ruby_llm_reported:, llama_probe_url:)
+      # @param model_id [String, nil] the chat model id, used only to
+      #   follow a llama.cpp router via +/props?model=<id>+ when the bare
+      #   probe reports +role: router+. +nil+ or empty disables that
+      #   second hop.
+      def initialize(override:, ruby_llm_reported:, llama_probe_url:, model_id: nil)
         @override = override
         @ruby_llm_reported = ruby_llm_reported
         @llama_probe_url = llama_probe_url
+        @model_id = model_id
       end
 
       # @return [Integer, nil] resolved cap, or +nil+ if no source produced
@@ -83,25 +103,65 @@ module Pikuri
       private
 
       def probe_llama_cpp
-        response = Faraday.new(
-          request: { open_timeout: OPEN_TIMEOUT, timeout: READ_TIMEOUT }
-        ).get(@llama_probe_url) do |req|
-          req.headers['Accept'] = 'application/json'
-        end
+        data = fetch_props(@llama_probe_url)
+        return nil if data.nil?
 
-        return warn_and_nil("HTTP #{response.status} from #{@llama_probe_url}") unless response.status == 200
+        n_ctx = positive_n_ctx(data)
+        return n_ctx if n_ctx
 
-        data = JSON.parse(response.body)
-        n_ctx = data.dig('default_generation_settings', 'n_ctx')
-        return n_ctx if n_ctx.is_a?(Integer) && n_ctx.positive?
+        # llama.cpp router: the bare /props carries no model, so its
+        # n_ctx is 0. Follow the router to the model's own instance.
+        return probe_router_model if data['role'] == 'router' && model_id_present?
 
         warn_and_nil(
           "no positive integer at default_generation_settings.n_ctx in #{@llama_probe_url} response"
         )
+      end
+
+      def probe_router_model
+        url = "#{@llama_probe_url}?model=#{CGI.escape(@model_id)}"
+        data = fetch_props(url)
+        return nil if data.nil?
+
+        n_ctx = positive_n_ctx(data)
+        return n_ctx if n_ctx
+
+        warn_and_nil(
+          "no positive integer at default_generation_settings.n_ctx in router probe #{url}"
+        )
+      end
+
+      # GETs +url+ and parses its JSON body.
+      #
+      # @param url [String] a llama.cpp +/props+ URL
+      # @return [Hash, nil] the parsed body, or +nil+ (after one +warn+
+      #   line) on non-200, timeout, transport error, or non-JSON body
+      def fetch_props(url)
+        response = Faraday.new(
+          request: { open_timeout: OPEN_TIMEOUT, timeout: READ_TIMEOUT }
+        ).get(url) do |req|
+          req.headers['Accept'] = 'application/json'
+        end
+
+        return warn_and_nil("HTTP #{response.status} from #{url}") unless response.status == 200
+
+        JSON.parse(response.body)
       rescue Faraday::Error, JSON::ParserError => e
         warn_and_nil("#{e.class.name.split('::').last}: #{e.message}")
       end
 
+      # @param data [Hash] a parsed +/props+ body
+      # @return [Integer, nil] the launched +n_ctx+ when present and
+      #   positive, else +nil+
+      def positive_n_ctx(data)
+        n_ctx = data.dig('default_generation_settings', 'n_ctx')
+        n_ctx if n_ctx.is_a?(Integer) && n_ctx.positive?
+      end
+
+      def model_id_present?
+        !@model_id.nil? && !@model_id.empty?
+      end
+
       def warn_and_nil(reason)
         LOGGER.warn("llama.cpp /props probe failed: #{reason}")
         nil

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

@@ -123,6 +123,14 @@ module Pikuri
           @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
+        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
@@ -147,8 +155,8 @@ module Pikuri
         #   the pending-count so a debug print or banner can tell
         #   an idle interloper apart from one with queued items
         def to_s
-          size = @mutex.synchronize { @items.size }
-          size.zero? ? 'Interloper' : "Interloper(#{size} pending)"
+          pending = size
+          pending.zero? ? 'Interloper' : "Interloper(#{pending} pending)"
         end
       end
     end

data/lib/pikuri/agent/event.rb

@@ -45,6 +45,21 @@ module Pikuri
         end
       end
 
+      # A system-role block an {Extension#on_user_message} hook
+      # injected into the chat log — recalled reference (memory
+      # context, retrieved snippets) tagged +role: :system+ so the
+      # model reads it as background, not new user input. Carries
+      # the injected text verbatim.
+      #
+      # Emitted by {Agent#dispatch_ext_on_user_message}, once per
+      # extension that returns a non-empty block, at the same site
+      # that grows the chat log — so the event stream stays a
+      # faithful mirror of what the model actually sees. Without it
+      # an injection is invisible: it never surfaces in the stream,
+      # only as a secondary echo in the assistant's later reasoning.
+      # {Listener::Terminal} renders it dim grey with a +⊕+ marker.
+      SystemInjected = Data.define(:content)
+
       # Assistant reasoning ("thinking") block, extracted from the
       # +thinking.text+ field on a +RubyLLM::Message+ with role
       # +:assistant+. Emitted by {Agent}'s +after_message+ wiring;

data/lib/pikuri/agent/extension.rb

@@ -5,17 +5,20 @@ module Pikuri
     # The Extension protocol — how hosts bolt extra capabilities
     # (system-prompt snippets, tools, lifecycle hooks) onto an
     # {Agent}. Extensions are added via {Configurator#add_extension}
-    # inside the +Agent.new+ block; the Agent then drives two hooks
-    # on each — {#configure} during the block, {#bind} once the
-    # agent is fully constructed.
+    # inside the +Agent.new+ block; the Agent then drives three hooks
+    # on each — {#configure} during the block, {#bind} once the agent
+    # is fully constructed, and {#on_user_message} on every user turn
+    # thereafter.
     #
     # Mix this module into an extension class to inherit empty
-    # default implementations of both hooks; override the ones you
-    # need. Extensions that don't +include+ this module still work
-    # if they define both methods themselves (the Agent and
-    # Configurator call them by name) — the module exists to make
-    # the protocol *explicit* and to give "I want to implement just
-    # +configure+" extensions a free no-op +bind+ (and vice versa).
+    # default implementations of all three hooks; override the ones
+    # you need. Extensions that don't +include+ this module still
+    # work *if they define all three methods themselves* — the Agent
+    # and Configurator call them by name with no +respond_to?+ guard,
+    # so a missing one raises. The module exists to make the protocol
+    # *explicit* and to give "I want to implement just +configure+"
+    # extensions free no-op +bind+ / +on_user_message+ defaults (and
+    # any other combination).
     #
     # == Example
     #
@@ -75,6 +78,31 @@ module Pikuri
       # @param agent [Agent] the live agent, fully wired
       # @return [void]
       def bind(agent); end
+
+      # Optional per-turn hook fired by the {Agent} after a user-message
+      # is added to the chat. The
+      # default is a no-op returning +nil+; override and return {String}
+      # to emit a `:system` message with that text.
+      #
+      # == Append-only, never mutate
+      #
+      # The Agent only ever *appends* the returned block at the tail; it never
+      # rewrites or removes an earlier one. Mutating mid-log would bust the
+      # provider prefix cache for every message after the edit. Stale blocks
+      # ride the existing context-window machinery, not a per-turn rewrite.
+      #
+      # == Not inherited by sub-agents
+      #
+      # Like the rest of the extension surface, this fires on the parent agent
+      # only — sub-agents do not inherit extensions, so a persona's turns are
+      # never prefetched or recorded by the parent's memory.
+      #
+      # @param agent [Agent] the live agent whose turn this is
+      # @param content [String] the user message (initial or interloper) about
+      #   to be sent to the model
+      # @return [String, nil] an optional block of text to be injected verbatim as
+      #   a system-role message (after the user message), or +nil+ to inject nothing
+      def on_user_message(agent, content); end
     end
   end
 end

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

@@ -1,19 +1,32 @@
 # frozen_string_literal: true
 
 require 'rainbow'
-require 'tty-markdown'
 
 module Pikuri
   class Agent
     module Listener
       # Terminal renderer for the normalized event stream: dim grey
-      # reasoning, Markdown-rendered assistant content, cyan tool-
-      # call and tool-result lines, yellow fallback notice, red
-      # cancelled notice. {Event::UserTurn} is intentionally silent
+      # reasoning, assistant content printed raw (Markdown as-is),
+      # cyan tool-call and tool-result lines, yellow fallback
+      # notice, red cancelled 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}).
       #
+      # 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).
+      #
       # 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}
@@ -28,11 +41,8 @@ module Pikuri
       # - {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, *raw* — no
-      #   Markdown render. tty-markdown can't render half-finished
-      #   Markdown (broken code blocks, half-rendered tables), so
-      #   the live stream gives up formatting in exchange for
-      #   liveness.
+      # - {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
@@ -43,15 +53,6 @@ module Pikuri
       # the deltas are silently ignored and the bookend events
       # render the full text the way they always have.
       class Terminal < Base
-        # Subsystem logger; set its level with +PIKURI_LOG_TERMINAL+
-        # or the global +PIKURI_LOG+. Used for the narrow rescue
-        # around third-party rendering (+tty-markdown+ choking on
-        # assistant output) — see the CLAUDE.md "secondary to the
-        # loop" carve-out.
-        #
-        # @return [Logger]
-        LOGGER = Pikuri.logger_for('Terminal')
-
         # 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
@@ -117,12 +118,14 @@ module Pikuri
             if @streaming
               terminate_stream
             else
-              println(indent(render_markdown(content)))
+              println(indent(content))
             end
           in Event::ThinkingDelta(content:)
             stream_fragment(Rainbow(content).color(85, 85, 85)) if @streaming
           in Event::AssistantDelta(content:)
             stream_fragment(content) if @streaming
+          in Event::SystemInjected(content:)
+            println(indent(Rainbow("⊕ #{content}").color(85, 85, 85)))
           in Event::ToolCall(name:, arguments:)
             args = arguments.map { |k, v| "#{k}=#{v.inspect}" }.join(', ')
             println(indent(Rainbow("→ #{name}(#{args})").cyan))
@@ -224,23 +227,6 @@ module Pikuri
           text.to_s.each_line.map { |line| prefix + line }.join
         end
 
-        # Render assistant Markdown for the terminal, degrading to
-        # the raw string when the renderer raises. tty-markdown /
-        # strings have known bugs around ANSI inside tables (e.g.
-        # +Strings::Wrap.insert_ansi+ raising +IndexError+); we'd
-        # rather show ugly Markdown than abort an in-flight
-        # conversation.
-        #
-        # @param content [String] assistant Markdown
-        # @return [String] rendered ANSI text, or +content+
-        #   unchanged on render failure
-        def render_markdown(content)
-          TTY::Markdown.parse(content)
-        rescue StandardError => e
-          LOGGER.warn("TTY::Markdown render failed (#{e.class}: #{e.message}); falling back to raw text")
-          content
-        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