pikuri-core 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f26e9b56204d1fbbaf64390e643a26c4183b3c21d45e3dcc43984c677a09f400
-  data.tar.gz: e657171d9440ef19a53ae5ad9335c62ff34ea8db62c9753ce79352f699122f06
+  metadata.gz: 914f6e02052e97773e630e32bc9689bf7edc0eee4e962419aa41a15ca4afa667
+  data.tar.gz: e9a68c3813a0bbcd292757ee2cb4dbce6df7abc890e0d4afa6cf51cae77a6247
 SHA512:
-  metadata.gz: 4f53aef4566f6218750c58b0cac4d1015d9ae2d2a1d464481ff4eabae3d42eb560559517a105ccd6fb2128e0b8e1b9393fdea257757dd6c85af0dc7a47683ed3
-  data.tar.gz: ba4adbf32911a499111eaf26057622e94fa27511aaefb5f9fb705ac3471a20d860536d1717e6933ec3e2b55af152fbfb8b479f99e11e44ea9ad907dd1c666a66
+  metadata.gz: 3f0bdf7af9a4a85d3669b01f0929b92fdb2acbc9c7cb083611c4acaecc4d3b5b37a3e3d97a1fd060bec143016f4db00968707d149f127eb1dea5a7243dd51a73
+  data.tar.gz: cf92ad370fed6574f9cd7cc44fbd93e36c6bb03c6d56555267dc0a22a723ca9ce298231495b902570bfbbdde6b5e6b319860b2b625818eb2bdbb51d5dd2346e2

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

@@ -9,7 +9,9 @@ module Pikuri
       # 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
+      # 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}).
@@ -123,6 +125,8 @@ module Pikuri
             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))

data/lib/pikuri/agent.rb

@@ -94,8 +94,16 @@ module Pikuri
     #   queue is drained on every +after_tool_result+, each item
     #   appended as a +role: :user+ message and emitted as
     #   {Event::UserTurn} with +mid_loop: true+
+    # @param on_user_message [Proc, nil] when set, called with each
+    #   drained interloper +content+ String *after* it is appended
+    #   to the chat — the per-turn {Extension#on_user_message}
+    #   dispatch (prefetch + recording). Threaded through here rather
+    #   than fired inline so {Synthesizer.run}, which reuses this
+    #   wiring without an interloper or memory, simply passes +nil+.
+    #   Only consulted when +interloper+ is also set.
     # @return [void]
-    def self.wire_chat(chat, listeners:, step_limit: nil, cancellable: nil, interloper: nil)
+    def self.wire_chat(chat, listeners:, step_limit: nil, cancellable: nil, interloper: nil,
+                       on_user_message: nil)
       chat.after_message do |msg|
         emit_after_message(msg, listeners)
       end
@@ -106,7 +114,7 @@ module Pikuri
       end
       chat.after_tool_result do |result|
         listeners.emit(Event::ToolResult.new(content: result))
-        drain_interloper(interloper, chat, listeners) if interloper
+        drain_interloper(interloper, chat, listeners, on_user_message) if interloper
       end
     end
 
@@ -216,18 +224,29 @@ module Pikuri
 
     # Drain the interloper queue: for each pending item, append a
     # +role: :user+ message to the chat history so the next
-    # round-trip sees it, then emit an {Event::UserTurn} with
-    # +mid_loop: true+ to the listener stream so renderers see
-    # the injection.
+    # round-trip sees it, emit an {Event::UserTurn} with
+    # +mid_loop: true+ to the listener stream so renderers see the
+    # injection, then run the per-turn {Extension#on_user_message}
+    # dispatch (so mid-loop injections are prefetched + recorded
+    # exactly like initial turns).
+    #
+    # The dispatch runs *after* the +:user+ append so any
+    # +<memory-context>+ it injects lands as a +:system+ message
+    # right behind the user turn it annotates — the same
+    # append-at-the-tail ordering {#run_loop} produces for initial
+    # turns.
     #
     # @param interloper [Control::Interloper]
     # @param chat [RubyLLM::Chat]
     # @param listeners [ListenerList]
+    # @param on_user_message [Proc, nil] per-content dispatch; +nil+
+    #   skips it (e.g. an interloper with no memory extension wired)
     # @return [void]
-    def self.drain_interloper(interloper, chat, listeners)
+    def self.drain_interloper(interloper, chat, listeners, on_user_message = nil)
       interloper.drain!.each do |content|
         chat.add_message(role: :user, content: content)
         listeners.emit(Event::UserTurn.new(content: content, mid_loop: true))
