samagotchi 0.153.0 → 0.154.1

data/lib/samagotchi/engine/side_requests.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class Engine
+    # Side requests: a plugin's ctx.ask_model and Check this on their own
+    # IdleClient, their usage in the session's side line, and System 1's
+    # recording of judged asks. Writes @side_client/@side_client_key (under
+    # @side_client_mutex); reads @metrics, @session, @host_registry.
+    module SideRequestsPart
+      # Count one side request (a recap, a plugin's ctx.ask_model: IdleClient's
+      # on_usage) in the session's side line, apart from its turns' totals.
+      # Folded and announced as :side_usage under the event lock, so the side
+      # blocks reach the UIs in fold order (the lock order event lock →
+      # metrics mutex is the existing one); then, between turns, saved to
+      # analytics.json (a running turn's end or checkpoint saves it), unless
+      # the session is gone (no session file: a late recap thread must not
+      # recreate a deleted session's folder; the folder itself may not exist
+      # yet before a first turn). Safe from any thread: the recap's, a
+      # plugin's, the turn's.
+      # A side request counts against the participant who caused it
+      # (#side_author), its usage's own author when it names one.
+      # @param usage [SideUsage]
+      # @return [void]
+      def note_side_usage(usage)
+        usage = usage.with(author: side_author(usage.kind)) if usage.author.nil?
+        synchronize_events do
+          block = @metrics.add_side(usage)
+          @session_observer.notify(type: :side_usage, kind: usage.kind, side: block)
+        end
+        sid = @metrics.session_id
+        return if sid.nil? || turn_running?
+        return unless File.exist?(Session.session_file(sid, state_dir: session_state_dir))
+
+        @metrics.persist(state_dir: session_state_dir)
+      end
+
+      # Who caused a side request of +kind+ now: the running turn's author (a
+      # plugin's ctx.ask_model in it), the last turn's for the idle recap
+      # (it recaps that turn); nil, the owner's, for anything else (an owner
+      # command's ask_model between turns).
+      # @return [String, nil]
+      def side_author(kind)
+        # Check this is only ever the owner's, whichever turn runs as it ends.
+        return nil if kind.to_s == ObjectivesCheck::SOURCE
+        return nil unless turn_running? || kind.to_s == RECAP_SIDE_KIND
+
+        @guardrail_wiring.turn_author
+      end
+
+      private
+
+      # +client+ (nil for none) saving its asks as +judgment+'s runs. Anything
+      # going wrong here leaves the client as it was: a run is never worth a
+      # judgment.
+      #
+      # A scratch session's asks aren't saved; a participant's turn is never
+      # judged, so it never comes here.
+      # @param mode [String, nil] the use's mode, for its runs (Recording.wrap)
+      def system_one_recording(client, judgment, session, mode: nil)
+        return client if client.nil? || session&.scratch
+
+        context = SystemOne::Recording::Context.of(session, session_model: session && effective_model_name)
+        SystemOne::Recording.wrap(client, judgment: judgment, runs: system_one_runs, context: context, recorded_mode: mode)
+      rescue StandardError => e
+        Log.warn(:system_one, "system_one_recording_failed", error: e.class.name, msg: e.message.to_s[0, 200])
+        client
+      end
+      private :system_one_recording
+
+      # Where this Engine's runs are saved; read each time, as the settings are.
+      def system_one_runs = SystemOne::Runs.for_sessions_dir(session_state_dir)
+      private :system_one_runs
+
+      # ctx.ask_model's request: the session's current model on its host, as
+      # a turn resolves them (a /model switch counts), or a configured +model+
+      # (a host:id ref, an alias, a bare id one of a host's models), through its own
+      # IdleClient, so it shares nothing with the turn's backend. The client
+      # is kept while the target and timeout stay (what it learned, e.g. a
+      # refused thinking-off, holds for the next request); the session's id
+      # goes with the request. Its usage counts in the session's side line
+      # (#note_side_usage) under +source+, the asking bundle's name.
+      # @return [String] the answer
+      def ask_side_model(request, timeout:, max_tokens:, cancel_controller:, model: nil, source: nil)
+        target = model.nil? ? session_model_recap_target : configured_side_target(model)
+        client = side_model_client(target, timeout)
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        answer = client.ask(request, max_tokens: max_tokens, cancel_controller: cancel_controller, session_id: @session&.id,
+                                     kind: source.to_s.empty? ? "ask" : source.to_s, on_usage: method(:note_side_usage))
+        Log.info(:plugins, "ask_model", model: target.label, answer_model: answer.model, chars: answer.text.length,
+                                        ms: ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round)
+        answer.text
+      end
+      private :ask_side_model
+
+      # The target of ctx.ask_model(model:): +model+ as a turn resolves it,
+      # once it is known to name something configured. IdleTarget.of_model
+      # never raises (an unknown host falls to the default host, an unknown id
+      # to the default entry), so a typo would silently ask another model.
+      # @raise [ArgumentError] +model+ names no configured host and is no
+      #   host's model (cached, declared or saved lists; nothing is asked)
+      def configured_side_target(model)
+        ref = @host_registry.model_ref(model)
+        unless ref.host_name || ref.alias_name || @host_registry.hosts_with_model(ref.id).any?
+          raise ArgumentError, "ask_model: unknown model #{model.to_s.inspect} (use a configured host:id, an alias, " \
+                               "or a model id one of your hosts lists)"
+        end
+
+        IdleTarget.of_model(@host_registry, model)
+      end
+      private :configured_side_target
+
+      # The IdleClient for +target+ at +timeout+: the last one when both are
+      # the same, else a new one.
+      def side_model_client(target, timeout)
+        @side_client_mutex.synchronize do
+          key = [target, timeout]
+          unless @side_client && @side_client_key == key
+            @side_client = IdleClient.for(target, timeout: timeout)
+            @side_client_key = key
+          end
+          @side_client
+        end
+      end
+      private :side_model_client
+
+      # The session's current model as a recap target: its host's OpenAI API
+      # (native llama.cpp hosts serve /v1/chat/completions too), key variable
+      # and bare model name, as a turn resolves them.
+      # @return [IdleTarget]
+      def session_model_recap_target
+        IdleTarget.of_model(@host_registry, effective_model_name)
+      end
+    end
+  end
+end

