samagotchi 0.9.0 → 0.10.0

data/lib/samagotchi/session.rb

@@ -20,10 +20,16 @@ module Samagotchi
 
     STATUS_IDLE = "idle"
     STATUS_RUNNING = "running"
-    STATUS_COMPLETED = "completed"
     STATUS_ERROR = "error"
     STATUS_STOPPED = "stopped"
 
+    # A stopped session's marker, <session dir>/stopped: a stop (chi
+    # sessions stop, from another process) creates it instead of rewriting
+    # the session file a worker may be saving at the same moment, and a
+    # resume removes it. A file from before the marker says "stopped" in
+    # its status field, which reads the same.
+    STOPPED_FILE = "stopped"
+
     SORT_KEYS = %w[created_at updated_at].freeze
     SORT_ORDERS = %w[asc desc].freeze
 
@@ -147,37 +153,57 @@ module Samagotchi
       path = session_path(session_id, state_dir: state_dir)
       raise ArgumentError, "Session not found: #{session_id}" unless File.exist?(path)
 
-      data = JSON.parse(File.read(path))
-      messages = (data["messages"] || []).map { |msg| symbolize_message_keys(msg) }
-      pending = data["pending_question"]
-      pending = symbolize_message_keys(pending) if pending.is_a?(Hash)
-      used_mems = data["used_memory_names"] || data["used_memories"] || []
-      new(
-        id: data.fetch("id"),
-        metadata_version: data.fetch("metadata_version", 1),
-        mode: data.fetch("mode"),
-        model_name: data.fetch("model_name"),
-        working_directory: data.fetch("working_directory"),
-        messages: messages,
-        created_at: data.fetch("created_at"),
-        updated_at: data.fetch("updated_at"),
-        status: data.fetch("status", STATUS_IDLE),
-        last_prompt: data.fetch("last_prompt", ""),
-        first_preview: data.fetch("first_preview", ""),
-        test_run: data.fetch("test_run", false),
-        pending_question: pending,
-        used_memory_names: Array(used_mems),
-        project_root: data["project_root"],
-        preloaded_memory_names: Array(data["preloaded_memory_names"]),
-        muted_memory_names: Array(data["muted_memory_names"]),
-        parent_id: data["parent_id"],
-        scratch: data.fetch("scratch", false),
-        last_turn: data["last_turn"]
-      )
+      session = from_h(JSON.parse(File.read(path)))
+      session.status = STATUS_STOPPED if stopped_marker?(session.id, state_dir: state_dir)
+      session
     rescue JSON::ParserError => e
       raise ArgumentError, "Session file corrupted (#{session_id}): #{e.message}"
     end
 
+    # A field a session file must have (KeyError without it).
+    REQUIRED = Object.new.freeze
+
+    # The fields of <id>.json, in the order #save writes them: key => the
+    # value for a file without it (REQUIRED for the ones it must have).
+    # .from_h and #to_h both go by this table; messages and
+    # pending_question change key type on the way (symbols in memory,
+    # strings on disk).
+    FIELDS = {
+      "metadata_version" => 1,
+      "id" => REQUIRED,
+      "mode" => REQUIRED,
+      "model_name" => REQUIRED,
+      "working_directory" => REQUIRED,
+      "messages" => [],
+      "created_at" => REQUIRED,
+      "updated_at" => REQUIRED,
+      "status" => STATUS_IDLE,
+      "last_prompt" => "",
+      "first_preview" => "",
+      "test_run" => false,
+      "pending_question" => nil,
+      "used_memory_names" => [],
+      "project_root" => nil,
+      "preloaded_memory_names" => [],
+      "muted_memory_names" => [],
+      "parent_id" => nil,
+      "scratch" => false,
+      "last_turn" => nil
+    }.freeze
+
+    # A session from a parsed session file. +messages+ false leaves the
+    # conversation out (the lists' lightweight summaries).
+    # @raise [KeyError] for a missing REQUIRED field
+    def self.from_h(data, messages: true)
+      attrs = FIELDS.to_h do |key, default|
+        [key.to_sym, default.equal?(REQUIRED) ? data.fetch(key) : data.fetch(key, default)]
+      end
+      attrs[:messages] = messages ? Array(attrs[:messages]).map { |msg| symbolize_message_keys(msg) } : []
+      pending = attrs[:pending_question]
+      attrs[:pending_question] = pending.is_a?(Hash) ? symbolize_message_keys(pending) : nil
+      new(**attrs)
+    end
+
     # A prefix that names more than one session.
     class AmbiguousId < ArgumentError; end
 
