samagotchi 0.102.0 → 0.104.0

data/lib/samagotchi/session_access/web_bridge_client.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+require_relative "../session_access"
+require_relative "../bridge_client"
+require_relative "../delivery"
+require_relative "../log"
+require_relative "http_transport"
+
+module Samagotchi
+  module SessionAccess
+    # A session's worker reached through another machine's chi web, with the
+    # interface the attached TUI (TerminalUI::AttachedLoop) and its
+    # EventStream use on a BridgeClient: chi web relays each request to the
+    # worker's Bridge, on loopback there. One object per remote attach, for
+    # its whole life: a new worker changes its #worker_key (the worker's
+    # Bridge epoch), never the object. Built by Remote#attach_client.
+    #
+    # Every reply goes through one status mapper (Mapping), so the loop
+    # reads each condition as it reads it from a Bridge here. Every
+    # RemoteFailed (a refused connection, a timeout, a chi web too old, a
+    # refused token) becomes Unreachable with its message: the loop catches
+    # IOError wherever a Bridge call can fail, so it never crashes on one.
+    class WebBridgeClient
+      # The worker can't be reached through chi web: no live worker there,
+      # the session is gone, or chi web itself can't be asked (the message
+      # says which).
+      class Unreachable < IOError; end
+
+      # A one-shot's read timeout: above chi web's own 30 s read of the
+      # Bridge plus its <= 5 s wait for a waking worker's Bridge.
+      READ_TIMEOUT = 45
+      # An answer or a dismissal: chi web sends it once more after a 408.
+      ANSWER_READ_TIMEOUT = HTTPTransport::READ_TIMEOUT
+      # No byte for this long on the stream (the Bridge pings every 15 s): a
+      # half-open connection (Wi-Fi gone, the laptop asleep), reconnected.
+      STREAM_IDLE_TIMEOUT = 40.0
+      # A read a join waits on (a turn's saved records, the children
+      # counts): a slow chi web can't hold the join up for long (L9).
+      JOIN_READ_TIMEOUT = 5
+      # chi web answers no live worker for the session (Mapping).
+      NO_WORKER = "no live worker for session %s on %s"
+
+      # chi web's answers as the session's Bridge would have given them.
+      module Mapping
+        module_function
+
+        # @param route [Symbol] :turn, :command, :answer, :dismiss,
+        #   :dequeue, :cancel, :exit, :recap, :stats, :children, :records
+        # @param reply [HTTPTransport::Reply]
+        # @param session_id [String]
+        # @param remote [String] the remote's name
+        # @return [BridgeClient::Response] 504 as the Bridge's 408
+        #   deadline_passed; 501 as its 404 not_found (an older worker),
+        #   and /command's for one builtin as its 400 unknown_command;
+        #   the rest unchanged (202 acks, 409s, the route's own 404s,
+        #   403 parent_answer_refused, 502 bridge_error)
+        # @raise [Unreachable] 503 not_live, or 404 not_found (the session)
+        def response(route, reply, session_id:, remote:)
+          json = reply.json.is_a?(Hash) ? reply.json : {}
+          case [reply.status, json["error"]]
+          in [503, "not_live"] | [404, "not_found"] then raise Unreachable, format(NO_WORKER, session_id, remote)
+          in [504, _] then bridge(408, error: "deadline_passed", detail: json["detail"])
+          in [501, _] if route == :command && json["command"]
+            bridge(400, error: "unknown_command", detail: json["detail"], command: json["command"])
+          in [501, _] then bridge(404, error: "not_found", detail: json["detail"])
+          else BridgeClient::Response.new(status: reply.status, body: reply.body)
+          end
+        end
+
+        def bridge(status, **body) = BridgeClient::Response.new(status: status, body: JSON.generate(body.compact))
+      end
+
+      attr_reader :session_id
+      # @return [String, nil] the worker followed: its Bridge's epoch (its
+      #   start time for a worker from before the epoch in its sidecar)
+      attr_accessor :worker_key
+
+      # @param remote [Remote] the remote's chi web
+      # @param session_id [String]
+      # @param worker_key [String, nil] the live worker's epoch, from the wake
+      def initialize(remote:, session_id:, worker_key:)
+        @remote = remote
+        @session_id = session_id
+        @worker_key = worker_key
+      end
+
+      def inspect = "#<#{self.class.name} #{@remote.entry.label} #{@session_id}>"
+
+      # No Bridge port here: the worker is reached through chi web.
+      def port = nil
+
+      # POST …/turn. history: false (chi web's prompt history is that
+      # machine's page's).
+      # @return [BridgeClient::Response]
+      def post_turn(prompt:, client_id: nil, no_interrupt: false, images: nil, delivery: nil)
+        body = { prompt: prompt, client_id: client_id, history: false }
+        body[:no_interrupt] = true if no_interrupt
+        body[:images] = images if images && !images.empty?
+        body[:delivery] = delivery unless delivery.nil? || Delivery.next_step?(delivery)
+        post(:turn, "turn", body)
+      end
+
+      # POST …/command.
+      # @return [BridgeClient::Response]
+      def post_command(line:, client_id: nil, card: false)
+        body = { line: line, client_id: client_id, history: false }
+        body[:card] = true if card
+        post(:command, "command", body)
+      end
+
+      # POST …/answer (chi web passes client_id on only when it is chi
+      # answer's).
+      # @return [BridgeClient::Response]
+      def answer(id:, selected:, freeform: nil, client_id: nil)
+        post(:answer, "answer", { id: id, selected: selected, freeform: freeform, client_id: client_id }.compact,
+             read_timeout: ANSWER_READ_TIMEOUT)
+      end
+
+      # POST …/question/dismiss.
+      # @return [BridgeClient::Response]
+      def dismiss_question(id:)
+        post(:dismiss, "question/dismiss", { id: id }, read_timeout: ANSWER_READ_TIMEOUT)
+      end
+
+      # POST …/turn/:enqueued_id/dequeue.
+      # @return [BridgeClient::Response]
+      def dequeue(enqueued_id:, client_id: nil)
+        post(:dequeue, "turn/#{URI.encode_www_form_component(enqueued_id.to_s)}/dequeue", { client_id: client_id }.compact)
+      end
+
+      # POST …/cancel.
+      # @return [BridgeClient::Response]
+      def cancel(reason:)
+        post(:cancel, "cancel", { reason: reason })
+      end
+
+      # POST …/exit: the worker asked to exit (chi web passes client_id on
+      # only when it is an attached TUI's).
+      # @return [BridgeClient::Response] 200 {status: exiting, discard}, 409
+      #   held {reason, tasks}, 408 late, 404 an older worker's
+      def request_exit(client_id:, delete: false)
+        body = { client_id: client_id }
+        body[:delete] = true if delete
+        post(:exit, "exit", body)
+      end
+
+      # POST …/recap: the saved recap, and a new one asked for.
+      # @return [BridgeClient::Response] 200 {enabled, saved, request, min_user_turns, session_off}
+      def request_recap = post(:recap, "recap", {})
+
+      # GET …/stats: the worker's metrics (its state's, for an older
+      # worker), nil when it didn't give them.
+      # @return [Hash, nil]
+      # @raise [Unreachable]
+      def stats
+        response = get(:stats, "stats", read_timeout: READ_TIMEOUT)
+        response.status == 200 ? response.json&.dig("metrics") : nil
+      end
+
+      # GET …/children/counts: the session's delegates' counts there.
+      # @return [Hash] {running, waiting, unreported}
+      # @raise [Unreachable] chi web couldn't answer (or the session is gone)
+      def children_counts
+        response = get(:children, "children/counts", read_timeout: JOIN_READ_TIMEOUT)
+        raise Unreachable, "children counts: chi web answered #{response.status}" unless response.status == 200
+
+        response.json
+      end
+
+      # GET …/turns/:turn_id/records: a turn's saved tool records and turn
+      # record there.
+      # @return [Hash] {tool_records: [...], turn_record: {...} | nil}
+      # @raise [Unreachable]
+      def turn_records(turn_id)
+        response = get(:records, "turns/#{URI.encode_www_form_component(turn_id.to_s)}/records",
+                       read_timeout: JOIN_READ_TIMEOUT)
+        raise Unreachable, "turn records: chi web answered #{response.status}" unless response.status == 200
+
+        response.json
+      end
+
+      # Follow the session's events through chi web (see EventStream): with
+      # epoch_watch, announce_retries and STREAM_IDLE_TIMEOUT.
+      # @return [BridgeClient::EventStream] started
+      def follow(snapshot: true, client_id: nil, reconnect_delays: BridgeClient::EventStream::DEFAULT_RECONNECT_DELAYS,
+                 rediscover: nil, &on_event)
+        BridgeClient::EventStream.new(self, snapshot: snapshot, client_id: client_id, reconnect_delays: reconnect_delays,
+                                            rediscover: rediscover, epoch_watch: true, announce_retries: true,
+                                            idle_timeout: STREAM_IDLE_TIMEOUT, &on_event).start
+      end
+
+      # GET /api/sessions/:id/stream through StreamRequest, with the token
+      # as Bearer. A chunked response (a proxy in between: no decoding in
+      # v1) and an https chi web (no TLS on the stream yet) are logged and
+      # read as unreachable.
+      # @return [Array(TCPSocket, Integer, Hash), nil] see StreamRequest.open
+      def connect_stream(query: "", last_event_id: nil, timeout: nil)
+        uri = URI(@remote.entry.url)
+        return refused("tls_unsupported") if uri.scheme == "https"
+
+        token = @remote.entry.token
+        opened = BridgeClient::StreamRequest.open(host: uri.host, port: uri.port,
+                                                  path: "/api/sessions/#{@session_id}/stream#{query}",
+                                                  last_event_id: last_event_id, timeout: timeout,
+                                                  headers: token ? { "Authorization" => "Bearer #{token}" } : {})
+        return opened unless opened && opened[2]["transfer-encoding"].to_s.downcase.include?("chunked")
+
+        opened[0].close rescue nil
+        refused("chunked_unsupported")
+      end
+
+      private
+
+      def post(route, path, body, read_timeout: READ_TIMEOUT)
+        reply = @remote.route_request(:post, "/api/sessions/#{@session_id}/#{path}", body: body, read_timeout: read_timeout)
+        Mapping.response(route, reply, session_id: @session_id, remote: @remote.name)
+      rescue RemoteFailed => e
+        raise Unreachable, e.message
+      end
+
+      def get(route, path, read_timeout:)
+        reply = @remote.route_request(:get, "/api/sessions/#{@session_id}/#{path}", read_timeout: read_timeout)
+        Mapping.response(route, reply, session_id: @session_id, remote: @remote.name)
+      rescue RemoteFailed => e
+        raise Unreachable, e.message
+      end
+
+      def refused(reason)
+        Log.warn(:attached, "stream_refused", reason: reason, remote: @remote.name)
+        nil
+      end
+    end
+  end
+end

