samagotchi 0.6.0 → 0.8.0

data/lib/samagotchi/session_retention.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "time"
+require_relative "session"
+require_relative "archive_store"
+require_relative "config"
+require_relative "log"
+require_relative "model_profile"
+require_relative "session_manager"
+
+module Samagotchi
+  # Which sessions go: `chi sessions prune` / `clean` (.prune) and the lazy
+  # sweep chi web runs at most once a day (.sweep_if_due). Age
+  # (session.retention_days), count (session.max_count, counting only the
+  # sessions that stay), statuses kept (session.keep_status), sessions left
+  # empty (SessionManager.discardable?, an hour on), leftover scratch
+  # sessions and skeleton-only directories; a session with a live owner
+  # always stays.
+  module SessionRetention
+    # The session.retention_days / max_count / keep_status defaults.
+    DEFAULT_RETENTION_DAYS = 14
+    DEFAULT_MAX_COUNT = 500
+    # status is turn state; a live owner (the prune alive_check) is what
+    # protects a session in use, so no status is kept by default: a
+    # "running" left by a crashed worker must not keep it forever.
+    DEFAULT_KEEP_STATUS = [].freeze
+
+    # How long a session may sit empty before the sweep takes it: its
+    # worker (or a REPL) deletes it as it leaves, so the sweep only catches
+    # those killed first (a reboot, kill -9).
+    EMPTY_GRACE_SECONDS = 3600
+
+    # The settings (or the caller's flags) applied, with live owners kept and
+    # sessions left empty an hour taken (unless session.keep_empty).
+    # @return [Hash] { deleted: [ids], kept: [ids], skipped: [ids] }
+    def self.prune(state_dir: nil, days: nil, max_count: nil, keep_status: nil, dry_run: false, test_only: false,
+                   any_age: false)
+      sd = state_dir || Session.default_state_dir
+      days = resolve_days(days)
+      max_count = resolve_max_count(max_count)
+      keep_status = resolve_keep_status(keep_status)
+      discard = SessionManager.discard_empty?
+      default_model = discard ? (begin ModelProfile.required_model_name(nil) rescue nil end) : nil
+      result = apply(
+        state_dir: sd,
+        days: days,
+        max_count: max_count,
+        keep_status: keep_status,
+        dry_run: dry_run,
+        test_only: test_only,
+        any_age: any_age,
+        alive_check: ->(sid) { !SessionManager.session_owner(sid, state_dir: sd).nil? },
+        empty_check: discard ? ->(sid) { left_empty?(sid, state_dir: sd, default_model: default_model) } : nil
+      )
+      result[:deleted].concat(prune_orphan_dirs(sd, dry_run: dry_run)) if discard && !test_only
+      result
+    end
+
+    private_class_method def self.left_empty?(session_id, state_dir:, default_model:)
+      path = Session.session_file(session_id, state_dir: state_dir)
+      Time.now - File.mtime(path) > EMPTY_GRACE_SECONDS &&
+        SessionManager.discardable?(session_id, state_dir: state_dir, default_model: default_model)
+    rescue SystemCallError
+      false
+    end
+
+    # Directories with no session file and nothing but the skeleton, nobody
+    # owning them: a REPL killed before its first save, or a worker woken
+    # just as its session was discarded.
+    # @return [Array<String>] their ids
+    private_class_method def self.prune_orphan_dirs(state_dir, dry_run:)
+      return [] unless Dir.exist?(state_dir)
+
+      Dir.children(state_dir).filter_map do |name|
+        dir = File.join(state_dir, name)
+        next unless Session.valid_id?(name) && File.directory?(dir)
+        next if File.exist?(File.join(state_dir, "#{name}#{Session::FILE_EXT}"))
+        next unless Time.now - File.mtime(dir) > EMPTY_GRACE_SECONDS && SessionManager.empty_session_dir?(dir)
+        next if SessionManager.session_owner(name, state_dir: state_dir)
+
+        FileUtils.rm_rf(dir) unless dry_run
+        name
+      rescue SystemCallError
+        nil
+      end
+    end
+
+    # Lazy sweep guard: runs prune at most once per SWEEP_INTERVAL_HOURS
+    # (session.sweep_interval_hours).
+    MARKER = ".last_retention"
+    SWEEP_INTERVAL_HOURS = 24
+
+    def self.sweep_if_due(state_dir: nil)
+      sd = state_dir || Session.default_state_dir
+      return unless Dir.exist?(sd)
+
+      hours = Samagotchi::Config.get("session.sweep_interval_hours").to_i
+      interval = (hours.positive? ? hours : SWEEP_INTERVAL_HOURS) * 3600
+      marker = File.join(sd, MARKER)
+      if File.exist?(marker)
+        age = Time.now - File.mtime(marker)
+        return if age < interval
+      end
+      result = prune(state_dir: sd)
+      FileUtils.touch(marker)
+      if result[:deleted].any?
+        Log.info(:worker, "retention_pruned", echo: "[retention] pruned #{result[:deleted].size} sessions (kept #{result[:kept].size})", deleted: result[:deleted].size, kept: result[:kept].size)
+      end
+      result
+    rescue StandardError => e
+      Log.warn(:worker, "retention_failed", echo: "[retention] sweep failed: #{e.class}: #{e.message}", error: e.class.name)
+      nil
+    end
+
+    # The caller's value (a sessions prune flag) or session.retention_days.
+    private_class_method def self.resolve_days(val)
+      return val.to_i if !val.nil? && val.to_s.strip != ""
+
+      Samagotchi::Config.get("session.retention_days").to_i
+    end
+
+    private_class_method def self.resolve_max_count(val)
+      return val.to_i if !val.nil? && val.to_s.strip != ""
+
+      Samagotchi::Config.get("session.max_count").to_i
+    end
+
+    # A comma list of statuses never pruned; "" keeps none.
+    private_class_method def self.resolve_keep_status(val)
+      raw = !val.nil? && val.to_s.strip != "" ? val.to_s : Samagotchi::Config.get("session.keep_status").to_s
+      raw.split(",").map(&:strip).reject(&:empty?)
+    end
+
+    # Apply the retention policy to the sessions on disk.
+    #
+    # Only deletes when the json file exists — orphan dirs without json are never removed.
+    # Honors keep_status and live-worker guard.
+    # A session is kept only if it is NOT expired by age AND within max_count;
+    # either expiry or overflow triggers deletion (unless protected).
+    #
+    # +empty_check+ (id → Boolean) marks a session left empty: it goes
+    # whatever its age and the count (.prune).
+    #
+    # +any_age+ makes every session eligible, whatever its age and the
+    # count (`chi sessions clean` with no --days: test runs are throwaway).
+    #
+    # A scratch session nobody owns (its REPL was killed) goes whatever its
+    # age, its status and the count; +test_only+ takes it too.
+    #
+    # +max_count+ counts the sessions that stay: one deleted whatever its
+    # place (scratch, left empty, expired, +any_age+) takes no slot.
+    #
+    # Archived sessions are not in Session.list, so they are neither deleted nor
+    # counted. One unarchived is aged from when it was unarchived, if later.
+    #
+    # @return [Hash] { deleted: [ids], kept: [ids], skipped: [ids] }
+    def self.apply(state_dir: Session.default_state_dir, days: DEFAULT_RETENTION_DAYS, max_count: DEFAULT_MAX_COUNT,
+                   keep_status: DEFAULT_KEEP_STATUS, dry_run: false, test_only: false, alive_check: nil,
+                   empty_check: nil, any_age: false)
+      keep_status = Array(keep_status).map(&:to_s)
+      # Fetch all sessions sorted newest-first for count logic
+      all = Session.list(state_dir: state_dir, sort: "updated_at", order: "desc")
+      # Filter test_only if requested
+      if test_only
+        all = all.select { |session| session.test_run || session.scratch }
+      end
+
+      now = Time.now
+      cutoff = days.to_i.positive? ? now - days.to_i * 86_400 : nil
+      max = max_count.to_i
+
+      deleted = []
+      kept = []
+      skipped = []
+      passed_over = 0
+
+      all.each_with_index do |session, idx|
+        path = File.join(state_dir, "#{session.id}#{Session::FILE_EXT}")
+        # Only when json present
+        unless File.exist?(path)
+          skipped << session.id
+          next
+        end
+
+        # Protected by keep_status
+        if keep_status.include?(session.status.to_s) && !session.scratch
+          kept << session.id
+          next
+        end
+
+        # Protected by live worker
+        if alive_check
+          begin
+            if alive_check.call(session.id)
+              kept << session.id
+              next
+            end
+          rescue StandardError
+            nil
+          end
+        end
+
+        left_empty = begin
+          empty_check&.call(session.id)
+        rescue StandardError
+          false
+        end
+
+        # Determine expiry and overflow
+        expired = false
+        if cutoff
+          begin
+            updated = Time.iso8601(session.updated_at.to_s)
+          rescue ArgumentError
+            updated = File.mtime(path) rescue now
+          end
+          unarchived = ArchiveStore.unarchived_at(Session.session_dir(session.id, state_dir: state_dir))
+          updated = unarchived if unarchived && unarchived > updated
+          expired = updated < cutoff
+        end
+
+        # A session deleted whatever its place (scratch, left empty,
+        # expired, any_age) takes no max_count slot: the count is of the
+        # sessions ahead that stay.
+        overflow = max.positive? && idx - passed_over >= max
+        passed_over += 1 if expired || left_empty || any_age || session.scratch
+
+        # retain forever when both disabled
+        if max.zero? && cutoff.nil? && !left_empty && !any_age && !session.scratch
+          kept << session.id
+          next
+        end
+
+        # If neither expired nor overflow, keep
+        unless expired || overflow || left_empty || any_age || session.scratch
+          kept << session.id
+          next
+        end
+
+        # Eligible for deletion
+        if dry_run
+          deleted << session.id
+        else
+          begin
+            FileUtils.rm_f(path)
+            sidecar = File.join(state_dir, session.id)
+            FileUtils.rm_rf(sidecar) if File.exist?(sidecar)
+            deleted << session.id
+          rescue StandardError
+            skipped << session.id
+          end
+        end
+      end
+
+      { deleted: deleted, kept: kept, skipped: skipped }
+    end
+  end
+end

