samagotchi 0.36.0 → 0.38.0

data/lib/samagotchi/desktop/macos.rb

@@ -41,6 +41,10 @@ module Samagotchi
       ENV_ALLOWLIST = %w[XDG_CONFIG_HOME XDG_STATE_HOME GEM_HOME GEM_PATH RUBYLIB].freeze
       # Without it Ruby reads stdin as US-ASCII and non-ASCII notes break.
       LANG = "en_US.UTF-8"
+      # chi broadcast's default triage deadline, and the helper's seconds on
+      # top of it (MacOS.broadcast_timeout).
+      BROADCAST_TRIAGE_DEADLINE = 20
+      BROADCAST_MARGIN = 10
 
       # Runs a command without a shell; [output, success].
       class Runner
@@ -62,11 +66,25 @@ module Samagotchi
         { "listen_on" => listen_on, "binary" => get.call("kitty.binary").to_s, "agents" => agents }
       end
 
+      # The helper as chi desktop and chi update make it: the settings it
+      # bakes into the launch file read from the config.
+      def self.from_config(register: true)
+        new(register: register, kitty: kitty_settings, broadcast_timeout: broadcast_timeout)
+      end
+
+      # Seconds the helper gives `chi broadcast` before it stops it: the
+      # triage deadline, then the deliveries and chi's own start. Baked into
+      # the launch file: a changed deadline reaches the helper with chi update.
+      def self.broadcast_timeout(get = Config.method(:get))
+        (get.call("broadcast.triage_deadline") || BROADCAST_TRIAGE_DEADLINE).to_f + BROADCAST_MARGIN
+      end
+
       attr_reader :app_dir, :support_dir
 
       def initialize(app_dir: nil, support_dir: nil, env: ENV, runner: Runner.new,
                      source_dir: SelfReport::SOURCE_DIR, ruby: RbConfig.ruby, version: VERSION,
-                     arch: nil, sources_dir: SOURCES_DIR, register: true, chi_path: nil, kitty: nil)
+                     arch: nil, sources_dir: SOURCES_DIR, register: true, chi_path: nil, kitty: nil,
+                     broadcast_timeout: nil)
         home = env["HOME"] || Dir.home
         @app_dir = app_dir || File.join(home, "Applications")
         @support_dir = support_dir || File.join(home, "Library", "Application Support", APP_NAME)
@@ -80,6 +98,7 @@ module Samagotchi
         @sources_dir = sources_dir
         @register = register
         @kitty = kitty
+        @broadcast_timeout = broadcast_timeout
       end
 
       def app_path = File.join(@app_dir, "#{APP_NAME}.app")
@@ -93,12 +112,13 @@ module Samagotchi
       # shell's PATH), and the allowlisted env. chi is an installed gem's
       # RubyGems wrapper (it activates the gem and outlives upgrades and
       # `gem cleanup`), else this checkout's bin/chi. The kitty section only
-      # when kitty.listen_on is set.
+      # when kitty.listen_on is set; the broadcast timeout when given.
       def launch_config
         env = { "LANG" => LANG }
         ENV_ALLOWLIST.each { |name| env[name] = @env[name] unless @env[name].to_s.empty? }
         config = { "version" => @version, "argv" => [@ruby, @chi_path], "env" => env, "sources_sha" => sources_sha }
         config["kitty"] = @kitty if @kitty
+        config["broadcast_timeout"] = @broadcast_timeout if @broadcast_timeout
         config
       end
 
@@ -122,13 +142,15 @@ module Samagotchi
       end
 
       # The launch file names another chi version or path than this one, or
-      # other kitty settings: refresh_launch_file fixes that without a rebuild.
+      # other kitty settings or broadcast timeout: refresh_launch_file fixes
+      # that without a rebuild.
       def launch_outdated?
         launch = read_launch
-        launch["version"] != @version || Array(launch["argv"]) != launch_config["argv"] || launch["kitty"] != @kitty
+        launch["version"] != @version || Array(launch["argv"]) != launch_config["argv"] || launch["kitty"] != @kitty ||
+          launch["broadcast_timeout"] != @broadcast_timeout
       end
 
-      # Rewrite the launch file for this chi and the kitty settings, keeping
+      # Rewrite the launch file for this chi and its settings, keeping
       # the env it was installed with. The app reads it at each send: no restart.
       def refresh_launch_file
         config = launch_config

data/lib/samagotchi/desktop_command.rb

