pikuri-core 0.0.6 → 0.1.0

data/lib/pikuri/agent/context_window_detector.rb

@@ -1,59 +1,49 @@
 # frozen_string_literal: true
 
+require 'ruby_llm'
 require 'faraday'
 require 'json'
 require 'cgi'
 
 module Pikuri
   class Agent
-    # Resolves the model's context-window cap from three sources, in order:
-    # an explicit override, the value ruby_llm reports for the model, or a
-    # llama.cpp +/props+ probe. Returns +nil+ if none of those produce a
-    # value.
+    # Resolves the model's context-window cap by asking the server that serves
+    # it. The only authoritative runtime source is llama.cpp's non-standard
+    # +/props+ endpoint, reporting the server's *launched* +n_ctx+ (the real
+    # window — possibly smaller than the model's max, e.g. +llama-server -c
+    # 8192+ on a 128k model). Returns +nil+ — an honest "we don't know" — for
+    # anything else. {Agent#detect_and_emit_context_cap!} calls it only when
+    # the transport carries no explicit {ChatTransport#context_window}.
     #
-    # Used by {Agent#initialize} at construction time to feed
-    # {Listener::TokenLog} a cap it can render alongside the running
-    # context size (so the +ctx=12.2k/32.0k+ line tells the operator how
-    # close the conversation is to the limit).
+    # This probe and an explicit {ChatTransport#context_window} are the *only*
+    # sources: +RubyLLM::Model::Info#context_window+ is deliberately never
+    # consulted (why: +DECISIONS.md+ +D_context_window_sources+).
     #
-    # == Precedence
+    # == The openai-provider gate + auto-derived URL
     #
-    # 1. +override+ — the +Agent.new(context_window:)+ kwarg. Wins over
-    #    everything; an explicit value is the operator's statement of
-    #    truth.
-    # 2. +ruby_llm_reported+ — +RubyLLM::Model::Info#context_window+ from
-    #    {Agent#chat}'s resolved model. Populated for models in ruby_llm's
-    #    bundled registry (OpenAI, Anthropic, Gemini, …); +nil+ for custom
-    #    local model ids that fall through to +Model::Info.default+.
-    # 3. +llama_probe_url+ — HTTP GET against llama.cpp's non-standard
-    #    +/props+ endpoint. The server exposes the launched +n_ctx+ at
-    #    +default_generation_settings.n_ctx+ there. Probed only when the
-    #    first two are +nil+. Provider-specific to llama.cpp; the caller
-    #    (typically +bin/pikuri-chat+) derives the right URL from its configured
-    #    base.
+    # The probe only makes sense against an OpenAI-compatible local server
+    # (llama.cpp) via ruby_llm's +:openai+ provider, so {.detect} runs only for
+    # +transport.provider == :openai+ and derives the URL from the *same*
+    # +RubyLLM.config.openai_api_base+ the chat uses (+/props+ is at the host
+    # root, so the +/v1+ suffix is stripped) — so it can't target a different
+    # server than the chat. A bare +:openai+ at real +api.openai.com+ gets one
+    # fast +/props+ 404 that degrades to +nil+.
     #
     # == 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.
+    # A llama.cpp *router* (the multi-instance front) answers a bare +/props+
+    # with +{"role":"router", ..., "n_ctx":0}+ — no single loaded model. The
+    # real per-model cap is one hop away: +GET /props?model=<id>+ routes to that
+    # model's instance. So when the bare probe reports +role: router+ and a
+    # +model_id+ is known, this re-probes with the id. A plain single-model
+    # server (bare +/props+ already positive) never hits this branch.
     #
     # == Failure handling
     #
-    # The probe is best-effort. HTTP error, timeout, non-JSON body, or a
-    # missing/invalid +n_ctx+ field all return +nil+ and log one +warn+
-    # line via +Pikuri.logger_for('ContextWindowDetector')+. This is the
-    # CLAUDE.md "secondary to the loop" carve-out — a wedged or
-    # non-llama.cpp server should not abort agent construction over a
-    # cosmetic readout.
+    # Best-effort: HTTP error, timeout, non-JSON body, or a missing/invalid
+    # +n_ctx+ all return +nil+ with one +warn+ line. The CLAUDE.md
+    # "secondary to the loop" carve-out — a wedged or non-llama.cpp server must
+    # not abort agent construction over a cosmetic readout.
     class ContextWindowDetector
       # Subsystem logger; set its level with
       # +PIKURI_LOG_CONTEXTWINDOWDETECTOR+ or the global +PIKURI_LOG+.
