samagotchi 0.2.0

data/lib/samagotchi/turn_flow.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+require_relative "output_formatter"
+require_relative "turn_note"
+require_relative "context_note"
+
+module Samagotchi
+  # The state around turns that the REPL and a session worker share, kept out
+  # of either loop: the pre-turn checkpoint (what !rollback and a failed turn
+  # restore), the continue offer after a turn that ran out of iterations, and
+  # the checkpoint a continue turn starts from.
+  #
+  # It edits the conversation only through the Engine's out-of-turn messages
+  # API (messages_checkpoint / rollback_to / append_messages); saving the
+  # session and telling the user are the host's.
+  class TurnFlow
+    CONTINUE_COMMAND = "/continue"
+    SUMMARY_PROMPT_LIMIT = 600
+    SUMMARY_MODEL_LIMIT = 360
+    SUMMARY_PARAMS_LIMIT = 80
+    SUMMARY_TOOLS_LIMIT = 5
+
+    # Read an answer to the continue offer.
+    # @return [Array(Symbol, String|nil)] [:resume | :abort | :abort_with_reason | :invalid, reason]
+    def self.continue_decision(input)
+      normalized = input.to_s.strip
+      return [:resume, nil] if normalized.empty?
+
+      lowered = normalized.downcase
+      return [:resume, nil] if lowered == CONTINUE_COMMAND || lowered == "yes" || lowered == "y"
+      return [:abort, nil] if lowered == "no" || lowered == "n"
+
+      reason_match = normalized.match(/\A(?:no|n)\s*[,:\-]\s*(.+)\z/i)
+      if reason_match
+        reason = reason_match[1].to_s.strip
+        return [:abort, nil] if reason.empty?
+
+        return [:abort_with_reason, reason]
+      end
+
+      [:invalid, nil]
+    end
+
+    # @return [Hash, nil] the pending continue offer: {context:, no_interrupt:}
+    #   (context summarizes the interrupted turn for a "no, <reason>")
+    attr_reader :offer
+
+    def initialize(engine:)
+      @engine = engine
+      @checkpoint = nil
+      @continue_checkpoint = nil
+      @offer = nil
+    end
+
+    def awaiting_continue? = !@offer.nil?
+
+    # A prompt turn is about to start: remember the conversation before it.
+    def before_prompt_turn
+      @checkpoint = @engine.messages_checkpoint
+    end
+
+    # A continue turn is about to start: a cancel goes back to here.
+    def before_continue_turn
+      @continue_checkpoint = @engine.messages_checkpoint
+    end
+
+    # Take a turn's result.
+    # @param continue [Boolean] it was a continue turn
+    # @param no_interrupt [Boolean] the turn ran with no iteration limit to
+    #   speak of; an offer it makes keeps that for its continue turn
+    # @return [Symbol] :completed, :continue_offered, :cancelled (a prompt
+    #   turn: its partial progress stays, !rollback can undo it) or
+    #   :continue_cancelled (back to before the continue; the offer stays)
+    def after_turn(result, continue: false, no_interrupt: false)
+      if result.respond_to?(:canceled?) && result.canceled?
+        if continue
+          restore(@continue_checkpoint)
+          return :continue_cancelled
+        end
+
+        # The kernel salvaged the completed tool calls and the partial reply
+        # into the conversation; without one, the turn leaves nothing.
+        restore(@checkpoint) if @checkpoint && !conversation_of(result)
+        @offer = nil
+        return :cancelled
+      end
+
+      if result.respond_to?(:resumable?) && result.resumable?
+        @offer = { context: interrupted_turn_context(result), no_interrupt: no_interrupt }
+        :continue_offered
+      else
+        @offer = nil
+        @checkpoint = nil
+        :completed
+      end
+    end
+
+    # A prompt turn failed: back to the conversation before it, plus the
+    # note that says so (TurnNote.failed) in place of an older one at the
+    # tail, so the model reads why its last message went unanswered.
+    def prompt_turn_failed(note: nil)
+      if @checkpoint
+        restore(@checkpoint, note: note)
+      elsif note
+        @engine.rollback_to(TurnNote.replace_trailing(@engine.messages_checkpoint, note))
+      end
+      @offer = nil
+      @checkpoint = nil
+    end
+
+    # Answer the offer with no: the interrupted turn is discarded, and a
+    # reason (with a summary of that turn) is left for the model to read.
+    def abort_continue!(reason: nil)
+      restore(@checkpoint) if @checkpoint
+      @checkpoint = nil
+      @engine.append_messages([{ role: "user", content: reason_message(reason) }]) if reason
+      @offer = nil
+    end
+
+    # A new prompt came instead of an answer (a worker takes it): the offer
+    # is gone and the partial turn stays, as after a Ctrl-C.
+    def drop_offer!
+      @offer = nil
+    end
+
+    # Restore the pre-turn checkpoint (!rollback after a Ctrl-C). A pending
+    # offer goes too: the turn it offered to continue is gone. (The REPL
+    # reads every line as an answer while an offer is pending; a worker
+    # also takes !rollback then.)
+    # @return [Boolean] false when there is none
+    def rollback!
+      return false unless @checkpoint
+
+      restore(@checkpoint)
+      @checkpoint = nil
+      @offer = nil
+      true
+    end
+
+    # The conversation changed outside a turn (!cmd output): rolling back
+    # past that would silently drop it.
+    def note_conversation_changed
+      @checkpoint = nil
+    end
+
+    # A reminder turn ran. The checkpoint stays only for a pending offer.
+    def after_reminder_turn
+      @checkpoint = nil unless awaiting_continue?
+    end
+
+    private
+
+    # Back to +checkpoint+, keeping the context notes that arrived since:
+    # notes land between turns, after the checkpoint was taken, and a
+    # rollback must not drop them. One rollback, +note+ included.
+    def restore(checkpoint, note: nil)
+      kept = Array(checkpoint).filter_map { |m| m[:note_id] }
+      arrived = @engine.messages_checkpoint.select { |m| ContextNote.note?(m) && !kept.include?(m[:note_id]) }
+      restored = Array(checkpoint) + arrived
+      restored = TurnNote.replace_trailing(restored, note) if note
+      @engine.rollback_to(restored)
+    end
+
+    def conversation_of(result)
+      result.conversation if result.respond_to?(:conversation) && result.conversation.is_a?(Array)
+    end
+
+    def interrupted_turn_context(result)
+      messages = interrupted_turn_messages(conversation_of(result))
+      {
+        original_prompt: preview_text(messages.find { |m| m[:role] == "user" }&.dig(:content), SUMMARY_PROMPT_LIMIT),
+        tool_trace: tool_trace(result),
+        last_model_intent: preview_text(model_intent(messages.reverse.find { |m| m[:role] == "model" }&.dig(:content)), SUMMARY_MODEL_LIMIT)
+      }
+    end
+
+    # The messages the turn added after the checkpoint (all of them after an
+    # empty one: a new session's first turn). The prefix is matched by role,
+    # not content: the kernel returns earlier model messages without their
+    # thinking, so they differ from the saved ones, one for one.
+    def interrupted_turn_messages(conversation)
+      checkpoint = Array(@checkpoint)
+      conversation = Array(conversation)
+      return [] if conversation.length < checkpoint.length
+      return [] unless conversation.first(checkpoint.length).map { |m| m[:role] } == checkpoint.map { |m| m[:role] }
+
+      conversation[checkpoint.length..] || []
+    end
+
+    def tool_trace(result)
+      activities = result.respond_to?(:tool_activity) ? Array(result.tool_activity) : []
+      activities.last(SUMMARY_TOOLS_LIMIT).map do |activity|
+        tool = activity[:tool].to_s.strip
+        status = activity[:status].to_s.strip
+        params = preview_text(activity[:params], SUMMARY_PARAMS_LIMIT)
+        parts = [tool]
+        parts << "status=#{status}" unless status.empty?
+        parts << "params=#{params}" unless params.empty?
+        parts.join(" ")
+      end
+    end
+
+    def reason_message(reason)
+      context = @offer && @offer[:context]
+      lines = ["I chose not to continue the interrupted turn because: #{reason}"]
+      lines << ""
+      lines << "Interrupted turn summary:"
+      original_prompt = context && context[:original_prompt]
+      lines << "- original_prompt: #{original_prompt.to_s.empty? ? "(unavailable)" : original_prompt}"
+
+      tool_trace = context ? Array(context[:tool_trace]) : []
+      if tool_trace.empty?
+        lines << "- interrupted_tools: (none)"
+      else
+        lines << "- interrupted_tools: #{tool_trace.join("; ")}"
+      end
+
+      model_intent = context && context[:last_model_intent]
+      lines << "- last_model_intent: #{model_intent.to_s.empty? ? "(unavailable)" : model_intent}"
+      lines << ""
+      lines << "Please keep the original prompt context. If my next message does not provide a clear replacement request, ask what we should do instead."
+      lines.join("\n")
+    end
+
+    # The model's words without its thinking and tool-call markup; when it
+    # wrote nothing else, its thinking says what it was about to do.
+    def model_intent(content)
+      text = OutputFormatter.strip(content)
+      return text unless text.empty?
+
+      OutputFormatter.strip(content.to_s.gsub(%r{</?think>}, ""))
+    end
+
+    def preview_text(text, limit)
+      normalized = text.to_s.gsub(/\s+/, " ").strip
+      return "" if normalized.empty?
+      return normalized if normalized.length <= limit
+
+      normalized[0, limit].rstrip + "..."
+    end
+  end
+end