data/lib/samagotchi/engine/steering.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class Engine
+    # The running turn as other threads see it: steering into it (now or
+    # at the next turn), the drains, the cut, the activity clock and the
+    # cancel. Reads @turn_state and @steer_cut; writes nothing of its own.
+    module SteeringPart
+      # Record that activity happened (user input or a completed turn): the
+      # idle jobs' seam (TurnState#record_activity). Each call advances both
+      # the last-activity timestamp and the activity sequence.
+      # @param now [Float, nil] injectable monotonic time (defaults to now)
+      def record_activity(now = nil)
+        @turn_state.record_activity(now)
+      end
+
+      # @return [Float] monotonic seconds of the last recorded activity
+      def last_activity_at
+        @turn_state.last_activity_at
+      end
+
+      # @return [Integer] monotonically-increasing activity counter (advanced by
+      #   #record_activity; lets the idle detector summarize once per idle window)
+      def activity_seq
+        @turn_state.activity_seq
+      end
+
+      # @return [Boolean] true while a turn is in flight (the idle jobs never
+      #   fire, nor render, while the model is generating)
+      def turn_running?
+        @turn_state.running?
+      end
+
+      # Put +text+ into the running turn, as a UI's steering does: it joins the
+      # conversation at the loop's next iteration boundary as its own user
+      # message (kind: "steer", source:). Callable from any thread; never
+      # blocks. With no turn running it does nothing (it never starts one).
+      # True means queued, not merged: at the after-answer boundary, and when
+      # the turn ends first, it is dropped (logged).
+      # @return [Boolean] whether it was queued
+      def steer(text, source:)
+        @turn_state.steer(text, source: source)
+      end
+
+      # A message for the running turn from +source+ cuts the generation
+      # streaming only thinking (SteerCut#cut_for_steer). Call it after the
+      # message is queued, with the #input_epoch read before queueing it.
+      # @return [Boolean] whether a generation was cut now
+      def cut_for_steer(source, epoch: nil) = @steer_cut.cut_for_steer(source, epoch: epoch)
+
+      # The drains that took input so far: read it before queueing a message
+      # for #cut_for_steer.
+      def input_epoch = @steer_cut.input_epoch
+
+      # The running generation's phase (SteerCut#generation_snapshot): what
+      # Bridge#snapshot puts in current_turn.generation.
+      def generation_snapshot = @steer_cut.generation_snapshot
+
+      # Like #steer, for the turn that begins next (a continue turn answered
+      # with a text): it joins that turn at its first boundary. Callable from
+      # any thread; a turn that never begins keeps it for the next one, unless
+      # #drop_carried_steers drops it.
+      # @return [Boolean] whether it was queued (false: blank)
+      def steer_next_turn(text, source:)
+        @turn_state.steer_next_turn(text, source: source)
+      end
+
+      # Drop the #steer_next_turn steers no turn began with (the continue turn
+      # failed before it began), logged; a no-op once a turn took them.
+      def drop_carried_steers
+        log_dropped_steers(@turn_state.drop_carried_steers, "not_begun")
+      end
+
+      # The drain a turn's loop gets: the caller's lines (a UI's steering; nil
+      # in a --non-interactive run) and the plugin steers. At the after-answer
+      # boundary the steers are dropped: the model answered, and a nudge would
+      # only restart the turn. The steer part fails on its own, never taking
+      # the user's lines with it. Items are a String (a user line), a
+      # Steer::Line (a worker's input line with its sender) or a steer Hash.
+      def turn_drain(pending_input)
+        lambda do |at_answer: false|
+          lines = pending_input ? Array(pending_input.call) : []
+          # The input went to the model: a message that waited to cut is in.
+          @steer_cut.delivered! unless lines.empty?
+          lines + take_steers(at_answer)
+        end
+      end
+      private :turn_drain
+
+      def take_steers(drop)
+        steers = @turn_state.take_steers
+        return steers unless drop
+
+        log_dropped_steers(steers, "answered")
+        []
+      rescue StandardError => e
+        Log.warn(:turn, "take_steers_failed", error: e.class.name, msg: e.message.to_s[0, 200])
+        []
+      end
+      private :take_steers
+
+      def log_dropped_steers(steers, why)
+        steers.each { |steer| Log.info(:turn, "steer_dropped", source: steer[:source], why: why, chars: steer[:text].length) }
+      end
+      private :log_dropped_steers
+
+      # @return [CancellationController, nil] active turn's cancellation controller
+      def active_cancel_controller
+        @turn_state.controller
+      end
+
+      # Whether a message a person sent waits for the running turn's next
+      # boundary (run_turn's input_waiting: probe): a task_wait or delegate wait
+      # returns on it, an execute hands its command over early
+      # (PeerView#input_waiting?). False outside a turn, for a turn given no
+      # probe, and when the probe raises (warned once a turn; the tool never
+      # fails for it).
+      def input_waiting?
+        probe = @turn_state.input_waiting
+        !!probe&.call
+      rescue StandardError => e
+        Log.warn(:turn, "input_waiting_failed", error: e.class.name, msg: e.message) if @turn_state.input_waiting_failed!
+        false
+      end
+
+      # Cancel the currently running turn, if any.
+      # @param reason [Symbol] cancellation reason
+      # @return [Boolean] whether a cancellation was triggered
+      def cancel_current_turn!(reason = :manual)
+        @turn_state.cancel!(reason)
+      end
+    end
+  end
+end

