samagotchi 0.155.0 → 0.157.0

data/lib/samagotchi/session_access/local.rb

@@ -33,6 +33,8 @@ module Samagotchi
   # Loaded on first use: SessionManager and its ~80 files only when a
   # command reaches it (chi context never does).
   autoload :SessionManager, File.expand_path("../session_manager", __dir__)
+  # A continue (#create with continues); it requires session_manager.
+  autoload :SessionContinue, File.expand_path("../session_continue", __dir__)
 
   module SessionAccess
     # This machine's sessions: the calls the session commands made before
@@ -63,11 +65,11 @@ module Samagotchi
       # @raise [Session::AmbiguousId]
       def resolve_id(given) = Session.resolve_id(given, **dir)
 
-      # The full id of +given+, of a session that exists.
-      # @raise [ArgumentError] no such session (Session::AmbiguousId: a
+      # The full id of +given+, of a session that exists (and loads).
+      # @raise [Session::NotFound] no such session (Session::AmbiguousId: a
       #   prefix of several)
       def resolve(given)
-        id = resolve_id(given)
+        id = Session.resolve!(given, **dir)
         show(id)
         id
       end
@@ -79,12 +81,11 @@ module Samagotchi
       # @return [OwnerLock::Owner, nil] the worker or one-turn chi run that owns it
       def owner(id) = SessionManager.session_owner(id, **dir)
 
-      # SessionManager.list_sessions: Session objects, for chi sessions list.
-      def list(**filters) = SessionManager.list_sessions(**filters, **dir)
-
-      # SessionManager.session_summaries: the summary hashes (chi sessions
-      # list --live/--format, chi note --all).
-      def summaries(**filters) = SessionManager.session_summaries(**filters, **dir)
+      # SessionManager.session_rows: the SessionRows chi sessions list
+      # prints and chi note --all reaches (chi web's summaries route answers
+      # their #to_summary_h).
+      # @return [Array<SessionRow>]
+      def summaries(**filters) = SessionManager.session_rows(**filters, **dir)
 
       # The session's worker for an attach: the live one as is, else
       # resumed and waited for up to +wait+ seconds (chi --attach on this
@@ -140,7 +141,7 @@ module Samagotchi
 
         start = spec.preview ? { prompt: spec.prompt, preview: spec.preview } : { prompt: spec.prompt }
         if spec.continues
