samagotchi 0.152.0 → 0.154.0

data/lib/samagotchi/session_metrics.rb

@@ -25,8 +25,8 @@ module Samagotchi
   # SessionMetrics is a persistent, error-isolated collector of per-session
   # analytics. It implements the same #call(event) sink contract as
   # SessionObserver subscribers, so Engine#run_turn feeds it (it forwards every
-  # event to its SessionObserver): the REPL, the -p/--non-interactive/--resume
-  # paths and SessionManager background workers.
+  # event to its SessionObserver): a --non-interactive one-shot and the
+  # session workers.
   #
   # Each finished turn leaves a record (status, timings, model, prompt and
   # completion tokens, tool calls, iterations, retries, cuts); session totals are

data/lib/samagotchi/session_model_settings.rb

@@ -7,6 +7,7 @@ require_relative "session_setting"
 require_relative "steer_cut"
 require_relative "steer_cut_after"
 require_relative "thinking"
+require_relative "session"
 
 module Samagotchi
   # The session's settings on its effective model, as the Engine reads them:
@@ -163,7 +164,7 @@ module Samagotchi
     # @raise [ArgumentError] with no session yet
     def reasoning_history_override=(level)
       session = @session.call
-      raise ArgumentError, "no session yet" unless session
+      raise ArgumentError, Session::NONE_YET unless session
 
       SessionSetting::REASONING_HISTORY.set(session, level)
     end
@@ -178,7 +179,7 @@ module Samagotchi
     # @raise [ArgumentError] with no session yet
     def thinking_override=(level)
       session = @session.call
-      raise ArgumentError, "no session yet" unless session
+      raise ArgumentError, Session::NONE_YET unless session
 
       SessionSetting::THINKING.set(session, level)
     end

data/lib/samagotchi/session_participants.rb

@@ -4,7 +4,7 @@ require_relative "steer"
 require_relative "participant_mode"
 
 module Samagotchi
-  # Loaded only when a session is read: it brings Web::Grants (and Rack).
+  # Loaded only when a session is read: it brings Grants.
   autoload :Participants, File.expand_path("participants", __dir__)
 
   # What a session's Engine knows of its participants: participants.json

data/lib/samagotchi/session_retention.rb

@@ -30,7 +30,7 @@ module Samagotchi
     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
+    # worker deletes it as it leaves, so the sweep only catches
     # those killed first (a reboot, kill -9).
     EMPTY_GRACE_SECONDS = 3600
 
@@ -69,7 +69,7 @@ module Samagotchi
     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
+    # owning them: a one-shot 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:)
@@ -161,7 +161,7 @@ module Samagotchi
     # +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
+    # A scratch session nobody owns (its terminal and worker were 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

data/lib/samagotchi/sessions_command.rb

@@ -21,7 +21,7 @@ module Samagotchi
   # `chi sessions`: list, stop, restart, archive/unarchive, delete, prune,
   # clean and stats sessions from the shell (bin/chi dispatches here before
   # OptionParser; the subcommands have their own flags). Not SessionCommands,
-  # the REPL's slash commands for sessions (session_commands.rb).
+  # the slash commands a session's worker runs (session_commands.rb).
   class SessionsCommand
     include CLI::Command
 
@@ -207,15 +207,15 @@ module Samagotchi
       )
       case format
       when "json"
-        # owner: "worker", "tui" (a chi REPL: it takes no notes or messages)
+        # owner: "worker", "tui" (a one-turn chi run: it takes no notes or messages)
         # or nil; recap: the saved recap's first sentence, or nil; project:
         # its git project's root, or nil
         # parent_id: the session that delegated it (the delegate tool), or nil
         # delegate: started by the delegate tool (a fork has a parent_id too)
         # continues: the session it continues (its chain's previous link), or nil
         # archived: hidden from the lists (only with --archived can it be true)
