samagotchi 0.2.0

data/lib/samagotchi/plugin/context.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "../log"
+require_relative "../guardrails/context"
+require_relative "../idle_client"
+require_relative "side_question"
+require_relative "sessions"
+
+module Samagotchi
+  module Plugin
+    # The Engine's side of a Context: callables, so the Engine itself is
+    # never handed out. +messages+ returns the conversation, +notify+ takes
+    # (text, level, label), +ask_user+ takes (question:, options:, header:,
+    # allow_freeform:, hook:) like the hook runtime's, +card+ takes
+    # Engine#show_card's keywords and returns the id, +ask_model+ takes
+    # (chat messages, timeout:, max_tokens:, cancel_controller:) and returns
+    # the answer text.
+    # +messages_partial+ says whether +messages+ leaves out a running turn;
+    # +model_name+ and +state_dir+ are what ctx.sessions forks with.
+    Host = Struct.new(:session_id, :cwd, :messages, :messages_partial, :notify, :ask_user, :cancelled, :card,
+                      :ask_model, :model_name, :state_dir, keyword_init: true)
+
+    # ctx.ask_model failed: the model couldn't be reached, timed out, or
+    # sent nothing usable. The message says why, for the user.
+    class ModelError < StandardError; end
+
+    # ctx.ask_model was cancelled (its cancel: controller).
+    class ModelCancelled < ModelError; end
+
+    # What a plugin's handlers get as +ctx+ (docs/plugins.md): the session
+    # they run for, the bundle's settings and storage, a log, and the
+    # user-facing helpers hooks have. One per plugin, for the Engine's life:
+    # each read is of the session now.
+    class Context
+      # Debug-log records tagged plugins, with bundle=<bundle> (tags are a
+      # closed list, LogLine::TAGS).
+      class Logger
+        def initialize(bundle)
+          @bundle = bundle
+        end
+
+        %i[debug info warn error].each do |level|
+          define_method(level) do |event, **fields|
+            Samagotchi::Log.public_send(level, :plugins, event.to_s, bundle: @bundle, **fields)
+          end
+        end
+      end
+
+      # @return [String] the bundle the plugin came with
+      attr_reader :bundle
+
+      # @return [Hash] config.yml `bundles: <bundle>:` (string keys), frozen
+      attr_reader :settings
+
+      # @return [Logger]
+      attr_reader :log
+
+      # @param label [String] "<file> (bundle <name>)", what notices and
+      #   questions are labelled by
+      # @param host [Host]
+      def initialize(bundle:, label:, settings:, host:, env: ENV)
+        @bundle = bundle.to_s
+        @label = label
+        @settings = deep_freeze(settings.is_a?(Hash) ? settings : {})
+        @host = host
+        @env = env
+        @log = Logger.new(@bundle)
+        @git = Guardrails::GitInfo.new
+        @data_dir = nil
+      end
+
+      # @return [String, nil] the session's id (nil before the first one)
+      def session_id = @host.session_id.call
+
+      # @return [String] the session's working directory
+      def cwd = @host.cwd.call || Dir.pwd
+
+      # @return [String, nil] the git checkout holding #cwd
+      def repo_root = @git.root(cwd)
+
+      # $XDG_STATE_HOME/samagotchi/plugins/<bundle>/, created on first use.
+      # @return [String]
+      def data_dir
+        @data_dir ||= begin
+          xdg = @env.fetch("XDG_STATE_HOME", "").to_s.strip
+          base = xdg.empty? ? File.join(Dir.home, ".local", "state") : xdg
+          File.join(base, "samagotchi", "plugins", @bundle).tap { |dir| FileUtils.mkdir_p(dir) }
+        end
+      end
+
+      # The conversation so far, a frozen copy, without the system prompt.
+      # While a turn runs, a session worker's (attached TUI, web) adds the
+      # turn so far: its prompt, the model's text and the lines merged into
+      # it; the REPL's is the conversation before that turn
+      # (#messages_partial?).
+      # @return [Array<Hash>]
+      def messages
+        Array(@host.messages.call).map { |message| message.dup.freeze }.freeze
+      end
+
+      # Whether #messages leaves out a running turn (the REPL mid-turn), so
+      # a plugin can say what its answer is about.
+      def messages_partial? = !!@host.messages_partial&.call
+
+      # One line to the user, labelled by the plugin, like a hook's
+      # event[:notify]. Every UI shows it, during a turn or between turns.
+      # @param level [Symbol] :info or :warn
+      def notify(text, level: :info)
+        @host.notify.call(text.to_s, level, @label)
+        nil
+      end
+
+      # A card in every UI: a title, a body (markdown in the web, plain
+      # text in the terminal) and actions, each a command line the session
+      # runs when the user picks it (docs/plugins.md, Cards). Showing a card
+      # with an earlier card's id replaces that card.
+      # @param actions [Array<Hash>] {label:, command:} ("/hello again")
+      # @param level [Symbol] :info or :warn
+      # @param id [String, nil] an earlier card's id to replace it
+      # @return [String] the card's id
+      # @raise [ArgumentError] no title, a bad level or action
+      def card(title:, body: "", actions: [], level: :info, id: nil)
+        @host.card.call(source: @bundle, title: title, body: body, actions: actions, level: level, id: id)
+      end
+
+      # A side answer (plan D7): one request to the session's current model
+      # on its host, with no tools and thinking off. It writes nothing,
+      # fires no hooks, and doesn't touch the conversation. It blocks until
+      # the answer comes, so call it from an anytime command or your own
+      # thread; with a local server that runs one request at a time it
+      # waits for a running turn.
+      # @param messages [Array<Hash>] the conversation to ask about
+      #   (usually #messages); sent as a transcript without the system
+      #   prompt, tool calls, tool output and thinking; an image is a line
+      #   naming it
+      # @param prompt [String] the question
+      # @param system [String, nil] instructions (a short default)
+      # @param timeout [Numeric] seconds
+      # @param max_tokens [Integer, nil] the answer's limit (default
+      #   ASK_MAX_TOKENS); an answer cut off ends with "…"
+      # @param cancel [CancellationController, nil] cancelling it aborts
+      #   the request
+      # @return [String] the answer ("" when the model said nothing)
+      # @raise [ModelError] the request failed or timed out
+      # @raise [ModelCancelled] +cancel+ was cancelled
+      def ask_model(messages:, prompt:, system: nil, timeout: 120, max_tokens: nil, cancel: nil)
+        raise ArgumentError, "ask_model needs a prompt" if prompt.to_s.strip.empty?
+
+        request = SideQuestion.request(messages: messages, prompt: prompt, system: system)
+        limit = max_tokens.nil? ? ASK_MAX_TOKENS : Integer(max_tokens)
+        @host.ask_model.call(request, timeout: Float(timeout), max_tokens: limit, cancel_controller: cancel).to_s
+      rescue IdleClient::SummarizeError => e
+        raise ModelError, e.message
+      rescue LLM::RequestCancelled
+        raise ModelCancelled, "the request was cancelled"
+      end
+
+      # ctx.ask_model's answer limit when none is given.
+      ASK_MAX_TOKENS = 1024
+
+      # Other sessions: fork one from a conversation, send one a message,
+      # read one (Sessions).
+      # @return [Sessions]
+      def sessions
+        @sessions ||= Sessions.new(@host)
+      end
+
+      # A single-select question through the question flow, like a hook's
+      # event[:ask_user].
+      # @return [Hash, nil] {selected:, freeform:, selected_indices:}, or nil
+      #   (no one to ask, cancelled, bad options)
+      def ask_user(question:, options:, header: nil, allow_freeform: false)
+        @host.ask_user.call(question: question, options: options, header: header, allow_freeform: allow_freeform,
+                            hook: @label)
+      end
+
+      # Whether the running turn was cancelled (a long tool should stop).
+      def cancelled? = !!@host.cancelled.call
+
+      private
+
+      def deep_freeze(value)
+        case value
+        when Hash then value.to_h { |k, v| [deep_freeze(k), deep_freeze(v)] }.freeze
+        when Array then value.map { |v| deep_freeze(v) }.freeze
+        when String then value.dup.freeze
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/plugin/loader.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require_relative "api"
+require_relative "context"
+require_relative "../hooks"
+require_relative "../log"
+require_relative "../version"
+require_relative "../memory_bundle/manifest"
+require_relative "../memory_bundle/provenance"
+
+module Samagotchi
+  module Plugin
+    # What a plugin registers into: an Engine's own registries.
+    # +context_for+ is (bundle_name, settings, label) → the Plugin::Context
+    # its handlers get; +tools_changed+ drops what was built from the tools
+    # (the Engine's system prompts); +services+ (Plugin::Services) is what
+    # Engine#shutdown stops; +stage_tools+ is (bundle, specs, context),
+    # chi.replace_tools' set, which the Engine applies on its turn thread;
+    # +init+ adds a chi.init task (Engine#add_init_task).
+    Registries = Struct.new(:commands, :tools, :hooks, :context_for, :tools_changed, :services, :stage_tools, :init,
+                            keyword_init: true)
+
+    # Loads installed bundles' plugins (manifest plugin: {file:, sha256:})
+    # into an Engine's registries (docs/plugins.md).
+    #
+    # For each bundle, by name: the file must match the sha256 recorded at
+    # install and chi must meet the bundle's requires_chi. The file is
+    # module_eval'd into the bundle's namespace (as its hooks are), the
+    # class named like the file (plugin.rb → Plugin) is built with the
+    # bundle's settings, and its #register gets a Plugin::Api. What it
+    # registered takes effect only when #register returns: a plugin that
+    # fails adds nothing.
+    #
+    # A failure is logged and added to +failures+ (not required: tool calls
+    # still run), which the Engine announces once. Not fail-closed.
+    module Loader
+      TAG = :plugins
+
+      module_function
+
+      # @param registries [Registries]
+      # @param failures [Guardrails::LoadFailures, nil]
+      # @param settings [Hash{String => Hash}] config.yml `bundles:`
+      # @return [Array<String>] the bundles whose plugin loaded
+      def load_installed(registries, failures: nil, settings: {})
+        loaded = []
+        MemoryBundle::Provenance.each_installed_with_plugin do |bundle_name, data|
+          ok = load_bundle(bundle_name, data, registries, failures: failures, settings: settings[bundle_name.to_s] || {})
+          loaded << bundle_name if ok
+        end
+        loaded
+      rescue StandardError => e
+        Log.error(TAG, "plugins_load_failed", echo: "[samagotchi:plugins] failed to load bundle plugins: #{e.class}: #{e.message}",
+                                              error: e.class.name)
+        loaded || []
+      end
+
+      # @return [Boolean] whether the plugin loaded
+      def load_bundle(bundle_name, data, registries, failures: nil, settings: {})
+        file = MemoryBundle::Provenance.new(name: bundle_name).plugin_path(data) unless data[:error]
+        basename = file ? File.basename(file) : "plugin"
+        reason = data[:error] || unloadable_reason(file, data)
+        return failed(bundle_name, basename, reason, failures) if reason
+
+        api = nil
+        plugin = instantiate(bundle_name, file, settings)
+        plugin_label = label(bundle_name, basename)
+        api = Api.new(bundle: bundle_name, label: plugin_label, registries: registries,
+                      context: registries.context_for&.call(bundle_name, settings, plugin_label))
+        plugin.register(api)
+        api.commit!
+        Log.info(TAG, "plugin_loaded", bundle: bundle_name, file: basename, **api.counts)
+        true
+      rescue Exception => e # rubocop:disable Lint/RescueException -- a plugin's SyntaxError or exit must not stop chi
+        api&.abort!
+        raise if e.is_a?(Interrupt)
+
+        failed(bundle_name, basename, "#{e.class}: #{e.message}", failures)
+      end
+
+      # What a plugin's hooks, notices and failures are named by.
+      def label(bundle_name, basename) = "#{basename} (bundle #{bundle_name})"
+
+      # Why the installed file can't be loaded, or nil.
+      def unloadable_reason(file, data)
+        failure = MemoryBundle::Manifest.requires_chi_failure(data[:requires_chi], Samagotchi::VERSION)
+        return failure if failure
+        return "the file is missing" unless file && File.file?(file)
+
+        Hooks::BundleLoader.sha_mismatch(file, data[:plugin][:sha256], required: true)
+      end
+
+      # module_eval the file into a fresh module in the bundle's namespace
+      # (Samagotchi::Bundles::<bundle>::PluginLoad<n>: each load gets new
+      # classes, not the last load's reopened) and build its class
+      # (plugin.rb → Plugin; my_plugin.rb → MyPlugin) as hooks are built:
+      # an initialize that takes an argument gets the settings.
+      def instantiate(bundle_name, file, settings)
+        namespace = fresh_namespace(bundle_name)
+        namespace.module_eval(File.read(file), file, 1)
+        class_name = File.basename(file, ".rb").split("_").map(&:capitalize).join
+        klass = namespace.const_get(class_name, false)
+        plugin = Hooks.build_plugin(klass, settings)
+        raise ArgumentError, "#{class_name} does not respond to #register" unless plugin.respond_to?(:register)
+
+        plugin
+      end
+
+      LOADS = Mutex.new
+
+      def fresh_namespace(bundle_name)
+        LOADS.synchronize do
+          @loads = (@loads || 0) + 1
+          Hooks::BundleLoader.namespace_for(bundle_name).const_set(:"PluginLoad#{@loads}", Module.new)
+        end
+      end
+
+      def failed(bundle_name, basename, reason, failures)
+        Log.warn(TAG, "plugin_not_loaded", echo: "[samagotchi:plugins] bundle '#{bundle_name}' plugin '#{basename}' not loaded: #{reason}",
+                                           bundle: bundle_name, file: basename)
+        failures&.add("plugin #{basename} (bundle #{bundle_name})", reason, required: false)
+        false
+      end
+    end
+  end
+end

