pikuri-core 0.0.7 → 0.1.0

data/lib/pikuri/agent/context_window_detector.rb

@@ -7,72 +7,43 @@ require 'cgi'
 
 module Pikuri
   class Agent
-    # Resolves the model's context-window cap by asking the server that
-    # actually serves it. The only authoritative runtime source pikuri
-    # has is llama.cpp's non-standard +/props+ endpoint, which reports
-    # the server's *launched* +n_ctx+ (the real window — possibly
-    # smaller than the model's theoretical max, e.g. +llama-server -c
-    # 8192+ on a 128k model). Returns +nil+ — an honest "we don't
-    # know" — for anything else.
+    # 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#detect_and_emit_context_cap!} at construction and
-    # after every model switch 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).
-    # The caller prefers an explicit/inherited
-    # {ChatTransport#context_window} over this probe; this runs only when
-    # the transport carries none.
-    #
-    # == Why no ruby_llm registry source
-    #
-    # +RubyLLM::Model::Info#context_window+ is a static lookup in a
-    # bundled +models.json+ snapshot: +nil+ for every +assume_exists+
-    # local model id, +nil+ for anything newer than the snapshot, and —
-    # worst — a *frozen* value for known models, so a window the provider
-    # later bumped (256k → 1M) still reports the old number. A cap you
-    # have to caveat defeats the cap's only job (a number trustworthy
-    # enough to act on before +RubyLLM::ContextLengthExceededError+), so
-    # pikuri deliberately does not consult it. The probe (server truth)
-    # and an explicit {ChatTransport#context_window} (operator/parent
-    # truth) are the only two sources; absent both, the cap is +nil+.
+    # 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+).
     #
     # == The openai-provider gate + auto-derived URL
     #
-    # The probe only makes sense against an OpenAI-compatible local
-    # server (llama.cpp), reached through ruby_llm's +:openai+ provider
-    # with a custom base. So {.detect} runs only when
-    # +transport.provider == :openai+ and derives the probe URL from the
-    # *same* +RubyLLM.config.openai_api_base+ the chat itself uses —
-    # +/props+ lives at the host root, NOT under +/v1+, so the +/v1+
-    # suffix is stripped. Deriving from the live config (rather than a
-    # URL passed in) means the probe can't target a different server than
-    # the chat. A bare +:openai+ pointed at real +api.openai.com+ gets
-    # one fast +/props+ 404 that degrades to +nil+ (the simple gate; not
-    # worth narrowing — you're already sending that server the whole
-    # conversation).
+    # 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+.
@@ -80,39 +51,29 @@ module Pikuri
       # @return [Logger]
       LOGGER = Pikuri.logger_for('ContextWindowDetector')
 
-      # Connect timeout in seconds for the llama.cpp +/props+ probe.
-      # Short on purpose: a server that isn't even listening should fail
-      # fast rather than stall +Agent+ construction.
+      # 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.
-      # Generous on purpose, and the reason it differs from
-      # {OPEN_TIMEOUT}: a llama.cpp router answers +/props?model=<id>+
-      # only *after* spinning up that model's instance, and a cold model
-      # load can take 10+ seconds — which the next chat turn must wait
-      # for anyway. A read timeout shorter than the load would abandon
-      # the probe (and lose the cap) precisely when switching to a
-      # cold model. A server that accepts the connection but then hangs
-      # would stall the actual chat identically, so tolerating the wait
-      # here costs nothing extra.
+      # 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 = 30
 
-      # Resolve the context-window cap for +transport+ by probing the
-      # server that serves it.
+      # Resolve the context-window cap for +transport+ by probing its server.
       #
-      # @param transport [Agent::ChatTransport] the model-resolution
-      #   triple; +provider+ gates the probe and +model+ drives the
-      #   router +?model=+ hop
-      # @param openai_base [String, nil] the configured OpenAI-compatible
-      #   base URL the probe URL is derived from; defaults to the live
-      #   +RubyLLM.config.openai_api_base+. Passed explicitly only by
-      #   tests, which don't want to mutate global config.
+      # @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, an unconfigured base, or any probe
-      #   failure
+      #   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
 
@@ -122,13 +83,11 @@ module Pikuri
         new(probe_url: url, model_id: transport.model).probe
       end
 
-      # Derive the llama.cpp +/props+ URL from the OpenAI-compatible
-      # base. +/props+ sits at the host root, so a trailing +/v1+ is
-      # stripped before appending.
+      # 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
+      # @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?

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