@@ -41,7 +41,7 @@ module Samagotchi
       @argv = argv.dup
       @stdout = stdout
       @stderr = stderr
-      @platform = platform || ->(register:) { Desktop::MacOS.new(register: register, kitty: Desktop::MacOS.kitty_settings) }
+      @platform = platform || Desktop::MacOS.method(:from_config)
       @supported = supported
     end
 

data/lib/samagotchi/engine.rb

@@ -1531,8 +1531,9 @@ module Samagotchi
     # @param on_event [Proc, nil] receives event hashes
     # @param max_iterations [Integer, nil] max kernel iterations (nil: IterationLimit.for)
     # @param cancel_controller [CancellationController, nil]
-    # @param max_tool_output_chars [Integer, nil] per-output char cap for the
-    #   :tool_call_completed event's `output:` (nil → max_tool_output_chars)
+    # @param max_tool_output_chars [Integer, nil] per-output char cap on what
+    #   the model gets back and the :tool_call_completed event's `output:`
+    #   (nil → max_tool_output_chars)
     # @return [LLM::ModelResult]
     # @param pending_input [#call, nil] optional drain proc returning
     #   Array<String> of steering messages queued while the turn runs; drained
@@ -2352,11 +2353,10 @@ module Samagotchi
     # @return [String] the answer
     def ask_side_model(request, timeout:, max_tokens:, cancel_controller:)
       target = session_model_recap_target
-      client = IdleClient.new(model: target[:model], base_url: target[:base_url], api_key_env: target[:api_key_env],
-                              timeout: timeout)
+      client = IdleClient.for(target, timeout: timeout)
       started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       answer = client.ask(request, max_tokens: max_tokens, cancel_controller: cancel_controller)
