samagotchi 0.102.0 → 0.103.0

data/lib/samagotchi/session_access/web_bridge_client.rb

@@ -0,0 +1,181 @@
+# 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
+      # 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
+        # @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
+
+      # 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 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,141 @@
+# 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 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
+
+    # 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).
+    # +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) do
+      def initialize(prompt:, preview: nil, continues: nil, working_directory: nil, model_name: nil, setup: nil,
+                     client_id: nil, images: 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?
+    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)
+
+    # 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_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

data/lib/samagotchi/session_manager.rb

@@ -1199,6 +1199,9 @@ module Samagotchi
     # @param images [Array<Hash>] refs ({file:, name:}) already in images/
     # @param delivery [String, nil] what the message asks the running turn
     #   for: "next_step" (default), "cut" or "queue"
+    # @param no_interrupt [Boolean] the turn runs with the raised iteration
+    #   limit (an attached TUI's --no-interrupt), through the Bridge or the
+    #   file; sent only when true, so older callees see no new field
     # @param manager [#resume_session, #write_turn_input] this class, or a
     #   stand-in (the web's specs); #session_owner is optional
     # @param bridge [#call, nil] returns the BridgeClient or nil; defaults to
@@ -1211,8 +1214,8 @@ module Samagotchi
     #   :failed when the input file couldn't be written
     # @raise [OwnedByTUI] a chi REPL owns the session
     # @raise [ArgumentError] no such session
-    def self.deliver_turn(session_id, prompt:, client_id: nil, images: [], delivery: nil, state_dir: nil, manager: self,
-                          bridge: nil)
+    def self.deliver_turn(session_id, prompt:, client_id: nil, images: [], delivery: nil, no_interrupt: false,
+                          state_dir: nil, manager: self, bridge: nil)
       session_dir = Session.session_dir(session_id, state_dir: state_dir || Session.default_state_dir)
       bridge ||= -> { BridgeClient.wait_for(session_id, session_dir: session_dir, timeout: TURN_BRIDGE_WAIT) }
       manager.resume_session(session_id, state_dir: state_dir)
@@ -1226,6 +1229,7 @@ module Samagotchi
           options[:images] = images unless images.empty?
           # An old worker ignores the field: it cuts anyway (its own default).
           options[:delivery] = delivery unless Delivery.next_step?(delivery)
+          options[:no_interrupt] = true if no_interrupt
           reply = client.post_turn(**options)
           ack = reply.json
           return DeliverResult.new(status: :accepted, via: :bridge, ack: ack) if reply.status == 202 && ack.is_a?(Hash)
@@ -1252,6 +1256,7 @@ module Samagotchi
       input = { prompt: prompt, client_id: client_id, enqueued_id: enqueued_id, state_dir: state_dir }
       input[:images] = images unless images.empty?
       input[:delivery] = delivery unless Delivery.next_step?(delivery)
+      input[:no_interrupt] = true if no_interrupt
       path = manager.write_turn_input(session_id, **input)
       return DeliverResult.new(status: :failed) unless path
 

data/lib/samagotchi/session_setup.rb

@@ -5,6 +5,7 @@ require_relative "reasoning_history"
 require_relative "thinking"
 require_relative "toolkit"
 require_relative "session_config"
+require_relative "working_set_pin"
 
 module Samagotchi
   # A session's own settings that come before its model's, carried as one
@@ -20,24 +21,27 @@ module Samagotchi
   # settings chi --set gave (SessionConfig::Settings; its bundles part is
   # what Plugin::Context#settings lays over config.yml's),
   # +parent_answers+ the session's own guardrails.parent_answers (a level
-  # String, tighten-only: Guardrails::ParentPolicy.effective) or nil.
+  # String, tighten-only: Guardrails::ParentPolicy.effective) or nil,
+  # +working_set_pins+ the items the user pinned in the working set
+  # (WorkingSetPin; [] with none).
   #
   # It doesn't save itself: the session keeps each setting in its own field
   # and file key, and resolves it on its own. A delegate child starts
   # without one (but the toolkit its delegate call named, and its parent's
   # parent_answers); a continue and a fork copy their session's (.of).
   SessionSetup = Data.define(:llm_context, :thinking, :reasoning_history, :appended_prompt_files, :toolkit,
-                             :settings, :parent_answers) do
+                             :settings, :parent_answers, :working_set_pins) do
     def initialize(llm_context: nil, thinking: nil, reasoning_history: nil, appended_prompt_files: [], toolkit: nil,
-                   settings: nil, parent_answers: nil)
+                   settings: nil, parent_answers: nil, working_set_pins: [])
       super(llm_context: llm_context, thinking: thinking, reasoning_history: reasoning_history,
             appended_prompt_files: Array(appended_prompt_files).map(&:to_s).freeze, toolkit: toolkit,
-            settings: SessionConfig::Settings.of(settings), parent_answers: parent_answers&.to_s)
+            settings: SessionConfig::Settings.of(settings), parent_answers: parent_answers&.to_s,
+            working_set_pins: WorkingSetPin.list(working_set_pins))
     end
 
     def empty?
       llm_context.nil? && thinking.nil? && reasoning_history.nil? && appended_prompt_files.empty? && toolkit.nil? &&
-        settings.empty? && parent_answers.nil?
+        settings.empty? && parent_answers.nil? && working_set_pins.empty?
     end
 
     # A session's own setup, for a session that starts from it. Its
@@ -50,7 +54,8 @@ module Samagotchi
 
       new(llm_context: session.llm_context, thinking: session.thinking, reasoning_history: session.reasoning_history,
           appended_prompt_files: session.appended_prompt_files, toolkit: Toolkit.of(session.toolkit),
-          settings: session.settings, parent_answers: session.parent_answers)
+          settings: session.settings, parent_answers: session.parent_answers,
+          working_set_pins: session.working_set_pins)
     end
   end
 end