data/lib/samagotchi/session_access.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # The seam between chi's session commands (chi send, answer, note,
+  # session-scope context, sessions list/stop/restart/archive/unarchive/
+  # delete) and where the sessions live. One object per command run:
+  # Local reads and writes this machine's session files and workers; a
+  # Remote (chi --remote NAME, CHI_REMOTE) does the same over another
+  # machine's chi web, raising the same errors with the same words.
+  # The commands keep their wording, exit codes and checks; what they ask
+  # of a session goes through here. Session commands and flags that run on
+  # this machine only are listed in SessionAccess::Contract. See
+  # docs/architecture.md (Session access).
+  module SessionAccess
+    autoload :Local, File.expand_path("session_access/local", __dir__)
+    autoload :Contract, File.expand_path("session_access/contract", __dir__)
+    autoload :Remote, File.expand_path("session_access/remote", __dir__)
+    autoload :Dispatch, File.expand_path("session_access/dispatch", __dir__)
+
+    # A remote's chi web could not be asked, or answered what this chi can't
+    # use: the message names the remote and what failed ("remote studio
+    # (http://192.168.1.29:4567): connection refused"). Only a Remote raises
+    # it; a command prints it as it prints its other failures (exit 1).
+    class RemoteFailed < StandardError; end
+
+    # A remote's chi web is from before the routes this command needs
+    # ("remote studio runs chi 0.102.0, too old for this command through
+    # --remote: update chi there (chi update)").
+    class RemoteTooOld < RemoteFailed; end
+
+    # A remote's chi web refused this machine's token (401), or answers its
+    # LAN IP only (403 forbidden): Remote.access_error's words.
+    class AuthRefused < RemoteFailed; end
+
+    # The errors a participant's token meets (docs/internals/participants.md),
+    # one message each, built from the remote's label ("remote studio
+    # (http://…)"). chi web's code for each is its CODE.
+
+    # 401 token_revoked: the owner revoked the grant, or archived or
+    # deleted its session.
+    class TokenRevoked < AuthRefused
+      CODE = "token_revoked"
+      def initialize(label) = super("#{label}: this review link was revoked by the session's owner")
+    end
+
+    # 401 token_expired: the grant's time ran out.
+    class TokenExpired < AuthRefused
+      CODE = "token_expired"
+      def initialize(label) = super("#{label}: this review link expired: ask the session's owner for a new one")
+    end
+
+    # 403 not_permitted: a participant's token on a route only the session's
+    # owner may use.
+    class NotPermitted < RemoteFailed
+      CODE = "not_permitted"
+      def initialize(label) = super("#{label}: this token is a participant's: only the session's owner can do that")
+    end
+
+    # 429 too_many_turns (P3b): the participant's turns already wait in the
+    # queue up to their limit.
+    class TooManyTurns < RemoteFailed
+      CODE = "too_many_turns"
+      def initialize(label) = super("#{label}: this participant has too many turns waiting: wait for one to finish")
+    end
+
+    # 429 cap_reached (P3b): the participant's grant spent its cap.
+    class CapReached < RemoteFailed
+      CODE = "cap_reached"
+      def initialize(label) = super("#{label}: this participant's spending cap is reached: ask the session's owner to raise it")
+    end
+
+    # A remote's chi web refused a request for a reason this machine checks
+    # itself before sending (a parent's /continue yes, a loosening
+    # /parent-answers, images to a model that can't see them): +message+
+    # is the server's text, the words chi send uses on its own machine.
+    # +code+ is chi web's error code.
+    class Refused < StandardError
+      attr_reader :code
+
+      def initialize(message, code:)
+        @code = code
+        super(message)
+      end
+    end
+
+    # A remote's chi web refused a request's values as a usage error would
+    # on this machine (a bad --set, --toolkit or --dir there): chi send
+    # exits 2 with its message.
+    class BadRequest < Refused; end
+
+    # One participant's grant as chi share ls shows it
+    # (Web::Grants::Grant#public_h): never its token or digest. +state+
+    # "active", "revoked" or "expired".
+    ParticipantView = Data.define(:id, :session_id, :kind, :name, :role, :created_at, :expires_at, :revoked_at,
+                                  :revoked_by, :last_used_at, :state) do
+      def self.from_h(hash) = new(**members.to_h { |key| [key, hash[key] || hash[key.to_s]] })
+    end
+
+    # What chi share made: the participant, their token and the link that
+    # carries it (both shown this once: chi keeps only a digest), and
+    # whether that chi web listens on the LAN (+lan+ false: the link works
+    # on that machine only).
+    Invitation = Data.define(:participant, :token, :link, :lan) do
+      def inspect = "#<Invitation #{participant.id}>"
+      alias_method :to_s, :inspect
+    end
+
+    # A session to create (chi send --new): a new one, or with +continues+
+    # the next link of that session's chain (which brings its own folder,
+    # LLM context, thinking, toolkit and settings: the rest is nil then).
+    # +preview+ set: the session starts idle with it as its preview, and
+    # +prompt+ (nil) goes in later as a turn (images, a session command);
+    # +idle+ alone: it starts idle with no preview (a remote attach's new
+    # session, whose -p goes in once attached).
+    # +setup+ is a SessionSetup for Local, a SetupWords for Remote (the
+    # flags as typed: the server checks them against its own config and
+    # bundles). +client_id+ (chi send's, or chi answer's for a parent's
+    # /continue yes) and +images+ (images follow) are for a Remote's server,
+    # which checks the first line and the model as chi send checks them
+    # here (Local checks before it creates).
+    NewSession = Data.define(:prompt, :preview, :continues, :working_directory, :model_name, :setup, :client_id,
+                             :images, :idle) do
+      def initialize(prompt:, preview: nil, continues: nil, working_directory: nil, model_name: nil, setup: nil,
+                     client_id: nil, images: false, idle: false) = super
+    end
+
+    # chi send --new's setup flags as typed, for a Remote: +llm_context+
+    # {strategy:, apply:, budget_tokens:} words, +thinking+ and
+    # +parent_answers+ level words, +toolkit+ a name, +tools+ and
+    # +no_tools+ names, +settings+ {"KEY" => "VALUE"} as --set gave them.
+    # The server reads each as its create route does (POST /api/sessions).
+    SetupWords = Data.define(:llm_context, :thinking, :toolkit, :tools, :no_tools, :settings, :parent_answers) do
+      def initialize(llm_context: nil, thinking: nil, toolkit: nil, tools: [], no_tools: [], settings: nil,
+                     parent_answers: nil) = super
+    end
+
+    # A session as a session command reads it (Local: the Session itself;
+    # Remote: chi web's brief read). The fields the commands use, and
+    # Session's #display_title.
+    # @!attribute owner [OwnerLock::Owner, nil] its worker or chi REPL
+    # @!attribute pending_question [PendingQuestion, nil] the file's
+    SessionView = Data.define(:id, :status, :title, :display_title, :project_root, :working_directory, :model_name,
+                              :model_typed, :parent_answers, :owner, :pending_question)
+
+    # What chi send --new created (Remote; Local gives the Session): its
+    # id, a model warning, the session it continues, the delegates it took
+    # over, and the server's word on a --parent-answers looser than its
+    # config.yml's (capped).
+    Created = Data.define(:id, :model_warning, :continues, :moved_children, :parent_answers_warning)
+
+    # A session's worker as an attach finds it (Local#worker, chi web's GET
+    # …/worker): +sidecar+ the live worker's WorkerSidecar (port, version,
+    # features, epoch; nil: none runs), +stopped+ its stop marker, +owner+
+    # its OwnerLock::Owner (a worker, a chi REPL, nil).
+    WorkerState = Data.define(:sidecar, :stopped, :owner) do
+      def live? = !sidecar.nil?
+
+      # No Bridge, and the owner is a worker leaving (writing its recap on
+      # leave): a wake waits for it (Local#wake).
+      def leaving? = !live? && !!owner&.leaving?
+    end
+
+    # What a wake for an attach did (Local#wake, chi web's POST …/wake):
+    # +woke+ it started the worker (false: one ran), +sidecar+ the live
+    # worker's (nil: its Bridge didn't come within the wait).
+    Woken = Data.define(:woke, :sidecar)
+
+    # A remote attach's wake (Remote#attach_wake, chi web's POST …/wake):
+    # +worker+ the live worker as chi web names it ({"epoch", "started_at",
+    # "version", "features"}, string keys: Remote#attach_client's), and
+    # what the TUI reads of that machine: its config's +default_model+,
+    # the session's parent +strategy+ (Guardrails::ParentPolicy::Strategy),
+    # the newest chi +installed+ there.
+    WakeReply = Data.define(:woke, :worker, :default_model, :strategy, :installed)
+
+    # A remote session's worker now (Remote#attach_worker, chi web's GET
+    # …/worker): +live+, +stopped+ (its stop marker), +worker+ as in
+    # WakeReply (nil: none runs), the parent +strategy+ read now, and that
+    # machine's +default_model+ (nil from a chi web before it sent one).
+    # +leaving+: its worker is leaving (WorkerState#leaving?), for up to
+    # +leave_seconds+ more there (nil from a chi web before it sent them).
+    WorkerReply = Data.define(:live, :stopped, :worker, :strategy, :default_model, :leaving, :leave_seconds) do
+      def initialize(live:, stopped:, worker:, strategy:, default_model: nil, leaving: false, leave_seconds: nil) = super
+    end
+
+    # What chi send --wait and chi answer read before anything is sent, so
+    # neither an older reply nor a turn that ends before the first look is
+    # taken for the answer (ReplyWait's cursor:, baseline:, turn:).
+    # @!attribute cursor [String, nil] the newest reply file already there
+    # @!attribute baseline [ReplyWait::Baseline] the session as it was
+    # @!attribute own_turn [String, nil] ReplyWait.own_turn: the turn
+    #   running now, or the one whose continue offer stands
+    # @!attribute known_turn [Boolean, nil] with a turn asked for
+    #   (--turn), ReplyWait.known_turn?; nil without one
+    # @!attribute running [Boolean] the session's status was running
+    # @!attribute live [Boolean] running, or a worker or a REPL owns it
+    # @!attribute settled [Boolean] idle, a turn ended and no question
+    #   stands (a continue offer waits for its answer)
+    # @!attribute last_turn_id [String, nil] the last ended turn's
+    #   enqueued_id
+    WaitStart = Data.define(:cursor, :baseline, :own_turn, :known_turn, :running, :live, :settled, :last_turn_id)
+
+    # One attached context source as a session (or a project) sees it:
+    # its Source and Snapshot (ContextSources), and for a session's list
+    # whether it mutes it, a session source shadows it, and its text is
+    # unread (nil for a project's, or where not asked).
+    ContextEntry = Data.define(:source, :snapshot, :muted, :shadowed, :unread) do
+      def initialize(source:, snapshot:, muted: nil, shadowed: nil, unread: nil) = super
+    end
+
+    # chi context push's outcome: :pushed (+before+ the revision it had,
+    # +revision+ the new one), :missing (no such source) or :not_push (a
+    # command source, whose text is its command's).
+    ContextPush = Data.define(:status, :before, :revision) do
+      def initialize(status:, before: nil, revision: nil) = super
+
+      # Why a push to +name+ was refused as :not_push: a command source's
+      # text is its command's, and a push between two fetches would read
+      # as a change and then vanish.
+      def self.not_push_message(name) = "#{name} runs a command, which writes its text: push goes to a --push source"
+    end
+  end
+end