data/lib/samagotchi/sessions_command.rb

@@ -3,6 +3,7 @@
 require "json"
 require_relative "session"
 require_relative "session_manager"
+require_relative "session_retention"
 require_relative "project_scope"
 require_relative "session_metrics"
 require_relative "recap_store"
@@ -239,8 +240,8 @@ module Samagotchi
       # unless --days asks for the older ones only. Live workers and
       # keep_status still protect a session.
       any_age = sub == "clean" && test_only && days.nil?
-      result = Samagotchi::SessionManager.prune_sessions(days: days, max_count: keep, keep_status: keep_status, dry_run: dry_run,
-                                                         test_only: test_only, any_age: any_age)
+      result = Samagotchi::SessionRetention.prune(days: days, max_count: keep, keep_status: keep_status, dry_run: dry_run,
+                                                  test_only: test_only, any_age: any_age)
       mode = dry_run ? "Would delete" : "Deleted"
       @stdout.puts "#{mode} #{result[:deleted].size} sessions (kept #{result[:kept].size}, skipped #{result[:skipped].size})"
       if result[:deleted].any?

data/lib/samagotchi/terminal_ui/attached_loop.rb

@@ -523,8 +523,7 @@ module Samagotchi
         # Read after its deadline and dropped (BridgeClient::DEADLINE_SHARE).
         return @screen.commit("could not send the prompt (#{LATE})") if detail == "deadline_passed"
 
