samagotchi 0.2.0 → 0.4.0

data/lib/samagotchi/reply_wait.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require_relative "session"
+
+module Samagotchi
+  # Loaded on first use: session_manager requires terminal_ui, which
+  # requires KernelLoop and so the tools that use this (a require cycle
+  # otherwise).
+  autoload :SessionManager, File.expand_path("session_manager", __dir__)
+
+  # Waiting for a session's next reply. A reply is the worker's
+  # output/<timestamp>.txt file (one per turn that ended with visible text,
+  # written just before its idle save), so "next" means a filename past the
+  # cursor the caller holds: the newest one it already has, or nil for any.
+  # The delegate tools and `chi send --wait` wrap it in their own words.
+  module ReplyWait
+    POLL_INTERVAL = 0.5
+
+    # @!attribute status [Symbol] :done, :waiting_for_answer, :no_reply,
+    #   :error, :stopped, :canceled, :timeout or :worker_gone
+    # @!attribute text [String, nil] the reply (:done) or the worker's error
+    #   (:error)
+    # @!attribute file [String, nil] the reply's filename, the next cursor
+    # @!attribute question [Hash, nil] the pending question
+    #   (:waiting_for_answer)
+    Result = Struct.new(:status, :text, :file, :question, keyword_init: true)
+
+    module_function
+
+    # @param id [String] the session's full id
+    # @param state_dir [String]
+    # @param cursor [String, nil] the newest reply filename already had
+    # @param timeout [Numeric, nil] seconds; nil waits with no limit
+    # @param poll_interval [Float]
+    # @param cancelled [#call] true stops the wait (:canceled)
+    # @param baseline [Hash, nil] {messages:, question_id:} as the session
+    #   was before the message went in. With it, a turn that grew the
+    #   messages (a failed, canceled or empty one leaves its note) and went
+    #   idle again ends the wait even if it was never seen running, and a
+    #   question already pending then is not the answer's. A nil
+    #   messages: skips the count.
+    # @param owner_grace [Numeric, nil] seconds with no live worker before
+    #   :worker_gone (one that died before its rescue leaves it running)
+    # @return [Result]
+    # @raise [ArgumentError] no such session
+    def call(id, state_dir:, cursor:, timeout: nil, poll_interval: POLL_INTERVAL, cancelled: -> { false },
+             baseline: nil, owner_grace: nil)
+      deadline = timeout && (monotonic + timeout.to_f)
+      seen_running = false
+      gone_since = nil
+
+      loop do
+        session = Session.load(id, state_dir: state_dir)
+
+        if (reply = reply_past(id, state_dir: state_dir, cursor: cursor))
+          return reply
+        end
+
+        case session.status
+        when Session::STATUS_ERROR
+          return Result.new(status: :error, text: session.last_prompt.to_s.strip)
+        when Session::STATUS_STOPPED
+          return Result.new(status: :stopped)
+        end
+
+        pending = session.pending_question
+        if pending && !(baseline && pending[:id] == baseline[:question_id])
+          return Result.new(status: :waiting_for_answer, question: pending)
+        end
+
+        return Result.new(status: :canceled) if cancelled.call
+
+        if session.status == Session::STATUS_RUNNING
+          seen_running = true
+        elsif seen_running || (baseline&.dig(:messages) && session.messages.size > baseline[:messages])
+          # It ran and is idle again with no new reply: canceled, failed or
+          # empty. Before it was ever seen running, idle means a
+          # file-delivered message its worker has not picked up yet.
+          # The worker writes the reply before its idle save, so the read
+          # above has it; one more look costs nothing should that change.
+          return reply_past(id, state_dir: state_dir, cursor: cursor) || Result.new(status: :no_reply)
+        end
+
+        if owner_grace
+          if SessionManager.session_owner(id, state_dir: state_dir)
+            gone_since = nil
+          elsif monotonic - (gone_since ||= monotonic) > owner_grace
+            return Result.new(status: :worker_gone)
+          end
+        end
+
+        return Result.new(status: :timeout) if deadline && monotonic > deadline
+
+        sleep(poll_interval)
+      end
+    end
+
+    # @return [Result, nil] :done with the newest reply past the cursor
+    def reply_past(id, state_dir:, cursor:)
+      file = newest_reply(id, state_dir: state_dir)
+      return nil unless file && newer?(file, cursor)
+
+      Result.new(status: :done, text: File.read(File.join(reply_dir(id, state_dir: state_dir), file)), file: file)
+    end
+
+    # @return [String, nil] the newest reply filename (sortable timestamps)
+    def newest_reply(id, state_dir:)
+      dir = reply_dir(id, state_dir: state_dir)
+      return nil unless Dir.exist?(dir)
+
+      Dir.children(dir).select { |f| f.end_with?(".txt") }.max
+    end
+
+    def reply_dir(id, state_dir:)
+      File.join(Session.session_dir(id, state_dir: state_dir), SessionManager::OUTPUT_DIR)
+    end
+
+    def newer?(file, cursor)
+      cursor.nil? || file > cursor
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/samagotchi/sampling_settings.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "config"
+
+module Samagotchi
+  # The request parameters (temperature, penalties, …) a model's generations
+  # go out with: hosts.<name>.sampling merged with models.<key>.sampling, the
+  # model's keys winning per key (a host can set a penalty and a model move
+  # only the temperature). Recap and side clients keep their own options.
+  module SamplingSettings
+    EMPTY = {}.freeze
+
+    # @param target [HostRegistry::ModelTarget]
+    # @param names [Array<String>, nil] the model as typed, alias-resolved,
+    #   bare (the Engine's lookup names); default: the target's model and bare model
+    # @param models [Hash, nil] ConfigFile.model_settings (specs)
+    # @return [Hash] frozen, symbol keys; may be empty
+    def self.for(target, names: nil, models: nil)
+      resolve(target, names, models).first
+    end
+
+    # "temperature=0.6 presence_penalty=1.5 (hosts.work, models: qwen)" for
+    # /model, or nil when nothing is configured.
+    def self.summary(target, names: nil, models: nil)
+      params, sources = resolve(target, names, models)
+      return nil if params.empty?
+
+      pairs = params.map { |key, value| "#{key}=#{value.nil? ? "(not sent)" : value.inspect}" }
+      "#{pairs.join(" ")} (#{sources.join(", ")})"
+    end
+
+    # Request fields as the http log line shows them:
+    # "temperature=0.6 presence_penalty=1.5", nil for none.
+    def self.log_text(fields)
+      return nil if fields.nil? || fields.empty?
+
+      fields.map { |key, value| "#{key}=#{value.is_a?(String) ? value : JSON.generate(value)}" }.join(" ")
+    end
+
+    def self.resolve(target, names, models)
+      models ||= begin
+        ConfigFile.model_settings
+      rescue StandardError
+        {}
+      end
+      names ||= [target.model, target.bare_model]
+      host = target.entry.sampling || EMPTY
+      key, model = ConfigFile.model_setting(names, :sampling, models: models)
+      sources = []
+      sources << "hosts.#{target.entry.name}" unless host.empty?
+      sources << "models: #{key}" if key
+      [host.merge(model || EMPTY).freeze, sources]
+    end
+
+    private_class_method :resolve
+  end
+end