+        on_user_message&.call(content)
       end
     end
     private_class_method :drain_interloper
@@ -381,71 +400,31 @@ module Pikuri
       @streaming = streaming
       @synth_answer = nil
       @on_close_handlers = []
-
-      # Single Configurator funnel for everything the block adds —
-      # tools, listeners, system-prompt snippets, extensions, and
-      # on_close handlers. See {Configurator} for the per-method
-      # contract.
-      configurator = Configurator.new(
-        transport: @transport,
-        system_prompt_base: system_prompt,
-        id: @id,
-        streaming: @streaming,
-        step_limit: @step_limit,
-        cancellable: @cancellable,
-        interloper: @interloper
-      )
-
-      block&.call(configurator)
-
-      @tools = configurator.tools.dup
-      @sub_agent_tools = configurator.sub_agent_tools.dup
-      @listeners = ListenerList.new(configurator.listeners)
-      configurator.system_prompt_additions.each do |snippet|
-        @system_prompt = "#{@system_prompt}\n\n#{snippet}"
+      # Stashed for {#run_configure}, which runs the failure-prone
+      # build phase below out of a separate method.
+      @block = block
+      @context_window = context_window
+      @llama_probe_url = llama_probe_url
+
+      # Register *before* the build phase so a mid-construction raise
+      # is still recoverable: extensions arm their cleanup via
+      # +c.on_close+ (which writes straight to +@on_close_handlers+,
+      # see {Configurator}), and the rescue below fires whatever was
+      # armed before the failure. On the happy path this registration
+      # is the at-exit backstop if the host forgets {#close}; an
+      # explicit {#close} unregisters, so the agent isn't pinned alive
+      # until process exit.
+      Pikuri::Finalizers.register(self)
+
+      begin
+        run_configure
+      rescue StandardError
+        # Half-built agent (e.g. an extension's +configure+ raised
+        # Cancelled mid-spawn). Fire the handlers armed so far, drop
+        # out of the registry, and re-raise — no partial state leaks.
+        close
+        raise
       end
-      @on_close_handlers.concat(configurator.on_close_handlers)
-      @extensions = configurator.extensions.dup
-
-      @chat = RubyLLM.chat(**@transport.to_h)
-      @chat.with_instructions(@system_prompt)
-      @tools.each { |t| @chat.with_tool(t.to_ruby_llm_tool) }
-
-      @context_window_cap = ContextWindowDetector.new(
-        override: context_window,
-        ruby_llm_reported: @chat.model.context_window,
-        llama_probe_url: llama_probe_url
-      ).detect
-
-      self.class.wire_chat(
-        @chat,
-        listeners: @listeners,
-        step_limit: @step_limit,
-        cancellable: @cancellable,
-        interloper: @interloper
-      )
-
-      # One-shot context-window cap: lets every listener that
-      # cares (notably TokenLog) pick the value off the stream
-      # before any Tokens event arrives.
-      @listeners.emit(Event::ContextCap.new(cap: @context_window_cap))
-
-      # Bind sweep — each extension gets its chance to install
-      # per-agent state (dynamic tools via #internal_add_tool,
-      # per-agent close hooks via #on_close, etc.) now that the
-      # chat is fully wired. See IDEAS.md §"Extension protocol
-      # design" for what #configure vs #bind are each for.
-      @extensions.each { |ext| ext.bind(self) }
-
-      # Fallback cleanup: if the host forgets to call #close, the
-      # at_exit hook fires it on process exit. Idempotent, so an
-      # explicit close earlier makes this a no-op. The closure
-      # captures self, which keeps the agent reachable until
-      # process exit — fine for the handful of agents a typical
-      # host creates; if pikuri grows a long-running host that
-      # constructs many short-lived agents, switch to a single
-      # process-global registry that close-then-removes.
-      at_exit { close }
     end
 
     # @return [RubyLLM::Chat] underlying chat; the extension seam
@@ -601,13 +580,23 @@ module Pikuri
         if user_message.nil? || user_message.to_s.strip.empty?
 
       @synth_answer = nil
-      @listeners.emit(Event::UserTurn.new(content: user_message, mid_loop: false))
       @step_limit&.reset!
       @cancellable&.reset!
