samagotchi 0.2.0 → 0.3.0

data/lib/samagotchi/bootstrap_command.rb

@@ -0,0 +1,347 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+require_relative "config"
+require_relative "model_profile"
+require_relative "bootstrap/probe"
+require_relative "bootstrap/config_writer"
+
+module Samagotchi
+  # `chi bootstrap [TARGET]`: the first setup. It names a model server, works
+  # out what it is (llama.cpp's native API or an OpenAI-compatible one),
+  # picks the model, sends one test request and writes config.yml: a fresh
+  # file, or a hosts: entry added to an existing one. Prompts only on a
+  # terminal; a script gets the list and exit 2 instead.
+  class BootstrapCommand
+    USAGE = <<~TEXT
+      Usage: chi bootstrap [TARGET] [--name NAME] [--model ID] [--key-env VAR] [--no-test] [--dry-run]
+        Finds the model server at TARGET and writes config.yml for it.
+          chi bootstrap 192.168.1.29:8081          llama.cpp on the LAN
+          chi bootstrap localhost:11434            Ollama
+          chi bootstrap https://openrouter.ai/api/v1 --key-env OPENROUTER_API_KEY
+          chi bootstrap                            look on this machine's usual ports
+        TARGET        host[:port] (port 8080 when none), or a URL; a URL's
+                      path is the OpenAI API base
+        --name NAME   the hosts entry's name (default: local, lan, or the
+                      domain's name)
+        --model ID    the model, when the server has several
+        --key-env VAR the environment variable holding the API key (the
+                      key itself is never written)
+        --no-test     skip the test request
+        --dry-run     show what would be written; write nothing
+        With no config.yml it writes one; an existing one gets a hosts:
+        entry added (after a backup), and its other lines stay as they are.
+    TEXT
+
+    PICK_SHOWN = 20
+    # A test request slower than this says it is waiting (a model loading).
+    LOADING_AFTER = 3
+
+    # @param argv [Array<String>] the arguments after "bootstrap"
+    # @param probe [Bootstrap::Probe, nil] (specs)
+    def initialize(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, env: ENV, probe: nil, config_path: nil,
+                   platform: RbConfig::CONFIG["host_os"])
+      @argv = argv.dup
+      @stdin = stdin
+      @stdout = stdout
+      @stderr = stderr
+      @env = env
+      @probe = probe || Bootstrap::Probe.new(env: env)
+      @config_path = config_path || ConfigFile.global_path(env: env)
+      @platform = platform
+    end
+
+    # @return [Integer] 0 written (or already there), 1 failed (a failed
+    #   test still writes the config), 2 usage or a choice to make
+    def run
+      options = parse or return 2
+      return 0 if options[:help]
+
+      key_env = options[:key_env]
+      return fail!("#{key_env} is not set; export it first (the API key; chi only writes its name)") if key_env && unset?(key_env)
+
+      result = find(options, key_env) or return @exit
+      unlocked = with_key(result, key_env) or return @exit
+      result, key_env = unlocked
+      describe(result)
+      model = pick_model(result, options[:model]) or return @exit
+      show_model(result, model, key_env)
+      tested = options[:no_test] || test(result, model, key_env)
+      written = write(result, model, key_env, options) or return @exit
+      written.zero? && tested ? 0 : 1
+    end
+
+    private
+
+    def parse
+      options = {}
+      until @argv.empty?
+        arg = @argv.shift
+        case arg
+        when "-h", "--help", "help"
+          @stdout.puts(USAGE)
+          return { help: true }
+        when "--name", "--model", "--key-env"
+          options[arg.delete_prefix("--").tr("-", "_").to_sym] = @argv.shift or return usage_error("#{arg} needs a value")
+        when /\A--(name|model|key-env)=(.+)\z/ then options[Regexp.last_match(1).tr("-", "_").to_sym] = Regexp.last_match(2)
+        when "--no-test" then options[:no_test] = true
+        when "--dry-run" then options[:dry_run] = true
+        when /\A-/ then return usage_error("unknown option #{arg}")
+        else
+          return usage_error("one TARGET only (got #{options[:target]} and #{arg})") if options[:target]
+
+          options[:target] = arg
+        end
+      end
+      if options[:key_env] && !options[:key_env].match?(ConfigFile::ENV_NAME_RE)
+        return usage_error("--key-env takes the variable's name (e.g. OPENROUTER_API_KEY), not the key")
+      end
+
+      options
+    end
+
+    # The server's Probe::Result, or nil with @exit set.
+    def find(options, key_env)
+      return scan unless options[:target]
+
+      candidates = begin
+        Bootstrap::Probe.candidates(options[:target])
+      rescue ArgumentError => e
+        usage_error(e.message)
+        @exit = 2
+        return nil
+      end
+      result = @probe.classify_target(candidates, key_env: key_env)
+      case result.kind
+      when :unreachable
+        fail!("can't reach #{result.candidate.label} (#{result.reason})")
+      when :unknown
+        detail = result.status ? "HTTP #{result.status}" : result.reason
+        fail!("reached #{result.candidate.label} but it answers neither llama.cpp /props nor /v1/models (#{detail})")
+      else result
+      end
+    end
+
+    def scan
+      found = @probe.scan_local
+      ports = Bootstrap::Probe::LOCAL_PORTS.keys.join(", ")
+      return fail!("no model server found on localhost (#{ports}); pass one: chi bootstrap HOST[:PORT]") if found.empty?
+      return found.first if found.size == 1
+
+      labels = found.map { |r| "#{r.candidate.label} (#{Bootstrap::Probe::LOCAL_PORTS[r.candidate.port]}, #{models_count(r)})" }
+      unless tty?
+        @stderr.puts("chi bootstrap: model servers on this machine:")
+        labels.each { |label| @stderr.puts("  #{label}") }
+        @stderr.puts("pick one: chi bootstrap localhost:PORT")
+        @exit = 2
+        return nil
+      end
+      picked = pick(labels, "server") or return fail!("nothing picked")
+      found[labels.index(picked)]
+    end
+
+    def models_count(result)
+      n = result.models.size
+      n == 1 ? "1 model" : "#{n} models"
+    end
+
+    # [result, key_env] once the server lets us in, or nil with @exit set.
+    def with_key(result, key_env)
+      return [result, key_env] unless result.kind == :needs_key
+
+      host = result.candidate.label
+      return fail!("#{host} refused the key in #{key_env} (HTTP #{result.status})") if key_env
+
+      unless tty?
+        @stderr.puts("chi bootstrap: #{host} wants an API key (HTTP #{result.status}); " \
+                     "pass the variable that holds it: --key-env VAR")
+        @exit = 2
+        return nil
+      end
+      @stdout.print("#{host} wants an API key. API key environment variable (e.g. OPENROUTER_API_KEY): ")
+      key_env = @stdin.gets.to_s.strip
+      return fail!("no variable given") if key_env.empty?
+      return fail!("#{key_env} isn't a variable name") unless key_env.match?(ConfigFile::ENV_NAME_RE)
+      return fail!("#{key_env} is not set; export it and run chi bootstrap again") if unset?(key_env)
+
+      result = @probe.classify(result.candidate, key_env: key_env)
+      return fail!("#{host} refused the key in #{key_env} (HTTP #{result.status})") if result.kind == :needs_key
+      return fail!("can't reach #{host} (#{result.reason || "HTTP #{result.status}"})") unless result.reached?
+
+      [result, key_env]
+    end
+
+    def describe(result)
+      if result.native?
+        build = result.props["build_info"].to_s
+        @stdout.puts("found: llama.cpp at #{result.candidate.root}#{build.empty? ? "" : " (build #{build})"}")
+      else
+        @stdout.puts("found: an OpenAI-compatible API at #{result.candidate.base}")
+      end
+    end
+
+    def pick_model(result, wanted)
+      ids = result.models.map(&:id).reject(&:empty?)
+      if wanted
+        return wanted if ids.empty?
+
+        match = ids.find { |id| id == wanted } || ids.find { |id| id.casecmp?(wanted) }
+        return match if match
+
+        @stderr.puts("chi bootstrap: #{result.candidate.label} has no model #{wanted}; it lists:")
+        ids.each { |id| @stderr.puts("  #{id}") }
+        @exit = 1
+        return nil
+      end
+      return fail!("#{result.candidate.label} lists no models; pass one: --model ID") if ids.empty?
+      return ids.first if ids.size == 1
+      return pick(ids, "model") || fail!("nothing picked") if tty?
+
+      @stderr.puts("chi bootstrap: #{result.candidate.label} has #{ids.size} models:")
+      ids.each { |id| @stderr.puts("  #{id}") }
+      @stderr.puts("pick one: --model ID")
+      @exit = 2
+      nil
+    end
+
+    def show_model(result, model, key_env)
+      @stdout.puts("model: #{model}")
+      return unless result.native?
+
+      props = @probe.model_props(result.candidate, model, key_env: key_env) || result.props
+      n_ctx = props.dig("default_generation_settings", "n_ctx")
+      @stdout.puts("context: #{n_ctx} tokens") if n_ctx.is_a?(Integer) && n_ctx.positive?
+      profile, evidence = ModelProfile.fingerprint(props)
+      @stdout.puts("profile: #{profile} (chat template: #{evidence})") if profile
+    end
+
+    def test(result, model, key_env)
+      done = Queue.new
+      waiting = Thread.new do
+        @stdout.puts("test: waiting for an answer (loading the model?)…") if done.pop(timeout: LOADING_AFTER).nil?
+      end
+      seconds = @probe.test_turn(result.candidate, model, key_env: key_env)
+      @stdout.puts(format("test: answered in %.1f s", seconds))
+      true
+    rescue StandardError => e
+      @stdout.puts("test: failed: #{e.message}")
+      false
+    ensure
+      done&.push(true)
+      waiting&.join
+    end
+
+    # 0 written, 1 written but not as planned, nil with @exit on a refusal.
+    def write(result, model, key_env, options)
+      writer = Bootstrap::ConfigWriter.new(path: @config_path, env: @env)
+      fields = host_fields(result.candidate, result.native?, key_env)
+      ids = result.models.map(&:id)
+      name = begin
+        writer.host_name(Bootstrap::ConfigWriter.derived_name(result.candidate.host), requested: options[:name], model_ids: ids)
+      rescue Bootstrap::ConfigWriter::Error => e
+        usage_error(e.message)
+        @exit = 2
+        return nil
+      end
+      outcome = writer.write(name: name, fields: fields, model: model, dry_run: options[:dry_run])
+      report(outcome, model)
+    end
+
+    # The hosts entry: host/port for a plain http server (api: openai when it
+    # isn't llama.cpp), url for https or a URL with its own path.
+    def host_fields(candidate, native, key_env)
+      fields = if candidate.url || candidate.scheme == "https"
+                 { "url" => native ? candidate.root : candidate.base }
+               else
+                 { "host" => candidate.host, "port" => candidate.port }
+               end
+      fields["api"] = "openai" unless native
+      fields["api_key_env"] = key_env if key_env
+      fields
+    end
+
+    def report(outcome, model)
+      path = outcome.path
+      case outcome.kind
+      when :dry_run
+        @stdout.puts("dry run: would write #{outcome.where} (#{path}):")
+        @stdout.puts(outcome.text.gsub(/^/, "  "))
+        @stdout.puts("and print: #{outcome.model_hint}") if outcome.model_hint
+        0
+      when :new
+        @stdout.puts("config: #{path} (new)")
+        next_steps
+        0
+      when :appended
+        @stdout.puts("config: #{path} (hosts entry '#{outcome.name}' added; backup #{File.basename(outcome.backup)})")
+        @stdout.puts("default.model: #{outcome.default_model}") if outcome.default_model
+        @stdout.puts("add under default: in config.yml:\n#{outcome.model_hint}") if outcome.model_hint
+        @stdout.puts("use it: chi --model #{outcome.name}:#{model}   (or /model in a session)") unless outcome.default_model
+        0
+      when :exists
+        @stdout.puts("config: #{path} already has this server as '#{outcome.existing}'; nothing written")
+        @stdout.puts("use it: chi --model #{outcome.existing}:#{model}   (or /model in a session)")
+        0
+      when :snippet
+        @stdout.puts("config: #{path} uses YAML chi won't edit (flow style or anchors); add this yourself:")
+        @stdout.puts(outcome.text.gsub(/^/, "  "))
+        @stdout.puts("use it: chi --model #{outcome.name}:#{model}")
+        0
+      else
+        @stderr.puts("chi bootstrap: the edited #{path} didn't read back as expected; " \
+                     "it is back as it was (#{File.basename(outcome.backup)}). Add this yourself:")
+        @stderr.puts(outcome.text.gsub(/^/, "  "))
+        1
+      end
+    end
+
+    def next_steps
+      lines = [["chi", "a session"], ["chi web --open", "the web UI"], ["chi bundle list", "optional bundles (guardrails, …)"]]
+      lines << ["chi desktop install", "macOS \"Send to chi\" helper"] if @platform.to_s.include?("darwin")
+      lines.each_with_index do |(command, what), i|
+        @stdout.puts("#{i.zero? ? "next:" : "     "}  #{command.ljust(20)} # #{what}")
+      end
+    end
+
+    # A numbered list (the first PICK_SHOWN; a typed word narrows it).
+    def pick(items, noun)
+      shown = items
+      loop do
+        shown.first(PICK_SHOWN).each_with_index { |item, i| @stdout.puts(format("  %2d) %s", i + 1, item)) }
+        more = shown.size - PICK_SHOWN
+        @stdout.puts("  … #{more} more: type part of a name to narrow the list") if more.positive?
+        @stdout.print("#{noun} (number#{items.size > PICK_SHOWN ? " or text" : ""}, empty to stop): ")
+        answer = @stdin.gets.to_s.strip
+        return nil if answer.empty?
+
+        number = Integer(answer, exception: false)
+        return shown[number - 1] if number && number.between?(1, [shown.size, PICK_SHOWN].min)
+
+        narrowed = items.select { |item| item.downcase.include?(answer.downcase) }
+        if narrowed.empty?
+          @stdout.puts("no #{noun} matches '#{answer}'")
+        else
+          shown = narrowed
+          return shown.first if shown.size == 1
+        end
+      end
+    end
+
+    def tty?
+      @stdin.respond_to?(:tty?) && @stdin.tty?
+    end
+
+    def unset?(name) = @env[name].to_s.strip.empty?
+
+    def fail!(message)
+      @stderr.puts("chi bootstrap: #{message}")
+      @exit = 1
+      nil
+    end
+
+    def usage_error(message)
+      @stderr.puts("chi bootstrap: #{message} (see chi bootstrap --help)")
+      nil
+    end
+  end
+end

data/lib/samagotchi/bridge/pending_card.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module Samagotchi
+  class Bridge
+    # The running turn's open card with actions (check-in's Nudge / Keep
+    # going / Stop) as a file in the session's folder, pending_card.json
+    # {id:, bundle:}, for `chi web`'s session hub: it watches files, not
+    # workers, and a tab behind notifies from its summary (notify.js), as
+    # for a pending question. A persistent observer, like CardStore.
+    #
+    # Written when such a card shows; removed when that card comes again
+    # without actions (resolved), when the turn ends, and when the Bridge
+    # starts or stops. A card with no actions (loop-guard's warn) never
+    # writes it, nor does a card between turns.
+    class PendingCard
+      FILE = "pending_card.json"
+      TURN_ENDS = %i[turn_completed turn_canceled turn_failed].freeze
+
+      # @param session_dir [String] the session's folder
+      # @return [Hash, nil] {id:, bundle:}, nil without a readable file
+      def self.read(session_dir)
+        data = JSON.parse(File.read(File.join(session_dir, FILE)))
+        return nil unless data.is_a?(Hash) && !data["id"].to_s.empty?
+
+        { id: data["id"].to_s, bundle: data["bundle"].to_s }
+      rescue StandardError
+        nil
+      end
+
+      def initialize(session_dir)
+        @path = File.join(session_dir, FILE)
+        @mutex = Mutex.new
+        @id = nil
+      end
+
+      def call(event)
+        @mutex.synchronize { fold(event) }
+      rescue StandardError
+        nil # never break the running turn
+      end
+
+      # No card is open (a start after a worker that died with one, a stop).
+      def clear
+        @mutex.synchronize do
+          @id = nil
+          FileUtils.rm_f(@path)
+        end
+      rescue StandardError
+        nil
+      end
+
+      private
+
+      def fold(event)
+        case event[:type]
+        when :card then card(event)
+        when *TURN_ENDS then remove
+        end
+      end
+
+      def card(event)
+        asks = Array(event[:actions]).any?
+        if event[:in_turn] && asks
+          write(event[:id].to_s, event[:source].to_s)
+        elsif @id && event[:id].to_s == @id
+          remove
+        end
+      end
+
+      def write(id, bundle)
+        FileUtils.mkdir_p(File.dirname(@path))
+        temp = "#{@path}.tmp"
+        File.write(temp, JSON.generate({ "id" => id, "bundle" => bundle }))
+        File.rename(temp, @path)
+        @id = id
+      end
+
+      def remove
+        return unless @id
+
+        @id = nil
+        FileUtils.rm_f(@path)
+      end
+    end
+  end
+end

data/lib/samagotchi/bridge/turn_accumulator.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../kernel_loop"
+require_relative "../steer"
 
 module Samagotchi
   class Bridge
@@ -32,7 +33,7 @@ module Samagotchi
       end
 
       # @return [Hash, nil] a copy of the turn in progress: prompt, origin,
-      #   continue, ordered parts (thinking / text / tool / input / reminder / hook_notice),
+      #   continue, ordered parts (thinking / text / tool / input / steer / reminder / hook_notice),
       #   pending_question and the last event_seq folded in
       def current_turn
         @mutex.synchronize { @turn && Marshal.load(Marshal.dump(@turn)) }
@@ -67,6 +68,9 @@ module Samagotchi
           when "input"
             flush.call
             messages << { role: "user", content: part[:text].to_s }
+          when "steer"
+            flush.call
+            messages << Steer.message(text: part[:text], source: part[:source])
           end
         end
         flush.call
@@ -156,8 +160,15 @@ module Samagotchi
           tool[:output_truncated] = capped || !!event[:output_truncated]
           tool[:images] = event[:images] if event[:images]
         when :pending_input_merged
-          parts << { kind: "input", iteration: event[:iteration], text: event[:content].to_s.dup, origins: @merged_origins }
-          @merged_origins = []
+          # A steer-only merge (count 0) has no user part: the origins stay
+          # for the user lines' own merge.
+          unless event[:content].nil?
+            parts << { kind: "input", iteration: event[:iteration], text: event[:content].to_s.dup, origins: @merged_origins }
+            @merged_origins = []
+          end
+          Array(event[:steers]).each do |steer|
+            parts << { kind: "steer", iteration: event[:iteration], source: steer[:source].to_s, text: steer[:text].to_s.dup }
+          end
         when :reminder_injected
           parts << { kind: "reminder", reminders: Array(event[:reminders]).map(&:dup) }
         when :hook_notice

data/lib/samagotchi/bridge.rb

@@ -10,6 +10,7 @@ require "time"
 require_relative "bridge/bounded_queue"
 require_relative "bridge/card_store"
 require_relative "bridge/event_id"
+require_relative "bridge/pending_card"
 require_relative "bridge/ring_buffer"
 require_relative "bridge/sse_writer"
 require_relative "bridge/turn_accumulator"
@@ -92,6 +93,7 @@ module Samagotchi
       @ring = RingBuffer.new(capacity: ring_capacity)
       @accumulator = TurnAccumulator.new
       @cards = CardStore.new
+      @pending_card = PendingCard.new(session_dir)
       @heartbeat_interval = heartbeat_interval
       @epoch = SecureRandom.hex(4)
 
@@ -151,6 +153,9 @@ module Samagotchi
       # A plugin's ctx.messages mid-turn holds the turn so far (plan O1).
       @engine.running_turn_messages = -> { @accumulator.current_messages } if @engine.respond_to?(:running_turn_messages=)
       @cards_handle = @engine.subscribe(observer: @cards)
+      # One a worker that died left is not open.
+      @pending_card.clear
+      @pending_card_handle = @engine.subscribe(observer: @pending_card)
       @accept_thread = Thread.new { accept_loop }
       @accept_thread.report_on_exception = false
       write_sidecar
@@ -175,6 +180,8 @@ module Samagotchi
       @accumulator_handle&.unsubscribe
       @engine.running_turn_messages = nil if @engine.respond_to?(:running_turn_messages=)
       @cards_handle&.unsubscribe
+      @pending_card_handle&.unsubscribe
+      @pending_card&.clear
       # A turn post killed between its enqueue and its reply looks failed to
       # the web, which then queues the prompt again from the input file.
       await_answers(REQUEST_GRACE_SECONDS)
@@ -597,6 +604,8 @@ module Samagotchi
       return BAD_DEADLINE unless deadline_valid?(deadline)
 
       command = { command_id: SecureRandom.uuid, client_id: fetched(parsed, "client_id"), line: line }
+      # A card's action: the UIs leave its line out (the card is the echo).
+      command[:card] = true if fetched(parsed, "card") == true
       queued = @engine.synchronize_events do
         next false if expired?("command_expired", deadline, sid: session_id, client_id: command[:client_id])
 

data/lib/samagotchi/bridge_client.rb

@@ -162,9 +162,13 @@ module Samagotchi
     # !rollback, !cmd, /continue) for the worker to run. 202 = queued (body
     # carries the command_id its :command_ran will name), 400 = not a
     # command, 404 = a worker older than the route, 408 = too late.
+    # @param card [Boolean] the line is a card's action: its command_queued
+    #   and command_ran carry card: true, and the UIs show no echo of it
     # @return [Response]
-    def post_command(line:, client_id: nil)
-      post("command", { line: line, client_id: client_id, deadline: deadline }, read_body: true)
+    def post_command(line:, client_id: nil, card: false)
+      payload = { line: line, client_id: client_id, deadline: deadline }
+      payload[:card] = true if card
+      post("command", payload, read_body: true)
     end
 
     # POST /session/:id/exit: ask the worker to exit now. 200 = it will

data/lib/samagotchi/bundles/check-in/manifest.yml

@@ -0,0 +1,10 @@
+---
+name: check-in
+version: 0.1.1
+scope: system
+description: "Checks on a long turn: after N tool calls with no answer, a card asks the user (Nudge / Keep going / Stop), or the model is nudged to say what it has found"
+trust_level: reviewed
+plugin:
+  file: plugin.rb
+  sha256: sha256:b2ca10c949734ef3d31df9ff775cf136d7f86f185e875a4c16259e8f871bfb82
+requires_chi: ">= 0.3.0"