data/lib/samagotchi/self_report.rb

@@ -7,6 +7,7 @@ require_relative "context_window"
 require_relative "session"
 require_relative "log_path"
 require_relative "model_profile"
+require_relative "thinking"
 require_relative "served_model"
 require_relative "host_registry"
 require_relative "tools/memory"
@@ -50,6 +51,7 @@ module Samagotchi
         ["api key", model ? api_key_for(model, env) : "-"],
         ["loop", model ? loop_for(model, env) : "-"],
         ["profile", model ? profile_for(model, env) : "-"],
+        ["thinking", model ? thinking_for(model, env) : "-"],
         ["served model", model ? served_model_for(model, env) : "-"],
         ["context window", context_window(env)],
         ["bundles", bundles_summary],
@@ -116,6 +118,7 @@ module Samagotchi
       client = registry.client_for(entry)
       props = client.server_props(model: bare) if client.respond_to?(:server_props)
       return "reported per turn (the server has no /props)" if props.nil?
+      return "unknown (the server didn't answer; is it running?)" if props.status == :network_error
 
       served = ServedModel.from_props(props)
       return "unknown (no answer from the server's /props)" unless served
@@ -149,6 +152,15 @@ module Samagotchi
       end
     end
 
+    # The model's thinking level and where it came from (Thinking.resolve).
+    def thinking_for(model, env)
+      target = HostRegistry.new(env: env).resolve(model)
+      level, source = Thinking.resolve(target, models: ConfigFile.model_settings(env: env))
+      source ? "#{level} (#{source})" : level.to_s
+    rescue StandardError => e
+      "(unknown: #{e.message})"
+    end
+
     def host_for(model, env)
       entry, bare = HostRegistry.new(env: env).host_for_model(model)
       return "(no hosts configured)" unless entry