-      Log.info(:plugins, "ask_model", model: target[:label], answer_model: answer.model, chars: answer.text.length,
+      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
@@ -2372,10 +2372,9 @@ module Samagotchi
     # 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
-      target = @host_registry.resolve(@effective_model_name)
-      { base_url: target.openai_base_url, api_key_env: target.entry.api_key_env,
-        model: target.bare_model, label: @effective_model_name.to_s }
+      IdleTarget.of_model(@host_registry, @effective_model_name)
     end
 
     # Build the idle reminders job. Always created (reminders are opt-in

data/lib/samagotchi/guardrail_wiring.rb

@@ -226,8 +226,13 @@ module Samagotchi
         return verdict.settle!(:deny, decided_by: "no one", note: "No one to approve it (non-interactive run).")
       end
 
-      # A plugin tool is asked about by its label, as its row shows it.
-      label = ToolActivity.plugin_label(verdict.call[:name].to_s, registry: @tools_lookup.call)
+      # A plugin tool is asked about by its targets:' label:, else its
+      # label, as its row shows it; a call that acts as another tool (an MCP
+      # tool behind mcp_call) by that tool's label, else (none registered)
+      # by its name (Approval.payload).
+      acts_as = verdict.targets&.acts_as
+      label = verdict.targets&.label ||
+              ToolActivity.plugin_label(acts_as || verdict.call[:name].to_s, registry: @tools_lookup.call)
       # verdict.call is the call that will run (a hook may have replaced it).
       payload = Guardrails::Approval.payload(verdict, label: label, preview: approval_preview(verdict.call),
                                                       only: (SCRATCH_SCOPES if @scratch))

data/lib/samagotchi/guardrails/approval.rb

@@ -18,7 +18,8 @@ module Samagotchi
 
       # @param verdict [Verdict] an ask, with its targets and context
       # @param label [String, nil] a plugin tool's label ("chrome:
-      #   screenshot"): the question names the tool by it, as its row does;
+      #   screenshot"): the question names the tool by it, as its row does
+      #   (without one, by the tool the call acts as, else its name);
       #   approval[:tool] stays the raw name
       # @param preview [Hash, nil] EditPreview.for(verdict.call) for edit and
       #   write: the card shows its diff, the question text one change line
@@ -37,6 +38,8 @@ module Samagotchi
           kind: KIND,
           approval: {
             tool: targets&.tool || verdict.call[:name].to_s,
+            # The tool the call acts as (an MCP tool behind mcp_call).
+            acts_as: targets&.acts_as,
             label: label,
             command: targets&.command,
             paths: targets && !targets.paths.empty? ? targets.paths : nil,
@@ -126,7 +129,7 @@ module Samagotchi
       #   change: +3 −1                      (edit/write, from the preview)
       def question_text(verdict, label: nil, preview: nil)
         targets = verdict.targets
-        tool = label || targets&.tool || verdict.call[:name].to_s
+        tool = label || targets&.acts_as || targets&.tool || verdict.call[:name].to_s
         what = targets&.command || (targets && targets.paths.join(", "))
         what = Approval.args_text(targets&.args, limit: ARGS_CHARS) if what.to_s.empty?
         lines = ["#{tool}: #{what}"]

data/lib/samagotchi/guardrails/approvals.rb

@@ -90,7 +90,7 @@ module Samagotchi
         return nil unless STORED_SCOPES.include?(scope)
 
         entry = { "scope" => scope, "tool" => verdict.targets&.tool || verdict.call[:name].to_s,
-                  "rule" => verdict.rule, "source" => verdict.source, "created_at" => Time.now.utc.iso8601 }
+                  "acts_as" => verdict.targets&.acts_as, "rule" => verdict.rule, "source" => verdict.source, "created_at" => Time.now.utc.iso8601 }
         case scope
         when "session" then entry.merge!("session_id" => verdict.context&.session_id, "key" => key_for(verdict))
         when "repo"
@@ -110,14 +110,18 @@ module Samagotchi
 
       # tool + the normalized command, or the sorted paths; for a plugin
       # tool with neither (an MCP tool), its arguments, so "this call" is
-      # this call.
+      # this call. A call that acts as another tool keys as
+      # `mcp_call>mcp_github_x`: the real name stays in, so it never reuses
+      # that tool's own approvals (nor they its).
       def self.key_for(verdict)
         t = verdict.targets
         return "#{verdict.call[:name]}:" unless t
-        return "#{t.tool}:#{t.command.to_s.strip.gsub(/\s+/, " ")}" if t.command
-        return "#{t.tool}:#{Approval.args_text(t.args)}" if t.paths.empty?
 
-        "#{t.tool}:#{t.paths.sort.join("\n")}"
+        tool = t.acts_as ? "#{t.tool}>#{t.acts_as}" : t.tool
+        return "#{tool}:#{t.command.to_s.strip.gsub(/\s+/, " ")}" if t.command
+        return "#{tool}:#{Approval.args_text(t.args)}" if t.paths.empty?
+
+        "#{tool}:#{t.paths.sort.join("\n")}"
       end
 
       def self.place_for(verdict)

data/lib/samagotchi/guardrails/rules.rb

@@ -9,7 +9,9 @@ module Samagotchi
     # Declarative rules from config.yml's `guardrails:` section (and, later,
     # installed bundles). All the fields a rule gives must match:
     #   tool:    a tool name, a list, or "shell" (execute + task_create);
-    #            a name may be a glob ("mcp_*", "mcp_{git,gh}_*")
+    #            a name may be a glob ("mcp_*", "mcp_{git,gh}_*"); it
+    #            matches the call's name or the tool a plugin tool's call
+    #            acts as (Targets#acts_as: an MCP tool behind mcp_call)
     #   command: a Ruby regex on a shell tool's command
     #   path:    "outside_repo", or a glob on the resolved paths (absolute
     #            or "**/…" globs match the absolute path; others the path
@@ -51,7 +53,7 @@ module Samagotchi
         def matches?(targets)
           return false unless targets
           return false unless for_model?(targets.model_name, targets.model_key, -> { targets.small_model? })
-          return false if tools && !tool_matches?(targets.tool)
+          return false if tools && !tool_matches?(targets.tool) && !(targets.acts_as && tool_matches?(targets.acts_as))
           return false if command && !(targets.command && command.match?(targets.command))
           return false if path && !path_matches?(targets)
           return false if git && !targets.git_outside_repo?

data/lib/samagotchi/guardrails/targets.rb

@@ -2,6 +2,7 @@
 
 require_relative "../tools/tool_path"
 require_relative "../tools/memory"
+require_relative "../tool_declarations"
 require_relative "../log"
 require_relative "model_size"
 require_relative "outside"
@@ -21,6 +22,9 @@ module Samagotchi
       SHELL_TOOLS = %w[execute task_create].freeze
       PATH_TOOLS = %w[write edit read memory_write].freeze
 
+      # chi's own tools, by name, whether this session has them or not.
+      CORE_TOOLS = ToolDeclarations::TOOL_SCHEMAS.map { |schema| schema[:name] }.freeze
+
       attr_reader :tool, :command, :paths, :cwd, :repo_root
 
       # @return [String, nil] the call's repository (Context#repo: its
@@ -37,11 +41,25 @@ module Samagotchi
       #   prefix) and its key (ModelOverlay.key_for), for a rule's models:
       attr_reader :model_name, :model_key
 
-      # @return [Hash, nil] a plugin tool's arguments (call[:args]), for an
-      #   approval of a call whose targets name no command or path; nil for
-      #   chi's own tools
+      # @return [Hash, nil] a plugin tool's arguments, for an approval of a
+      #   call whose targets name no command or path: its targets:' args:
+      #   when given (the arguments it acts with, a dispatcher's inner
+      #   ones), else call[:args]; nil for chi's own tools
       attr_reader :args
 
+      # @return [String, nil] the tool a plugin tool's call acts as (its
+      #   targets:' acts_as:, an MCP tool behind mcp_call): a rule's tool:
+      #   matches it as well as the call's name. Never a core tool's or
+      #   another bundle's (.plugin_targets drops those). #tool stays the
+      #   call's name.
+      attr_reader :acts_as
+
+      # @return [String, nil] what a plugin tool's targets: says to name the
+      #   call by in the approval question (label:, "github: x"), in place of
+      #   the tool's registered label; display only (no rule or approval key
+      #   reads it)
+      attr_reader :label
+
       # @return [Boolean] a memory_write call that removes a memory (remove:
       #   true), for a rule's memory: remove
       attr_reader :memory_remove
@@ -61,6 +79,8 @@ module Samagotchi
         paths = []
         cwd = base
         args = nil
+        acts_as = nil
+        label = nil
         case tool
         when *SHELL_TOOLS
           command = call[:content].to_s
@@ -79,21 +99,27 @@ module Samagotchi
           cwd = File.expand_path(given_cwd, base) unless given_cwd.empty?
           paths.concat(given[:paths].map { |path| absolute(path, cwd) })
           entry = registry && registry[tool]
-          args = call[:args] if entry && !entry.core? && call[:args].is_a?(Hash)
+          args = given[:args] || call[:args] if entry && !entry.core? && call[:args].is_a?(Hash)
+          acts_as = given[:acts_as]
+          label = given[:label]
         end
         memory_remove = tool == "memory_write" && call[:remove].to_s.strip.downcase == "true"
         new(tool: tool, command: command, paths: paths.compact, cwd: cwd, repo_root: context.repo_root(cwd),
-            repo: context.repo(cwd), args: args, memory_remove: memory_remove,
+            repo: context.repo(cwd), args: args, acts_as: acts_as, label: label, memory_remove: memory_remove,
             model_name: model_name, model_key: model_key, session_root: context.repo_root(base) || base,
             chi_dirs: -> { chi_dirs(context, base) })
       end
 
       # What a plugin tool's targets: callable says the call acts on:
-      # {command:, paths:, cwd:}, each optional; a callable that raises or
-      # gives something else counts as nothing (and is logged).
+      # {command:, paths:, cwd:, acts_as:, args:, label:}, each optional; a callable
+      # that raises or gives something else counts as nothing (and is
+      # logged). args: counts when it is a Hash; acts_as: is dropped (and
+      # logged) when it names a core tool or another bundle's tool, so a
+      # call can't pass for one and match (or reuse the approvals of) its
+      # rules. label: counts when it is one short line (.label_of).
       def self.plugin_targets(call, registry)
         entry = registry && registry[call[:name].to_s]
-        none = { command: nil, paths: [], cwd: nil }
+        none = { command: nil, paths: [], cwd: nil, acts_as: nil, args: nil, label: nil }
         return none unless entry && !entry.core? && entry.targets
 
         given = entry.targets.call(call)
@@ -101,13 +127,50 @@ module Samagotchi
 
         given = given.transform_keys(&:to_sym)
         command = given[:command].to_s
-        { command: command.empty? ? nil : command, paths: Array(given[:paths]).map(&:to_s), cwd: given[:cwd] }
+        { command: command.empty? ? nil : command, paths: Array(given[:paths]).map(&:to_s), cwd: given[:cwd],
+          acts_as: acts_as_of(given[:acts_as], entry, registry), args: given[:args].is_a?(Hash) ? given[:args] : nil,
+          label: label_of(given[:label], entry) }
       rescue StandardError => e
         Log.warn(:plugins, "plugin_targets_failed", tool: call[:name].to_s, error: e.class.name,
                                                     msg: "#{call[:name]} targets failed: #{e.message}")
         none
       end
 
+      # +name+ as the acts_as of +entry+'s calls: nil for none, and for a
+      # core tool or a tool another bundle registered (logged); the tool's
+      # own name is no alias either.
+      def self.acts_as_of(name, entry, registry)
+        name = name.to_s.strip
+        return nil if name.empty? || name == entry.name
+
+        other = registry[name]
+        whose = if CORE_TOOLS.include?(name) || other&.core? then "a core tool"
+                elsif other && other.source != entry.source then "bundle #{other.source}'s tool"
+                end
+        return name unless whose
+
+        Log.warn(:plugins, "plugin_acts_as_dropped", tool: entry.name, acts_as: name,
+                                                     msg: "#{entry.name} targets: acts_as #{name} dropped: it is #{whose}")
+        nil
+      end
+
+      # The longest label: the question takes from targets:.
+      LABEL_CHARS = 80
+
+      # +label+ as a call's question label: stripped; nil for none, and for
+      # anything but a String of one line up to LABEL_CHARS (logged).
+      def self.label_of(label, entry)
+        return nil if label.nil?
+
+        text = label.is_a?(String) ? label.strip : nil
+        return nil if text && text.empty?
+        return text if text && !text.include?("\n") && text.length <= LABEL_CHARS
+
+        Log.warn(:plugins, "plugin_label_ignored", tool: entry.name,
+                                                   msg: "#{entry.name} targets: label ignored: not one line of at most #{LABEL_CHARS} characters")
+        nil
+      end
+
       # chi's own dirs (ParentApprovals.chi_dirs) and the session repo's
       # git hooks dir.
       def self.chi_dirs(context, base)
@@ -133,8 +196,10 @@ module Samagotchi
       end
 
       # @param chi_dirs [#call, nil] → the dirs touches_chi? looks for
-      def initialize(tool:, command:, paths:, cwd:, repo_root:, repo: nil, args: nil, model_name: nil, model_key: nil,
-                     session_root: nil, chi_dirs: nil, memory_remove: false)
+      def initialize(tool:, command:, paths:, cwd:, repo_root:, repo: nil, args: nil, acts_as: nil, label: nil,
+                     model_name: nil, model_key: nil, session_root: nil, chi_dirs: nil, memory_remove: false)
+        @acts_as = acts_as
+        @label = label
         @memory_remove = memory_remove
         @repo = repo
         @chi_dirs = chi_dirs

data/lib/samagotchi/idle_client.rb

@@ -24,10 +24,14 @@ module Samagotchi
     # Raised when summarization fails (server down, timeout, malformed body…).
     class SummarizeError < StandardError; end
 
-    # What #summarize returns: the recap text and the model that answered
-    # (the server's name for it; nil when the reply names none). #to_s is
-    # the text.
-    Summary = Data.define(:text, :model) do
+    # What #summarize and #ask return: the text and the model that
+    # answered (the server's name for it; nil when the reply names none).
+    # +top_logprobs+: the first token's alternatives (LLM::TokenLogprob)
+    # when #ask asked for logprobs and the server sent them, else [].
+    # #to_s is the text.
+    Summary = Data.define(:text, :model, :top_logprobs) do
+      def initialize(top_logprobs: [].freeze, **) = super
+
       def to_s = text
     end
 
@@ -40,12 +44,21 @@ module Samagotchi
     # @param timeout [Numeric] HTTP request timeout. Kept to the recap's own
     #   wait budget (not the chat's global request_timeout) so an abandoned
     #   summarize thread can't outlive the recap attempt by minutes.
-    def initialize(model:, base_url: nil, api_key_env: nil, timeout: DEFAULT_TIMEOUT_SECONDS, env: ENV)
+    # @param purpose [String] what the requests are for, in the HTTP log
+    #   lines and error messages ("recap", "broadcast")
+    def initialize(model:, base_url: nil, api_key_env: nil, timeout: DEFAULT_TIMEOUT_SECONDS, env: ENV, purpose: "recap")
       @model = model
       # A recap is best-effort: one short attempt, no retries. The idle job
       # tries again after the next activity, never on its own.
-      @chat = LLM::OpenAIChat.new(base_url: base_url.to_s, host_name: "recap", api_key_env: api_key_env,
-                                  stream: false, retries: false, timeout: timeout, env: env, purpose: "recap")
+      @chat = LLM::OpenAIChat.new(base_url: base_url.to_s, host_name: purpose, api_key_env: api_key_env,
+                                  stream: false, retries: false, timeout: timeout, env: env, purpose: purpose)
+    end
+
+    # A client for +target+ (an IdleTarget: a recap's, ctx.ask_model's, a
+    # broadcast's triage model).
+    # @return [IdleClient]
+    def self.for(target, **)
+      new(model: target.model, base_url: target.base_url, api_key_env: target.api_key_env, **)
     end
 
     THINK_RE = /<\|think\|.*?\|think\|>/m
@@ -77,25 +90,31 @@ module Samagotchi
       messages = prompt.is_a?(Array) ? prompt : [{ role: "user", content: prompt.to_s.strip }]
       return nil if messages.all? { |m| m[:content].to_s.strip.empty? }
 
-      content, served = generate(messages)
-      cleaned = content.to_s.strip
-      cleaned.empty? ? nil : Summary.new(text: cleaned, model: served)
+      response = generate(messages)
+      cleaned = response.text.to_s.strip
+      cleaned.empty? ? nil : Summary.new(text: cleaned, model: response.model)
     rescue SummarizeError
       raise
     rescue StandardError => e
       raise SummarizeError, "recap summarization failed: #{e.class}: #{e.message}"
     end
 
-    # One side answer (a plugin's ctx.ask_model): +messages+ as they are, no
-    # tools, thinking off. An answer cut off by +max_tokens+ is kept as it
-    # is, marked with "…". Cancelling +cancel_controller+ aborts the request.
+    # One side answer (a plugin's ctx.ask_model, a broadcast's triage):
+    # +messages+ as they are, no tools, thinking off. An answer cut off by
+    # +max_tokens+ is kept as it is, marked with "…". Cancelling
+    # +cancel_controller+ aborts the request.
+    # @param kind [String] what it is for, in the usage log line
+    # @param options [Hash] more request body fields (logprobs: true,
+    #   top_logprobs: 5)
     # @return [Summary] the answer ("" when the model said nothing)
-    # @raise [SummarizeError] any failure but a cancel
+    # @raise [SummarizeError] any failure but a cancel; its #cause is an
+    #   LLM::BadRequest when the host refused the request (+options+ it
+    #   doesn't take, say)
     # @raise [LLM::RequestCancelled] +cancel_controller+ was cancelled
-    def ask(messages, max_tokens: MAX_TOKENS, cancel_controller: nil)
-      content, served = generate(messages, max_tokens: max_tokens, cancel_controller: cancel_controller, whole_sentences: false,
-                                           kind: "ask")
-      Summary.new(text: content.to_s.strip, model: served)
+    def ask(messages, max_tokens: MAX_TOKENS, cancel_controller: nil, kind: "ask", options: {})
+      response = generate(messages, max_tokens: max_tokens, cancel_controller: cancel_controller, whole_sentences: false,
+                                    kind: kind, options: options)
+      Summary.new(text: response.text.to_s.strip, model: response.model, top_logprobs: response.top_logprobs)
     rescue SummarizeError, LLM::RequestCancelled
       raise
     rescue StandardError => e
@@ -104,15 +123,16 @@ module Samagotchi
 
     private
 
-    # One plain /chat/completions request. Returns the cleaned assistant text
-    # ("" when there is nothing after stripping) and the served model's name
-    # (nil when the reply names none). Raises SummarizeError when
+    # One plain /chat/completions request. Returns a Summary of the cleaned
+    # assistant text ("" when there is nothing after stripping), the served
+    # model's name (nil when the reply names none) and the first token's
+    # logprobs. Raises SummarizeError when
     # the reply has neither content nor reasoning_content. Cut off by
     # +max_tokens+, the text keeps its finished sentences (+whole_sentences+)
     # or all of it, with "…".
-    def generate(messages, max_tokens: MAX_TOKENS, cancel_controller: nil, whole_sentences: true, kind: "recap")
+    def generate(messages, max_tokens: MAX_TOKENS, cancel_controller: nil, whole_sentences: true, kind: "recap", options: {})
       response = begin
-        request(messages, max_tokens, cancel_controller)
+        request(messages, max_tokens, cancel_controller, options)
       rescue LLM::BadRequest => e
         raise unless e.reasoning_refused? && !@thinking_refused
 
@@ -120,7 +140,7 @@ module Samagotchi
         # fields, and leave them out from now on.
         @thinking_refused = true
         Log.info(:recap, "thinking_refused", model: @model, detail: e.detail)
-        request(messages, max_tokens, cancel_controller)
+        request(messages, max_tokens, cancel_controller, options)
       end
       log_usage(response, kind)
       content = response.text
@@ -130,7 +150,7 @@ module Samagotchi
       cut_off = response.finish_reason == "length"
       # Reasoning cut off by max_tokens is the model's thinking, not a recap
       # (a server that ignores the thinking switch thinks until the limit).
-      return ["", response.model] if content.empty? && cut_off
+      return Summary.new(text: "", model: response.model, top_logprobs: response.top_logprobs) if content.empty? && cut_off
 
       # Prefer content, fall back to a finished reasoning_content (e.g.
       # Qwen3.6), and strip thinking tokens some models (Qwen, Gemma) leave
@@ -138,7 +158,7 @@ module Samagotchi
       text = self.class.strip_thinking(content.empty? ? reasoning : content)
       # Cut off by max_tokens: keep the sentences that finished ("" if none).
       text = whole_sentences ? self.class.full_sentences(text) : "#{text}…" if cut_off && !text.empty?
-      [text, response.model]
+      Summary.new(text: text, model: response.model, top_logprobs: response.top_logprobs)
     rescue LLM::ProtocolError => e
       raise SummarizeError, "server returned no parseable assistant content (#{e.message})"
     end
@@ -153,9 +173,9 @@ module Samagotchi
                                         cached: fields[:cached_tokens], cache_write: fields[:cache_write_tokens])
     end
 