@@ -61,49 +51,69 @@ module Pikuri
       # @return [Logger]
       LOGGER = Pikuri.logger_for('ContextWindowDetector')
 
-      # Connect timeout in seconds for the llama.cpp +/props+ probe.
-      # Short on purpose: this runs synchronously during +Agent.new+ and
-      # a wedged server should not stall startup noticeably.
+      # Connect timeout (s) for the +/props+ probe. Short: a server that isn't
+      # listening should fail fast rather than stall {Agent} construction.
       #
       # @return [Integer]
       OPEN_TIMEOUT = 2
-      # Read timeout in seconds for the llama.cpp +/props+ probe; matches
-      # {OPEN_TIMEOUT} for the same reason.
+      # Read timeout (s) for the +/props+ probe — generous, unlike
+      # {OPEN_TIMEOUT}: a router answers +/props?model=<id>+ only after spinning
+      # up that model's instance, and a cold load can take 10+s (which the next
+      # chat turn must wait for anyway). A shorter timeout would lose the cap
+      # exactly when switching to a cold model.
       #
       # @return [Integer]
-      READ_TIMEOUT = 2
-
-      # @param override [Integer, nil] explicit cap from the caller; wins if
-      #   non-+nil+
-      # @param ruby_llm_reported [Integer, nil] value off
-      #   +RubyLLM::Chat#model.context_window+
-      # @param llama_probe_url [String, nil] full URL to llama.cpp +/props+;
-      #   +nil+ or empty string skips the probe
-      # @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
+      READ_TIMEOUT = 30
+
+      # Resolve the context-window cap for +transport+ by probing its server.
+      #
+      # @param transport [Agent::ChatTransport] +provider+ gates the probe,
+      #   +model+ drives the router +?model=+ hop
+      # @param openai_base [String, nil] base URL the probe URL derives from;
+      #   defaults to the live +RubyLLM.config.openai_api_base+ (passed
+      #   explicitly only by tests, to avoid mutating global config)
+      # @return [Integer, nil] the launched +n_ctx+, or +nil+ for a
+      #   non-+:openai+ transport, unconfigured base, or any probe failure
+      def self.detect(transport, openai_base: RubyLLM.config.openai_api_base)
+        return nil unless transport.provider == :openai
+
+        url = props_url(openai_base)
+        return nil if url.nil?
+
+        new(probe_url: url, model_id: transport.model).probe
       end
 
-      # @return [Integer, nil] resolved cap, or +nil+ if no source produced
-      #   one
-      def detect
-        return @override if @override
-        return @ruby_llm_reported if @ruby_llm_reported
-        return nil if @llama_probe_url.nil? || @llama_probe_url.empty?
+      # Derive the +/props+ URL from the OpenAI-compatible base (+/props+ is at
+      # the host root, so a trailing +/v1+ is stripped).
+      #
+      # @param openai_base [String, nil]
+      # @return [String, nil] the +/props+ URL, or +nil+ when the base is blank
+      def self.props_url(openai_base)
+        base = openai_base.to_s.strip.chomp('/')
+        return nil if base.empty?
+
+        "#{base.delete_suffix('/v1')}/props"
+      end
+
+      # @param probe_url [String] full URL to llama.cpp +/props+
+      # @param model_id [String, nil] the chat model id, used 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(probe_url:, model_id:)
+        @probe_url = probe_url
+        @model_id = model_id
+      end
 
+      # @return [Integer, nil] resolved cap, or +nil+ if the probe
+      #   produced none
+      def probe
         probe_llama_cpp
       end
 
       private
 
       def probe_llama_cpp
-        data = fetch_props(@llama_probe_url)
+        data = fetch_props(@probe_url)
         return nil if data.nil?
 
         n_ctx = positive_n_ctx(data)
@@ -114,12 +124,12 @@ module Pikuri
         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"
+          "no positive integer at default_generation_settings.n_ctx in #{@probe_url} response"
         )
       end
 
       def probe_router_model
-        url = "#{@llama_probe_url}?model=#{CGI.escape(@model_id)}"
+        url = "#{@probe_url}?model=#{CGI.escape(@model_id)}"
         data = fetch_props(url)
         return nil if data.nil?
 

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

@@ -3,112 +3,133 @@
 module Pikuri
   class Agent
     module Control