data/lib/samagotchi/turn_note.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # The one-line system note a turn leaves in the conversation when it ends
+  # without an answer: failed before the model replied, cancelled, or over
+  # with nothing visible. The UIs show these ends live (`turn failed …`, a
+  # cancel line, `(the model returned an empty answer)`), but the model saw
+  # none of that on its next turn: the session held an unanswered user
+  # message and no reason. A tail system message, like a reminder or a
+  # context note, keeps the prompt cache and is hidden by the UIs (they
+  # show system messages only when `kind: note`).
+  module TurnNote
+    KIND = "turn_note"
+    OPEN = "[SYSTEM: "
+    CLOSE = "]"
+
+    module_function
+
+    # @param summary [String] the error's one-line summary
+    # @param restored [Boolean] the prompt went back to its sender (the
+    #   failed user message is not in the conversation any more)
+    # @param continued [Boolean] it was a continue turn (no user message)
+    def failed(summary, restored: false, continued: false)
+      tail = if restored then "The message went back to the user, who may send it again."
+             elsif continued then "The continued turn stopped there."
+             else "The user's last message was not answered."
+             end
+      message("the previous turn failed before any answer: #{one_line(summary)}. #{tail}")
+    end
+
+    # @param reason [Symbol, String, nil] the cancel reason (:ctrl_c, :user…)
+    # @param seconds [Numeric, nil] how long the turn had run
+    # @param shown [Boolean] visible text had streamed (an `[interrupted]`
+    #   model message precedes this note)
+    def cancelled(reason, seconds: nil, shown: false)
+      why = reason.to_s.empty? ? "" : " (#{reason.to_s.tr("_", "-")})"
+      after = seconds ? " after #{seconds.round}s" : ""
+      what = shown ? "the answer above ends where it was cut off." : "no answer had been shown."
+      message("the previous turn was cancelled#{why}#{after}; #{what}")
+    end
+
+    def empty
+      message("the previous turn ended with no visible answer (thinking only, or nothing). The user's last message is still unanswered.")
+    end
+
+    def note?(entry)
+      return false unless entry.respond_to?(:[])
+
+      (entry[:kind] || entry["kind"]).to_s == KIND
+    end
+
+    def message(text)
+      { role: "system", content: "#{OPEN}#{text}#{CLOSE}", kind: KIND }
+    end
+
+    # +messages+ plus +note+, in place of a note already at the tail (behind
+    # context notes at most): failed retries leave one note, not a pile.
+    def replace_trailing(messages, note)
+      list = Array(messages).dup
+      index = list.length - 1
+      index -= 1 while index >= 0 && (list[index][:role] || list[index]["role"]).to_s == "system" && !note?(list[index])
+      list.delete_at(index) if index >= 0 && note?(list[index])
+      list << note
+    end
+
+    # The last message is a reply cut short (`[interrupted]`).
+    def interrupted_tail?(messages)
+      last = Array(messages).last
+      !!(last && (last[:interrupted] || last["interrupted"]))
+    end
+
+    def one_line(text)
+      text.to_s.gsub(/\s+/, " ").strip
+    end
+  end
+end