-    def request(messages, max_tokens, cancel_controller)
+    def request(messages, max_tokens, cancel_controller, options = {})
       @chat.chat(messages: messages, model: @model, tools: [], cancel_controller: cancel_controller,
-                 options: { max_tokens: max_tokens, **thinking_fields })
+                 options: { max_tokens: max_tokens, **thinking_fields, **options })
     end
 
     # A recap or side answer is short and tool-less: thinking off, whatever

data/lib/samagotchi/idle_recap.rb

@@ -6,6 +6,7 @@ require "monitor"
 require "time"
 
 require_relative "idle_client"
+require_relative "idle_target"
 require_relative "output_formatter"
 require_relative "steer"
 require_relative "recap_store"
@@ -279,7 +280,7 @@ module Samagotchi
     # attempt (the session's current model, so a /model switch counts).
     # @param base_url [String] the OpenAI API base the recap asks
     # @param api_key_env [String, nil] the variable holding its key
-    # @param target [#call, nil] -> {base_url:, api_key_env:, model:, label:}
+    # @param target [#call, nil] -> IdleTarget
     def initialize(engine:, model: nil, base_url: nil, api_key_env: nil, target: nil,
                    inactivity: DEFAULT_INACTIVITY_SECONDS,
                    min_user_turns: DEFAULT_MIN_USER_TURNS,
@@ -292,7 +293,7 @@ module Samagotchi
 
       @engine = engine
       @target = target || lambda {
-        { base_url: base_url, api_key_env: api_key_env, model: model, label: model }
+        IdleTarget.new(base_url: base_url, api_key_env: api_key_env, model: model, label: model)
       }
       @inactivity = inactivity
       @min_user_turns = min_user_turns
@@ -455,7 +456,7 @@ module Samagotchi
 
       asked = target
       @in_flight = { thread: spawn_summarize(client_for(asked), prompt), generation: gen, deadline: @clock.call + @timeout,
-                     covered: parsed.size, covered_digest: self.class.digest(parsed.last), model: asked[:label] }
+                     covered: parsed.size, covered_digest: self.class.digest(parsed.last), model: asked.label }
       :started
     rescue StandardError
       :failed
@@ -534,9 +535,9 @@ module Samagotchi
     def client_for(asked)
       return @client_override if @client_override
 
-      key = asked.values_at(:base_url, :api_key_env, :model)
+      key = [asked.base_url, asked.api_key_env, asked.model]
       unless @client && @client_key == key
-        @client = IdleClient.new(model: asked[:model], base_url: asked[:base_url], api_key_env: asked[:api_key_env], timeout: @timeout)
+        @client = IdleClient.for(asked, timeout: @timeout)
         @client_key = key
       end
       @client