@@ -169,14 +181,17 @@ module Samagotchi
     end
 
     # The Chi Helper app's version against this chi's (read from its
-    # Info.plist; no process or Services checks: chi desktop status has those).
+    # Info.plist and launch file; no process or Services checks: chi desktop
+    # status has those). An older app is fine while its sources are unchanged.
     def desktop_summary(env)
       return "- (macOS only)" unless Desktop.supported?
 
-      version = Desktop::MacOS.new(env: env).app_version
+      helper = Desktop::MacOS.new(env: env)
+      version = helper.app_version
       return "not installed" unless version
+      return "#{version} (matches)" if version == VERSION
 
-      version == VERSION ? "#{version} (matches)" : "#{version} (chi is #{VERSION}: chi desktop upgrade)"
+      helper.stale? ? "#{version} (chi is #{VERSION}: chi update)" : "#{version} (up to date for chi #{VERSION})"
     end
 
     # "samagotchi-system 0.1.5 (shipped 0.1.5), other 1.0.0"

data/lib/samagotchi/send_command.rb

@@ -3,6 +3,8 @@
 require_relative "session"
 require_relative "session_manager"
 require_relative "context_quote"
+require_relative "reply_wait"
+require_relative "image_store"
 
 module Samagotchi
   # `chi send`: put text into sessions as the user's message, the same as
@@ -10,15 +12,43 @@ module Samagotchi
   # `chi note`. Fire and forget: it returns once the message is queued, and
   # the answer shows in whatever is attached. For a script:
   #   pbpaste | chi send -m "is this the same bug?" 3fa2
+  # --new starts a session instead, and --wait blocks for the reply and
+  # prints it: an agent's one-shot the user can watch in the web.
   class SendCommand
     CLIENT_ID = "cli:send"
+    POLL_INTERVAL = ReplyWait::POLL_INTERVAL
+    # No live worker this long while waiting: it died before it could mark
+    # the session (a worker takes well under a second to start).
+    WORKER_GONE_AFTER = 5
+    # The Bridge's cap on one turn's images (Bridge::MAX_TURN_IMAGES).
+    MAX_IMAGES = 20
 
     USAGE = <<~TEXT
-      Usage: chi send [-m TEXT] (ID|PREFIX)...
+      Usage: chi send [-m TEXT] [--image PATH]... (ID|PREFIX)...
+             chi send --new [--dir DIR] [--model M] [-m TEXT] [--image PATH]...
+             chi send --wait [--timeout S] [-m TEXT] [--image PATH]... (--new | ID)
+             chi send --wait [--timeout S] ID
         Sends a message to each session, as if typed in it: a turn starts,
         or a running one picks it up. A stopped session's worker starts.
-        -m TEXT   the message; stdin, when piped too, goes above it as a
-                  quote (context); without -m, stdin is the message
+        -m TEXT     the message; stdin, when piped too, goes above it as a
+                    quote (context); without -m, stdin is the message
+        --image PATH
+                    an image sent with the message (png, jpeg, gif, webp;
+                    others converted, large ones downscaled); repeat for
+                    more, up to 20. Needs text too (-m or stdin) and a
+                    model that sees images
+        --new       start a new session with the message instead, as the
+                    web does, and print its id
+        --dir DIR   (--new) its folder, the project it belongs to; default
+                    the current one
+        --model M   (--new) its model; default the configured one
+        --wait      wait for the answer and print it (one session); the
+                    other lines go to stderr. Exit 3: it waits for an
+                    answer from you (chi --attach ID or the web). With
+                    no message (no -m, nothing piped) nothing is sent: it
+                    waits for the session's next reply, a running turn's
+                    too (after exit 3 or 130, wait again this way)
+        --timeout S (--wait) give up after S seconds; default no limit
         Only sessions on this machine. Answers show in the attached TUI
         or web page, not here.
         Find ids with: chi sessions list --live [--scope=all] [--format tsv]
@@ -34,12 +64,21 @@ module Samagotchi
     end
 
     # @return [Integer] exit status: 0 all sent, 1 any refused or failed,