data/lib/samagotchi/turn_tally.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # A running count of one turn's tool calls, for the one-line tally a long,
+  # tool-heavy turn shows under its activity row:
+  #
+  #   12 tool calls (2 failed) · execute ×7 · read_file ×3 · edit ×2 · last: execute command=rspec
+  #
+  # Built from the turn's :tool_call_started / :tool_call_completed events
+  # (or a joined turn's snapshot parts), with no model call. The web builds
+  # the same text from its activity rows (public/tally.js); both follow
+  # spec/shared/tally_matrix.json.
+  class TurnTally
+    # Below this many calls the "running <tool>…" row says enough.
+    MIN_CALLS = 3
+    TOP_TOOLS = 3
+    SEPARATOR = " · "
+
+    def initialize
+      reset
+    end
+
+    # @return [TurnTally] self
+    def reset
+      @calls = {}
+      self
+    end
+
+    def count
+      @calls.size
+    end
+
+    # @param key [Object] one call's identity within the turn (the event's
+    #   [iteration, call_index])
+    def started(key:, tool:, params: nil)
+      call = (@calls[key] ||= { tool: tool.to_s, params: "", status: "running" })
+      call[:tool] = tool.to_s unless tool.to_s.empty?
+      call[:params] = params.to_s unless params.nil?
+      call[:status] = "running"
+      call
+    end
+
+    # A completion with no start seen still counts as a call (as the web's
+    # activity rows do). Only "error" is a failure: a call a guardrail or an
+    # approval blocked still counts as a call, not as a failed one.
+    def completed(key:, tool:, status:, params: nil)
+      call = @calls[key] || started(key: key, tool: tool, params: params)
+      call[:params] = params.to_s if params
+      call[:status] = status.to_s == "error" ? "error" : "ok"
+      call
+    end
+
+    # Pick up a turn joined mid-way: its snapshot's tool parts.
+    # @param parts [Array<Hash>] the Bridge snapshot's current_turn parts
+    def seed(parts)
+      Array(parts).each do |part|
+        part = part.transform_keys(&:to_sym)
+        next unless part[:kind].to_s == "tool"
+
+        key = [part[:iteration].to_i, part[:call_index].to_i]
+        started(key: key, tool: part[:tool], params: part[:params])
+        completed(key: key, tool: part[:tool], status: part[:status]) unless part[:status].to_s == "running"
+      end
+      self
+    end
+
+    # @param width [Integer, nil] cut the text to this many characters
+    # @param last [Boolean] end with the last call and its params
+    # @return [String, nil] nil below MIN_CALLS
+    def text(width: nil, last: true)
+      self.class.format(@calls.values, last: last, width: width)
+    end
+
+    # @param calls [Array<Hash>] {tool:, params:, status:} in call order
+    def self.format(calls, last: true, width: nil)
+      return nil if calls.size < MIN_CALLS
+
+      failed = calls.count { |c| c[:status] == "error" }
+      head = "#{calls.size} tool calls"
+      head += " (#{failed} failed)" if failed.positive?
+      counts = calls.each_with_object(Hash.new(0)) { |c, h| h[c[:tool]] += 1 }
+      # Ties go to the tool used first (a Hash keeps insertion order, and
+      # sort_by is not stable, so the index breaks them).
+      top = counts.each_with_index.sort_by { |(_, n), i| [-n, i] }.first(TOP_TOOLS)
+      fields = [head] + top.map { |(tool, n), _| "#{tool} ×#{n}" }
+      if last
+        call = calls.last
+        params = call[:params].to_s.gsub(/\s+/, " ").strip
+        fields << "last: #{[call[:tool], params].reject(&:empty?).join(" ")}"
+      end
+      cut(fields.join(SEPARATOR), width)
+    end
+
+    def self.cut(text, width)
+      return text if width.nil? || text.length <= width
+      return text[0, width] if width < 2
+
+      "#{text[0, width - 1]}…"
+    end
+  end
+end

