samagotchi 0.101.0 → 0.103.0

data/lib/samagotchi/message_parts.rb

@@ -187,6 +187,9 @@ module Samagotchi
       mark[:staged] = true unless edit.applied?
       if edit.kind == :stale
         mark[:note] = edit.note[/superseded by .*\z/] || edit.note
+      elsif edit.kind == LLMContextEdit::DROP
+        # The user's: no note, no grouping (a forget's key is its note).
+        mark[:by] = edit.by
       else
         key = [edit.note, edit.by, edit.staged_at]
         if first.key?(key)
@@ -201,12 +204,14 @@ module Samagotchi
       mark
     end
 
-    # +output+'s ✂ mark (+marks+ by +id+); an applied stale stub says
-    # what it frees: its output, ~chars/4.
+    # +output+'s ✂ mark (+marks+ by +id+); an applied stale stub or a
+    # user's drop says what it frees: its output, ~chars/4.
+    WHOLE_STUBS = %w[stale drop].freeze
+
     def mark_of(id, marks, output)
       mark = marks[id]
       return nil unless mark
-      return mark unless mark[:kind] == "stale" && !mark[:staged] && output
+      return mark unless WHOLE_STUBS.include?(mark[:kind]) && !mark[:staged] && output
 
       mark.merge(tokens: (output.length / TokenUsage::CHARS_PER_TOKEN).ceil)
     end

data/lib/samagotchi/note_command.rb

@@ -6,6 +6,7 @@ require_relative "note_delivery"
 require_relative "session_manager"
 require_relative "cli/command"
 require_relative "cli/flags"
+require_relative "session_access/local"
 
 module Samagotchi
   # `chi note`: push text into sessions as a context note (background the
@@ -33,12 +34,15 @@ module Samagotchi
     end
 
     # @param argv [Array<String>] the arguments after "note"
-    def initialize(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, state_dir: nil)
+    # @param access [SessionAccess::Local, nil] where the sessions are;
+    #   default this machine's, in +state_dir+
+    def initialize(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, state_dir: nil, access: nil)
       @argv = argv.dup
       @stdin = stdin
       @stdout = stdout
       @stderr = stderr
       @state_dir = state_dir || Session.default_state_dir
+      @access = access || SessionAccess::Local.new(state_dir: @state_dir)
     end
 
     # @return [Integer] exit status: 0 all queued, 1 any refused or failed,
@@ -93,8 +97,7 @@ module Samagotchi
 
     # --all: every live session. @return [Integer] exit status
     def deliver_to_live(text, source)
-      ids = SessionManager.session_summaries(live: true, include_tests: Session.test_session_env?,
-                                             state_dir: @state_dir).map { |s| s[:id] }
+      ids = @access.summaries(live: true, include_tests: Session.test_session_env?).map { |s| s[:id] }
       if ids.empty?
         error_line("chi note: no live sessions (chi sessions list --live --scope=all)")
         return 1
@@ -104,9 +107,7 @@ module Samagotchi
     end
 
     def resolve(given)
-      id = Session.resolve_id(given, state_dir: @state_dir)
-      Session.load(id, state_dir: @state_dir)
-      id
+      @access.resolve(given)
     rescue ArgumentError => e
       message = e.is_a?(Session::AmbiguousId) ? e.message : "no session #{given}"
       error_line("chi note: #{message}")
@@ -115,7 +116,7 @@ module Samagotchi
 
     # @return [Boolean] whether the note was queued
     def deliver(id, text, source)
-      result = NoteDelivery.deliver(id, text: text, source: source, state_dir: @state_dir)
+      result = @access.note(id, text: text, source: source)
       @stdout.puts("#{id[0, 8]}  #{outcome(result)}")
       result.delivered?
     end

data/lib/samagotchi/parent_report.rb

@@ -3,6 +3,7 @@
 require "delegate"
 require "json"
 
+require_relative "chi_invocation"
 require_relative "cli/exit"
 require_relative "pending_question"
 require_relative "session"