-    #   2 usage
+    #   2 usage; with --wait 0 answered, 3 waiting for an answer, 130
+    #   Ctrl-C (the turn goes on)
     def run
       options = parse or return 2
       return 0 if options[:help]
 
+      # With --wait stdout is the answer alone.
+      @info = options[:wait] ? @stderr : @stdout
       prompt = compose(utf8(read_stdin), utf8(options[:message]))
+      # Before the wait-only case, which would drop the images.
+      if prompt.nil? && !options[:images].empty?
+        usage_error("--image needs a message: pass -m TEXT or pipe it in")
+        return 2
+      end
+      return run_wait_only(options) if prompt.nil? && options[:wait] && !options[:new]
       unless prompt
         usage_error("no message: pass -m TEXT or pipe it in")
         return 2
@@ -50,6 +89,10 @@ module Samagotchi
         @stderr.puts("chi send: #{e.message}")
         return 1
       end
+      return 2 unless ingest_images(options[:images])
+
+      return run_new(prompt, options) if options[:new]
+      return run_wait(prompt, options) if options[:wait]
 
       # One id at a time, so each line follows the order of the ids given.
       seen = {}
@@ -62,12 +105,14 @@ module Samagotchi
         deliver(id, prompt)
       end
       results.all? ? 0 : 1
+    ensure
+      FileUtils.rm_rf(@image_dir) if @image_dir
     end
 
     private
 
     def parse
-      options = { ids: [] }
+      options = { ids: [], images: [] }
       until @argv.empty?
         arg = @argv.shift
         case arg
@@ -77,6 +122,15 @@ module Samagotchi
         when "-m", "--message"
           options[:message] = @argv.shift or return usage_error("#{arg} needs a value")
         when /\A--message=(.*)\z/m then options[:message] = Regexp.last_match(1)
+        when "--new" then options[:new] = true
+        when "--dir", "--model"
+          options[arg.delete_prefix("--").to_sym] = @argv.shift or return usage_error("#{arg} needs a value")
+        when /\A--(dir|model)=(.*)\z/m then options[Regexp.last_match(1).to_sym] = Regexp.last_match(2)
+        when "--image" then options[:images] << (@argv.shift or return usage_error("#{arg} needs a value"))
+        when /\A--image=(.*)\z/m then options[:images] << Regexp.last_match(1)
+        when "--wait" then options[:wait] = true
+        when "--timeout" then options[:timeout] = @argv.shift or return usage_error("#{arg} needs a value")
+        when /\A--timeout=(.*)\z/ then options[:timeout] = Regexp.last_match(1)
         # Starting a turn in every live session at once is too easy to do
         # by accident.
         when "--all" then return usage_error("there is no --all: name the sessions")
@@ -84,11 +138,31 @@ module Samagotchi
         else options[:ids] << arg
         end
       end
+      if options[:timeout]
+        return usage_error("--timeout needs --wait") unless options[:wait]
+
+        options[:timeout] = Float(options[:timeout], exception: false)
+        return usage_error("--timeout takes seconds") unless options[:timeout]&.positive?
+      end
+      return usage_error("--wait takes one session") if options[:wait] && options[:ids].uniq.size > 1
+      return usage_error("at most #{MAX_IMAGES} images") if options[:images].size > MAX_IMAGES
+      return new_options(options) if options[:new]
+      %i[dir model].each { |key| return usage_error("--#{key} needs --new") if options[key] }
       return usage_error("give session ids") if options[:ids].empty?
 
       options
     end
 
+    def new_options(options)
+      return usage_error("--new takes no session ids: it starts one session") unless options[:ids].empty?
+
+      if options[:dir]
+        options[:dir] = File.expand_path(options[:dir])
+        return usage_error("no folder #{options[:dir]}") unless File.directory?(options[:dir])
+      end
+      options
+    end
+
     # With both, stdin is the context quoted above the message; with one,
     # it goes in as is. nil when both are blank.
     def compose(context, message)
@@ -123,30 +197,197 @@ module Samagotchi
       nil
     end
 