+      # Append the user turn, emit it, then run the memory dispatch — so
+      # any <memory-context> the dispatch injects lands as a :system
+      # message *after* the user turn it annotates (append-only at the
+      # tail; see {#dispatch_ext_on_user_message}). `ask` would bundle the
+      # user-message append with completion atomically, leaving no seam to
+      # inject between them, so the two halves run explicitly here:
+      # add_message + complete (the exact pair `ask` is sugar for). A raw
+      # String content matches the interloper drain path.
+      @chat.add_message(role: :user, content: user_message)
+      @listeners.emit(Event::UserTurn.new(content: user_message, mid_loop: false))
+      dispatch_ext_on_user_message(user_message)
       if @streaming
-        @chat.ask(user_message, &self.class.streaming_block(listeners: @listeners, cancellable: @cancellable))
+        @chat.complete(&self.class.streaming_block(listeners: @listeners, cancellable: @cancellable))
       else
-        @chat.ask(user_message)
+        @chat.complete
       end
       nil
     rescue Control::Cancellable::Cancelled
@@ -661,6 +650,10 @@ module Pikuri
       return if @closed
 
       @closed = true
+      # Drop out of the process-global registry first: a deliberate
+      # close means this agent no longer needs the at-exit fallback,
+      # and removing the reference lets it be garbage-collected.
+      Pikuri::Finalizers.unregister(self)
       @on_close_handlers.reverse_each do |handler|
         handler.call
       rescue StandardError => e
@@ -719,5 +712,113 @@ module Pikuri
     def to_s
       "Agent(id=#{@id}, model=#{model}, tools=#{@tools.size}, listeners=#{@listeners})"
     end
+
+    private
+
+    # The failure-prone build phase, split out of {#initialize} so the
+    # constructor can wrap it in a rescue and self-heal. Funnels the
+    # +Agent.new+ block through a single {Configurator} — tools,
+    # listeners, system-prompt snippets, extensions, and +on_close+
+    # handlers — then wires the chat and runs the extension +bind+
+    # sweep. The Configurator's +on_close_sink:+ is +@on_close_handlers+
+    # itself, so a handler an extension arms via +c.on_close+ is live on
+    # the agent the instant it's registered — that's what lets the
+    # constructor's rescue close a half-built agent.
+    #
+    # @return [void]
+    def run_configure
+      configurator = Configurator.new(
+        transport: @transport,
+        system_prompt_base: @system_prompt,
+        id: @id,
+        streaming: @streaming,
+        step_limit: @step_limit,
+        cancellable: @cancellable,
+        interloper: @interloper,
+        on_close_sink: @on_close_handlers
+      )
+
+      @block&.call(configurator)
+
+      @tools = configurator.tools.dup
+      @sub_agent_tools = configurator.sub_agent_tools.dup
+      @listeners = ListenerList.new(configurator.listeners)
+      configurator.system_prompt_additions.each do |snippet|
+        @system_prompt = "#{@system_prompt}\n\n#{snippet}"
+      end
+      @extensions = configurator.extensions.dup
+
+      @chat = RubyLLM.chat(**@transport.to_h)
+      @chat.with_instructions(@system_prompt)
+      @tools.each { |t| @chat.with_tool(t.to_ruby_llm_tool) }
+
+      @context_window_cap = ContextWindowDetector.new(
+        override: @context_window,
+        ruby_llm_reported: @chat.model.context_window,
+        llama_probe_url: @llama_probe_url,
+        model_id: @chat.model.id
+      ).detect
+
+      self.class.wire_chat(
+        @chat,
+        listeners: @listeners,
+        step_limit: @step_limit,
+        cancellable: @cancellable,
+        interloper: @interloper,
+        on_user_message: method(:dispatch_ext_on_user_message)
+      )
+
+      # One-shot context-window cap: lets every listener that
+      # cares (notably TokenLog) pick the value off the stream
+      # before any Tokens event arrives.
+      @listeners.emit(Event::ContextCap.new(cap: @context_window_cap))
+
+      # Bind sweep — each extension gets its chance to install
+      # per-agent state (dynamic tools via #internal_add_tool,
+      # per-agent close hooks via #on_close, etc.) now that the
+      # chat is fully wired. See IDEAS.md §"Extension protocol
+      # design" for what #configure vs #bind are each for.
+      @extensions.each { |ext| ext.bind(self) }
+    end
+
+    # Fire the per-turn {Extension#on_user_message} hook on every
+    # extension that defines it, appending any returned
+    # +<memory-context>+ block to the chat as a +role: :system+
+    # message right after the user turn it annotates (callers append
+    # the +:user+ message first; this runs last). The system role is
+    # load-bearing — it tags the block as recalled reference (not new
+    # input) and keeps it excludable from a later extraction pass.
+    # See {Extension#on_user_message}.
+    #
+    # Each injected block also emits an {Event::SystemInjected} at
+    # this site, so the listener stream mirrors the log growth (the
+    # Terminal renders it; otherwise an injection would be invisible
+    # except as a downstream echo in the assistant's reasoning).
+    #
+    # Private and the single place the chat log grows by a memory
+    # block — keeps "what mutates the log, when" one grep in this
+    # file. Fired from {#run_loop} (initial turn) and, via the
+    # +on_user_message:+ proc threaded into {.wire_chat}, from
+    # {.drain_interloper} (mid-loop interlopers). Called on every
+    # extension unconditionally — same as {Extension#configure} /
+    # {Extension#bind}: the hook is part of the protocol and the
+    # {Extension} module supplies a no-op default, so any extension
+    # that includes the module responds. An extension is "opted out"
+    # by leaving the default in place (it returns +nil+, injecting
+    # nothing), not by omitting the method.
+    #
+    # @param content [String] the incoming user message
+    # @return [void]
+    def dispatch_ext_on_user_message(content)
+      @extensions.each do |ext|
+        message = ext.on_user_message(self, content)
+        next unless message.is_a?(String) && !message.strip.empty?
+
+        block = message.strip
+        @chat.add_message(role: :system, content: block)
+        @listeners.emit(Event::SystemInjected.new(content: block))
+      end
+      nil
+    end
   end
 end

