samagotchi 0.2.0 → 0.4.0

data/lib/samagotchi/bootstrap/probe.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "json"
+require "uri"
+require "ipaddr"
+require_relative "../version"
+require_relative "../llm/openai_chat"
+
+module Samagotchi
+  module Bootstrap
+    # What `chi bootstrap TARGET` finds at a model server: llama.cpp's native
+    # API (/props), an OpenAI-compatible one (/v1/models), one that wants an
+    # API key, or nothing. One attempt per request, no retries: a refused
+    # port answers at once instead of after chi's usual backoff.
+    class Probe
+      # The ports `chi bootstrap` with no target tries on localhost.
+      LOCAL_PORTS = { 8080 => "llama.cpp", 11434 => "Ollama", 1234 => "LM Studio", 8000 => "vLLM" }.freeze
+      DEFAULT_PORT = 8080
+      # Connect and read seconds for /props and /v1/models: a remote https
+      # handshake needs more than Client#server_props' 1 s / 2 s.
+      TIMEOUT = 5
+      # Seconds a local-port scan waits per port.
+      SCAN_TIMEOUT = 1
+      TEST_TIMEOUT = 60
+      TEST_PROMPT = "Reply with the word ok."
+
+      # One place a server may be: root is scheme://host:port (llama.cpp's
+      # /props), base the OpenAI API base (<root>/v1, or a URL's own path).
+      # url is true when the user gave a URL with a path, which the config
+      # then keeps as written.
+      Candidate = Data.define(:root, :base, :url) do
+        def uri = URI(root)
+        def host = uri.host
+        def port = uri.port
+        def scheme = uri.scheme
+        def label = "#{host}:#{port}"
+      end
+
+      # kind: :native, :openai, :needs_key, :unreachable or :unknown.
+      # props: the /props JSON (native); models: [LLM::ModelInfo];
+      # status: the HTTP status that decided (:unknown, :needs_key);
+      # reason: why it's unreachable.
+      Result = Data.define(:kind, :candidate, :props, :models, :status, :reason) do
+        def self.of(kind, candidate, props: nil, models: [], status: nil, reason: nil)
+          new(kind: kind, candidate: candidate, props: props, models: models, status: status, reason: reason)
+        end
+
+        def native? = kind == :native
+        def reached? = %i[native openai].include?(kind)
+      end
+
+      # The target the user typed, as the candidates to try in order.
+      #   host, host:port, an IP  → http://host:port (port 8080 when none)
+      #   a domain without a scheme → https first, then http
+      #   a URL → as given; a path is the OpenAI base
+      # Raises ArgumentError for something that isn't a host or URL.
+      def self.candidates(target)
+        text = target.to_s.strip
+        raise ArgumentError, "no target" if text.empty?
+
+        if text.match?(%r{\A[a-z][a-z0-9+.-]*://}i)
+          uri = parse_uri(text)
+          raise ArgumentError, "not an http(s) URL: #{text}" unless uri.is_a?(URI::HTTP) && !uri.host.to_s.empty?
+
+          root = root_url(uri.scheme, uri.host, uri.port)
+          path = uri.path.to_s.chomp("/")
+          return [Candidate.new(root: root, base: path.empty? ? "#{root}/v1" : "#{root}#{path}", url: !path.empty?)]
+        end
+
+        uri = parse_uri("http://#{text}")
+        raise ArgumentError, "not a host or URL: #{text}" unless uri.is_a?(URI::HTTP) && !uri.host.to_s.empty?
+
+        path = uri.path.to_s.chomp("/")
+        port = text.match?(%r{:\d+(/|\z)}) ? uri.port : nil
+        schemes = domain?(uri.host) ? { "https" => 443, "http" => 80 } : { "http" => DEFAULT_PORT }
+        schemes.map do |scheme, default_port|
+          root = root_url(scheme, uri.host, port || default_port)
+          Candidate.new(root: root, base: path.empty? ? "#{root}/v1" : "#{root}#{path}", url: !path.empty?)
+        end
+      end
+
+      # scheme://host:port, without the port when it is the scheme's own
+      # (https://openrouter.ai, not https://openrouter.ai:443): it is written
+      # into config.yml as typed.
+      def self.root_url(scheme, host, port)
+        default = { "http" => 80, "https" => 443 }[scheme]
+        port == default ? "#{scheme}://#{host}" : "#{scheme}://#{host}:#{port}"
+      end
+
+      # A name with a dot that isn't an IP or localhost: reached over https
+      # on 443 first, like a browser would.
+      def self.domain?(host)
+        return false if host.nil? || host.casecmp?("localhost") || ip?(host)
+
+        host.include?(".")
+      end
+
+      def self.ip?(host)
+        IPAddr.new(host.to_s.delete_prefix("[").delete_suffix("]"))
+        true
+      rescue IPAddr::InvalidAddressError, IPAddr::AddressFamilyError
+        false
+      end
+
+      def self.parse_uri(text)
+        URI.parse(text)
+      rescue URI::InvalidURIError
+        nil
+      end
+      private_class_method :parse_uri
+
+      # @param env [Hash] where the API key variable is read
+      # @param timeout [Numeric] connect and read seconds per request
+      def initialize(env: ENV, timeout: TIMEOUT)
+        @env = env
+        @timeout = timeout
+      end
+
+      # Probe the target's candidates in order; the next one is tried only
+      # when this one refused the connection or failed its TLS handshake
+      # (https → http), not on a timeout.
+      # @param key_env [String, nil] the API key's environment variable
+      # @return [Result]
+      def classify_target(candidates, key_env: nil)
+        result = nil
+        candidates.each do |candidate|
+          result = classify(candidate, key_env: key_env)
+          break unless result.kind == :unreachable && result.reason.to_s.match?(/refused|SSL|TLS|certificate/i)
+        end
+        result
+      end
+
+      # @return [Result]
+      def classify(candidate, key_env: nil)
+        props = begin
+          status, body = get(URI("#{candidate.root}/props"), key_env)
+          status == 200 ? parse_object(body) : nil
+        rescue *network_errors => e
+          return Result.of(:unreachable, candidate, reason: reason(e))
+        end
+        return Result.of(:native, candidate, props: props, models: native_models(candidate, props, key_env)) if native_props?(props)
+
+        begin
+          Result.of(:openai, candidate, models: list_models(candidate.base, key_env))
+        rescue LLM::ProviderError => e
+          kind = [401, 403].include?(e.status) ? :needs_key : :unknown
+          Result.of(kind, candidate, status: e.status, reason: e.status ? nil : e.message)
+        rescue *network_errors => e
+          Result.of(:unreachable, candidate, reason: reason(e))
+        end
+      end
+
+      # The ports in LOCAL_PORTS that answer as a model server, probed in
+      # parallel. @return [Array<Result>] the reached ones, in LOCAL_PORTS order
+      def scan_local(ports: LOCAL_PORTS.keys)
+        scanner = self.class.new(env: @env, timeout: SCAN_TIMEOUT)
+        ports.map do |port|
+          Thread.new { scanner.classify(Candidate.new(root: "http://localhost:#{port}", base: "http://localhost:#{port}/v1", url: false)) }
+        end.map(&:value).select(&:reached?)
+      end
+
+      # /props for one model (a llama.cpp router loads it on demand), or nil
+      # when the server doesn't answer it.
+      def model_props(candidate, model, key_env: nil)
+        status, body = get(URI("#{candidate.root}/props?#{URI.encode_www_form(model: model)}"), key_env)
+        status == 200 ? parse_object(body) : nil
+      rescue StandardError
+        nil
+      end
+
+      # One short chat request: does the server generate for +model+? Any 200
+      # with a choice counts (a thinking model may spend its 16 tokens
+      # reasoning). @return [Float] seconds taken
+      # @raise [RuntimeError] with what went wrong
+      def test_turn(candidate, model, key_env: nil, read_timeout: TEST_TIMEOUT)
+        uri = URI("#{candidate.base}/chat/completions")
+        request = Net::HTTP::Post.new(uri)
+        request["Content-Type"] = "application/json"
+        request.body = JSON.generate(model: model, messages: [{ role: "user", content: TEST_PROMPT }], max_tokens: 16,
+                                     stream: false)
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        response = send_request(uri, request, key_env, read_timeout: read_timeout)
+        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started
+        body = parse_object(response.body)
+        unless response.code.to_i == 200 && body && body["choices"].is_a?(Array) && !body["choices"].empty?
+          raise "HTTP #{response.code}: #{error_text(body, response.body)}"
+        end
+
+        elapsed
+      rescue *network_errors => e
+        raise "#{reason(e)} (#{candidate.label})"
+      end
+
+      private
+
+      def native_props?(props)
+        props.is_a?(Hash) && (props.key?("chat_template") || props.key?("build_info"))
+      end
+
+      # llama.cpp serves /v1/models too; a server that doesn't gets its
+      # model_alias.
+      def native_models(candidate, props, key_env)
+        models = begin
+          list_models(candidate.base, key_env)
+        rescue StandardError
+          []
+        end
+        return models unless models.empty?
+
+        name = props["model_alias"].to_s.strip
+        name.empty? ? [] : [LLM::ModelInfo.new(id: name, context_window: nil, supports_tools: nil, raw: {})]
+      end
+
+      def list_models(base, key_env)
+        LLM::OpenAIChat.new(base_url: base, host_name: URI(base).host, api_key_env: key_env, retries: false,
+                            timeout: @timeout, env: @env).list_models
+      end
+
+      def get(uri, key_env)
+        response = send_request(uri, Net::HTTP::Get.new(uri), key_env, read_timeout: @timeout)
+        [response.code.to_i, response.body]
+      end
+
+      def send_request(uri, request, key_env, read_timeout:)
+        request["User-Agent"] = Samagotchi::USER_AGENT
+        key = key_env && @env[key_env].to_s
+        request["Authorization"] = "Bearer #{key}" if key && !key.strip.empty?
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: @timeout,
+                                            read_timeout: read_timeout) { |http| http.request(request) }
+      end
+
+      def network_errors
+        [*LLM::HTTP::NETWORK_ERRORS, OpenSSL::SSL::SSLError, Errno::EADDRNOTAVAIL, Errno::ENETDOWN, Errno::EPIPE]
+      end
+
+      def reason(error)
+        case error
+        when Errno::ECONNREFUSED then "connection refused"
+        when Net::OpenTimeout then "no answer in #{@timeout} s"
+        when Timeout::Error, IO::TimeoutError then "timed out"
+        when SocketError then "unknown host"
+        when OpenSSL::SSL::SSLError then "TLS: #{error.message}"
+        else error.message
+        end
+      end
+
+      def parse_object(text)
+        parsed = JSON.parse(text.to_s)
+        parsed.is_a?(Hash) ? parsed : nil
+      rescue JSON::ParserError
+        nil
+      end
+
+      def error_text(body, raw)
+        message = body.is_a?(Hash) && (body.dig("error", "message") || body["error"] || body["message"])
+        (message || raw.to_s)[0, 200].to_s.strip
+      end
+    end
+  end
+end

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