data/lib/samagotchi/plugin/service.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "monitor"
+require_relative "../log"
+
+module Samagotchi
+  module Plugin
+    # A plugin's long-lived thing (a server process, a connection), from
+    # chi.service (docs/plugins.md, Services). Its block starts it: on
+    # first #value, or at register time with eager: true. What the block
+    # returns is #value. Stop callbacks (#on_stop, given inside the block)
+    # run when the Engine shuts down (Engine#shutdown), newest first.
+    class Service
+      # The service was stopped (the Engine shut down): it doesn't start
+      # again.
+      class Stopped < StandardError; end
+
+      # @return [String] "<bundle>:<name>"
+      attr_reader :name
+
+      def initialize(name, &start)
+        @name = name
+        @start = start
+        @mutex = Monitor.new
+        @state = :idle
+        @value = nil
+        @on_stop = []
+      end
+
+      # Start it if it hasn't started, and return what its block returned.
+      # A block that raises leaves it idle (its on_stop callbacks so far
+      # run), so the next use tries again.
+      # @raise [Stopped] after #stop
+      def value
+        @mutex.synchronize do
+          raise Stopped, "service #{@name} is stopped" if @state == :stopped
+          return @value if @state == :running
+
+          begin
+            @value = @start.call(self)
+            @state = :running
+            Log.info(:plugins, "service_started", service: @name)
+            @value
+          rescue Exception # rubocop:disable Lint/RescueException -- clean up, then re-raise as is
+            run_on_stop
+            raise
+          end
+        end
+      end
+      alias start value
+
+      # A callback for #stop, given in the start block (close the pipes,
+      # kill the process).
+      def on_stop(&block)
+        raise ArgumentError, "on_stop needs a block" unless block
+
+        @mutex.synchronize { @on_stop << block }
+        nil
+      end
+
+      # @return [Boolean]
+      def running? = @state == :running
+
+      # @return [Symbol] :idle, :running or :stopped
+      def state = @state
+
+      # Run the stop callbacks (newest first) once; a raise is logged, the
+      # rest still run. It never starts again after this.
+      def stop
+        @mutex.synchronize do
+          return if @state == :stopped
+
+          was = @state
+          @state = :stopped
+          @value = nil
+          run_on_stop
+          Log.info(:plugins, "service_stopped", service: @name) if was == :running
+        end
+        nil
+      end
+
+      private
+
+      def run_on_stop
+        callbacks = @on_stop.reverse
+        @on_stop = []
+        callbacks.each do |callback|
+          callback.call
+        rescue StandardError => e
+          Log.warn(:plugins, "service_stop_failed", service: @name, error: e.class.name, msg: e.message)
+        end
+      end
+    end
+
+    # An Engine's services, in the order they were registered. #stop_all
+    # stops them newest first.
+    class Services
+      def initialize
+        @list = []
+        @mutex = Mutex.new
+      end
+
+      def add(service)
+        @mutex.synchronize { @list << service }
+        service
+      end
+
+      # @return [Array<Service>]
+      def to_a = @mutex.synchronize { @list.dup }
+
+      def stop_all
+        to_a.reverse_each(&:stop)
+        nil
+      end
+    end
+  end
+end