data/lib/pikuri/file_type.rb

@@ -21,6 +21,15 @@ module Pikuri
   #   The pure-extraction shape consumers like +Pikuri::VectorDb+'s
   #   indexer want (no LLM-tool concerns — no paging, no line
   #   numbering, no byte caps; just bytes-in-text-out).
+  # * {.read_as_text_paged} — the LLM-tool shape: the same
+  #   extraction as {.read_as_text}, but lazily windowed to a
+  #   line range with a byte cap, returning a {Page} value the
+  #   caller renders. Shared by +Workspace::Read+ and
+  #   +VectorDb::Tools::Read+ so the offset/limit/byte-cap windowing lives
+  #   in one tested place; each tool keeps its own presentation
+  #   (cat-n numbering, trailer wording, citation vs. path). Same
+  #   refusal contract as {.read_as_text} (raises on image / binary
+  #   / missing / malformed-PDF).
   #
   # {.detect_mime} and {.binary?} accept either a +String+ of bytes
   # (sample taken by the caller) or a +Pathname+ — when given a path,
@@ -85,6 +94,58 @@ module Pikuri
     #   with this five-byte ASCII sequence per ISO 32000-1 §7.5.2.
     PDF_MAGIC = '%PDF-'
 
+    # @return [Integer] default line-window size for
+    #   {.read_as_text_paged} when the caller omits +limit+.
+    PAGE_DEFAULT_LIMIT = 2000
+
+    # @return [Integer] default hard byte cap on the content collected
+    #   by a single {.read_as_text_paged} call. Bypassable by paging
+    #   via +offset+. The rendered output is slightly larger (line
+    #   numbering, trailer) — that's the caller's concern.
+    PAGE_MAX_BYTES = 50 * 1024
+
+    # @return [Integer] default per-line character cap;
+    #   {.read_as_text_paged} truncates longer lines and appends
+    #   {PAGE_LINE_TRUNCATION_MARKER}.
+    PAGE_MAX_LINE_LENGTH = 2000
+
+    # @return [String] suffix appended to a line truncated at
+    #   {PAGE_MAX_LINE_LENGTH}.
+    PAGE_LINE_TRUNCATION_MARKER = "... (line truncated to #{PAGE_MAX_LINE_LENGTH} chars)"
+
+    # One windowed slice of a document, returned by
+    # {.read_as_text_paged}. The caller turns this into an
+    # observation; this struct carries everything a trailer needs
+    # without the caller re-reading the file.
+    #
+    # == Fields
+    #
+    # * +lines+ — +Array<String>+, the collected window. Already
+    #   per-line truncated (with {PAGE_LINE_TRUNCATION_MARKER}); *not*
+    #   line-numbered — numbering is presentation the caller adds. For
+    #   a PDF the array includes +"--- Page N ---"+ marker lines (one
+    #   per page that contributed text), which count toward +limit+ /
+    #   the byte cap like any other line.
+    # * +start_line+ — the 1-indexed line number of +lines.first+
+    #   (i.e. the +offset+ the caller asked for). +lines.last+ is at
+    #   +start_line + lines.length - 1+.
+    # * +total_lines+ — total line count of the document when known,
+    #   else +nil+. Known when extraction reached EOF (so the caller
+    #   can print "of N"); +nil+ when the read stopped early — the
+    #   byte cap fired, or a PDF filled the window before its last
+    #   page (counting the rest would defeat the laziness).
+    # * +more+ — +true+ if content remains past this window (the
+    #   caller should offer +offset = start_line + lines.length+).
+    # * +byte_capped+ — +true+ if {PAGE_MAX_BYTES} (not the line
+    #   limit) was the stopping criterion.
+    # * +kind+ — +:text+ or +:pdf+; lets the caller word PDF-specific
+    #   trailers and the empty-document message.
+    #
+    # An empty document yields +lines: []+, +total_lines: 0+; an
+    # +offset+ past EOF yields +lines: []+ with +total_lines+ set to
+    # the real (non-zero) count — the caller distinguishes the two.
+    Page = Data.define(:lines, :start_line, :total_lines, :more, :byte_capped, :kind)
+
     # Recognise a file from its leading bytes. Returns the MIME type
     # as a String for formats pikuri handles specially, or +nil+ for
     # "unrecognised" — callers interpret +nil+ themselves (text,