data/lib/samagotchi/session_archive_command.rb

@@ -3,6 +3,7 @@
 require_relative "session"
 require_relative "session_manager"
 require_relative "cli/command"
+require_relative "session_access/local"
 
 module Samagotchi
   # `chi sessions archive|unarchive`: hide sessions from every list and keep
@@ -29,12 +30,15 @@ module Samagotchi
 
     # @param action [String] "archive" or "unarchive"
     # @param argv [Array<String>] the arguments after "sessions <action>"
-    def initialize(action, argv, 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(action, argv, stdout: $stdout, stderr: $stderr, state_dir: nil, access: nil)
       @action = action
       @argv = argv.dup
       @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 done, 1 any refused or unknown, 2 usage
@@ -57,9 +61,9 @@ module Samagotchi
     private
 
     def archive(given)
-      id = Session.resolve_id(given, state_dir: @state_dir)
+      id = @access.resolve_id(given)
       short = id[0, 8]
-      result = SessionManager.archive_session(id, state_dir: @state_dir)
+      result = @access.archive(id)
       if result[:archived].include?(id)
         notes = []
         notes << "stopped its worker" if result[:stopped].include?(id)
@@ -86,9 +90,9 @@ module Samagotchi
     end
 
     def unarchive(given)
-      id = Session.resolve_id(given, state_dir: @state_dir)
+      id = @access.resolve_id(given)
       short = id[0, 8]
-      result = SessionManager.unarchive_session(id, state_dir: @state_dir)
+      result = @access.unarchive(id)
       @stdout.puts(result[:unarchived].empty? ? "#{short}  not archived" : "#{short}  unarchived")
       true
     rescue ArgumentError => e

data/lib/samagotchi/session_commands.rb

@@ -113,9 +113,9 @@ module Samagotchi
       registry.register(TOOLKIT_COMMAND, "show or change the tools this session declares (NAME, add TOOL, remove TOOL)",
                         id: :toolkit, mid_turn: show_mid_turn(TOOLKIT_COMMAND),
                         match: ->(text) { text.match?(%r{\A/toolkit(?:\s+.*)?\z}) }) { |text| toolkit(text) }
-      # The list reads only: mid-turn too; a drop waits for the turn's end
+      # The list reads only: mid-turn too; an op waits for the turn's end
       # (the next turn's first request is the first with it).
-      registry.register(WORKING_SET_COMMAND, "list the working set; drop or undrop an item (drop KEY, undrop KEY)",
+      registry.register(WORKING_SET_COMMAND, "list the working set; drop, undrop, pin or unpin an item (drop KEY…)",
                         id: :working_set, mid_turn: show_mid_turn(WORKING_SET_COMMAND),
                         match: ->(text) { text.match?(%r{\A/working-set(?:\s+.*)?\z}) }) { |text| working_set(text) }
       # Tighten-only from anyone; loosening is a user's at a UI (#run's user_ui:).
@@ -205,12 +205,14 @@ module Samagotchi
     end
 
     # Why a UI-only command isn't run by +runner+ ("chi send"): /stats points
-    # at its model-free reader (naming the session +id+ when there is one).
+    # at its model-free reader (naming the session +id+ when there is one),
+    # which reads the session's machine: under chi --remote NAME (+remote+)
+    # it runs there.
     # @return [String]
-    def self.ui_only_refusal(name, id, runner:)
+    def self.ui_only_refusal(name, id, runner:, remote: nil)
       return "#{name} is a terminal and web command; #{runner} doesn't run it" unless name == "/stats"
 
-      "#{name} is a terminal and web command; use chi sessions stats #{id ? id[0, 8] : "ID"}"
+      "#{name} is a terminal and web command; use chi sessions stats #{id ? id[0, 8] : "ID"}#{" on #{remote}" if remote}"
     end
 
     # The name of this chi's own session command +line+ is (one a worker
@@ -501,6 +503,9 @@ module Samagotchi
     def llm_context(text)
       output, changed = LLMContextCommand.new(engine: @engine, save: ->(session) { save_setup(session) })
                                          .run(text.delete_prefix(LLM_CONTEXT_COMMAND))
+      # What the model has of each item is the next turn's strategy's: the
+      # working set goes out again (sent only when it differs).
+      @engine.announce_working_set if changed
       reply(output, changed: changed ? [:llm_context] : [])
     rescue ArgumentError => e
       reply(e.message, status: :error)
@@ -545,18 +550,18 @@ module Samagotchi
       reply(output, status: status, changed: changed ? [:parent_answers] : [])
     end
 
-    # /working-set (WorkingSetCommand): an op changes the conversation
-    # (changed :messages: the worker saves it, the web reads it again), so
-    # a rollback past it would drop it silently (as !cmd), and the working
-    # set goes out again (held after the command's command_ran).
+    # /working-set (WorkingSetCommand): an op that changes the conversation
+    # (changed :messages: the worker saves it, the web reads it again)
+    # closes the rollback window (a rollback past it would drop it
+    # silently, as !cmd); a pin changes the session's working_set_pins.
+    # Either way the working set goes out again (held after the command's
+    # command_ran).
     def working_set(text)
       output, changed, status = WorkingSetCommand.new(engine: @engine, save: ->(_session) { save_session })
                                                  .run(text.delete_prefix(WORKING_SET_COMMAND))
-      if changed
-        @turn_flow.note_conversation_changed
-        @engine.announce_working_set
-      end
-      reply(output, status: status, changed: changed ? [:messages] : [])
+      @turn_flow.note_conversation_changed if changed.include?(:messages)
+      @engine.announce_working_set unless changed.empty?
+      reply(output, status: status, changed: changed)
     rescue ArgumentError => e
       reply(e.message, status: :error)
     end
@@ -565,7 +570,7 @@ module Samagotchi
     # cleared its name. A plain save: no setting moved, and it may run on
     # an anytime thread beside a turn.
     def title(text)
-      output, changed, status = TitleCommand.new(engine: @engine, save: @save).run(text.delete_prefix(TITLE_COMMAND))
+      output, changed, status = TitleCommand.new(engine: @engine).run(text.delete_prefix(TITLE_COMMAND))
       reply(output, status: status, changed: changed ? [:title] : [])
     end
 

data/lib/samagotchi/session_continue.rb

@@ -170,7 +170,7 @@ module Samagotchi
     private_class_method def self.discard_failed_link(id, state_dir)
       orphan = SessionChain.next_of(id, state_dir: state_dir) or return
       if SessionManager.refuse_tui!(orphan, state_dir: state_dir) &&
-         !SessionManager.stop_session(orphan, state_dir: state_dir, wait: 10)
+         !SessionManager.stop_session(orphan, state_dir: state_dir, wait: SessionManager::STOP_WAIT)
         raise SessionManager::DeleteRefused.new(orphan, :still_stopping)
       end
 

data/lib/samagotchi/session_delete_command.rb

@@ -4,6 +4,7 @@ require_relative "session"
 require_relative "session_manager"
 require_relative "cli/command"
 require_relative "cli/flags"
+require_relative "session_access/local"
 
 module Samagotchi
   # `chi sessions delete`: remove sessions for good (SessionManager.delete_session),
@@ -24,11 +25,14 @@ module Samagotchi
     FLAGS = CLI::Flags.new(help: CLI::Command::HELP_WORDS) { |f| f.switch "-f", "--force" }
 
     # @param argv [Array<String>] the arguments after "sessions delete"
-    def initialize(argv, 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, stdout: $stdout, stderr: $stderr, state_dir: nil, access: nil)
       @argv = argv.dup
       @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 deleted, 1 any refused or
@@ -56,10 +60,10 @@ module Samagotchi
 
     # @return [Boolean] whether the session is gone
     def delete(given, force:)
-      id = Session.resolve_id(given, state_dir: @state_dir)
+      id = @access.resolve_id(given)
       short = id[0, 8]
       preview = preview_of(id)
-      result = SessionManager.delete_session(id, state_dir: @state_dir, stop: force)
+      result = @access.delete(id, force: force)
       @stdout.puts(["#{short}  deleted#{" (stopped its worker)" if result[:stopped]}", preview].compact.join("  "))
       true
     rescue SessionManager::OwnedByTUI
@@ -80,7 +84,7 @@ module Samagotchi
     end
 
     def preview_of(id)
-      text = Session.load(id, state_dir: @state_dir).display_title.gsub(/\s+/, " ").strip
+      text = @access.show(id).display_title.gsub(/\s+/, " ").strip
       return nil if text.empty?
 
       text.length > PREVIEW_LIMIT ? "#{text[0, PREVIEW_LIMIT - 1]}…" : text