-          return SessionManager.continue_session(spec.continues, **start, model: spec.model_name, **dir)
+          return SessionContinue.run(spec.continues, **start, model: spec.model_name, **dir)
         end
 
         SessionManager.spawn_session(**start, working_directory: spec.working_directory, model_name: spec.model_name,
@@ -269,7 +270,7 @@ module Samagotchi
       # @return [Boolean] whether the worker released the session
       def stop(id, wait:) = SessionManager.stop_session(id, wait: wait, **dir)
 
-      # @return [SessionManager::RestartResult]
+      # @return [SessionManager::Restarted]
       def restart(id) = SessionManager.restart_session(id, **dir)
 
       # @return [SessionManager::ArchiveResult]

data/lib/samagotchi/session_access/remote.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../session"
+require_relative "../session_row"
 require_relative "../session_access"
 require_relative "../remotes"
 require_relative "../reply_wait"
@@ -137,11 +138,11 @@ module Samagotchi
         end
       end
 
-      # @raise [ArgumentError] no such session (Session::AmbiguousId: a
+      # @raise [Session::NotFound] no such session (Session::AmbiguousId: a
       #   prefix of several)
       def resolve(given)
         id = resolve_id(given)
-        raise ArgumentError, "Session not found: #{given}" if id == given.to_s && !exists?(id)
+        raise Session::NotFound, given if id == given.to_s && !exists?(id)
 
         id
       end
@@ -158,8 +159,9 @@ module Samagotchi
       # @return [OwnerLock::Owner, nil]
       def owner(id) = show(id).owner
 
-      # The rows chi sessions list prints, as SessionManager.session_summaries
-      # gives them (symbol keys).
+      # The rows chi sessions list prints: chi web's summaries
+      # (SessionRow#to_summary_h) read back as SessionRows.
+      # @return [Array<SessionRow>]
       def summaries(live: false, cwd: nil, limit: nil, include_tests: true, project_root: nil, include_archived: false,
                     sort: nil, order: nil)
         query = { live: (1 if live), cwd: cwd, limit: limit, tests: (0 unless include_tests), dir: project_root,
@@ -167,7 +169,7 @@ module Samagotchi
         reply = request(:get, "/api/sessions/summaries", query: query)
         raise_refusal(reply) unless reply.status == 200
 
-        Array(reply.json).map { |row| symbolize(row) }
+        Array(reply.json).map { |row| SessionRow.from_summary_h(symbolize(row)) }
       end
 
       # --- create and send
@@ -704,6 +706,20 @@ module Samagotchi
         reply.json["detail"].to_s.start_with?("no installed bundle resolves")
       end
 
+      # chi web's 404 not_found detail for a session it doesn't have:
+      # "no session X" (Session::NotFound), or "Session not found: X" from
+      # chi web 0.155.0 and older (compat N-1: the same line either way).
+      SESSION_NOT_FOUND = /\A(?:no session |Session not found: )(.+)\z/m
+
+      # Session::NotFound for a missing session's 404, else an
+      # ArgumentError with chi web's words (another route's 404). chi web
+      # never answers Session::NONE_YET ("no session yet") as a 404
+      # not_found; were it to, the pattern would read it as NotFound("yet").
+      def not_found_error(detail)
+        given = detail[SESSION_NOT_FOUND, 1]
+        given ? Session::NotFound.new(given) : ArgumentError.new(detail)
+      end
+
       # Raises what Local's callee raises for this refusal (chi web sends
       # the fields each class is built from; see docs/architecture.md, chi
       # web's routes for the session commands), else RemoteFailed.
@@ -714,7 +730,7 @@ module Samagotchi
         sid = json["session_id"]
         reason = json["reason"]&.to_sym
         case error
-        when "not_found" then raise ArgumentError, message.to_s
+        when "not_found" then raise not_found_error(message.to_s)
         when "ambiguous_id" then raise Session::AmbiguousId.new(message, ids: Array(json["ids"]))
         when "owned_by_tui"
           raise SessionManager::ScratchSession, sid if json["scratch"] == true

data/lib/samagotchi/session_archive_command.rb

@@ -82,7 +82,7 @@ module Samagotchi
       @stdout.puts("#{short}  refused: #{e.message}")
       false
     rescue ArgumentError => e
-      error_line("chi sessions archive: #{e.is_a?(Session::AmbiguousId) ? e.message : "no session #{given}"}")
+      error_line("chi sessions archive: #{e.message}")
       false
     rescue SystemCallError => e
       @stdout.puts("#{short}  failed: #{e.message}")
@@ -96,7 +96,7 @@ module Samagotchi
       @stdout.puts(result[:unarchived].empty? ? "#{short}  not archived" : "#{short}  unarchived")
       true
     rescue ArgumentError => e
-      error_line("chi sessions unarchive: #{e.is_a?(Session::AmbiguousId) ? e.message : "no session #{given}"}")
+      error_line("chi sessions unarchive: #{e.message}")
       false
     rescue SystemCallError => e
       @stdout.puts("#{short}  failed: #{e.message}")

data/lib/samagotchi/session_chain.rb

@@ -15,7 +15,7 @@ module Samagotchi
   # "the next run of the same routine". The chain is derived, never stored:
   # follow +continues+ back for the earlier links, forward (the session whose
   # +continues+ names this one) for the later ones. A link is continued at
-  # most once (SessionManager.continue_session refuses a second), so the
+  # most once (SessionContinue.run refuses a second), so the
   # chain's latest link is the one nobody continues.
   module SessionChain
     # `--continues last:<id>`: the latest link of the chain <id> is in.
@@ -62,15 +62,16 @@ module Samagotchi
     # A session to continue as the CLI and the web name it: an id, a unique
     # prefix, or `last:<id or prefix>` for that chain's latest link.
     # @return [String] the full id of an existing session
-    # @raise [ArgumentError] none such (Session::AmbiguousId for a prefix of several)
+    # @raise [Session::NotFound] none such (Session::AmbiguousId for a prefix of several)
     def resolve(ref, state_dir:)
       given = ref.to_s.strip
       last = given.start_with?(LAST_PREFIX)
       given = given.delete_prefix(LAST_PREFIX) if last
-      raise ArgumentError, "no session #{ref}" unless Session.valid_id?(given)
-
-      id = Session.resolve_id(given, state_dir: state_dir)
-      raise ArgumentError, "no session #{ref}" unless Session.exist?(id, state_dir: state_dir)
+      id = begin
+        Session.resolve!(given, state_dir: state_dir)
+      rescue Session::NotFound
+        raise Session::NotFound, ref # as given, last: and all
+      end
 
       last ? latest(id, state_dir: state_dir) : id
     end

data/lib/samagotchi/session_continue.rb

@@ -7,6 +7,7 @@ require_relative "session_inbox"
 require_relative "session_chain"
 require_relative "objectives"
 require_relative "child_move"
+require_relative "starting_marker"
 require_relative "context_move"
 require_relative "archive_store"
 require_relative "recap_store"
@@ -17,9 +18,9 @@ require_relative "log"
 require_relative "session_manager"
 
 module Samagotchi
-  # The next link of a session chain (chi send --new --continues, web
-  # Continue →): SessionManager.continue_session runs .run. The archive,
-  # spawn, stop and wake it builds on are SessionManager's.
+  # The next link of a session chain: chi send --new --continues and web
+  # Continue → run .run. The archive, spawn, stop and wake it builds on are
+  # SessionManager's.
   module SessionContinue
     # A continue that can't happen (#run). reason: :continued
     # (another session continues it already: +ids+ names it), :open_children
@@ -198,7 +199,7 @@ module Samagotchi
       Log.warn(:worker, "continue_wake_failed", sid: id, error: e.class.name, msg: e.message)
     end
 
-    # The new link, holding off any worker but its own (ChildMove.starting?)
+    # The new link, holding off any worker but its own (StartingMarker.fresh?)
     # while +move+ goes to it.
     private_class_method def self.spawn_continuation(previous, prompt:, preview:, choice:, state_dir:, move:)
       recap = RecapStore.read(Session.session_dir(previous.id, state_dir: state_dir))
@@ -206,7 +207,7 @@ module Samagotchi
       preview = previous.first_preview if preview.to_s.strip.empty? && start.nil?
       moved_context = nil
       before_spawn = lambda do |link|
-        ChildMove.mark_starting(link.id, state_dir: state_dir)
+        StartingMarker.mark(link.id, state_dir: state_dir)
         ChildMove.apply(move, from: previous.id, to: link.id, state_dir: state_dir)
         # Its movable context too, with a note saying what moved and stayed.
         moved_context = ContextMove.call(from: previous.id, to: link.id, mode: :continue, state_dir: state_dir)

data/lib/samagotchi/session_delete_command.rb

@@ -76,7 +76,7 @@ module Samagotchi
       @stdout.puts("#{short}  refused: #{line}")
       false
     rescue ArgumentError => e
-      error_line("chi sessions delete: #{e.is_a?(Session::AmbiguousId) ? e.message : "no session #{given}"}")
+      error_line("chi sessions delete: #{e.message}")
       false
     rescue SystemCallError => e
       @stdout.puts("#{short}  failed: #{e.message}")

data/lib/samagotchi/session_field.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # One key of a session file (a Session::FIELDS row): +key+ the file's
+  # key, +attr+ Session's attribute and keyword (nil for a key only the
+  # file has: the settings pair, written from Session's +from+), +default+
+  # the value of a file without the key (REQUIRED for one it must have),
+  # +fresh+ a new Session's when it isn't given (it differs only for
+  # metadata_version and messages), +optional+ a key written only when set,
+  # +cast+ what a value is read as (Session.new, .from_h and the writers),
+  # +write+ what the file gets from the attribute (the value as is without
+  # one). +unread+ and +keep+ are the Unread rule's (.level): what of a
+  # value the field couldn't read the session keeps, and how the file gets
+  # it back. A leaf: the types a row names are named in session.rb, in a
+  # block its lambdas call (`type.call`, not `yield`: never while the
+  # constructor runs, so Performance/RedundantBlockCall is off for them).
+  SessionField = Data.define(:key, :attr, :from, :default, :fresh, :optional, :cast, :write, :unread, :keep) do
+    # A field read as given, or through +cast+.
+    def self.plain(key, default, cast: nil, write: nil, fresh: default, optional: false)
+      new(key: key, attr: key.to_sym, from: nil, default: default, fresh: fresh, optional: optional, cast: cast,
+          write: write, unread: nil, keep: nil)
+    end
+
+    # rubocop:disable Performance/RedundantBlockCall
+    # A value object's field (nil for none): a value that is already one
+    # is taken as it is, nil is nil (the type isn't loaded for it: an
+    # autoloaded one stays unloaded), anything else is read with the type's
+    # +reader+ (from_file, of); the file gets its #to_file, through
+    # .scrub_utf8 with +scrub+. +type+ is a block, so the row names its type
+    # without loading it.
+    def self.value(key, reader, optional: false, scrub: false, &type)
+      cast = lambda do |value|
+        next nil if value.nil?
+
+        klass = type.call
+        value.is_a?(klass) ? value : klass.public_send(reader, value)
+      end
+      write = scrub ? ->(value) { value && scrub_utf8(value.to_file) } : ->(value) { value&.to_file }
+      new(key: key, attr: key.to_sym, from: nil, default: nil, fresh: nil, optional: optional, cast: cast,
+          write: write, unread: nil, keep: nil)
+    end
+
+    # A list of value objects ([] for none): read with the type's .list, each
+    # written with its #to_file.
+    def self.list(key, &type)
+      new(key: key, attr: key.to_sym, from: nil, default: [], fresh: [], optional: false,
+          cast: ->(value) { type.call.list(value) }, write: ->(values) { values.map(&:to_file) }, unread: nil,
+          keep: nil)
+    end
+
+    # A session's own level (nil for none), with the Unread rule: a value
+    # that isn't one reads as nil, and the session keeps it as written (a
+    # newer chi's level, a hand edit) and saves it back so, until it sets
+    # its own. A level is the type's .session_level of the value; a String
+    # that doesn't read as one, other than the +unset+ word (any case and
+    # spaces), is the one kept. With +merge_unread+ the field is a value
+    # object of several parts (LLMContextOverride: .from_file, .unread):
+    # the parts it couldn't read are kept, and the file gets them under the
+    # parts it has (nil when there is none).
+    def self.level(key, unset: nil, merge_unread: false, &type)
+      if merge_unread
+        cast = ->(value) { type.call.from_file(value) }
+        unread = ->(value) { type.call.unread(value) }
+        write = ->(value) { value&.to_file }
+        keep = lambda do |written, kept|
+          saved = kept.merge(written || {})
+          saved.empty? ? nil : saved
+        end
+      else
+        cast = ->(value) { type.call.session_level(value) }
+        unread = lambda do |value|
+          value if value.is_a?(String) && type.call.session_level(value).nil? && !value.strip.casecmp?(unset)
+        end
+        write = ->(value) { value&.to_s }
+        keep = ->(written, kept) { written || kept }
+      end
+      new(key: key, attr: key.to_sym, from: nil, default: nil, fresh: nil, optional: false, cast: cast, write: write,
+          unread: unread, keep: keep)
+    end
+    # rubocop:enable Performance/RedundantBlockCall
+
+    # A key only the file has: +write+ takes Session's +from+ attribute.
+    def self.file_only(key, default, from:, write:)
+      new(key: key, attr: nil, from: from, default: default, fresh: nil, optional: false, cast: nil, write: write,
+          unread: nil, keep: nil)
+    end
+
+    def required? = default.equal?(SessionField::REQUIRED)
+
+    def fresh_required? = fresh.equal?(SessionField::REQUIRED)
+
+    # A new Session's value when it isn't given: a fresh copy of a list or
+    # a Hash, never one shared with another session.
+    def fresh_value = fresh.is_a?(Array) || fresh.is_a?(Hash) ? fresh.dup : fresh
+
+    # The instance variable #to_h reads (never the reader: project_root's
+    # and verdicts' have logic of their own).
+    def ivar = :"@#{attr || from}"
+
+    # +value+ as the attribute holds it.
+    def load(value) = cast ? cast.call(value) : value
+
+    # The attribute's +value+ as the file holds it, with what the session
+    # kept of a value it couldn't read (+kept+, .level's).
+    def dump(value, kept = nil)
+      written = write ? write.call(value) : value
+      keep ? keep.call(written, kept) : written
+    end
+
+    # The last guard before JSON.generate, which raises on bytes that
+    # aren't UTF-8: a save that raised would lose the whole conversation.
+    # ToolRunner already scrubs tool output; this covers any other source.
+    def self.scrub_utf8(obj)
+      case obj
+      when String
+        str = obj.encoding == Encoding::UTF_8 ? obj : obj.dup.force_encoding(Encoding::UTF_8)
+        str.valid_encoding? ? str : str.scrub("?")
+      when Array then obj.map { |element| scrub_utf8(element) }
+      when Hash then obj.to_h { |key, value| [key, scrub_utf8(value)] }
+      else obj
+      end
+    end
+
+    # A Hash with String keys (one level).
+    def self.stringify_keys(hash)
+      hash.each_with_object({}) { |(k, v), h| h[k.to_s] = v }
+    end
+  end
+
+  # A field a session file must have (KeyError without it, ArgumentError
+  # from Session.new).
+  SessionField::REQUIRED = Object.new.freeze
+end

data/lib/samagotchi/session_inbox.rb

@@ -442,7 +442,7 @@ module Samagotchi
     private_class_method :unmark_removed
 
     # How old a per-input tombstone (input/removed/, TurnCheckpoint's
-    # input/settled/) gets before a worker's start prunes it (#prune_old).
+    # input/settled/, a merge record in input/merged/) gets before a worker's start prunes it (#prune_old).
     # A wait reads one at its next poll (ReplyWait::POLL_INTERVAL) and a
     # later `chi send --wait --turn` reads a settled one at its start, so
     # only a wait whose process slept (a closed laptop) or one started long
@@ -470,6 +470,54 @@ module Samagotchi
     # The removed tombstones past +max_age+ (#prune_old).
     def self.prune_removed(session_dir, max_age: TOMBSTONE_MAX_AGE) = prune_old(session_dir, REMOVED_DIR, max_age: max_age)
 
+    # Where a running turn's drain records an input it merged as a steer:
+    # input/merged/<enqueued_id> = {"into": the turn's enqueued_id, "at"}.
+    # Its own directory: a file in input/settled/ reads as worker_stopped to
+    # a chi before it, and no *.json glob sees a subdirectory.
+    MERGED_DIR = "merged"
+
+    # Records that the input +id+ went into the turn +into+ (both
+    # enqueued_ids) as a steer, before the drain deletes its claimed file
+    # (Worker#pending_input_drain): a wait for it (ReplyWait's turn:) then
+    # waits for that turn (Poll#follow_merge). Nothing for an id that
+    # can't name a file, nor for a turn with none; a failed write only
+    # logs (the wait infers the merge, as for a worker before this).
+    def self.mark_merged(session_dir, id, into:, now: Time.now)
+      return unless ENQUEUED_ID_NAME.match?(id.to_s) && ENQUEUED_ID_NAME.match?(into.to_s)
+
+      dir = File.join(session_dir, INPUT_DIR, MERGED_DIR)
+      FileUtils.mkdir_p(dir)
+      AtomicFile.write(File.join(dir, id), JSON.generate("into" => into, "at" => now.iso8601(3)))
+    rescue SystemCallError, IOError => e
+      Log.warn(:worker, "merge_record_write_failed", error: e.class.name, msg: e.message, enqueued_id: id)
+    end
+
+    # A merge record (#mark_merged): the enqueued_id of the turn an input
+    # went into, and when (a Time, nil when unreadable).
+    Merge = Data.define(:into, :at)
+
+    # @return [Merge, nil] the turn the input +id+ was merged into
+    #   (#mark_merged), nil without a readable record
+    def self.merged_into(session_dir, id)
+      return nil unless ENQUEUED_ID_NAME.match?(id.to_s)
+
+      raw = JSON.parse(File.read(File.join(session_dir, INPUT_DIR, MERGED_DIR, id.to_s)))
+      into = raw["into"]
+      return nil unless ENQUEUED_ID_NAME.match?(into.to_s)
+
+      at = begin
+        Time.iso8601(raw["at"].to_s)
+      rescue ArgumentError
+        nil
+      end
+      Merge.new(into: into, at: at)
+    rescue JSON::ParserError, SystemCallError, TypeError, NoMethodError
+      nil
+    end
+
+    # The merge records past +max_age+ (#prune_old).
+    def self.prune_merged(session_dir, max_age: TOMBSTONE_MAX_AGE) = prune_old(session_dir, MERGED_DIR, max_age: max_age)
+
     # @return [Boolean] whether the queued input +enqueued_id+ was removed
     #   before it ran (#take_queued_input's tombstone), or is being removed:
     #   the tombstone goes first, so while its claimed file is still there