@@ -208,6 +269,165 @@ module Pikuri
     end
     private_class_method :read_pdf_text
 
+    # Extract +path+ as text and return a windowed {Page}: the lines
+    # from +offset+ (1-indexed) up to +limit+ of them, stopping early
+    # if +max_bytes+ is reached, with over-long lines truncated at
+    # +max_line_length+. Lazy by design — a text file is streamed
+    # line-by-line and a PDF is parsed page-by-page only until the
+    # window fills, so reading the first page of a 500-page PDF parses
+    # a handful of pages, not all of them.
+    #
+    # Same routing and refusal contract as {.read_as_text}: PDFs are
+    # extracted (with +"--- Page N ---"+ marker lines, unlike
+    # {.read_as_text}'s marker-free join — paging is a display path,
+    # the marker-free form stays the indexing path); images, binaries,
+    # directories, missing files, and malformed PDFs all raise rather
+    # than returning a sentinel. The LLM-facing callers map those into
+    # +"Error: ..."+ observations themselves.
+    #
+    # @param path [Pathname] file to read.
+    # @param offset [Integer] 1-indexed first line to include. The
+    #   caller is responsible for validating +offset >= 1+.
+    # @param limit [Integer] maximum lines to collect. Caller
+    #   validates +limit >= 1+.
+    # @param max_bytes [Integer] hard byte cap on collected content.
+    # @param max_line_length [Integer] per-line truncation threshold.
+    # @return [Page] the windowed slice.
+    # @raise [ArgumentError] if +path+ isn't a +Pathname+, is a
+    #   directory, an image, or binary.
+    # @raise [Errno::ENOENT] if +path+ doesn't exist.
+    # @raise [RuntimeError] on a malformed / unsupported PDF.
+    def read_as_text_paged(path, offset: 1, limit: PAGE_DEFAULT_LIMIT,
+                           max_bytes: PAGE_MAX_BYTES, max_line_length: PAGE_MAX_LINE_LENGTH)
+      raise ArgumentError, "expected Pathname, got #{path.class}" unless path.is_a?(Pathname)
+      raise Errno::ENOENT, path.to_s unless path.exist?
+      raise ArgumentError, "#{path} is a directory" if path.directory?
+
+      mime = detect_mime(path)
+      if mime == 'application/pdf'
+        return paged_pdf(path, offset: offset, limit: limit,
+                               max_bytes: max_bytes, max_line_length: max_line_length)
+      end
+      raise ArgumentError, "#{path} is an image (#{mime}); cannot extract as text" if mime&.start_with?('image/')
+      raise ArgumentError, "#{path} appears to be binary; cannot extract as text" if binary?(path)
+
+      paged_text(path, offset: offset, limit: limit,
+                       max_bytes: max_bytes, max_line_length: max_line_length)
+    end
+
+    # Stream a text file line-by-line into a {Page}. Keeps counting
+    # lines past the collection window so +total_lines+ can report the
+    # real total when the line limit (not the byte cap) stopped
+    # collection; on the byte cap it breaks and leaves +total_lines+
+    # +nil+ (the rest of the file is never read).
+    #
+    # @return [Page] +kind: :text+.
+    def paged_text(path, offset:, limit:, max_bytes:, max_line_length:)
+      start_index = offset - 1
+      collected   = []
+      total_lines = 0
+      bytes       = 0
+      byte_capped = false
+      more        = false
+
+      path.each_line do |raw|
+        total_lines += 1
+        next if total_lines <= start_index
+
+        if collected.length >= limit
+          more = true
+          next
+        end
+
+        line = truncate_line(raw.chomp, max_line_length)
+        size = line.bytesize + 1 # +1 for the joining newline
+        if bytes + size > max_bytes
+          byte_capped = true
+          more = true
+          break
+        end
+        collected << line
+        bytes += size
+      end
+
+      Page.new(lines: collected, start_line: offset,
+               total_lines: byte_capped ? nil : total_lines,
+               more: more, byte_capped: byte_capped, kind: :text)
+    end
+    private_class_method :paged_text
+
+    # PDF counterpart to {paged_text}: walk +pdf-reader+'s lazy page
+    # iterator, emitting a +"--- Page N ---"+ header line then each
+    # line of the page's text, applying the same offset / limit /
+    # byte-cap contract. The +throw :done+ short-circuits both loops
+    # the moment the window fills, so parsing stops — which is why a
+    # PDF that stops early can't report +total_lines+ (it would have
+    # to parse every page to count).
+    #
+    # @return [Page] +kind: :pdf+.
+    # @raise [RuntimeError] on a malformed / unsupported PDF.
+    def paged_pdf(path, offset:, limit:, max_bytes:, max_line_length:)
+      start_index = offset - 1
+      collected   = []
+      total_lines = 0
+      bytes       = 0
+      byte_capped = false
+      more        = false
+
+      catch(:done) do
+        path.open('rb') do |io|
+          reader = ::PDF::Reader.new(io)
+          reader.pages.each_with_index do |page, idx|
+            text = page.text.strip
+            next if text.empty?
+
+            ["--- Page #{idx + 1} ---", *text.split("\n")].each do |raw|
+              total_lines += 1
+              next if total_lines <= start_index
+
+              if collected.length >= limit
+                more = true
+                throw :done
+              end
+
+              line = truncate_line(raw, max_line_length)
+              size = line.bytesize + 1
+              if bytes + size > max_bytes
+                byte_capped = true
+                more = true
+                throw :done
+              end
+              collected << line
+              bytes += size
+            end
+          end
+        end
+      end
+
+      Page.new(lines: collected, start_line: offset,
+               total_lines: more ? nil : total_lines,
+               more: more, byte_capped: byte_capped, kind: :pdf)
+    rescue ::PDF::Reader::MalformedPDFError,
+           ::PDF::Reader::InvalidPageError,
+           ::PDF::Reader::UnsupportedFeatureError => e
+      raise "Cannot extract PDF text from #{path}: " \
+            "#{e.class.name.split('::').last}: #{e.message}"
+    end
+    private_class_method :paged_pdf
+
+    # Truncate +line+ to +max_line_length+ chars, appending
+    # {PAGE_LINE_TRUNCATION_MARKER} when it overflows.
+    #
+    # @param line [String]
+    # @param max_line_length [Integer]
+    # @return [String]
+    def truncate_line(line, max_line_length)
+      return line if line.length <= max_line_length
+
+      line[0, max_line_length] + PAGE_LINE_TRUNCATION_MARKER
+    end
+    private_class_method :truncate_line
+
     # Coerce an +input+ argument into a bytes String for the sniffs.
     # +String+ inputs are returned as-is (caller already sampled);
     # +Pathname+ inputs are opened in binary mode and up to