data/lib/samagotchi/plugin/sessions.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require_relative "../session"
+require_relative "../bridge_client"
+require_relative "../bridge/turn_accumulator"
+require_relative "../tools/delegate"
+
+module Samagotchi
+  # Loaded on first use: session_manager requires terminal_ui, which
+  # requires the Engine and so the plugins (a require cycle otherwise).
+  autoload :SessionManager, File.expand_path("../session_manager", __dir__)
+
+  module Plugin
+    # ctx.sessions (docs/plugins.md, Sessions): other sessions, from a
+    # plugin. A fork is an ordinary chi session in its own worker, shown in
+    # every list as a child of this one (↳ parent).
+    class Sessions
+      # A fork, send or read that couldn't be done; the message says why.
+      class Error < StandardError; end
+
+      # @param host [Host] session_id, cwd, model_name and state_dir
+      def initialize(host)
+        @host = host
+      end
+
+      # Start a child session from +messages+ (usually ctx.messages plus
+      # more). With no prompt the child waits idle for the user; with one it
+      # runs it as its first turn, and counts against session.max_children.
+      # Each image a message names is copied into the child, or dropped with
+      # a note in its message when its file is gone.
+      # @param messages [Array<Hash>] the child's conversation to start with
+      # @param title [String, nil] what the lists show for it (the prompt, or
+      #   the first user message, by default)
+      # @param prompt [String, nil] the child's first turn
+      # @return [String] the child's id
+      # @raise [Error] no session yet, or too many children running
+      def fork(messages:, title: nil, prompt: nil)
+        parent_id = @host.session_id.call or raise Error, "this session has no id yet"
+        state_dir = self.state_dir
+        prompt = prompt.to_s.strip.empty? ? nil : prompt.to_s
+        check_children(parent_id, state_dir) if prompt
+
+        child = SessionManager.spawn_session(
+          prompt: prompt, working_directory: @host.cwd.call || Dir.pwd, model_name: @host.model_name&.call,
+          parent_id: parent_id, messages: Array(messages).map { |message| unfrozen(message) }, title: title,
+          images_from: Session.session_dir(parent_id, state_dir: state_dir), state_dir: state_dir
+        )
+        child.id
+      end
+
+      # Send +text+ to session +id+ as a user message (it runs as a turn;
+      # a stopped session is woken). Waits up to 5 s for its worker, so call
+      # it from an anytime command or your own thread, never a tool or hook
+      # of a running turn.
+      # @return [String] the id of the session it went to
+      # @raise [Error] no such session, a REPL owns it, or it wasn't taken
+      def send(id, text)
+        raise Error, "nothing to send" if text.to_s.strip.empty?
+
+        state_dir = self.state_dir
+        sid = resolve(id, state_dir)
+        delivered = SessionManager.deliver_turn(sid, prompt: text.to_s, client_id: "plugin", state_dir: state_dir)
+        case delivered[:status]
+        when :accepted then sid
+        when :refused then raise Error, "session #{sid[0, 8]} refused the message (#{delivered.dig(:ack, "error")})"
+        when :timeout then raise Error, "session #{sid[0, 8]}'s worker did not answer in time; the message was not sent"
+        else raise Error, "the message to session #{sid[0, 8]} could not be written"
+        end
+      rescue SessionManager::OwnedByTUI
+        raise Error, "session #{sid[0, 8]} is open in a chi REPL, which takes no messages from others"
+      end
+
+      # Session +id+ now: from its worker when one runs (with a running turn
+      # so far), else as saved.
+      # @return [Hash] {id:, title:, status:, parent_id:, running:, messages:}
+      #   (messages without the system prompt, symbol keys)
+      # @raise [Error] no such session
+      def read(id)
+        state_dir = self.state_dir
+        sid = resolve(id, state_dir)
+        session = Session.load(sid, state_dir: state_dir)
+        messages = session.messages
+        running = false
+        if (live = live_snapshot(sid, state_dir))
+          messages = Array(live["messages"]).map { |message| symbolize_message(message) }
+          if (turn = live["current_turn"])
+            running = true
+            messages += Bridge::TurnAccumulator.messages_of(deep_symbolize(turn))
+          end
+        end
+        { id: sid, title: session.first_preview.to_s, status: session.status.to_s, parent_id: session.parent_id,
+          running: running, messages: without_system_head(messages) }
+      end
+
+      private
+
+      def state_dir = @host.state_dir&.call || Session.default_state_dir
+
+      def resolve(id, state_dir)
+        sid = Session.resolve_id(id.to_s.strip, state_dir: state_dir)
+        raise Error, "no session #{id}" unless sid && Session.exist?(sid, state_dir: state_dir)
+
+        sid
+      rescue Session::AmbiguousId, ArgumentError => e
+        raise Error, e.message
+      end
+
+      def check_children(parent_id, state_dir)
+        running = Tools::Delegate.running_children(parent_id, state_dir: state_dir)
+        max = Tools::Delegate.max_children
+        return if running.size < max
+
+        raise Error, "#{running.size} child sessions of this session are running (the most is #{max}, " \
+                     "#{Tools::Delegate::MAX_CHILDREN_KEY}): #{running.map { |s| s[:short_id] }.join(", ")}"
+      end
+
+      def live_snapshot(sid, state_dir)
+        BridgeClient.discover(sid, session_dir: Session.session_dir(sid, state_dir: state_dir))&.get_json("snapshot")
+      rescue StandardError
+        nil
+      end
+
+      def without_system_head(messages)
+        first = messages.first
+        system = first && first[:role].to_s == "system" && first[:kind].to_s.empty?
+        system ? messages.drop(1) : messages
+      end
+
+      # A message a plugin got frozen (ctx.messages), as a session holds it.
+      def unfrozen(message)
+        message.to_h { |key, value| [key.to_sym, value.frozen? && value.is_a?(String) ? value.dup : value] }
+      end
+
+      # Symbol keys, as Session.load gives them (its image refs too).
+      def symbolize_message(message)
+        message = message.transform_keys(&:to_sym)
+        message[:images] = message[:images].map { |ref| ref.transform_keys(&:to_sym) } if message[:images].is_a?(Array)
+        message
+      end
+
+      def deep_symbolize(value)
+        case value
+        when Hash then value.to_h { |k, v| [k.to_sym, deep_symbolize(v)] }
+        when Array then value.map { |v| deep_symbolize(v) }
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/plugin/side_question.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../idle_recap"
+
+module Samagotchi
+  module Plugin
+    # The request behind ctx.ask_model (plan D7): the conversation as a
+    # transcript, filtered like the idle recap's (IdleRecap::TranscriptFilter:
+    # no system prompt, no tool calls or outputs, no thinking, an image as a
+    # line naming it), then the question. One user message holds both, so a
+    # conversation that ends on a user turn (a running turn's prompt) doesn't
+    # run into the question.
+    module SideQuestion
+      DEFAULT_SYSTEM = "You answer a question about the conversation below, on the side. Answer briefly and " \
+                       "don't continue the conversation's task."
+      # The most transcript one request sends: the tail is kept.
+      MAX_TRANSCRIPT_CHARS = 32_000
+
+      module_function
+
+      # @param messages [Array<Hash>] the conversation (symbol or string keys)
+      # @param prompt [String] the question
+      # @param system [String, nil] instructions; DEFAULT_SYSTEM by default
+      # @return [Array<Hash>] chat messages: {role: "system"}, {role: "user"}
+      def request(messages:, prompt:, system: nil)
+        system = system.to_s.strip.empty? ? DEFAULT_SYSTEM : system.to_s
+        transcript = transcript(messages)
+        question = prompt.to_s.strip
+        user = if transcript.empty?
+                 question
+               else
+                 "<conversation>\n#{transcript}\n</conversation>\n\n#{question}"
+               end
+        [{ role: "system", content: system }, { role: "user", content: user }]
+      end
+
+      # "User: …" and "Assistant: …" paragraphs; the tail when it is long.
+      # @return [String]
+      def transcript(messages)
+        text = stringified(messages).filter_map do |message|
+          line = IdleRecap::TranscriptFilter.build([message])
+          next if line.strip.empty?
+
+          "#{message["role"] == "user" ? "User" : "Assistant"}: #{line}"
+        end.join("\n\n")
+        return text if text.length <= MAX_TRANSCRIPT_CHARS
+
+        "[earlier conversation left out]\n\n#{text[-MAX_TRANSCRIPT_CHARS..]}"
+      end
+
+      # String keys, as TranscriptFilter reads a saved session.
+      def stringified(messages)
+        JSON.parse(JSON.generate(Array(messages)))
+      rescue StandardError
+        []
+      end
+    end
+  end
+end

data/lib/samagotchi/plugin/tool_result.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module Plugin
+    # What a plugin tool's block returns to hand the model images too
+    # (docs/plugins.md, Returning images):
+    #
+    #   Samagotchi::Plugin::ToolResult.new("took a screenshot", images: [{ path: "/tmp/shot.png" }])
+    #   Samagotchi::Plugin::ToolResult.new("two frames", images: [{ bytes: png, name: "frame1.png" }, …])
+    #
+    # It is the text itself (a String), so everything that reads a tool's
+    # text keeps working; #images is what ToolRunner attaches. An entry
+    # is {path:} or {bytes:, name:} (raw bytes, not base64); one that isn't
+    # becomes an "Error:" line for that image, the rest still go.
+    class ToolResult < String
+      attr_reader :images
+
+      def initialize(text = "", images: [])
+        @images = (images.is_a?(Hash) ? [images] : Array(images)).freeze
+        super(text.to_s)
+      end
+    end
+  end
+end