@@ -250,30 +276,9 @@ module Samagotchi
       # An id that isn't one (hand-edited, or not ours) would be a path.
       return nil unless valid_id?(data["id"])
 
-      used_mems = data["used_memory_names"] || data["used_memories"] || []
-      pending = data["pending_question"]
-      new(
-        id: data.fetch("id"),
-        metadata_version: data.fetch("metadata_version", 1),
-        mode: data.fetch("mode"),
-        model_name: data.fetch("model_name"),
-        working_directory: data.fetch("working_directory"),
-        messages: [],
-        created_at: data.fetch("created_at"),
-        updated_at: data.fetch("updated_at"),
-        status: data.fetch("status", STATUS_IDLE),
-        last_prompt: data.fetch("last_prompt", ""),
-        first_preview: data.fetch("first_preview", ""),
-        test_run: data.fetch("test_run", false),
-        pending_question: pending.is_a?(Hash) ? symbolize_message_keys(pending) : nil,
-        used_memory_names: Array(used_mems),
-        project_root: data["project_root"],
-        preloaded_memory_names: Array(data["preloaded_memory_names"]),
-        muted_memory_names: Array(data["muted_memory_names"]),
-        parent_id: data["parent_id"],
-        scratch: data.fetch("scratch", false),
-        last_turn: data["last_turn"]
-      )
+      session = from_h(data, messages: false)
+      session.status = STATUS_STOPPED if stopped_marker?(session.id, state_dir: File.dirname(path))
+      session
     rescue JSON::ParserError, KeyError, SystemCallError
       nil
     end
@@ -290,45 +295,23 @@ module Samagotchi
       # Auto-compute first_preview if not yet cached and messages contain a user entry.
       compute_first_preview!
 
-      record = {
-        "metadata_version" => @metadata_version,
-        "id" => @id,
-        "mode" => @mode,
-        "model_name" => @model_name,
-        "working_directory" => @working_directory,
-        "messages" => @messages.map { |msg| scrub_utf8(stringify_message_keys(msg)) },
-        "created_at" => @created_at,
-        "updated_at" => @updated_at,
-        "status" => @status,
-        "last_prompt" => @last_prompt,
-        "first_preview" => @first_preview,
-        "test_run" => !!@test_run,
-        "pending_question" => @pending_question ? scrub_utf8(stringify_message_keys(@pending_question)) : nil,
-        "used_memory_names" => Array(@used_memory_names),
-        "project_root" => @project_root,
-        "preloaded_memory_names" => Array(@preloaded_memory_names),
-        "muted_memory_names" => Array(@muted_memory_names),
-        "parent_id" => @parent_id,
-        "scratch" => @scratch,
-        "last_turn" => @last_turn
-      }
-
-      AtomicFile.write(path, JSON.pretty_generate(record) + "\n")
+      AtomicFile.write(path, JSON.pretty_generate(to_h) + "\n")
       self
     end
 
-    # Mark a session as running.
-    def self.mark_running(session_id, state_dir: default_state_dir)
-      session = load(session_id, state_dir: state_dir)
-      session.status = STATUS_RUNNING
-      session.save(state_dir: state_dir)
-    end
-
-    # Mark a session as completed.
-    def self.mark_completed(session_id, state_dir: default_state_dir)
-      session = load(session_id, state_dir: state_dir)
-      session.status = STATUS_COMPLETED
-      session.save(state_dir: state_dir)
+    # The session as #save writes it (FIELDS, in their order).
+    def to_h
+      FIELDS.keys.to_h do |key|
+        value = case key
+                when "messages" then @messages.map { |msg| scrub_utf8(stringify_message_keys(msg)) }
+                when "pending_question" then @pending_question && scrub_utf8(stringify_message_keys(@pending_question))
+                when "test_run" then !!@test_run
+                when "used_memory_names", "preloaded_memory_names", "muted_memory_names"
+                  Array(instance_variable_get(:"@#{key}"))
+                else instance_variable_get(:"@#{key}")
+                end
+        [key, value]
+      end
     end
 
     # Mark a session as errored.
@@ -339,11 +322,24 @@ module Samagotchi
       session.save(state_dir: state_dir)
     end
 
-    # Mark a session as stopped.
+    # Mark a session as stopped (STOPPED_FILE); its session file stays as
+    # it is.
+    # @raise [ArgumentError] when there is no such session
     def self.mark_stopped(session_id, state_dir: default_state_dir)