@@ -81,7 +82,9 @@ module Samagotchi
     # @return [Hash] the --format json object
     # @param strategy [Guardrails::ParentPolicy::Strategy, nil] what a parent
     #   may pick on the waited-for session (#strategy_for); nil: config.yml's
-    def json(result, session_id:, timeout: nil, extra: {}, strategy: nil)
+    # @param via [ChiInvocation] how the printed commands are spelled (this
+    #   machine's chi, or chi --remote NAME); each function here takes it
+    def json(result, session_id:, timeout: nil, extra: {}, strategy: nil, via: ChiInvocation::HERE)
       report = { status: status(result), session_id: session_id }
       report[:turn_id] = result.turn_id unless result.turn_id.to_s.empty?
       case report[:status]
@@ -89,10 +92,10 @@ module Samagotchi
       when "question"
         question = question(result.question, strategy: strategy)
         report[:question] = question
-        report[:answer_with] = answer_with(session_id, question)
+        report[:answer_with] = answer_with(session_id, question, via: via)
       else
         report.merge!(stop_facts(result))
-        report[:detail] = detail(result, session_id: session_id, timeout: timeout, strategy: strategy)
+        report[:detail] = detail(result, session_id: session_id, timeout: timeout, strategy: strategy, via: via)
       end
       report.merge(extra)
     end
@@ -110,8 +113,8 @@ module Samagotchi
     end
 
     # @return [String] the JSON object as one line
-    def json_line(result, session_id:, timeout: nil, extra: {}, strategy: nil)
-      JSON.generate(json(result, session_id: session_id, timeout: timeout, extra: extra, strategy: strategy))
+    def json_line(result, session_id:, timeout: nil, extra: {}, strategy: nil, via: ChiInvocation::HERE)
+      JSON.generate(json(result, session_id: session_id, timeout: timeout, extra: extra, strategy: strategy, via: via))
     end
 
     # Print a wait's end the way the commands do: the JSON object on
@@ -120,17 +123,19 @@ module Samagotchi
     # @param command [String] "chi send", "chi answer"
     # @param extra [Hash] more keys for the JSON object (#json)
     # @return [Integer] the exit status
-    def report(result, session_id:, stdout:, stderr:, command:, json: false, timeout: nil, extra: {}, strategy: nil)
+    def report(result, session_id:, stdout:, stderr:, command:, json: false, timeout: nil, extra: {}, strategy: nil,
+               via: ChiInvocation::HERE)
       if json
-        stdout.puts(json_line(result, session_id: session_id, timeout: timeout, extra: extra, strategy: strategy))
+        stdout.puts(json_line(result, session_id: session_id, timeout: timeout, extra: extra, strategy: strategy, via: via))
       elsif result.status == :done
         stdout.puts(result.text)
       else
         stdout.flush
         text = if result.status == :waiting_for_answer
-                 question_text(result.question, session_id: session_id, strategy: strategy)
+                 question_text(result.question, session_id: session_id, strategy: strategy, via: via)
                else
-                 "#{detail(result, session_id: session_id, timeout: timeout, turn_id: result.turn_id, strategy: strategy)}\n"
+                 "#{detail(result, session_id: session_id, timeout: timeout, turn_id: result.turn_id, strategy: strategy,
+                                   via: via)}\n"
                end
         stderr.print("#{command}: #{text}")
       end
@@ -177,16 +182,22 @@ module Samagotchi
     # lists an Allow once a parent may give). A step-limit question's
     # continues the turn, or stops it where a parent may not continue (its
     # other form is in #question_text).
-    def answer_with(session_id, question)
-      return "chi answer #{session_id} --question #{question[:id]} --option Deny --text WHY" if approval?(question)
-      return stop_command(session_id, question) if continue?(question) && !may_continue?(question)
-      return "chi answer #{session_id} --question #{question[:id]} --option Continue" if continue?(question)
+    def answer_with(session_id, question, via: ChiInvocation::HERE)
+      return answer_command(session_id, question, "Deny --text WHY", via: via) if approval?(question)
+      return stop_command(session_id, question, via: via) if continue?(question) && !may_continue?(question)
+      return answer_command(session_id, question, "Continue", via: via) if continue?(question)
 
       # The one option a parent may pick (cost-cap's Stop under hard).
       only = Array(question[:allowed_options])