data/lib/samagotchi/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  VERSION = "0.2.0"
+  # Sent as the User-Agent of every HTTP request chi makes.
+  USER_AGENT = "chi/#{VERSION}"
+end

data/lib/samagotchi/vision_context.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require_relative "image_store"
+
+module Samagotchi
+  # What a turn's loops need to send images, set on the kernel by the
+  # Engine for one turn:
+  #   capability  VisionSupport::Answer (nil: unknown, send), or a callable
+  #               that answers it on first need (a probe only when a turn
+  #               has images)
+  #   session_dir where the session's images/ are (refs resolve against it)
+  #   limits      ImageStore::Limits
+  #   resizer     ImageResizer for images a tool returns (nil: detect)
+  class VisionContext
+    attr_reader :session_dir, :limits, :resizer
+
+    def initialize(capability: nil, session_dir: nil, limits: ImageStore::Limits.from_config, resizer: nil)
+      @capability = capability
+      @session_dir = session_dir
+      @limits = limits
+      @resizer = resizer
+      @mutex = Mutex.new
+    end
+
+    def capability
+      @mutex.synchronize do
+        @capability = @capability.call if @capability.respond_to?(:call)
+        @capability
+      end
+    end
+
+    def with(**changes)
+      self.class.new(capability: @capability, session_dir: session_dir, limits: limits, resizer: resizer, **changes)
+    end
+
+    # False only when the model is known not to see images.
+    def sendable? = capability.nil? || capability.value != false
+
+    # Why images aren't sent, for a line or a refusal.
+    def refusal_reason = capability&.reason || ImagePlan::CANT_SEE
+
+    # The ref's base64, or nil when it isn't a valid ref of this session.
+    def base64(ref)
+      return nil unless session_dir && ImageStore.valid_ref?(session_dir, ref)
+
+      ImageStore.base64(session_dir, ref)
+    rescue StandardError
+      nil
+    end
+
+    def data_uri(ref)
+      data = base64(ref)
+      data && "data:#{ref[:mime] || ref["mime"]};base64,#{data}"
+    end
+
+    # Stores an image a tool read or returned (source "tool", from a +path+
+    # or raw +bytes+) and returns its ref.
+    def ingest(path = nil, name: nil, bytes: nil)
+      raise ImageStore::Error, "no session to keep the image in" unless session_dir
+
+      ImageStore.ingest(session_dir, path: path, bytes: bytes, name: name, source: "tool", limits: limits,
+                                     resizer: resizer || ImageResizer.detect)
+    end
+  end
+
+  # Which images of a conversation one request sends. Every image that is
+  # not sent becomes a placeholder line: all of them when the model can't
+  # see images, the older ones past limits.max_per_request (the newest go),
+  # and any whose file is gone.
+  class ImagePlan
+    Item = Data.define(:ref, :data, :placeholder) do
+      def sent? = !data.nil?
+    end
+
+    ROLES = %w[user tool_response].freeze
+    CANT_SEE = "this model can't see images"
+    # Stands for the server's media marker in a native prompt until
+    # Client#complete swaps in the live one (random, so no typed text has it).
+    NATIVE_PLACEHOLDER = "<__chi_image_#{SecureRandom.hex(8)}__>".freeze
+
+    # @param conversation [Array<Hash>] engine-format messages
+    # @param vision [VisionContext, nil]
+    # @param data [Symbol] :base64 (native) or :data_uri (chat)
+    def initialize(conversation, vision, data: :data_uri)
+      @vision = vision
+      @data = data
+      occurrences = []
+      conversation.each_with_index do |entry, index|
+        next unless ROLES.include?(entry[:role].to_s)
+
+        Array(entry[:images]).each_index { |position| occurrences << [index, position] }
+      end
+      @limit = vision&.limits&.max_per_request || ImageStore::Limits.from_config.max_per_request
+      @sent = occurrences.last(@limit)
+    end
+
+    # The Items for conversation[+index+] (none when it has no images).
+    def items(entry, index)
+      return [] unless ROLES.include?(entry[:role].to_s)
+
+      Array(entry[:images]).each_with_index.map do |raw, position|
+        ref = ImageStore.symbolize(raw)
+        reason = skip_reason(index, position)
+        data = reason ? nil : fetch(ref)
+        reason ||= "the image file is missing" unless data
+        Item.new(ref: ref, data: data, placeholder: reason && ImageRef.placeholder(ref, reason))
+      end
+    end
+
+    # Estimated tokens of the images a request sends (ImageRef.estimated_tokens).
+    def self.estimated_tokens(conversation)
+      conversation.sum do |entry|
+        ROLES.include?(entry[:role].to_s) ? Array(entry[:images]).sum { |ref| ImageRef.estimated_tokens(ImageStore.symbolize(ref)) } : 0
+      end
+    end
+
+    private
+
+    def skip_reason(index, position)
+      return "no session images here" if @vision.nil?
+      return CANT_SEE unless @vision.sendable?
+      return "only the newest #{@limit} images are sent" unless @sent.include?([index, position])
+
+      nil
+    end
+
+    def fetch(ref)
+      @data == :base64 ? @vision.base64(ref) : @vision.data_uri(ref)
+    end
+  end
+end