+    # A worker session like the web start page's: saved as running with the
+    # message before its worker spawns, so lists and the web show it at
+    # once. The full id, so a script can pass it on. Only the model's host
+    # is checked here (in spawn_session, as in the web): a wrong model id
+    # fails in the worker.
+    # @return [Integer] the exit status
+    def run_new(prompt, options)
+      images = !@images.empty?
+      begin
+        # With images the web's way: idle (the message names it in the
+        # lists), the images copied in, then the message as a turn.
+        start = images ? { prompt: nil, title: prompt } : { prompt: prompt }
+        session = SessionManager.spawn_session(**start, working_directory: options[:dir],
+                                                        model_name: options[:model], state_dir: @state_dir)
+      rescue StandardError => e
+        error_line("chi send: could not start a session: #{e.message}")
+        return 1
+      end
+      if images
+        return 1 unless deliver_new(session, prompt)
+      else
+        @info.puts("#{session.id}  started")
+      end
+      return 0 unless options[:wait]
+
+      wait_for_reply(session.id, cursor: nil, baseline: { messages: session.messages.size, question_id: nil },
+                                 timeout: options[:timeout])
+    end
+
+    # One existing session, then its next reply. The cursor and baseline
+    # are taken before the message goes in, so neither an older reply nor a
+    # turn that ends before the first look is mistaken for the answer. A
+    # running turn is refused: a message that misses it runs next, and the
+    # running one's reply would come back as the answer.
+    # @return [Integer] the exit status
+    def run_wait(prompt, options)
+      id = resolve(options[:ids].first) or return 1
+      session = Session.load(id, state_dir: @state_dir)
+      if session.status == Session::STATUS_RUNNING && SessionManager.session_owner(id, state_dir: @state_dir)
+        error_line("#{id[0, 8]}  busy: a turn is running; wait or attach")
+        return 1
+      end
+
+      cursor = ReplyWait.newest_reply(id, state_dir: @state_dir)
+      baseline = { messages: session.messages.size, question_id: session.pending_question&.dig(:id) }
+      return 1 unless deliver(id, prompt)
+
+      wait_for_reply(id, cursor: cursor, baseline: baseline, timeout: options[:timeout])
+    end
+
+    # --wait with no message: the session's next reply, sending nothing,
+    # so an agent can go back to waiting after exit 3 or 130. A running
+    # turn is fine here (nothing joins its queue); a question pending now
+    # was already reported. No message count: a note landing between turns
+    # grows the messages without a turn. An idle session with no worker
+    # waits for whatever wakes one (the web, chi send) rather than calling
+    # it gone.
+    # @return [Integer] the exit status
+    def run_wait_only(options)
+      id = resolve(options[:ids].first) or return 1
+      session = Session.load(id, state_dir: @state_dir)
+      live = session.status == Session::STATUS_RUNNING || SessionManager.session_owner(id, state_dir: @state_dir)
+      wait_for_reply(id, cursor: ReplyWait.newest_reply(id, state_dir: @state_dir),
+                         baseline: { messages: nil, question_id: session.pending_question&.dig(:id) },
+                         timeout: options[:timeout], owner_grace: live ? WORKER_GONE_AFTER : nil)
+    end
+
+    # @return [Integer] the exit status
+    def wait_for_reply(id, cursor:, baseline:, timeout:, owner_grace: WORKER_GONE_AFTER)
+      result = ReplyWait.call(id, state_dir: @state_dir, cursor: cursor, timeout: timeout, baseline: baseline,
+                                  owner_grace: owner_grace, poll_interval: POLL_INTERVAL)
+      return reply(result.text) if result.status == :done
+
+      attach = "chi --attach #{id}"
+      line, status = case result.status
+                     when :waiting_for_answer
+                       question = result.question[:question].to_s.strip.lines.first.to_s.strip
+                       ["waiting for an answer: #{question}; open it: #{attach} or the web", 3]
+                     when :no_reply then ["the turn ended without a reply (canceled, failed or empty); #{attach} shows it", 1]
+                     when :error then ["the worker failed: #{result.text}; #{attach} shows what happened", 1]
+                     when :worker_gone then ["the worker is gone; #{attach} shows what happened", 1]
+                     when :stopped then ["the session was stopped (chi sessions stop)", 1]
+                     else ["still running after #{format("%g", timeout)} s: #{attach}", 1]
+                     end
+      error_line("chi send: #{line}")
+      status
+    rescue Interrupt
+      error_line("chi send: still running: chi --attach #{id}")
+      130
+    rescue ArgumentError
+      error_line("chi send: the session is gone (deleted while waiting)")
+      1
+    end
+
+    def reply(text)
+      @stdout.puts(utf8(text))
+      @stdout.flush
+      0
+    end
+
+    # A new idle session's first turn, with the images. Its worker's Bridge
+    # first: deliver_turn wakes a worker when none owns the session yet,
+    # and the spawned one takes its lock only once it runs.
+    # @return [Boolean] whether the message was queued
+    def deliver_new(session, prompt)
+      dir = Session.session_dir(session.id, state_dir: @state_dir)
+      result = nil
+      begin
+        refs = copy_images(dir)
+        if BridgeClient.wait_for(session.id, session_dir: dir, timeout: SessionManager::TURN_BRIDGE_WAIT)
+          result = SessionManager.deliver_turn(session.id, prompt: prompt, client_id: CLIENT_ID, images: refs,
+                                                           state_dir: @state_dir)
+        end
+      rescue StandardError => e
+        @info.puts("#{session.id}  failed: #{e.message}")
+        return false
+      end
+      # Kept, not deleted: it holds the images, and the message shows as
+      # its preview; the user can attach and send it again.
+      unless result
+        @info.puts("#{session.id}  failed: its worker did not start; the session is kept (chi --attach #{session.id})")
+        return false
+      end
+      unless result[:status] == :accepted
+        @info.puts("#{session.id}  failed: #{result.dig(:ack, "detail") || "could not queue it"}")
+        return false
+      end
+
+      @info.puts("#{session.id}  started#{with_images}")
+      true
+    end
+
     # @return [Boolean] whether the message was queued
     def deliver(id, prompt)
       short = id[0, 8]
       owner = SessionManager.session_owner(id, state_dir: @state_dir)
       running = owner && Session.load(id, state_dir: @state_dir).status == Session::STATUS_RUNNING