-      return "chi answer #{session_id} --question #{question[:id]} --option #{option_arg(only.first)}" if only.size == 1
+      return answer_command(session_id, question, option_arg(only.first), via: via) if only.size == 1
 
-      "chi answer #{session_id} --question #{question[:id]} --option N"
+      answer_command(session_id, question, "N", via: via)
+    end
+
+    # chi answer ID --question QID --option +option+ (its words after
+    # --option: a label, maybe --text).
+    def answer_command(session_id, question, option, via: ChiInvocation::HERE)
+      via.command("answer #{session_id} --question #{question[:id]} --option #{option}")
     end
 
     # What a parent does with an approval it may not allow.
@@ -239,17 +250,18 @@ module Samagotchi
       question.fetch(:allowed_options, question[:options]).include?(Guardrails::ParentPolicy::CONTINUE)
     end
 
-    def stop_command(session_id, question)
-      "chi answer #{session_id} --question #{question[:id]} --option Stop --text WHY"
+    def stop_command(session_id, question, via: ChiInvocation::HERE)
+      answer_command(session_id, question, "Stop --text WHY", via: via)
     end
 
     def option_arg(label) = label.match?(/\A[\w.-]+\z/) ? label : label.inspect
 
     # The other way: the user answers it in chi (the web's bell and badge
     # say it waits), and a wait with no message waits past it.
-    def leave_open(session_id)
-      "or leave it open: tell your user it waits in chi web (session #{session_id[0, 8]}); " \
-        "chi send --wait --format json #{session_id} waits until they answer"
+    def leave_open(session_id, via: ChiInvocation::HERE)
+      web = via.remote? ? via.web : "chi web"
+      "or leave it open: tell your user it waits in #{web} (session #{session_id[0, 8]}); " \
+        "#{via.command("send --wait --format json #{session_id}")} waits until they answer"
     end
 
     # @param question [PendingQuestion, Hash, nil] a pending question, or a
@@ -267,13 +279,13 @@ module Samagotchi
     end
 
     # What a message does to a step-limit question.
-    def message_drops(session_id)
-      "a message instead (chi send #{session_id} -m …) drops it and starts a new turn"
+    def message_drops(session_id, via: ChiInvocation::HERE)
+      "a message instead (#{via.command("send #{session_id} -m …")}) drops it and starts a new turn"
     end
 
     # What a wait that ended without an answer says, one line.
-    def detail(result, session_id:, timeout: nil, turn_id: nil, strategy: nil)
-      attach = "chi --attach #{session_id}"
+    def detail(result, session_id:, timeout: nil, turn_id: nil, strategy: nil, via: ChiInvocation::HERE)
+      shows = via.shows(session_id)
       case result.status
       when :waiting_for_answer
         q = question(result.question, strategy: strategy)
@@ -281,20 +293,20 @@ module Samagotchi
           "waiting for an approval: #{first_line(q[:text])}; #{approval_advice(q, strategy: strategy)}"
         elsif continue?(q) && !may_continue?(q)
           "waiting at the step limit: #{first_line(q[:text])}; a parent may only stop it here " \
-            "(#{policy(strategy).label}): #{stop_command(session_id, q)}, or tell your user it waits"
+            "(#{policy(strategy).label}): #{stop_command(session_id, q, via: via)}, or tell your user it waits"
         elsif continue?(q)
           "waiting at the step limit: #{first_line(q[:text])}; " \
-            "answer Continue or Stop: chi answer #{session_id} --question #{q[:id]} --option Continue"
+            "answer Continue or Stop: #{answer_command(session_id, q, "Continue", via: via)}"
         else
-          "waiting for an answer: #{first_line(q[:text])}; open it: #{attach} or the web"
+          "waiting for an answer: #{first_line(q[:text])}; open it: #{via.open_it(session_id)}"
         end