data/lib/pikuri/finalizers.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Pikuri
+  # Process-global teardown registry: one +at_exit+ for the whole
+  # process, with everything that owns a resource needing orderly
+  # shutdown (agents, {VectorDb::Server::Chroma}, future background
+  # workers) registering here instead of growing its own +at_exit+.
+  # It is {Agent#on_close} promoted from per-agent to per-process —
+  # the same LIFO + per-handler-rescue + idempotent shape, one level
+  # up.
+  #
+  # == Why one chokepoint
+  #
+  # Independent +at_exit+ hooks fire in an order decided by file load
+  # order, which is invisible and fragile. Routing every teardown
+  # through one registry makes the order explicit and controllable:
+  # the SIGTERM-the-strays backstop ({Subprocess.cleanup!}) registers
+  # at *load* time, so it sits at the bottom of the LIFO stack and runs
+  # *last* — after agents and servers (which register at *construction*
+  # time) have closed gracefully, while the subprocess machinery they
+  # shell out to during close (e.g. {VectorDb::Server::Chroma#close}'s
+  # +docker stop+) is still live.
+  #
+  # == Contract
+  #
+  # A registrant MUST respond to +#close+, and +#close+ MUST be
+  # idempotent and tolerant of running at process exit — the host may
+  # also have closed it explicitly earlier. Pass a block instead for
+  # teardown that has no natural +#close+ (e.g.
+  # +Finalizers.register { Pikuri::Subprocess.cleanup! }+).
+  #
+  # == Order: LIFO
+  #
+  # Last registered, first closed — Ruby +ensure+ semantics. A
+  # registrant that depends on an earlier one (a background indexer
+  # writing into {VectorDb::Server::Chroma}) is registered later and so
+  # tears down first. Registration order is therefore dependency order;
+  # register the dependency before its dependents.
+  #
+  # == Errors are contained
+  #
+  # Each +#close+ runs inside its own +rescue+: a raise is logged via
+  # {Pikuri.logger_for} and the sweep continues, so one botched
+  # teardown can't strand the rest. {.run!} drains the registry, so a
+  # second call (an explicit one, then the +at_exit+) closes nothing.
+  module Finalizers
+    # @return [Logger] subsystem logger for contained teardown failures.
+    LOGGER = Pikuri.logger_for('Finalizers')
+
+    # Adapts a teardown block to the +#close+ protocol, so a block and a
+    # closeable object can share one registry.
+    Closer = Struct.new(:block) do
+      # @return [void]
+      def close
+        block.call
+      end
+    end
+
+    @registered = []
+    @mutex      = Mutex.new
+
+    class << self
+      # Register a closeable (or a block) to be torn down at process
+      # exit. Returns the registered handle so the caller can later
+      # {.unregister} it — a resource closed explicitly before exit
+      # should drop out so it can be garbage-collected rather than
+      # pinned alive until the process dies.
+      #
+      # @param closeable [#close, nil] resource to close at exit; omit
+      #   when passing a block
+      # @yield teardown to run at exit, for resources with no +#close+
+      # @return [#close] the registered handle — the object itself, or
+      #   the {Closer} wrapping the block; pass it to {.unregister}
+      # @raise [ArgumentError] if neither an object nor a block is given
+      def register(closeable = nil, &block)
+        unless closeable || block
+          raise ArgumentError, 'Finalizers.register requires an object or a block'
+        end
+
+        handle = closeable || Closer.new(block)
+        @mutex.synchronize { @registered << handle }
+        handle
+      end
+
+      # Drop a previously-registered handle. Idempotent — unregistering
+      # something already gone (or never registered) is a no-op.
+      #
+      # @param handle [#close] the value returned by {.register}
+      # @return [void]
+      def unregister(handle)
+        @mutex.synchronize { @registered.delete(handle) }
+        nil
+      end
+
+      # Close every registrant in LIFO order, each guarded by its own
+      # +rescue+. Wired to +at_exit+ at the bottom of this file.
+      # Draining the registry under the lock makes a repeat call a
+      # no-op and keeps it safe against a concurrent caller.
+      #
+      # @return [void]
+      def run!
+        handles = @mutex.synchronize do
+          taken = @registered.reverse
+          @registered.clear
+          taken
+        end
+
+        handles.each do |handle|
+          handle.close
+        rescue StandardError => e
+          LOGGER.warn("finalizer #{handle.class} raised #{e.class}: #{e.message}")
+        end
+      end
+    end
+  end
+end
+
+at_exit { Pikuri::Finalizers.run! }