-        explained = reply.json&.fetch("detail", nil) if detail == "images_unsupported"
-        @screen.commit("could not send the prompt (#{[reply.status, detail].compact.join(" ")})#{": #{explained}" if explained}")
+        @screen.commit("could not send the prompt (#{[reply.status, detail].compact.join(" ")})")
       rescue SystemCallError, IOError => e
         own_prompt_failed
         @screen.commit("could not send the prompt (#{worker_down(e)})")

data/lib/samagotchi/terminal_ui/input_support.rb

@@ -6,6 +6,7 @@ require "reline"
 
 require_relative "../config"
 require_relative "../memory_paths"
+require_relative "../paths"
 require_relative "../tools/memory"
 require_relative "../session_commands"
 
@@ -20,7 +21,6 @@ module Samagotchi
     # Included for private use; it keeps state in @next_input_prefill and
     # reads @no_default_input.
     module InputSupport
-      XDG_STATE_HOME_ENV = "XDG_STATE_HOME"
       PROMPT_HISTORY_FILE = "history.json"
       PROMPT_HISTORY_STATE_DIR = "samagotchi"
       PROMPT_HISTORY_LIMIT = 20
@@ -207,14 +207,7 @@ module Samagotchi
         explicit = Samagotchi::Config.get("history.file").to_s.strip
         return explicit unless explicit.empty?
 
-        File.join(xdg_state_home, PROMPT_HISTORY_STATE_DIR, PROMPT_HISTORY_FILE)
-      end
-
-      def xdg_state_home
-        configured = ENV[XDG_STATE_HOME_ENV].to_s.strip
-        return configured unless configured.empty?
-
-        File.join(Dir.home, ".local", "state")
+        File.join(Paths.state_home, PROMPT_HISTORY_STATE_DIR, PROMPT_HISTORY_FILE)
       end
 
       def load_persistent_history

data/lib/samagotchi/terminal_ui.rb

@@ -37,9 +37,11 @@ module Samagotchi
   # process loads the whole UI stack through it), a require cycle otherwise.
   autoload :SessionManager, File.expand_path("session_manager", __dir__)
 
-  # TerminalUI encapsulates the single operating mode of the harness.
-  #
-  # assist mode  — interactive REPL: user types, model responds, tools execute inline.
+  # The in-process terminal front end (`chi --no-shared`, `chi scratch`,
+  # --verbose, --non-interactive): it owns one session and its Engine, runs
+  # an optional -p prompt (--non-interactive: that one turn and out), then the REPL,
+  # where the user types, the model answers and tools run inline. The
+  # attached terminal (a worker's session) is TerminalUI::AttachedLoop.
   class TerminalUI
     include Formatting
     include InputSupport
@@ -68,9 +70,8 @@ module Samagotchi
 
     # @param scratch [Boolean] `chi scratch`: a new session that is deleted
     #   however the REPL ends, saves no memories and writes no recap
-    def initialize(mode: :assist, prompt: nil, client: nil, host_registry: nil, profile: nil, session_id: nil, no_interrupt: false, no_default_input: false, model_name: nil, memories: [], muted_memories: [], non_interactive: false, surface: nil,
+    def initialize(prompt: nil, client: nil, host_registry: nil, profile: nil, session_id: nil, no_interrupt: false, no_default_input: false, model_name: nil, memories: [], muted_memories: [], non_interactive: false, surface: nil,
                    spinner_tick_interval: AttachedView::TICK_INTERVAL, spinner_clock: nil, scratch: false)
-      @mode           = mode.to_sym
       @scratch        = scratch
       @prompt         = prompt
       @default_model_name = ModelProfile.required_model_name(nil)
@@ -138,7 +139,6 @@ module Samagotchi
       @renderer = EventRenderer.new(@view)
       @render_event = ->(event) { handle_stream_event(event) }
       @engine         = Engine.new(
-        mode: :assist,
         client: client,
         host_registry: @host_registry,
         profile: profile,
@@ -206,16 +206,12 @@ module Samagotchi
     # @return [Symbol, nil] :turn_failed when lines came from a pipe and a
     #   turn failed (bin/chi exits 1)
     def run
-      unless @mode == :assist
-        raise ArgumentError, "Unknown mode '#{@mode}'. Use: assist"
-      end
-
       # --non-interactive with no --prompt is a harmless no-op exit: build
       # nothing and return (no transient session, no banner).
       return if @non_interactive && @prompt.nil?
 
       session = @resume_session || Session.new_session(
-        mode: @mode.to_s,
+        mode: "assist",
         model_name: @effective_model_name,
         working_directory: Dir.pwd,
         preloaded_memory_names: @requested_memories,
@@ -316,19 +312,13 @@ module Samagotchi
       nil
     end
 
-    # Nothing happened in the session (SessionManager.empty_session?). The
+    # Nothing happened in the session (SessionManager.discardable?). The
     # REPL saves only after a turn and keeps /model in its Engine, so a
     # session never saved is judged from memory, and one on another model
     # than the default (/model, --model) is kept.
     def discard_on_exit?(session)
-      return false unless SessionManager.discard_empty?
-      return false unless @effective_model_name == @default_model_name && Array(@engine.used_memory_names).empty?
-      if File.exist?(File.join(Session.default_state_dir, "#{session.id}#{Session::FILE_EXT}"))
-        return SessionManager.empty_session?(session.id, default_model: @default_model_name)
-      end
-
-      SessionManager.no_conversation?(session.messages) && session.last_prompt.to_s.strip.empty? &&
-        SessionManager.empty_session_dir?(Session.session_dir(session.id))
+      SessionManager.discardable?(session.id, default_model: @default_model_name, model_name: @effective_model_name,
+                                              used_memory_names: @engine.used_memory_names, unsaved: session)
     end
 
     # A session left empty: give it up and delete it, one quiet line.

data/lib/samagotchi/tools/memory.rb

@@ -4,6 +4,7 @@
 require "fileutils"
 require "digest"
 require "date"
+require_relative "../atomic_file"
 require_relative "../memory_paths"
 
 module Samagotchi
@@ -186,7 +187,7 @@ module Samagotchi
           end
 
           file_path = File.join(dir, "#{entry_name}.#{model_key}.md")
-          Samagotchi::MemoryBundle::IndexUpdater.atomic_write(file_path, body)
+          Samagotchi::AtomicFile.write(file_path, body)
           bytes = body.bytesize
           return "Model overlay '#{entry_name}' for #{model_key} saved to #{resolved_scope} scope (#{bytes} bytes). File written: #{file_path}"
         end
@@ -195,7 +196,7 @@ module Samagotchi
         if entry_name == MEMORY_INDEX
           Samagotchi::MemoryBundle::IndexUpdater.locked_write(dir) { body }
         else
-          Samagotchi::MemoryBundle::IndexUpdater.atomic_write(file_path, body)
+          Samagotchi::AtomicFile.write(file_path, body)
         end
         bytes = body.bytesize
         message = "Memory '#{entry_name}' saved to #{resolved_scope} scope (#{bytes} bytes). File written: #{file_path}"

data/lib/samagotchi/tools/send_note.rb

@@ -2,6 +2,7 @@
 
 require_relative "../session"
 require_relative "../context_note"
+require_relative "../session_inbox"
 require_relative "peers"
 
 module Samagotchi
@@ -33,13 +34,13 @@ module Samagotchi
           return "Error: session #{id[0, 8]} is open in a chi REPL, which can't take notes"
         end
 
-        SessionManager.write_note(id, text: content, source: "session", from_session: peers.session_id,
-                                      from_cwd: peers.cwd, state_dir: peers.state_dir)
+        SessionInbox.write_note(id, text: content, source: "session", from_session: peers.session_id,
+                                    from_cwd: peers.cwd, state_dir: peers.state_dir)
         where = owner ? "its worker adds it before its next turn" : "it has no worker now, so it waits for its next start"
         "Queued a note for session #{id[0, 8]}: #{where}. It does not start a turn there."
       rescue Session::AmbiguousId => e
         "Error: #{e.message}"
-      rescue SessionManager::NoteRejected => e
+      rescue SessionInbox::NoteRejected => e
         "Error: #{e.message}"
       rescue ArgumentError
         "Error: no session #{session.to_s.strip} (list_sessions shows them)"

data/lib/samagotchi/tools/task_runtime.rb

@@ -5,6 +5,7 @@ require "json"
 require "securerandom"
 require "shellwords"
 require "time"
+require_relative "../atomic_file"
 
 module Samagotchi
   module Tools
@@ -198,9 +199,7 @@ module Samagotchi
         FileUtils.mkdir_p(dir)
 
         path = File.join(dir, METADATA_FILENAME)
-        temp_path = "#{path}.tmp"
-        File.write(temp_path, JSON.pretty_generate(record) + "\n")
-        File.rename(temp_path, path)
+        AtomicFile.write(path, JSON.pretty_generate(record) + "\n")
       end
 
       def metadata_path(task_id)

data/lib/samagotchi/turn_note.rb

@@ -39,13 +39,24 @@ module Samagotchi
     #   model message precedes this note)
     # @param running_tasks [Array<Hash>] {id:, command:} of this session's
     #   background tasks still running: a Stop doesn't end them
-    def cancelled(reason, seconds: nil, shown: false, running_tasks: [])
-      why = reason.to_s.empty? ? "" : " (#{reason.to_s.tr("_", "-")})"
+    # @param stopped_by [Hash, nil] {by:, reason:} of a hook that stopped
+    #   it (stop_turn, or a cut with no retry left)
+    def cancelled(reason, seconds: nil, shown: false, running_tasks: [], stopped_by: nil)
+      why = reason.to_s.empty? ? "" : " (#{reason.to_s.tr("_", "-")}#{stopper(stopped_by)})"
       after = seconds ? " after #{seconds.round}s" : ""
       what = shown ? "the answer above ends where it was cut off." : "no answer had been shown."
       message("the previous turn was cancelled#{why}#{after}; #{what}#{still_running(running_tasks)}")
     end
 
+    # " <by>: <reason>" of a hook that stopped the turn, as far as known.
+    def stopper(stopped_by)
+      return "" unless stopped_by.is_a?(Hash)
+
+      by = one_line(stopped_by[:by])
+      reason = one_line(stopped_by[:reason])
+      [by.empty? ? nil : " #{by}", reason.empty? ? nil : ": #{reason}"].compact.join
+    end
+
     def still_running(tasks)
       return "" if tasks.empty?
 

data/lib/samagotchi/update_command.rb

@@ -62,7 +62,7 @@ module Samagotchi
       @stderr = stderr
       @gem_spec = gem_spec
       @shipped_dir = shipped_dir
-      @platform = platform || ->(register:) { Desktop::MacOS.new(register: register) }
+      @platform = platform || ->(register:) { Desktop::MacOS.new(register: register, kitty: Desktop::MacOS.kitty_settings) }
       @supported = supported
       @state_dir = state_dir
       @web = web || [Web::Lan.local_host(Config.get("web.host")), Config.get("web.port").to_i]
@@ -192,7 +192,7 @@ module Samagotchi
       row = Row.new(component: update.name, from: update.from, to: update.to)
       case update.status
       when :would_update, :updated
-        notes = [kept(update.kept, update.name), replaced(update.replaced)].compact
+        notes = [adds(update.adds), kept(update.kept, update.name), replaced(update.replaced)].compact
         done(row, :update, notes.empty? ? nil : notes.join("; "))
       when :up_to_date then up_to_date(row)
       when :skipped then skipped(row, update.note)
@@ -247,7 +247,9 @@ module Samagotchi
     def footers(options)
       return [] if off(options, "bundles")
 
-      names = MemoryBundle::ShippedUpdate.not_installed(shipped_dir: @shipped_dir).map(&:source)
+      names = MemoryBundle::ShippedUpdate.not_installed(shipped_dir: @shipped_dir).map do |s|
+        s.includes.empty? ? s.source : "#{s.source} (#{s.includes.join(", ")})"
+      end
       names.empty? ? [] : ["Also shipped, not installed: #{names.join(", ")} (chi bundle install NAME)"]
     end
 
@@ -284,6 +286,11 @@ module Samagotchi
       row
     end
 
+    # A profile's new members: "+ btw".
+    def adds(members)
+      members.nil? || members.empty? ? nil : "+ #{members.join(", ")}"
+    end
+
     def kept(files, bundle)
       return nil if files.empty?
 

data/lib/samagotchi/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Samagotchi
-  VERSION = "0.6.0"
+  VERSION = "0.8.0"
   # Sent as the User-Agent of every HTTP request chi makes.
   USER_AGENT = "chi/#{VERSION}"
 end