-      when :no_reply then "#{no_reply_line(result, session_id, strategy: strategy)}; #{attach} shows it"
-      when :error then "the worker failed: #{result.text}; #{attach} shows what happened"
-      when :worker_gone then "the worker is gone; #{attach} shows what happened"
+      when :no_reply then "#{no_reply_line(result, session_id, strategy: strategy, via: via)}; #{shows} shows it"
+      when :error then "the worker failed: #{result.text}; #{shows} shows what happened"
+      when :worker_gone then "the worker is gone; #{shows} shows what happened"
       when :stopped then "the session was stopped (chi sessions stop)"
       else
-        wait_again = "chi send --wait --turn #{turn_id} #{session_id}" unless turn_id.to_s.empty?
-        hint = wait_again || attach
+        wait_again = via.command("send --wait --turn #{turn_id} #{session_id}") unless turn_id.to_s.empty?
+        hint = wait_again || shows
         timeout ? "still running after #{format("%g", timeout)} s: #{hint}" : "still running: #{hint}"
       end
     end
@@ -302,7 +314,7 @@ module Samagotchi
     # The whole question for stderr: header, text, numbered options, what
     # else it takes, and the commands that answer it.
     # @return [String] lines, newline-terminated
-    def question_text(pending, session_id:, strategy: nil)
+    def question_text(pending, session_id:, strategy: nil, via: ChiInvocation::HERE)
       q = question(pending, strategy: strategy)
       lines = ["waiting for an answer (#{q[:kind]}): #{q[:header] || first_line(q[:text])}"]
       text_lines = q[:text].strip.lines.map(&:rstrip)
@@ -315,31 +327,31 @@ module Samagotchi
           lines << "  allowing it is up to your user: #{DENY_AND_TELL}"
         else
           lines << "  #{approval_advice(q, strategy: strategy)}"
-          allows.each { |label| lines << "  allow: chi answer #{session_id} --question #{q[:id]} --option #{option_arg(label)}" }
+          allows.each { |label| lines << "  allow: #{answer_command(session_id, q, option_arg(label), via: via)}" }
         end
-        lines << "  deny: #{answer_with(session_id, q)}"
-        lines << "  #{leave_open(session_id)}"
+        lines << "  deny: #{answer_with(session_id, q, via: via)}"
+        lines << "  #{leave_open(session_id, via: via)}"
       elsif continue?(q)
         lines << if may_continue?(q)
-                   "  continue: #{answer_with(session_id, q)}"
+                   "  continue: #{answer_with(session_id, q, via: via)}"
                  else
                    "  continuing it is up to your user (#{policy(strategy).label}): stop it, or tell your user it waits"
                  end
-        lines << "  stop: #{stop_command(session_id, q)} (the text is optional; the model reads it)"
-        lines << "  #{message_drops(session_id)}"
+        lines << "  stop: #{stop_command(session_id, q, via: via)} (the text is optional; the model reads it)"
+        lines << "  #{message_drops(session_id, via: via)}"
       else
         lines << "  more than one allowed: repeat --option" if q[:multi_select]
         lines << "  free text allowed: --text" if q[:allow_freeform]
         if q[:allowed_options]
           lines << "  a parent may pick #{q[:allowed_options].map { |o| option_arg(o) }.join(", ")}; the others are up to your user"
         end
-        lines << "  answer: #{answer_with(session_id, q)}"
-        lines << "  or open it: chi --attach #{session_id} or the web"
+        lines << "  answer: #{answer_with(session_id, q, via: via)}"
+        lines << "  or open it: #{via.open_it(session_id)}"
       end
       lines.map { |line| "#{line}\n" }.join
     end
 
-    def no_reply_line(result, session_id = nil, strategy: nil)
+    def no_reply_line(result, session_id = nil, strategy: nil, via: ChiInvocation::HERE)
       return command_line(result) if result.origin == TurnCheckpoint::COMMAND_ORIGIN
 
       case result.outcome