-      session = load(session_id, state_dir: state_dir)
-      session.status = STATUS_STOPPED
-      session.save(state_dir: state_dir)
+      raise ArgumentError, "Session not found: #{session_id}" unless exist?(session_id, state_dir: state_dir)
+
+      dir = session_dir(session_id, state_dir: state_dir)
+      FileUtils.mkdir_p(dir)
+      FileUtils.touch(File.join(dir, STOPPED_FILE))
+    end
+
+    # Remove the stop marker (a resume, before its worker starts).
+    def self.clear_stopped(session_id, state_dir: default_state_dir)
+      FileUtils.rm_f(File.join(session_dir(session_id, state_dir: state_dir), STOPPED_FILE))
+    end
+
+    def self.stopped_marker?(session_id, state_dir: default_state_dir)
+      File.exist?(File.join(session_dir(session_id, state_dir: state_dir), STOPPED_FILE))
     end
 
     # An id that is not a session id: it could name a path outside the

data/lib/samagotchi/session_archive_command.rb

@@ -2,6 +2,7 @@
 
 require_relative "session"
 require_relative "session_manager"
+require_relative "cli/command"
 
 module Samagotchi
   # `chi sessions archive|unarchive`: hide sessions from every list and keep
@@ -9,6 +10,8 @@ module Samagotchi
   # unarchive_session), one line per id. Delegated children follow their
   # parent.
   class SessionArchiveCommand
+    include CLI::Command
+
     USAGE = {
       "archive" => <<~TEXT,
         Usage: chi sessions archive (ID|PREFIX)...
@@ -36,8 +39,9 @@ module Samagotchi
 
     # @return [Integer] exit status: 0 all done, 1 any refused or unknown, 2 usage
     def run
-      if @argv.any? { |arg| %w[-h --help help].include?(arg) }
-        @stdout.puts(USAGE.fetch(@action))
+      # Help anywhere wins, even after an unknown option.
+      if @argv.any? { |arg| HELP_WORDS.include?(arg) }
+        @stdout.puts(usage_text)
         return 0
       end
       bad = @argv.find { |arg| arg.start_with?("-") }
@@ -91,17 +95,7 @@ module Samagotchi
       false
     end
 
-    # stdout is buffered when it's a pipe: flush the lines already printed,
-    # so the output keeps the order of the ids given.
-    def error_line(text)
-      @stdout.flush
-      @stderr.puts(text)
-    end
-
-    def usage_error(message)
-      error_line("chi sessions #{@action}: #{message}")
-      @stderr.puts(USAGE.fetch(@action))
-      2
-    end
+    def command_name = "chi sessions #{@action}"
+    def usage_text = USAGE.fetch(@action)
   end
 end

data/lib/samagotchi/session_commands.rb

@@ -30,7 +30,6 @@ module Samagotchi
     ROLLBACK_COMMAND = "!rollback"
     CONTINUE_COMMAND = TurnFlow::CONTINUE_COMMAND
     SHELL_BANG_PREFIX = "!"
-    RESERVED_MODEL_ARGS = %w[clear default none off].freeze
     ALIAS_USAGE = "usage /model <model> --alias <name> [--default]"
     # /exit --delete: delete the session on the way out.
     EXIT_DELETE_FLAG = "--delete"
@@ -355,10 +354,10 @@ module Samagotchi
 
       if alias_name
         return ["--alias requires a model name: #{ALIAS_USAGE}", false] if arg.empty?
-        return ["--alias cannot be combined with clear/default/none/off", false] if RESERVED_MODEL_ARGS.include?(arg.downcase)
+        return ["--alias cannot be combined with clear/default/none/off", false] if ConfigFile::RESERVED_MODEL_ALIASES.include?(arg.downcase)
 
         # Validate the alias before switching, so a bad one changes nothing.
-        invalid = alias_name_error(alias_name, arg)
+        invalid = ConfigFile.model_alias_error(alias_name, arg)
         return ["invalid alias: #{invalid}", false] if invalid
 
         switch_model(arg, persist_default: persist_default)
@@ -378,7 +377,7 @@ module Samagotchi
       else
         return ["--default requires a model name: usage /model --default <name> or /model <name> [--default]", false] if arg.empty?
 
-        if RESERVED_MODEL_ARGS.include?(arg.downcase)
+        if ConfigFile::RESERVED_MODEL_ALIASES.include?(arg.downcase)
           return ["--default cannot be combined with clear/default/none/off", false] if persist_default
 
           switch_model(@default_model)
@@ -394,23 +393,6 @@ module Samagotchi
       end
     end
 
-    # Mirrors ConfigFile.write_model_alias!'s checks without writing.
-    # @return [String, nil] what is wrong with the alias name
-    def alias_name_error(alias_name, target)
-      ak = alias_name.strip
-      return "alias name is required" if ak.empty?
-
-      lk = ak.downcase
-      return "alias name '#{ak}' is reserved" if RESERVED_MODEL_ARGS.include?(lk)
-      return "alias name must not contain whitespace" if ak.match?(/\s/)
-      return "alias name must not start with '-'" if ak.start_with?("-")
-      return "alias name must not contain '/'" if ak.include?("/")
-      return "alias name must match /[a-z0-9][a-z0-9._-]*/i (got '#{ak}')" unless ak.match?(/\A[a-z0-9][a-z0-9._-]*\z/i)
-      return "alias must not point to itself" if lk == target.strip.downcase
-
-      nil
-    end
-
     # Engine owns the switch (alias resolution, profile, kernel, client and
     # the optional default persist); the session keeps the new model.
     def switch_model(name, persist_default: false)

data/lib/samagotchi/session_delete_command.rb

@@ -2,12 +2,16 @@
 
 require_relative "session"
 require_relative "session_manager"
+require_relative "cli/command"
+require_relative "cli/flags"
 
 module Samagotchi
   # `chi sessions delete`: remove sessions for good (SessionManager.delete_session),
   # one line per id. A live worker's session is refused unless --force stops
   # the worker first; a chi REPL's never is.
   class SessionDeleteCommand
+    include CLI::Command
+
     USAGE = <<~TEXT
       Usage: chi sessions delete [--force] (ID|PREFIX)...
         Deletes each session: its history, notes, images and queued input.
@@ -17,6 +21,7 @@ module Samagotchi
                       chi REPL is always refused
     TEXT
     PREVIEW_LIMIT = 60
+    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)
@@ -29,30 +34,24 @@ module Samagotchi
     # @return [Integer] exit status: 0 all deleted, 1 any refused or
     #   unknown, 2 usage
     def run