data/lib/pikuri/paths.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+module Pikuri
+  # Standardized on-disk locations for pikuri's local state. Centralizes
+  # the XDG resolution so every component that caches to disk roots under
+  # one place instead of each re-deriving it — currently
+  # {Pikuri::VectorDb::Server::Chroma} (its corpus volume) and
+  # {Pikuri::Memory::Mem0Server} (its mem0 checkout + data volume).
+  module Paths
+    # Pikuri's cache root: +$XDG_CACHE_HOME/pikuri+ when +XDG_CACHE_HOME+
+    # is set and non-empty, else +~/.cache/pikuri+.
+    #
+    # A method, not a frozen constant, on purpose: a constant would
+    # snapshot +XDG_CACHE_HOME+ at +require+ time, which breaks
+    # env-stubbing in tests and ignores a runtime change in a long-lived
+    # process. The directory is *not* created — callers +mkdir_p+ the
+    # subdirectory they need (e.g. +Paths.cache.join('chroma')+,
+    # +Paths.cache.join('mem0')+).
+    #
+    # @return [Pathname] the +<cache home>/pikuri+ directory
+    def self.cache
+      home = ENV['XDG_CACHE_HOME']
+      home = File.expand_path('~/.cache') if home.nil? || home.empty?
+      Pathname.new(home).join('pikuri')
+    end
+  end
+end