@@ -354,7 +366,7 @@ module Samagotchi
         ran_out = "the turn ran out of iterations#{" (#{result.limit} steps)" if result.limit} before it answered"
         strategy = policy(strategy)
         if strategy.allow?(Guardrails::ParentPolicy::SPEND)
-          "#{ran_out}; chi send #{session_id} -m '/continue yes' continues it, a message drops it"
+          "#{ran_out}; #{via.command("send #{session_id} -m '/continue yes'")} continues it, a message drops it"
         else
           # No /continue yes hint: a parent may not continue it here.
           "#{ran_out}; continuing it is up to your user (#{strategy.label}), a message drops it"

data/lib/samagotchi/plugin/context.rb

@@ -104,7 +104,7 @@ module Samagotchi
 
       # config.yml `bundles: <bundle>:` with the session's own values for
       # the bundle laid over it (chi --set BUNDLE.KEY=VALUE, through the
-      # Host's setup: SessionSetup#bundle_settings), string keys, frozen.
+      # Host's setup: SessionSetup#settings's bundles), string keys, frozen.
       # Plugin init and chi.ctx run before the session is bound: with no
       # session id yet it is the config alone, and it is built again once
       # per session id (the session's values never change after it starts).
@@ -473,7 +473,7 @@ module Samagotchi
       # The session's own values for this bundle ({} without any; nil when
       # the Host couldn't tell them, so #settings can retry).
       def session_values(id)
-        values = @host.setup&.call&.bundle_settings
+        values = @host.setup&.call&.settings&.bundles
         values.is_a?(Hash) ? values.fetch(@bundle, {}) : {}
       rescue StandardError => e
         unless (@session_settings_unread ||= {}).key?(id)

data/lib/samagotchi/prompt.rb

@@ -27,7 +27,7 @@ module Samagotchi
   #   - Generation cue: <|im_start|>assistant\n
   module Prompt
     # Tail system messages whose text isn't the harness's own.
-    ESCAPED_KINDS = %w[note turn_note context].freeze
+    ESCAPED_KINDS = %w[note turn_note context working_set].freeze
 
     # @param messages [Array<Hash>] each element has :role and :content.
     #   Recognised roles: "system", "user", "model", "tool_response".

data/lib/samagotchi/recap_command.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative "config"
+
+module Samagotchi
+  # /recap on|off|default, the setting form of /recap (the bare /recap,
+  # which shows the recap, is the UIs' own): this session's own
+  # recap.enabled (Engine#recap_override=), the same value
+  # `chi --set recap.enabled=…` saves, applied at once (the idle recap job
+  # is rebuilt or dropped). `default` removes it, and config.yml (or env)
+  # decides again. The session's value beats config.yml's: `/recap on`
+  # turns it on under `recap: false` too. It doesn't save: its host does
+  # on the reply's changed: [:recap] (Worker#run_command).
+  class RecapCommand
+    NAME = "/recap"
+    CHOICES = { "on" => true, "off" => false, "default" => nil }.freeze
+    USAGE = "usage: #{NAME} [on|off|default]".freeze
+
+    # @param engine [Engine] #session, #recap_override=, #recap
+    def initialize(engine:)
+      @engine = engine
+    end
+
+    # @param args [String] what follows /recap
+    # @return [Array(String, Boolean, Symbol)] the reply, whether this
+    #   session's recap setting changed, and :ok or :error
+    def run(args)
+      word = args.to_s.strip.downcase
+      return [USAGE, false, :error] unless CHOICES.key?(word)
+      return ["no session yet", false, :error] unless @engine.session
+
+      value = CHOICES.fetch(word)
+      changed = @engine.recap_override != value
+      @engine.recap_override = value if changed
+      [status_line(value), changed, :ok]
+    end
+
+    # "recap: off (this session; config.yml: on)", "recap: on (config.yml)".
+    # @param own [Boolean, nil] the session's own value, nil for none
+    def status_line(own)
+      from_config = self.class.config_status
+      line = if own.nil?
+               "recap: #{word(from_config[:on])} (#{from_config[:source]})"
+             else
+               "recap: #{word(own)} (this session; #{from_config[:source]}: #{word(from_config[:on])})"
+             end
+      # On by its own word, yet no job: a pinned recap host or model that
+      # doesn't resolve (warned in the log), or an embedder's recap: false.
+      on = own.nil? ? from_config[:on] : own
+      on && @engine.recap.nil? ? "#{line}; no recap is written: its host or model doesn't resolve (see the log)" : line
+    end
+
+    # Whether the recap is on without the session's own value: off by a
+    # scalar `recap: false`, `recap: {enabled: false}` or
+    # SAMAGOTCHI_RECAP_ENABLED=false (ConfigFile.recap_config sees all
+    # three), else on (the default).
+    # @return [Hash] {on: Boolean, source: "config.yml" or "env"}
+    def self.config_status
+      on = ConfigFile.recap_config != false
+      _value, origin = Config.get_with_origin("recap.enabled")
+      { on: on, source: origin == :env ? "env" : "config.yml" }
+    end
+
+    private
+
+    def word(enabled) = enabled ? "on" : "off"
+  end
+end

data/lib/samagotchi/recap_setup.rb

@@ -7,8 +7,10 @@ require_relative "idle_target"
 require_relative "recap_store"
 
 module Samagotchi
-  # Builds (or disables) an Engine's idle recap job from the `recap:` kwarg
-  # and the Config registry. Init-only: the Engine keeps the job it returns.
+  # Builds (or disables) an Engine's idle recap job from the `recap:` kwarg,
+  # the session's own settings and the Config registry. The Engine builds
+  # one at start, and again when it binds a session whose own recap values
+  # differ (Engine#session=).
   module RecapSetup
     # Build (or disable) the idle recap job. On by default: with no recap
     # host or model configured it asks the session's current model on its
@@ -18,9 +20,10 @@ module Samagotchi
     # --model goes; an incomplete one warns and leaves recap off.
     #
     # Single precedence path: explicit `recap:` kwarg > Config registry
-    # (CLI > ENV > file > default). An explicit disable (`recap: false` as
-    # the kwarg or in the config file, `recap: {enabled: false}`, or
-    # SAMAGOTCHI_RECAP_ENABLED=false) always wins.
+    # (session > CLI > ENV > file > default). An explicit disable
+    # (`recap: false` as the kwarg or in the config file, `recap: {enabled:
+    # false}`, or SAMAGOTCHI_RECAP_ENABLED=false) wins, but over a session's
+    # own recap.enabled (chi --set recap.enabled=true) only as the kwarg.
     #
     # @param recap          [Hash, false, nil] the Engine's `recap:` kwarg
     # @param engine         [Engine] the recap job's engine
@@ -28,13 +31,22 @@ module Samagotchi
     # @param session_target [#call] → the session's current model as a recap target
     # @param session_id     [#call] → String, nil
     # @param state_dir      [#call] → String
+    # @param session_config [#call] → the session's own core settings
+    #   (SessionConfig::Settings#core), read once here
     # @return [IdleRecap, nil]
-    def self.build(recap, engine:, host_registry:, session_target:, session_id:, state_dir:)
+    def self.build(recap, engine:, host_registry:, session_target:, session_id:, state_dir:, session_config: -> { {} })
       return nil if recap == false
-      # The REPL and a worker pass nothing: the config is read here alone
-      # (a scalar `recap: false` is only seen this way).
-      return nil if recap.nil? && ConfigFile.recap_config == false
-      return nil if Samagotchi::Config.get("recap.enabled") == false
+
+      session = session_config.call || {}
+      # The session's own recap.enabled replaces both checks below.
+      if session.key?("recap.enabled")
+        return nil unless session["recap.enabled"]
+      else
+        # The REPL and a worker pass nothing: the config is read here alone
+        # (a scalar `recap: false` is only seen this way).
+        return nil if recap.nil? && ConfigFile.recap_config == false
+        return nil if Samagotchi::Config.get("recap.enabled") == false
+      end
 
       # An explicit kwarg (a spec, an embedder) over the registry.
       kwarg_config = recap.is_a?(Hash) ? recap : {}
@@ -64,7 +76,7 @@ module Samagotchi
         inactivity: recap_number_setting(kwarg_config, :inactivity, "recap.inactivity", IdleRecap::DEFAULT_INACTIVITY_SECONDS, :float),
         min_user_turns: recap_number_setting(kwarg_config, :min_user_turns, "recap.min_user_turns", IdleRecap::DEFAULT_MIN_USER_TURNS, :int),
         timeout: recap_number_setting(kwarg_config, :timeout, "recap.timeout", IdleRecap::DEFAULT_TIMEOUT_SECONDS, :float),
-        sentences: recap_sentences(string_config(kwarg_config, :sentences) || registry_string("recap.sentences")),
+        sentences: recap_sentences(string_config(kwarg_config, :sentences) || registry_string("recap.sentences", session: session)),
         store: RecapStore.new(session_id_lookup: -> { session_id.call }, state_dir_lookup: -> { state_dir.call }),
         session_id: -> { session_id.call },
         on_usage: ->(usage) { engine.note_side_usage(usage) }
@@ -108,9 +120,10 @@ module Samagotchi
     end
     private_class_method :recap_sentences
 
-    # Read a scalar recap setting via the Config registry (ENV > file > default).
-    def self.registry_string(key)
-      value = Samagotchi::Config.get(key)
+    # Read a scalar recap setting via the Config registry (session > CLI >
+    # ENV > file > default).
+    def self.registry_string(key, session: nil)
+      value = Samagotchi::Config.get(key, session: session)
       value = value.to_s.strip
       value.empty? ? nil : value
     rescue StandardError

data/lib/samagotchi/remote_command.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "cli/command"
+require_relative "cli/exit"
+require_relative "cli/flags"
+require_relative "paths"
+require_relative "remotes"
+require_relative "session_access"
+require_relative "session_access/http_transport"
+require_relative "session_access/remote"
+
+module Samagotchi
+  # `chi remote`: the other machines whose sessions chi --remote NAME (or
+  # CHI_REMOTE=NAME) reaches through their chi web (Remotes,
+  # SessionAccess::Remote). add checks the address and the token with GET
+  # /api/info before it saves anything; ls never prints a token.
+  class RemoteCommand
+    include CLI::Command
+
+    USAGE = <<~TEXT
+      Usage: chi remote <add|ls|rm> [options]
+        add NAME URL [--token-file FILE | --token-stdin]
+              a machine's chi web (http://LAN-IP:PORT, as chi web prints it with web.host: lan;
+              port 4567 by default), with its access token (chi web's LAN link carries it, after
+              ?token=). It is checked first: the chi it runs, or why it can't be reached. Saved
+              in #{Paths.tilde(Remotes.path)} (0600); an existing NAME is replaced.
+        ls [--format json]    the remotes (never their tokens)
+        rm NAME               forget one
+      Then: chi --remote NAME send|answer|note|context|sessions …, or CHI_REMOTE=NAME.
+    TEXT
+
+    SUBCOMMANDS = %w[add ls rm].freeze
+
+    FLAGS = {
+      "add" => CLI::Flags.new(help: HELP_WORDS) do |f|
+        f.value "--token-file"
+        f.switch "--token-stdin"
+      end,
+      "ls" => CLI::Flags.new(help: HELP_WORDS) { |f| f.value "--format" },
+      "rm" => CLI::Flags.new(help: HELP_WORDS)
+    }.freeze
+
+    # @param transport [#call, nil] (entry) → a transport for add's check;
+    #   HTTPTransport by default
+    def initialize(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, path: Remotes.path, transport: nil)
+      @argv = argv.dup
+      @stdin = stdin
+      @stdout = stdout
+      @stderr = stderr
+      @path = path
+      @transport = transport || ->(entry) { SessionAccess::HTTPTransport.new(entry) }
+    end
+
+    # @return [Integer] exit status: 0 done, 1 refused or unreachable, 2 usage
+    def run
+      @sub = @argv[0]
+      if @sub.nil? || HELP_WORDS.include?(@sub)
+        @stdout.puts(USAGE)
+        return 0
+      end
+      return usage_error("unknown subcommand #{@sub}") unless SUBCOMMANDS.include?(@sub)
+
+      parsed = parse_flags(FLAGS.fetch(@sub), @argv[1..])
+      return parsed if parsed.is_a?(Integer)
+
+      send(:"run_#{@sub}", parsed.options, parsed.args)
+    rescue Remotes::Invalid => e
+      error_line("#{command_name}: #{e.message}")
+      CLI::Exit::FAILED
+    end
+
+    private
+
+    def command_name = @sub && SUBCOMMANDS.include?(@sub) ? "chi remote #{@sub}" : "chi remote"
+    def usage_on_error = nil
+
+    def run_add(options, args)
+      return usage_error("give NAME and URL") unless args.size == 2
+      return usage_error("--token-file and --token-stdin: choose one") if options[:token_file] && options[:token_stdin]
+
+      name, url = args
+      begin
+        Remotes.check_name!(name)
+        url = Remotes.normalize_url(url)
+      rescue Remotes::Invalid => e
+        return usage_error(e.message)
+      end
+      token = read_token(options)
+      return CLI::Exit::FAILED if token == false
+
+      entry = Remotes::Entry.new(name: name, url: url, token: token)
+      found = check(entry) or return CLI::Exit::FAILED
+      Remotes.put(entry, path: @path)
+      @stdout.puts("#{name}  #{url}  chi #{found["version"]}, #{lan_words(found, entry)}")
+      0
+    end
+
+    def run_ls(options, args)
+      return usage_error("ls takes no arguments") unless args.empty?
+
+      format = options[:format]
+      return usage_error("unknown format #{format.inspect}: use --format text|json") unless [nil, "text", "json"].include?(format)
+
+      entries = Remotes.all(path: @path)
+      if format == "json"
+        @stdout.puts(JSON.generate(entries.map { |e| { name: e.name, url: e.url, token: !e.token.nil? } }))
+      elsif entries.empty?
+        @stdout.puts("no remotes (chi remote add NAME URL --token-file FILE)")
+      else
+        width = entries.map { |e| e.name.length }.max
+        entries.each { |e| @stdout.puts("#{e.name.ljust(width)}  #{e.url}#{"  (no token)" unless e.token}") }
+      end
+      0
+    end
+
+    def run_rm(_options, args)
+      return usage_error("give one NAME") unless args.size == 1
+      raise Remotes::NotFound, args.first unless Remotes.remove(args.first, path: @path)
+
+      @stdout.puts("#{args.first}  removed")
+      0
+    end
+
+    # The token from its file or stdin; nil for none (a loopback chi web
+    # needs none), false after the error line.
+    def read_token(options)
+      text = if options[:token_file]
+               begin
+                 File.read(File.expand_path(options[:token_file]))
+               rescue SystemCallError => e
+                 error_line("#{command_name}: can't read #{options[:token_file]}: #{e.message.sub(/ @ .*/, "")}")
+                 return false
+               end
+             elsif options[:token_stdin]
+               read_stdin.to_s
+             end
+      return nil if text.nil?
+
+      token = text.strip
+      return token unless token.empty? || token.match?(/\s/)
+
+      error_line("#{command_name}: #{options[:token_file] || "stdin"} holds no token (one line, chi web's web-token file)")
+      false
+    end
+
+    # GET /api/info with the token: the answer, or nil after the line that
+    # says why it can't be used.
+    def check(entry)
+      reply = @transport.call(entry).call(:get, "/api/info")
+      problem = SessionAccess::Remote.info_problem(entry, reply)
+      return fail_line(problem.message) if problem
+
+      reply.json
+    rescue SessionAccess::RemoteFailed => e
+      fail_line("#{e.message}: start chi web on #{entry.host} with web.host: lan")
+    end
+
+    def lan_words(found, entry)
+      return "loopback only" unless found["lan"]
+
+      found["lan"] == entry.host ? "LAN #{found["lan"]}" : "LAN #{found["lan"]} (reached as #{entry.host})"
+    end
+
+    def fail_line(message)
+      error_line("#{command_name}: #{message}")
+      nil
+    end
+  end
+end