-      options = parse or return 2
-      return 0 if options[:help]
+      options = parse
+      return options if options.is_a?(Integer)
 
       options[:ids].uniq.map { |given| delete(given, force: options[:force]) }.all? ? 0 : 1
     end
 
     private
 
+    def command_name = "chi sessions delete"
+
+    # @return [Hash, Integer] the options, or the exit status after the
+    #   help or a usage error
     def parse
-      options = { ids: [], force: false }
-      until @argv.empty?
-        arg = @argv.shift
-        case arg
-        when "-h", "--help", "help"
-          @stdout.puts(USAGE)
-          return { help: true }
-        when "-f", "--force" then options[:force] = true
-        when /\A-/ then return usage_error("unknown option #{arg}")
-        else options[:ids] << arg
-        end
-      end
-      return usage_error("give session ids") if options[:ids].empty?
+      parsed = parse_flags(FLAGS, @argv, force: false)
+      return parsed if parsed.is_a?(Integer)
+      return usage_error("give session ids") if parsed.args.empty?
 
-      options
+      parsed.options.merge(ids: parsed.args)
     end
 
     # @return [Boolean] whether the session is gone
@@ -88,18 +87,5 @@ module Samagotchi
     rescue ArgumentError, JSON::ParserError
       nil
     end
-
-    # stderr isn't buffered, stdout is when it's a pipe: flush the lines
-    # already printed, so the output keeps the order of the ids given.
-    def error_line(text)
-      @stdout.flush
-      @stderr.puts(text)
-    end
-
-    def usage_error(message)
-      error_line("chi sessions delete: #{message}")
-      @stderr.puts(USAGE)
-      nil
-    end
   end
 end

data/lib/samagotchi/session_manager.rb

@@ -233,7 +233,7 @@ module Samagotchi
                          .reject { |s| (!include_tests && s.test_run) || s.id == exclude }
                          .select { |s| root.nil? || in_folder?(s.working_directory, root) }
                          .filter_map do |s|
-        owner = session_owner(s.id, state_dir: sd)&.fetch("kind", nil)
+        owner = session_owner(s.id, state_dir: sd)&.kind
         owned = owner == "worker"
         next if live && !owned
 
@@ -277,7 +277,7 @@ module Samagotchi
         owner = owners[sid]
         next unless owner
 
-        raise OwnedByTUI, sid if owner["kind"] == "tui"
+        raise OwnedByTUI, sid if owner.tui?
         next unless Session.load(sid, state_dir: sd).status == Session::STATUS_RUNNING
 
         raise ArchiveRefused.new(id, sid == id ? :busy : :busy_child, busy_id: sid)
@@ -374,12 +374,12 @@ module Samagotchi
     def self.resume_session(session_id, state_dir: nil)
       sd = state_dir || Session.default_state_dir
       session = Session.load(session_id, state_dir: sd)