data/lib/samagotchi/engine/toolkit.rb

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  class Engine
+    # The session's toolkit: the kits and what a turn declares
+    # (ToolkitBinding, forwarded), ctx.load_tools and the staged loads a turn
+    # appends, and System 1's toolkit suggestion (start, settle, warm-up).
+    # Writes @toolkit_warmup_thread; reads @toolkit_binding, @tools,
+    # @tool_index, @tool_loads, @side_judgments, @session.
+    module ToolkitPart
+      private
+
+      # The session's toolkit (ToolkitBinding): the kits, what its next turn
+      # declares, ctx.use_toolkit and the turn-start apply.
+      def toolkit_kits(errors = []) = @toolkit_binding.kits(errors)
+      def resolved_toolkit(session, errors = []) = @toolkit_binding.resolved(session, errors)
+      def toolkit_explained(toolkit = nil) = @toolkit_binding.explained(toolkit)
+      def toolkit_summary = @toolkit_binding.summary
+
+      # The tools this session registered (Tools::Registry), declared or not.
+      attr_reader :tools
+
+      public :tools, :toolkit_kits, :resolved_toolkit, :toolkit_explained, :toolkit_summary
+
+      # A plugin's ctx.load_tools: stage the reachable tools +names+ names
+      # (Tools::ToolIndex#deferred_name) that the session neither declares
+      # nor loaded with an earlier tool change, for bundle +bundle+. A name
+      # that names no tool at all is logged; a declared or removed one is
+      # skipped quietly.
+      # @return [Array<String>] the wire names staged
+      def load_tools(names, bundle)
+        added = ToolLoads.added(@session&.messages)
+        wanted = names.filter_map do |name|
+          wire = @tool_index.deferred_name(name)
+          Log.info(:plugins, "load_tools_skipped", bundle: bundle, tool: name) unless wire || @tools.key?(name)
+          wire
+        end
+        @tool_loads.stage(wanted - added, by: bundle)
+      end
+      public :load_tools
+
+      # The staged tool loads, appended to +turn+'s messages (after its user
+      # message, or the trailing results and notes of a turn with none) as
+      # one ToolLoads entry per bundle, when the turn's host takes tool
+      # changes (ChatLoop#tool_changes?). Elsewhere they are dropped, logged.
+      # A conversation that ends with a reply keeps them staged (a system
+      # change must follow a user turn).
+      def append_tool_loads(turn)
+        return unless @tool_loads.any?
+        return if turn.messages.last&.dig(:role).to_s == "model"
+
+        model = effective_model
+        host = backend(model)
+        staged = @tool_loads.take
+        added = ToolLoads.added(turn.messages)
+        unless host.respond_to?(:tool_changes?) && host.tool_changes?(bare_model_name(model.name))
+          Log.info(:plugins, "tool_loads_not_sent", tools: staged.values.flatten.join(","), model: model.name.to_s)
+          return
+        end
+
+        staged.each do |bundle, names|
+          names -= added
+          next if names.empty?
+
+          turn.messages << ToolLoads.entry(names, by: bundle)
+          hook_notify("tools loaded: #{names.join(", ")}", :info, bundle)
+        end
+      end
+      private :append_tool_loads
+
+      # A plugin's ctx.use_toolkit (ToolkitBinding#use).
+      # @return [Boolean] whether it was staged
+      # @raise [ArgumentError] an unknown toolkit
+      def use_toolkit(name) = @toolkit_binding.use(name)
+      public :use_toolkit
+
+      # At a turn's start (ToolkitBinding#apply!).
+      # @return [Boolean] whether the declared tools changed
+      def apply_toolkit!(session, on_event = nil) = @toolkit_binding.apply!(session, on_event)
+      private :apply_toolkit!
+
+      # Start the toolkit classifier after :turn_started, for audit and on
+      # mode alike (one eligibility, one snapshot, one thread). All session
+      # and tool-registry reads happen here; the thread receives only this
+      # snapshot. Audit never blocks: the thread logs its line. On mode
+      # returns the ask's Pending, which the turn joins before apply_toolkit!
+      # (#settle_toolkit_suggestion), with the turn's controller as the
+      # request's cancel controller.
+      # @return [ToolkitSuggest::Pending, nil] nil unless the turn joins an ask
+      def start_toolkit_suggestion(turn)
+        mode = Config.get("toolkit.suggest.mode").to_s
+        return if mode == "off"
+
+        joined = mode == "on"
+        session = turn.session
+        default = Toolkit.of(session.toolkit)
+        log = toolkit_suggestion_log
+        # The predicate checks the session first; the kits (memory kits are
+        # read from disk) and the log (read whole) only when it gets there.
+        kits = nil
+        candidates = nil
+        return unless ToolkitSuggest.eligible?(
+          session: session, prompt: turn.prompt, author: turn.origin.author,
+          candidate_count: lambda {
+            kits = @toolkit_binding.kits
+            candidates = ToolkitSuggest.candidates(kits, default_name: default.name)
+            candidates.size
+          },
+          last_suggestion: -> { ToolkitSuggest.last_suggestion(log, session.id) },
+          defer_turns: Config.get("toolkit.suggest.defer_turns"),
+          defer_tokens: Config.get("toolkit.suggest.defer_tokens")
+        )
+
+        # One ask at a time: an eligible turn while the last one still runs
+        # goes unasked, and says so.
+        if @side_judgments.in_flight?(:toolkit)
+          Log.info(:toolkit, "toolkit_suggest_in_flight_skipped", session_id: session.id)
+          return
+        end
+
+        client = system_one_recording(SystemOne::Client.from_config(host_registry: @host_registry, mode: "on", tag: :toolkit),
+                                      ToolkitSuggest::JUDGMENT, session, mode: Config.get("toolkit.suggest.mode").to_s)
+        return unless client
+
+        # The warm-up's only value is the cache: the real ask never queues
+        # behind it.
+        stop_toolkit_warmup
+
+        # Rules, not tool lists: this runs before await_init_tasks and
+        # apply_staged_tools!, so a first turn's plugin/MCP tools aren't
+        # registered yet; the report expands the rules (ToolkitSuggest.rules).
+        snapshots = candidates.map do |kit|
+          ToolkitSuggest::Candidate.new(name: kit.name.dup.freeze, description: kit.description.dup.freeze,
+                                        rules: ToolkitSuggest.rules(Toolkit.resolve_kit(kit.name, kits)))
+        end.freeze
+        default_snapshot = ToolkitSuggest::Candidate.new(name: default.name.dup.freeze, description: nil,
+                                                         rules: ToolkitSuggest.rules(default.resolve(kits)))
+        registered = @tools.entries(toolkit: nil).reject { |entry| entry.source == Tools::ToolIndex::SOURCE }
+        core_tools, plugin_tools = registered.partition(&:core?).map { |entries| entries.map { |entry| entry.name.dup.freeze }.freeze }
+        state = ToolkitSuggest.question(
+          default: default, kits: kits, project: File.basename(session.project_root.to_s),
+          prompt: turn.prompt
+        ).last
+        snapshot = ToolkitSuggest::Snapshot.new(
+          session_id: session.id.dup.freeze, turn_number: ToolkitSuggest.turn_number(session.messages),
+          default: default_snapshot, candidates: snapshots, core_tools: core_tools, plugin_tools: plugin_tools,
+          state: { project: state[:project].dup.freeze, prompt: state[:prompt].dup.freeze }.freeze
+        )
+        threshold = Config.get("toolkit.suggest.threshold")
+        runs = session.scratch ? nil : system_one_runs
+        pending = ToolkitSuggest::Pending.new(log: log, joined: joined,
+                                              acted: runs && ->(judged, did) { runs.acted(judged.fields[:run_id], did) },
+                                              timeout_seconds: SystemOne::Client.configured_timeout_ms / 1000.0)
+        # On mode: cut by a Stop while the turn waits (Pending#wait), not
+        # by one after it went on; audit's ask is never cut.
+        controller = joined ? pending.cancel_controller : nil
+        @side_judgments.start(:toolkit, warn: ToolkitSuggest.method(:warn), finish: pending.method(:finish)) do
+          ToolkitSuggest.judge(client: client, snapshot: snapshot, threshold: threshold,
+                               cancel_controller: controller)
+        end
+        joined ? pending : nil
+      rescue StandardError => e
+        ToolkitSuggest.warn(e)
+        nil
+      end
+      private :start_toolkit_suggestion
+
+      # On mode, before apply_toolkit!: wait for the ask (#start_toolkit_
+      # suggestion) up to System 1's timeout from its start, or until a Stop,
+      # and put the session on a candidate picked with confidence ≥ threshold
+      # (ToolkitBinding#suggest: origin suggested, saved, the notice). Any
+      # other outcome (the default, below threshold, undecided, no judgment,
+      # a timeout, a Stop) leaves the session on its default. Nothing here
+      # sends a request; prepare_turn's cancel check ends a stopped turn. A
+      # Stop wins over an answer already in (Pending#wait checks it first).
+      def settle_toolkit_suggestion(turn, pending)
+        return if pending.nil?
+
+        outcome, judged = pending.wait(turn.controller)
+        if outcome == :timeout
+          # The session starts on its default without a word otherwise: a
+          # slow System 1 host (a local one) is the usual cause.
+          timeout_ms = SystemOne::Client.configured_timeout_ms
+          Log.warn(:toolkit, "toolkit_suggest_timeout", session_id: turn.session.id, timeout_ms: timeout_ms,
+                                                        reason: "System 1 gave no answer within system_one.timeout_ms")
+          @toolkit_binding.fell_back(turn.session, "System 1 took over #{timeout_ms} ms")
+          return
+        end
+        unless outcome == :answered
+          Log.info(:toolkit, "toolkit_suggest_#{outcome}", session_id: turn.session.id)
+          return
+        end
+        return if judged.nil?
+
+        pending.record(toolkit_suggestion_outcome(turn.session, judged))
+      rescue StandardError => e
+        ToolkitSuggest.warn(e)
+        pending&.record("failed")
+      end
+      private :settle_toolkit_suggestion
+
+      # What the turn does with an answered ask, as the log line's did:
+      # suggested (switched), chosen (the toolkit isn't the default any
+      # more), unavailable (the kit is gone), defer or default.
+      def toolkit_suggestion_outcome(session, judged)
+        case judged.would
+        when "suggested"
+          return "chosen" unless session.toolkit_origin == "default"
+          return "unavailable" unless @toolkit_binding.kits.key?(judged.suggestion.kit)
+
+          switched = @toolkit_binding.suggest(session, judged.suggestion.kit, confidence: judged.suggestion.confidence,
+                                                                              deferred: ToolkitSuggest.model_reply?(session.messages))
+          switched ? "suggested" : "chosen"
+        when "defer" then "defer"
+        when "no_judgment"
+          # System 1 failed (its own warn) or answered nothing usable.
+          @toolkit_binding.fell_back(session, "System 1 gave no answer")
+          "default"
+        else "default"
+        end
+      end
+      private :toolkit_suggestion_outcome
+
+      # On mode, as an idle worker starts (Worker#start_background): one ask
+      # with the real question and a stand-in prompt, on its own thread,
+      # never logged and never waited for, so System 1's server has the
+      # question's prefix cached for the first prompt. Only for a session a
+      # first prompt could be asked for: origin default, no model reply, not
+      # a delegate child or a review session, at least two candidates; and
+      # not when the worker starts on a first prompt (that ask comes at once).
+      def warm_toolkit_suggestion!
+        return unless Config.get("toolkit.suggest.mode").to_s == "on"
+
+        session = @session
+        return if session.nil? || session.toolkit_origin != "default" || session.delegate? || session.review?
+        return if ToolkitSuggest.model_reply?(session.messages) || !session.last_prompt.to_s.strip.empty?
+
+        default = Toolkit.of(session.toolkit)
+        kits = @toolkit_binding.kits
+        return if ToolkitSuggest.candidates(kits, default_name: default.name).size < 2
+
+        client = SystemOne::Client.from_config(host_registry: @host_registry, mode: "on", tag: :toolkit)
+        return unless client
+
+        project = File.basename(session.project_root.to_s)
+        @toolkit_warmup_thread = Thread.new do
+          ToolkitSuggest.warm(client: client, default: default, kits: kits, project: project)
+        end
+      rescue StandardError => e
+        ToolkitSuggest.warn(e)
+        nil
+      end
+      public :warm_toolkit_suggestion!
+
+      # A still-running warm-up, stopped: a real ask (or the worker leaving)
+      # doesn't wait behind it.
+      def stop_toolkit_warmup
+        @toolkit_warmup_thread&.kill
+        @toolkit_warmup_thread = nil
+      end
+      private :stop_toolkit_warmup
+
+      def toolkit_suggestion_log
+        SideJudgments.log(ToolkitSuggest.log_path(session_state_dir), tag: :toolkit, event: "toolkit_suggest_log_failed")
+      end
+      private :toolkit_suggestion_log
+    end
+  end
+end