-      result = SessionManager.deliver_turn(id, prompt: prompt, client_id: CLIENT_ID, state_dir: @state_dir)
+      refs = copy_images(Session.session_dir(id, state_dir: @state_dir))
+      result = SessionManager.deliver_turn(id, prompt: prompt, client_id: CLIENT_ID, images: refs, state_dir: @state_dir)
       unless result[:status] == :accepted
-        @stdout.puts("#{short}  failed: #{result.dig(:ack, "detail") || "could not queue it"}")
+        @info.puts("#{short}  failed: #{result.dig(:ack, "detail") || "could not queue it"}")
         return false
       end
 
+      # A busy worker runs a message with images as its own next turn
+      # rather than merging it into the running one.
       note = if owner.nil? then " (started its worker)"
-             elsif running then " (the running turn picks it up)"
+             elsif running then refs.empty? ? " (the running turn picks it up)" : " (runs after the current turn)"
              end
-      @stdout.puts("#{short}  sent#{note}")
+      @info.puts("#{short}  sent#{with_images}#{note}")
       true
     rescue SessionManager::OwnedByTUI
-      @stdout.puts("#{short}  refused: it is open in a chi REPL; messages need attached mode")
+      @info.puts("#{short}  refused: it is open in a chi REPL; messages need attached mode")
       false
     rescue StandardError => e
-      @stdout.puts("#{short}  failed: #{e.message}")
+      @info.puts("#{short}  failed: #{e.message}")
+      false
+    end
+
+    # Each --image read, converted and downscaled once, into a scratch
+    # session dir; each target then gets copies of the stored files. A file
+    # that can't be sent stops everything before anything is sent.
+    # @return [Boolean] false after the error line
+    def ingest_images(paths)
+      @images = []
+      return true if paths.empty?
+
+      @image_dir = Dir.mktmpdir("chi-send-images")
+      @images = paths.map { |path| ImageStore.ingest(@image_dir, path: path) }
+      true
+    rescue ImageStore::Error => e
+      error_line("chi send: #{e.message}")
       false
     end
 
+    # The images' files copied into a session dir, as the refs a turn takes.
+    def copy_images(session_dir)
+      @images.map do |ref|
+        ImageStore.copy_file(ref, from: @image_dir, to: session_dir)
+        { file: ref[:file], name: ref[:name] }
+      end
+    end
+
+    def with_images
+      case @images.size
+      when 0 then ""
+      when 1 then " with 1 image"
+      else " with #{@images.size} images"
+      end
+    end
+
     # The text as UTF-8 whatever the locale says: with no LANG/LC_* (an app
     # started from Finder, launchd) stdin reads as US-ASCII and ARGV as
     # binary. Invalid bytes become U+FFFD rather than an error.