-      # Cooperative cancellation token. The instance is normally
-      # constructed on the main thread and handed to
-      # {Agent#initialize} via the +cancellable:+ kwarg; an
-      # out-of-band caller (a SIGINT trap, a TUI key binding, an
-      # IPC handler) calls {#cancel!} to flip the flag, and the
-      # next {#check!} on the run thread raises {Cancelled} —
-      # which {Agent#run_loop} catches, normalizes into an
-      # {Event::Cancelled} on the listener stream, and re-raises
-      # so the caller's REPL can return control to the user.
+      # Cooperative cancellation token. Built on the main thread and handed to
+      # {Agent#initialize} via +cancellable:+; an out-of-band caller (a SIGINT
+      # trap, a TUI key, an IPC handler) calls {#cancel!} to flip the flag, and
+      # the next {#check!} on the run thread raises {Cancelled} — which
+      # {Agent#run_loop} catches, emits as {Event::Cancelled}, and re-raises so
+      # the REPL returns control to the user.
       #
       # == Cancellation boundary
       #
-      # The +Agent+ calls {#check!} from its +before_tool_call+
-      # wiring — between an LLM response that requested a tool
-      # and the actual tool invocation — which is the only point
-      # at which the conversation state is consistent (no
-      # in-flight subprocess, no half-applied write). An in-flight
-      # LLM HTTP call is *not* interrupted; the response lands,
-      # then the next tool-call boundary trips. An in-flight tool
-      # (notably +Bash+) is also not interrupted — cancellation
-      # lands after the tool returns. Both are intentional v1
-      # scope: the "gentle cancel" semantic that pikuri promises.
+      # The +Agent+ calls {#check!} from +before_tool_call+ — between an LLM
+      # response requesting a tool and the tool invocation — the only point
+      # where conversation state is consistent (no in-flight subprocess, no
+      # half-applied write). An in-flight LLM HTTP call is *not* interrupted
+      # (the response lands, then the next boundary trips), nor is an in-flight
+      # tool (notably +Bash+). Both are the intentional "gentle cancel" v1 scope.
       #
-      # == Thread safety
-      #
-      # {#cancel!} is intended to be called from a thread other
-      # than the one running {Agent#run_loop} (the typical case
-      # is a SIGINT trap handler on the main thread while the
-      # agent runs on a worker, or vice versa). A plain boolean
-      # ivar is sufficient under MRI: writes and reads of a
-      # single reference are atomic with respect to the GVL, and
-      # the only state transition we care about is +false → true+
-      # before the next {#check!} fires. There is no double-cancel
-      # hazard; repeated {#cancel!} calls are idempotent.
+      # {#sleep} widens that boundary by one case: code *waiting* inside a tool
+      # can wait through this instead of +Kernel#sleep+ and become
+      # interruptible. It reaches waits only — a thread blocked in IO (a Faraday
+      # read, +Subprocess#wait+) is still uninterruptible, so most of a tool's
+      # blocking is untouched by design.
       #
       # == Sub-agent semantics
       #
-      # Cancellation is a global "stop the whole tree" signal —
-      # the +agent+ tool from +pikuri-subagents+ shares the
-      # parent's +Cancellable+ by reference when spawning a child,
-      # so one {#cancel!} call stops the parent, every running
-      # sub-agent, and the synthesizer rescue. The sharing rule
-      # lives at the spawn site (sub-agent code), not on this
-      # class.
+      # Cancellation is a global "stop the whole tree" signal — the +agent+ tool
+      # shares the parent's +Cancellable+ by reference with each child, so one
+      # {#cancel!} stops the parent, every sub-agent, and the synthesizer. The
+      # sharing rule lives at the spawn site, not here.
+      #
+      # Thread-safe: {#cancel!} is meant to run on a thread other than the loop's
+      # (a SIGINT trap while the agent runs on a worker). A plain boolean ivar
+      # suffices under MRI — the only transition that matters is +false → true+
+      # before the next {#check!}, and repeated {#cancel!} is idempotent.
       class Cancellable
-        # Raised by {#check!} once {#cancel!} has been called.
-        # Carries no fields; the cancellation reason ("the user
-        # asked us to stop") is implicit in the exception class.
-        # {Agent#run_loop} catches this, emits {Event::Cancelled},
-        # and re-raises so the caller (typically a REPL) can
-        # return control to the user.
+        # Raised by {#check!} once {#cancel!} has been called; carries no fields.
+        # {Agent#run_loop} catches it, emits {Event::Cancelled}, and re-raises.
         class Cancelled < StandardError
           def initialize
             super('Agent loop cancelled')
           end
         end
 