-        # scratch: a `chi scratch` session (deleted when its REPL ends, a
-        # leftover one at the next sweep)
+        # scratch: a `chi scratch` session (deleted when its terminal leaves,
+        # a leftover one at the next sweep)
         # ctx_pct: how full the context was after the last turn, or nil
         # title: the session's own name (/title; desc shows it too), or nil;
         # auto_title: the one its recap gave it (RecapTitle), or nil

data/lib/samagotchi/share_command.rb

@@ -8,12 +8,12 @@ require_relative "cli/flags"
 require_relative "session"
 require_relative "session_access"
 require_relative "session_access/local"
-require_relative "web/grants"
+require_relative "grants"
 require_relative "web/qr"
 
 module Samagotchi
   # `chi share`: invite a participant to review a session (the
-  # shared-sessions plan: a Web::Grants grant, one session, one person or
+  # shared-sessions plan: a Grants grant, one session, one person or
   # agent, 7 days unless --expires says otherwise), list the participants,
   # revoke them. Local or through chi --remote NAME (SessionAccess). The
   # token is printed once, in the link; chi keeps only its digest. See
@@ -95,9 +95,9 @@ module Samagotchi
       return parsed if parsed.is_a?(Integer)
 
       send(:"run_#{@sub || "invite"}", parsed.options, parsed.args)
-    rescue SessionAccess::BadRequest, Web::Grants::BadIdentity => e
+    rescue SessionAccess::BadRequest, Grants::BadIdentity => e
       usage_error(e.message)
-    rescue Web::Grants::Unwritable => e
+    rescue Grants::Unwritable => e
       error_line("#{command_name}: #{e.message}")
       CLI::Exit::FAILED
     rescue ArgumentError => e
@@ -114,13 +114,13 @@ module Samagotchi
       return usage_error("give one session ID") unless args.size == 1
       return usage_error("--name NAME: who the link is for") if options[:name].to_s.strip.empty?
 
-      ttl = Web::Grants.parse_ttl(options[:expires])
+      ttl = Grants.parse_ttl(options[:expires])
       return usage_error("--expires takes Nh or Nd, 1h to 30d (e.g. 3d)") if ttl == false
 
       cap = options[:cap] && dollars(options[:cap])
       return usage_error(CAP_USAGE) if cap == false
 