data/lib/samagotchi/vision_support.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative "config"
+
+module Samagotchi
+  # Whether a model can take images, asked before a turn with images is
+  # sent: true (send), false (refuse, with a reason), or nil (unknown: send,
+  # and map the provider's error if it says no).
+  #
+  # First match wins:
+  #   1. config: models.<name>.vision, then hosts.<name>.vision
+  #   2. a native host: llama.cpp only, and it must give a media marker, have
+  #      vision in /props modalities, and use the profile's image template
+  #      (the prompt can't carry an image any other way)
+  #   3. a chat host: a local llama.cpp's /props modalities, then the host's
+  #      model list (input_modalities / "multimodal")
+  #   4. unknown
+  module VisionSupport
+    Answer = Data.define(:value, :reason) do
+      def yes? = value == true
+      def no? = value == false
+    end
+
+    # @param target [HostRegistry::ModelTarget]
+    # @param profile [ModelProfile, nil] the model's prompt profile (native)
+    # @param adapter [LLM::OpenAIChat, nil] the chat host's adapter
+    # @param models [Hash, nil] ConfigFile.model_settings (specs)
+    # @return [Answer]
+    def self.for(target, profile: nil, adapter: nil, models: nil)
+      entry = target.entry
+      configured = configured(target, entry, models)
+      return configured if configured&.no?
+
+      if entry.chat?
+        configured || chat(target, entry, adapter)
+      else
+        native(target, entry, profile, trust_config: configured&.yes?)
+      end
+    end
+
+    # The media marker the running llama.cpp wants in the prompt, or nil.
+    def self.media_marker(props)
+      marker = props&.answered? && props.body.is_a?(Hash) ? props.body["media_marker"] : nil
+      marker.is_a?(String) && !marker.empty? ? marker : nil
+    end
+
+    def self.configured(target, entry, models)
+      models ||= begin
+        ConfigFile.model_settings
+      rescue StandardError
+        {}
+      end
+      [target.model, target.bare_model].map { |name| name.to_s.strip.downcase }.uniq.each do |key|
+        value = models.dig(key, :vision)
+        next if value.nil?
+
+        return Answer.new(value: value, reason: value ? nil : "models: #{key} sets vision: false")
+      end
+      return nil if entry.vision.nil?
+
+      Answer.new(value: entry.vision, reason: entry.vision ? nil : "hosts.#{entry.name} sets vision: false")
+    end
+
+    def self.native(target, entry, profile, trust_config:)
+      client = target.client
+      transport = client.respond_to?(:transport) ? client.transport.name : :llama_cpp
+      return no("#{transport} hosts take no images (only llama.cpp does)") unless transport == :llama_cpp
+
+      props = client.respond_to?(:server_props) ? client.server_props(model: target.bare_model) : nil
+      return no("can't reach /props for the media marker") unless props&.answered?
+
+      body = props.body.is_a?(Hash) ? props.body : {}
+      unless trust_config || body.dig("modalities", "vision") == true
+        return no("the server has no vision model loaded (start llama.cpp with --mmproj)")
+      end
+      return no("the server gives no media marker (update llama.cpp)") unless media_marker(props)
+      return no("profile #{profile&.name || "?"} has no image template yet") unless profile&.image_template
+
+      open = profile.image_open_token
+      unless open.empty? || body["chat_template"].to_s.include?(open)
+        return no("the server's chat template doesn't use #{open} (profile #{profile.name})")
+      end
+
+      Answer.new(value: true, reason: nil)
+    end
+
+    def self.chat(target, entry, adapter)
+      unless entry.remote?
+        props = entry.client.respond_to?(:server_props) ? entry.client.server_props(model: target.bare_model) : nil
+        if props&.answered? && props.body.is_a?(Hash) && props.body.key?("modalities")
+          vision = props.body.dig("modalities", "vision") == true
+          return vision ? Answer.new(value: true, reason: nil) : no("the server has no vision model loaded (start llama.cpp with --mmproj)")
+        end
+      end
+
+      listed = adapter.respond_to?(:image_input) ? adapter.image_input(model: target.bare_model) : nil
+      return Answer.new(value: true, reason: nil) if listed == true
+      return no("host #{entry.name} lists #{target.bare_model} as text-only") if listed == false
+
+      Answer.new(value: nil, reason: nil)
+    rescue StandardError
+      Answer.new(value: nil, reason: nil)
+    end
+
+    def self.no(reason) = Answer.new(value: false, reason: reason)
+
+    private_class_method :configured, :native, :chat, :no
+  end
+end