+        # Longest a {#sleep} stays unresponsive to a {#cancel!}: it wakes on
+        # this cadence to re-check the flag. Polling rather than a
+        # +ConditionVariable+ because {#cancel!} must stay callable from a
+        # SIGINT trap, where taking a +Mutex+ raises +ThreadError+ — so the
+        # waking side pays, and the signalling side stays a bare flag write.
+        #
+        # @return [Float] seconds
+        SLICE_SECONDS = 0.1
+
         def initialize
           @cancelled = false
         end
 
-        # Flip the flag. Safe to call from a thread other than
-        # the one running the agent loop, and safe to call
-        # multiple times (idempotent). Takes effect at the next
-        # {#check!} on the run thread — see the class header for
-        # the "gentle cancel" caveats.
+        # A token that never trips — the null object for code that structurally
+        # needs one (a {#sleep} to wait through, a +cancellable:+ parameter) when
+        # the host wired no cancellation. Frozen, so a stray {#cancel!} raises
+        # +FrozenError+ rather than silently cancelling every agent that
+        # defaulted to it. Defined below {#initialize} so +@cancelled+ is set.
+        #
+        # @return [Cancellable]
+        NEVER = new.freeze
+
+        # Flip the flag. Safe off the loop thread and idempotent. Takes effect
+        # at the next {#check!} — see the class header for the gentle-cancel
+        # caveats.
         #
         # @return [void]
         def cancel!
           @cancelled = true
         end
 
-        # @return [Boolean] whether {#cancel!} has been called
-        #   since the last {#reset!}; observable from any thread.
+        # @return [Boolean] whether {#cancel!} has been called since the last
+        #   {#reset!}; observable from any thread.
         def cancelled?
           @cancelled
         end
 
-        # Raise {Cancelled} when the flag is set; otherwise no-op.
-        # Called by {Agent} from its +before_tool_call+ wiring.
+        # Raise {Cancelled} when the flag is set, else no-op. Called from
+        # {Agent}'s +before_tool_call+ wiring.
         #
         # @return [void]
-        # @raise [Cancelled] when {#cancel!} has been called since
-        #   the last {#reset!}
+        # @raise [Cancelled] when {#cancel!} has been called since {#reset!}
         def check!
           raise Cancelled if @cancelled
         end
 
-        # Reset the flag back to armed. Called by {Agent} at the
-        # start of each turn so a stale cancellation from a prior
-        # turn does not poison the next one. Mid-loop
-        # {Control::Interloper} injections deliberately do *not*
-        # trigger a reset — otherwise the cancel-then-inject
-        # ordering would lose the cancellation: +cancel!+ sets
-        # the flag, the injection lands and resets it, and the
-        # next +before_tool_call+ no longer raises.
+        # Wait +seconds+, cutting the wait short with {Cancelled} if {#cancel!}
+        # lands while waiting — the drop-in for +Kernel#sleep+ anywhere a tool
+        # paces or polls:
+        #
+        #   cancellable.sleep(2.0)   # returns after 2s, or raises on a cancel
+        #
+        # Checks the flag before waiting at all, so an already-cancelled token
+        # raises without a delay, and a non-positive +seconds+ is still a
+        # cancellation check rather than a no-op. Wakes every {SLICE_SECONDS} to
+        # look, so a cancel is honoured within that.
+        #
+        # @param seconds [Float] how long to wait; +<= 0+ returns at once.
+        # @return [void]
+        # @raise [Cancelled] if {#cancel!} has been called, before or during
+        #   the wait.
+        def sleep(seconds)
+          deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + seconds
+          loop do
+            check!
+            remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            return if remaining <= 0
+
+            # Kernel., or this recurses into itself.
+            Kernel.sleep([remaining, SLICE_SECONDS].min)
+          end
+        end
+
+        # Reset the flag to armed. Called by {Agent} at each turn start so a
+        # stale cancel doesn't poison the next turn. Mid-loop
+        # {Control::Interloper} injections deliberately do *not* reset —
+        # otherwise cancel-then-inject would lose the cancel (the injection
+        # resets the flag before the next +before_tool_call+ reads it).
         #
         # @return [void]
         def reset!
           @cancelled = false
         end
 
-        # @return [String] short label for {Agent#to_s}; reflects
-        #   the current flag state so a startup banner or debug
-        #   print can tell an armed token apart from one that has
-        #   already tripped.
+        # @return [String] short label for {Agent#to_s}, reflecting the flag state.
         def to_s
           "Cancellable(#{@cancelled ? 'cancelled' : 'armed'})"
         end