-      identity = options[:identity] && Web::Grants.clean_identity(options[:identity])
+      identity = options[:identity] && Grants.clean_identity(options[:identity])
 
       id = @access.resolve(args.first)
       invitation = @access.invite(id, name: options[:name], kind: options[:agent] ? "agent" : "human", ttl: ttl, cap: cap,
@@ -149,13 +149,13 @@ module Samagotchi
       0
     end
 
-    CAP_USAGE = "a cap is dollars, $0 to $#{Web::Grants::MAX_CAP.to_i} (e.g. --cap 5)".freeze
+    CAP_USAGE = "a cap is dollars, $0 to $#{Grants::MAX_CAP.to_i} (e.g. --cap 5)".freeze
 
     def run_cap(_options, args)
       return usage_error("give a session ID, a participant and dollars (chi share cap ID p_… 5)") unless args.size == 3
 
       participant = args[1]
-      return usage_error("not a participant: #{participant} (chi share ls lists them)") unless Web::Grants::ID_RE.match?(participant)
+      return usage_error("not a participant: #{participant} (chi share ls lists them)") unless Grants::ID_RE.match?(participant)
 
       cap = dollars(args[2])
       return usage_error(CAP_USAGE) if cap == false
@@ -172,7 +172,7 @@ module Samagotchi
       return false unless text.match?(/\A\d+(?:\.\d+)?\z/)
 
       value = text.to_f
-      Web::Grants.cap?(value) ? value : false
+      Grants.cap?(value) ? value : false
     end
 
     def money(value) = value.nil? ? "-" : format("$%.2f", value)
@@ -184,7 +184,7 @@ module Samagotchi
         return usage_error("give a session ID (and a participant), or --all")
       end
       participant = args[1]
-      return usage_error("not a participant: #{participant} (chi share ls lists them)") if participant && !Web::Grants::ID_RE.match?(participant)
+      return usage_error("not a participant: #{participant} (chi share ls lists them)") if participant && !Grants::ID_RE.match?(participant)
 
       id = args.first && @access.resolve(args.first)
       revoked = @access.revoke_participants(id, participant: participant)

data/lib/samagotchi/steer.rb

@@ -136,7 +136,7 @@ module Samagotchi
     PARTICIPANT_SOURCE = "participant"
     # The owner's author, when one is written out; absent means the same.
     OWNER_AUTHOR = "owner"
-    # A participant's author: this prefix, then its id (Web::Grants'
+    # A participant's author: this prefix, then its id (Grants'
     # grant id), "p:<id>" (#author_for, #participant_id).
     PARTICIPANT_PREFIX = "p:"
     # A participant's message's keys, which every message copy keeps.

data/lib/samagotchi/system_prompt.rb

@@ -2,6 +2,7 @@
 
 require_relative "config"
 require_relative "log"
+require_relative "degrade"
 require_relative "log_path"
 require_relative "memory_paths"
 require_relative "paths"
@@ -74,11 +75,7 @@ module Samagotchi
       @requested_memories = effective_preload_list(preload_memory_list(memories))
       # Read once, as the memories: list is: a config edit is picked up by
       # a new process. The files' text is read at each build.
-      @config_appended = begin
-        ConfigFile.appended_prompt_files
-      rescue StandardError
-        []
-      end
+      @config_appended = Degrade.call(:prompt, "appended_list_unreadable", fallback: []) { ConfigFile.appended_prompt_files }
       @cli_appended = Array(appended_files).map { |path| File.expand_path(path.to_s) }
     end
 
@@ -386,11 +383,11 @@ module Samagotchi
     # (Plugin::PromptSections). nil with none: the prompt is what it was
     # before prompt sections.
     def plugin_prompt_section
-      built = Array(@sections_lookup.call)
-      @section_plugins = built
-      Plugin::PromptSections.text(built)
-    rescue StandardError
-      nil
+      Degrade.call(:prompt, "plugin_section_failed") do
+        built = Array(@sections_lookup.call)
+        @section_plugins = built
+        Plugin::PromptSections.text(built)
+      end
     end
 
     def with_tail_declarations(prompt, chat:, layers:)
@@ -405,35 +402,35 @@ module Samagotchi
     # Identity is not tracked as an "activated" memory for the sticky status line
     # to avoid always showing `mem: identity`.
     def system_identity_section
-      DEFAULT_SYSTEM_MEMORIES.each do |name|
-        next if memory_muted?(name)
+      Degrade.call(:prompt, "identity_unreadable") do
+        DEFAULT_SYSTEM_MEMORIES.each do |name|
+          next if memory_muted?(name)
 
-        body = Tools::MemoryRead.call(name, scope: "system", **overlay_keys)
-        next if body.start_with?("Error:")
-        next if body.strip.empty?
+          body = Tools::MemoryRead.call(name, scope: "system", **overlay_keys)
+          next if body.start_with?("Error:")
+          next if body.strip.empty?
 
-        return "System identity (auto-loaded, scope=system):\n#{body}"
+          return "System identity (auto-loaded, scope=system):\n#{body}"
+        end
+        nil
       end
-      nil
-    rescue StandardError
-      nil
     end
 
     # The model notes for the session's model (ModelNotes), right after
     # identity: a heading per scope, each note under its name, the models:
     # line left out. nil without any, so the prompt stays as it was.
     def model_notes_section
-      @section_notes = []
-      notes = Array(@model_notes_lookup.call)
-      return nil if notes.empty?
-
-      ref = @model_lookup.call&.ref
-      notes.group_by(&:scope).map do |scope, list|
-        heading = ref.to_s.empty? ? "Model notes (scope=#{scope}):" : "Model notes (for #{ref}, scope=#{scope}):"
-        [heading, *list.map { |note| "## #{note.name}\n#{note.body}" }].join("\n\n")
-      end.join("\n\n").tap { @section_notes = notes }
-    rescue StandardError
-      nil
+      Degrade.call(:prompt, "model_notes_failed") do
+        @section_notes = []
+        notes = Array(@model_notes_lookup.call)
+        return nil if notes.empty?
+
+        ref = @model_lookup.call&.ref
+        notes.group_by(&:scope).map do |scope, list|
+          heading = ref.to_s.empty? ? "Model notes (scope=#{scope}):" : "Model notes (for #{ref}, scope=#{scope}):"
+          [heading, *list.map { |note| "## #{note.name}\n#{note.body}" }].join("\n\n")
+        end.join("\n\n").tap { @section_notes = notes }
+      end
     end
 
     # ── Memory helpers ─────────────────────────────────────────────────────────
@@ -441,23 +438,23 @@ module Samagotchi
     # The session model's overlay keys, so the prompt's own memory bodies
     # (identity, preloads) get `<name>.<key>.md` as memory_read gives it.
     def overlay_keys
-      model = @model_lookup.call
-      return {} unless model&.key
+      Degrade.call(:prompt, "overlay_keys_failed", fallback: {}) do
+        model = @model_lookup.call
+        return {} unless model&.key
 
-      { model_key: model.key, fallback_model_key: model.fallback_key }
-    rescue StandardError
-      {}
+        { model_key: model.key, fallback_model_key: model.fallback_key }
+      end
     end
 
     # { system: { tokens:, lines: }, project: { … } } of the index texts
     # the prompt holds; nil when they can't be measured.
     def measure_indexes(indexes)
-      chars_per_token = MemoryBundle::IndexSize.chars_per_token
-      %i[system project].to_h do |scope|
-        [scope, MemoryBundle::IndexSize.of_text(scope, indexes[scope], chars_per_token: chars_per_token).figures]
+      Degrade.call(:prompt, "index_size_failed") do
+        chars_per_token = MemoryBundle::IndexSize.chars_per_token
+        %i[system project].to_h do |scope|
+          [scope, MemoryBundle::IndexSize.of_text(scope, indexes[scope], chars_per_token: chars_per_token).figures]
+        end
       end
-    rescue StandardError
-      nil
     end
 
     # The scope's index text without the muted memories' lines, nor the
@@ -473,11 +470,7 @@ module Samagotchi
     # comma-split and appended without duplicates (same ref shape as --memory:
     # bare name or scope/name).
     def preload_memory_list(cli_memories)
-      baseline = begin
-        ConfigFile.preloaded_memories
-      rescue StandardError
-        []
-      end
+      baseline = Degrade.call(:prompt, "preload_list_unreadable", fallback: []) { ConfigFile.preloaded_memories }
 
       merged = Array(baseline).dup
       # For the warning when one can't be loaded: it names where it came from.
@@ -555,15 +548,15 @@ module Samagotchi
     # The AGENTS.md chain from the top of the git work tree down to the cwd
     # (PromptFiles.agents_sections), one section per file with text.
     def project_specific_description
-      return nil if skip_agent_description?
+      Degrade.call(:prompt, "agents_md_unreadable") do
+        return nil if skip_agent_description?
 
-      sections = PromptFiles.agents_sections(Dir.pwd)
-      return nil if sections.empty?
+        sections = PromptFiles.agents_sections(Dir.pwd)
+        return nil if sections.empty?
 
-      @section_files&.concat(sections.map(&:path))
-      sections.map(&:text).join("\n\n")
-    rescue StandardError
-      nil
+        @section_files&.concat(sections.map(&:path))
+        sections.map(&:text).join("\n\n")
+      end
     end
 
     # The appended files' text, right after AGENTS.md (the stable, cached
@@ -572,26 +565,26 @@ module Samagotchi
     # then --append-system-prompt's. A file the AGENTS.md chain holds, a
     # repeat and an empty or vanished file are left out.
     def appended_section
-      cwd = Dir.pwd
-      top = MemoryPaths.work_tree_root(cwd)
-      seen = Set.new((skip_agent_description? ? [] : PromptFiles.agents_paths(cwd)).map { |path| canonical_path(path) })
-      sections = []
-      appended_candidates(cwd).each do |path, source|
-        next unless seen.add?(canonical_path(path))
-
-        unless File.file?(path)
-          Log.debug(:config, "appended_prompt_file_missing", path: path, source: source)
-          next
-        end
-        text = PromptFiles.section(path, "Appended from #{PromptFiles.display_path(path, top: top)}:")
-        next unless text
+      Degrade.call(:prompt, "appended_files_failed") do
+        cwd = Dir.pwd
+        top = MemoryPaths.work_tree_root(cwd)
+        seen = Set.new((skip_agent_description? ? [] : PromptFiles.agents_paths(cwd)).map { |path| canonical_path(path) })
+        sections = []
+        appended_candidates(cwd).each do |path, source|
+          next unless seen.add?(canonical_path(path))
+
+          unless File.file?(path)
+            Log.debug(:config, "appended_prompt_file_missing", path: path, source: source)
+            next
+          end
+          text = PromptFiles.section(path, "Appended from #{PromptFiles.display_path(path, top: top)}:")
+          next unless text
 
-        @section_files&.push(path)
-        sections << text
+          @section_files&.push(path)
+          sections << text
+        end
+        sections.empty? ? nil : sections.join("\n\n")
       end
-      sections.empty? ? nil : sections.join("\n\n")
-    rescue StandardError
-      nil
     end
 
     # [absolute path, "config" | "cli"], in prompt order.
@@ -617,27 +610,27 @@ module Samagotchi
     # The home directory is spelled out once so the model copies the right
     # sequence, with the advice to write it as ~ or $HOME instead.
     def project_location
-      cwd = Dir.pwd
-      top = MemoryPaths.work_tree_root(cwd)
-      lines = ["Current working directory:", cwd]
-      if top && top != cwd
-        lines << "Top of this checkout (where the project's commands run from; stay inside it):"
-        lines << top
-      elsif top
-        lines << "This checkout (the project's files; its commands run here):"
-        lines << top
-      end
-      if top && MemoryPaths.project_root(cwd) != top
-        lines << "This checkout is a linked git worktree: read, edit, run and commit only in it, never in the " \
-                 "repository's other checkouts."
+      Degrade.call(:prompt, "location_failed") do
+        cwd = Dir.pwd
+        top = MemoryPaths.work_tree_root(cwd)
+        lines = ["Current working directory:", cwd]
+        if top && top != cwd
+          lines << "Top of this checkout (where the project's commands run from; stay inside it):"
+          lines << top
+        elsif top
+          lines << "This checkout (the project's files; its commands run here):"
+          lines << top
+        end
+        if top && MemoryPaths.project_root(cwd) != top
+          lines << "This checkout is a linked git worktree: read, edit, run and commit only in it, never in the " \
+                   "repository's other checkouts."
+        end
+        home = Dir.home
+        lines << "Home directory: #{home} (write it as ~ or $HOME in commands and paths)" unless home.to_s.empty?
+        lines << "Project memories folder (your notes about the project, not its files; never work or run commands there):"
+        lines << Paths.tilde(Tools::MemoryRead.memories_dir("project"))
+        lines.join("\n")
       end
-      home = Dir.home
-      lines << "Home directory: #{home} (write it as ~ or $HOME in commands and paths)" unless home.to_s.empty?
-      lines << "Project memories folder (your notes about the project, not its files; never work or run commands there):"
-      lines << Paths.tilde(Tools::MemoryRead.memories_dir("project"))
-      lines.join("\n")
-    rescue StandardError
-      nil
     end
 
     # Only while the session has participants (people its owner invited to
@@ -662,12 +655,12 @@ module Samagotchi
     # once a participant invited to act is in a working session, the review
     # line for review participants; nothing with none (nil, false).
     def participants_section
-      mode = @participants_lookup.call
-      return nil unless mode
+      Degrade.call(:prompt, "participants_line_failed") do
+        mode = @participants_lookup.call
+        return nil unless mode
 
-      mode == ParticipantMode::PAIR ? PAIR_PARTICIPANTS_LINE : PARTICIPANTS_LINE
-    rescue StandardError
-      nil
+        mode == ParticipantMode::PAIR ? PAIR_PARTICIPANTS_LINE : PARTICIPANTS_LINE
+      end
     end
 
     # The model this session runs on. A model guesses its name from
@@ -675,19 +668,19 @@ module Samagotchi
     # says to answer from here. It depends only on the effective model, and
     # the prompt is rebuilt only on a switch (#reset!): no per-turn churn.
     def current_model
-      model = @model_lookup.call
-      return nil unless model && !model.ref.to_s.empty?
-
-      details = [model.host, model.key && "model key #{model.key}", model.served && "the server says it serves #{model.served}"]
-      details = details.compact.reject(&:empty?)
-      where = details.empty? ? "" : " (#{details.join("; ")})"
-      "Model: this session runs on #{model.ref}#{where}.\n" \
-        "Asked which model you are, answer with this line, not from training: a fine-tuned model often knows only " \
-        "its base model's name, but this session runs what is named here; it changes only with /model. " \
-        "Guidance for this model only goes in a model note: a memory named model_notes_<name> whose first line is " \
-        "`models: <glob on this model's id or key>`."
-    rescue StandardError
-      nil
+      Degrade.call(:prompt, "model_line_failed") do
+        model = @model_lookup.call
+        return nil unless model && !model.ref.to_s.empty?
+
+        details = [model.host, model.key && "model key #{model.key}", model.served && "the server says it serves #{model.served}"]
+        details = details.compact.reject(&:empty?)
+        where = details.empty? ? "" : " (#{details.join("; ")})"
+        "Model: this session runs on #{model.ref}#{where}.\n" \
+          "Asked which model you are, answer with this line, not from training: a fine-tuned model often knows only " \
+          "its base model's name, but this session runs what is named here; it changes only with /model. " \
+          "Guidance for this model only goes in a model note: a memory named model_notes_<name> whose first line is " \
+          "`models: <glob on this model's id or key>`."
+      end
     end
 
     # Fixed for the session's lifetime, so it doesn't churn the prompt cache.
@@ -701,7 +694,7 @@ module Samagotchi
       line = "Current session id: #{id} (resume later with `chi --resume #{id}`)"
       # The log path too: asked what went wrong, a model that has to look
       # it up guesses ~/.local/state first (the self-awareness probes).
-      log = begin; LogPath.resolve; rescue StandardError; nil; end
+      log = Degrade.call(:prompt, "log_path_failed") { LogPath.resolve }
       line = "#{line}\nMy debug log: #{log} (one record per line; this session's carry sid=#{id[0, Log::SID_LENGTH]})" if log
       parent = session.parent_id.to_s
       return line if parent.empty?

data/lib/samagotchi/task_watch.rb

@@ -9,7 +9,7 @@ require_relative "tools/task_runtime"
 module Samagotchi
   # The background tasks a worker's session started that the model hasn't
   # seen finish (docs/internals/background-tasks.md, Finish wake). Held by
-  # the Worker (the --no-shared REPL has none) and fed by the Engine's raw
+  # the Worker (a --non-interactive one-shot has none) and fed by the Engine's raw
   # :tool_call_completed events (#observe), the input Bridge#own_task_ids
   # reads too; the idle loop takes the finished ones (#take_finished) for a
   # wake turn or a plain note. In memory only: a crash loses them, and they