data/lib/pikuri/subprocess.rb

@@ -15,8 +15,10 @@ module Pikuri
   # All subprocess spawning in +lib/+ goes through {.spawn}. Direct
   # +Process.spawn+ / +Open3.*+ / +system+ / backticks anywhere in
   # +lib/+ are bugs. The convention is grep-enforceable:
-  # +grep -rn 'Process\.spawn\|Open3\|system\|backtick' lib/+ should
-  # only hit this file.
+  # +grep -rnE 'Process\.spawn|Open3\.|\bsystem\(' lib/+ should
+  # only hit this file (plus the comment in
+  # +pikuri-mcp/lib/pikuri/mcp/servers.rb+ explaining the MCP
+  # exception).
   #
   # == Timeouts are the caller's job
   #
@@ -47,10 +49,11 @@ module Pikuri
   #
   # == State is process-global
   #
-  # One +@active+ Set and one +at_exit+ for the whole process. A
-  # +Mutex+ guards register/prune/cleanup; v1 is single-threaded, so
-  # this is more for the +at_exit+/register race than for current
-  # callers.
+  # One +@active+ Set for the whole process, swept once at exit via
+  # {Pikuri::Finalizers} (see the registration at the bottom of this
+  # file). A +Mutex+ guards register/prune/cleanup; v1 is
+  # single-threaded, so this is more for the exit-sweep/register race
+  # than for current callers.
   #
   # == Why +Pikuri::Subprocess+, not top-level
   #
@@ -122,6 +125,23 @@ module Pikuri
       self.class.send(:prune, @pgid)
     end
 
+    # SIGTERM the whole process group without blocking for output —
+    # the stop button for a *daemon* child (one the caller never
+    # {#wait}s on, e.g. {Pikuri::Memory::Mem0Server}'s socat relay).
+    # Best-effort and idempotent: an already-dead group is a no-op.
+    # The group stays in the exit-sweep set until it actually dies,
+    # so a child that ignores SIGTERM is still re-signalled by
+    # {.cleanup!} at process exit.
+    #
+    # @return [void]
+    def terminate
+      Process.kill('-TERM', @pgid)
+    rescue Errno::ESRCH
+      # already gone
+    ensure
+      self.class.send(:prune, @pgid)
+    end
+
     class << self
       # Currently-tracked process groups, with dead ones pruned as a
       # side effect. Useful for a future +/bg+ REPL command or a
@@ -135,9 +155,9 @@ module Pikuri
         end
       end
 
-      # SIGTERM every tracked process group. Used by +at_exit+
-      # (production) and +after+ blocks (specs). Best-effort —
-      # ignores errors from already-dead groups.
+      # SIGTERM every tracked process group. Run at process exit via
+      # {Pikuri::Finalizers} (production) and from +after+ blocks
+      # (specs). Best-effort — ignores errors from already-dead groups.
       #
       # @return [void]
       def cleanup!
@@ -170,4 +190,10 @@ module Pikuri
   end
 end
 
-at_exit { Pikuri::Subprocess.cleanup! }
+# Registered at load (boot) — before any agent or server registers at
+# construction time — so in {Pikuri::Finalizers}' LIFO sweep this runs
+# LAST: graceful +#close+ on agents and servers first, then SIGTERM
+# whatever child groups are still alive. The reaper, not a peer. (Was a
+# standalone +at_exit+; routed through Finalizers so the order relative
+# to every other teardown is controlled, not left to file load order.)
+Pikuri::Finalizers.register { Pikuri::Subprocess.cleanup! }

data/lib/pikuri/version.rb

@@ -6,5 +6,5 @@ module Pikuri
   # additions to the public surface (+Pikuri::Tool+ / +Pikuri::Agent+ /
   # listeners / bundled tools), major for breaking changes to that
   # surface or to the +bin/pikuri-*+ CLIs.
-  VERSION = '0.0.4'
+  VERSION = '0.0.5'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pikuri-core
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors:
 - Martin Vysny
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-29 00:00:00.000000000 Z
+date: 2026-06-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dentaku
@@ -200,6 +200,8 @@ files:
 - lib/pikuri/agent/listener_list.rb
 - lib/pikuri/agent/synthesizer.rb
 - lib/pikuri/file_type.rb
+- lib/pikuri/finalizers.rb
+- lib/pikuri/paths.rb
 - lib/pikuri/subprocess.rb
 - lib/pikuri/tool.rb
 - lib/pikuri/tool/calculator.rb