samagotchi 0.2.0 → 0.3.0

data/lib/samagotchi/log_subscriber.rb

@@ -27,8 +27,8 @@ module Samagotchi
       question_requested: [],
       question_answered: %i[id],
       question_cancelled: %i[id reason],
-      pending_input_merged: %i[iteration count],
-      generation_cancelled: %i[iteration]
+      generation_cancelled: %i[iteration],
+      empty_answer_retry: %i[iteration attempt of finish_reason thinking_chars]
     }.freeze
 
     # @param session_id [#call] the session the events are about (the
@@ -71,6 +71,15 @@ module Samagotchi
                                   exhausted: summary[:exhausted] || nil, **origin(event))
     end
 
+    # A plugin's steers by count and source, never their text.
+    def on_pending_input_merged(event)
+      steers = Array(event[:steers])
+      log(:info, :pending_input_merged, **event.slice(:iteration, :count),
+                                        steers: steers.empty? ? nil : steers.size,
+                                        steer_sources: steers.empty? ? nil : steers.map { |s| s[:source] }.uniq.join(","),
+                                        **origin(event))
+    end
+
     def on_turn_canceled(event)
       log(:info, :turn_canceled, ms: since(@turn_started_at), reason: event[:cancellation_reason], **origin(event))
     end
@@ -92,7 +101,7 @@ module Samagotchi
                                         ms: since(@generation_started_at.delete(event[:iteration])),
                                         served_model: event[:served_model], requested_model: event[:requested_model],
                                         content_length: event[:content_length],
-                                        thinking_chars: event[:thinking_chars])
+                                        thinking_chars: event[:thinking_chars], finish_reason: event[:finish_reason])
     end
 
     def on_generation_retrying(event)
@@ -125,6 +134,12 @@ module Samagotchi
       log(level, :hook_notice, hook: event[:hook], msg: event[:text].to_s[0, 300])
     end
 
+    # after_turn hooks presented the answer (AnswerDisplay): its size only
+    # (none for the display: nil that says nothing was presented).
+    def on_answer_display(event)
+      log(:info, :answer_display, chars: event[:display].to_s.length) if event[:display]
+    end
+
     # A card shown to the user (Engine#show_card): whose, which, and its
     # title (the body is the plugin's text; not logged).
     def on_card(event)

data/lib/samagotchi/model_profile.rb

@@ -139,7 +139,7 @@ module Samagotchi
         "~/.config/samagotchi/config.yml"
       end
       "no model configured: set default.model in #{path} to the model id your server serves " \
-        "(or #{MODEL_ENV}, or pass --model ID); see docs/configuration.md"
+        "(or #{MODEL_ENV}, or pass --model ID); see docs/configuration.md; or run: chi bootstrap HOST[:PORT]"
     end
 
     def self.from_model_name(model_name)

data/lib/samagotchi/plugin/context.rb

@@ -18,8 +18,10 @@ module Samagotchi
     # the answer text.
     # +messages_partial+ says whether +messages+ leaves out a running turn;
     # +model_name+ and +state_dir+ are what ctx.sessions forks with.
+    # +steer+ takes (text, source) and +stop_turn+ (reason, label), each
+    # true when it acted on a running turn.
     Host = Struct.new(:session_id, :cwd, :messages, :messages_partial, :notify, :ask_user, :cancelled, :card,
-                      :ask_model, :model_name, :state_dir, keyword_init: true)
+                      :ask_model, :model_name, :state_dir, :scratch, :steer, :stop_turn, 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.
@@ -178,6 +180,25 @@ module Samagotchi
       # Whether the running turn was cancelled (a long tool should stop).
       def cancelled? = !!@host.cancelled.call
 
+      # Put +text+ into the running turn, as a user's steering does: at the
+      # loop's next boundary (after the tool calls in flight) it joins the
+      # conversation as its own user message, shown in every UI as a nudge
+      # from this bundle. It never starts a turn. True means queued: if the
+      # model answers first, or the turn ends, it is dropped (logged).
+      # Callable from a hook, a command (an anytime one runs beside the
+      # turn) or your own thread.
+      # @return [Boolean] whether a turn was running and the text queued
+      def steer(text)
+        !!@host.steer&.call(text.to_s, @bundle)
+      end
+
+      # Stop the running turn, after a notice with +reason+, as a hook's
+      # event[:stop_turn] does (for commands and threads).
+      # @return [Boolean] whether a running turn was stopped now
+      def stop_turn(reason)
+        !!@host.stop_turn&.call(reason.to_s, @label)
+      end
+
       private
 
       def deep_freeze(value)

data/lib/samagotchi/plugin/sessions.rb

@@ -33,9 +33,11 @@ module Samagotchi
       #   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
+      # @raise [Error] no session yet, a scratch session (the child would
+      #   outlive it), 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"
+        raise Error, "a scratch session starts no other sessions: they would outlive it" if @host.scratch&.call
         state_dir = self.state_dir
         prompt = prompt.to_s.strip.empty? ? nil : prompt.to_s
         check_children(parent_id, state_dir) if prompt

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

@@ -116,6 +116,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

data/lib/samagotchi/send_command.rb

@@ -3,6 +3,7 @@
 require_relative "session"
 require_relative "session_manager"
 require_relative "context_quote"
+require_relative "reply_wait"
 
 module Samagotchi
   # `chi send`: put text into sessions as the user's message, the same as
@@ -10,15 +11,36 @@ 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
 
     USAGE = <<~TEXT
       Usage: chi send [-m TEXT] (ID|PREFIX)...
+             chi send --new [--dir DIR] [--model M] [-m TEXT]
+             chi send --wait [--timeout S] [-m TEXT] (--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
+        --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 +56,16 @@ 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]))
+      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
@@ -51,6 +77,9 @@ module Samagotchi
         return 1
       end
 
+      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 = {}
       results = options[:ids].uniq.map do |given|
@@ -77,6 +106,13 @@ 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 "--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 +120,30 @@ 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 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,6 +178,97 @@ 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. The model name isn't
+    # checked here (nor in the web): a wrong one fails in the worker.
+    # @return [Integer] the exit status
+    def run_new(prompt, options)
+      begin
+        session = SessionManager.spawn_session(prompt: prompt, 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
+      @info.puts("#{session.id}  started")
+      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
+
     # @return [Boolean] whether the message was queued
     def deliver(id, prompt)
       short = id[0, 8]
@@ -130,20 +276,20 @@ module Samagotchi
       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)
       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
 
       note = if owner.nil? then " (started its worker)"
              elsif running then " (the running turn picks it up)"
              end
-      @stdout.puts("#{short}  sent#{note}")
+      @info.puts("#{short}  sent#{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