-      owner = session_owner(session.id, state_dir: sd)
-      raise OwnedByTUI, session.id if owner && owner["kind"] == "tui"
-      return session if owner
+      return session if refuse_tui!(session.id, state_dir: sd)
 
       # status is turn state, not liveness: a new worker runs no turn yet,
-      # and must not find the session stopped (it would exit).
+      # and must not find the session stopped (it would exit): neither the
+      # marker nor a status field from before it.
+      Session.clear_stopped(session.id, state_dir: sd)
       session.status = Session::STATUS_IDLE
       session.save(state_dir: sd)
       spawn_worker_for_session(session, state_dir: sd)
@@ -404,13 +404,12 @@ module Samagotchi
     # @raise [OwnedByTUI] when the interactive TUI owns the session
     def self.stop_session(session_id, state_dir: nil, wait: nil)
       sd = state_dir || Session.default_state_dir
-      owner = session_owner(session_id, state_dir: sd)
-      raise OwnedByTUI, session_id if owner && owner["kind"] == "tui"
+      owner = refuse_tui!(session_id, state_dir: sd)
 
       cancel_running_turn(session_id, state_dir: sd)
       # Mark first: a worker that has not taken the lock yet sees it and exits.
       Session.mark_stopped(session_id, state_dir: sd)
-      pid = owner && owner["pid"].to_i
+      pid = owner&.pid.to_i
       begin
         Process.kill("TERM", pid) if pid && pid > 0
       rescue Errno::ESRCH
@@ -545,9 +544,8 @@ module Samagotchi
       dir = Session.session_dir(id, state_dir: sd)
       raise ArgumentError, "no session #{given}" unless File.exist?(path) || Dir.exist?(dir)
 
-      owner = session_owner(id, state_dir: sd)
+      owner = refuse_tui!(id, state_dir: sd)
       if owner
-        raise OwnedByTUI, id if owner["kind"] == "tui"
         raise DeleteRefused.new(id, :worker_running) unless stop
         raise DeleteRefused.new(id, :still_stopping) unless stop_session(id, state_dir: sd, wait: wait)
       end
@@ -594,6 +592,7 @@ module Samagotchi
     # @param idle_exit_minutes [Numeric, nil] nil: session.idle_exit_minutes
     # @param poll_interval [Numeric, nil] seconds between the loop's fallback
     #   ticks (nil: Worker::FALLBACK_TICK_SECONDS); queued turns wake it at once
+    # A stopped session's worker exits 0 and a crashed one 1, there.
     # @return [Symbol] :idle_exit or :exit_requested
     def self.run_session_loop(session_id, state_dir: nil, owner_wait: OwnerLock::DEFAULT_WAIT,
                               idle_exit_minutes: nil, poll_interval: nil)
@@ -619,6 +618,10 @@ module Samagotchi
         @owner_lock.release
       end
       Log.info(:worker, "stop", reason: result)
+      # A stopped session is left as it is: no resume for input that came
+      # in, no discard.
+      exit(0) if result == :stopped
+      exit(1) if result == :crashed
       # Only after the release: a writer that still saw this worker as the
       # owner may have queued input since the last check. Either it finds no
       # owner after its write and wakes one, or this finds its input.
@@ -776,7 +779,7 @@ module Samagotchi
       owner = delivery_owner(manager, session_id, state_dir)
       # A TUI that took the session between the resume and the write never
       # reads input files; a later worker would replay this one.
-      if owner&.fetch("kind", nil) == "tui"
+      if owner&.tui?
         FileUtils.rm_f(path) if path.is_a?(String)
         raise OwnedByTUI, session_id
       end
@@ -810,10 +813,21 @@ module Samagotchi
     # The session's live owner: the OwnerLock holder. The pid file workers
     # once wrote is never read: a stale one whose pid the OS reused would
     # make a session look owned.
-    # @return [Hash, nil] {"pid", "kind" ("worker"/"tui"), ...} or nil
+    # @return [OwnerLock::Owner, nil]
     def self.session_owner(session_id, state_dir: nil)
       OwnerLock.owner(Session.session_dir(session_id, state_dir: state_dir || Session.default_state_dir))
     end
+
+    # The session's owner (#session_owner), unless it is the interactive
+    # TUI, which nothing else may resume, stop or delete.
+    # @return [OwnerLock::Owner, nil]
+    # @raise [OwnedByTUI]
+    def self.refuse_tui!(session_id, state_dir: nil)
+      owner = session_owner(session_id, state_dir: state_dir)
+      raise OwnedByTUI, session_id if owner&.tui?
+
+      owner
+    end
   end
 end