samagotchi 0.51.0 → 0.53.0

data/lib/samagotchi/llm_context_strategy.rb

@@ -23,7 +23,7 @@ module Samagotchi
   # (false: edit-driven stale stubs are opt-in, experimental) are global only.
   #
   # A soft context budget, llm_context.budget_tokens, and per model or host
-  # the flat key llm_context_budget_tokens (a positive number of tokens),
+  # the flat key llm_context_budget_tokens (tokens or k, 4k to 10M, or off),
   # resolved as the apply rule is, each on its own: off (nil) by default.
   # When set, ContextStatus counts its bands against it instead of the
   # window (the smaller of the two), so the forget layer's offers come
@@ -103,21 +103,52 @@ module Samagotchi
       DEFAULT_APPLY
     end
 
-    # +raw+ as written, a context budget in tokens; nil for unset or 0
-    # (off). Anything but a number of tokens warns, naming +where+, and is
-    # unset.
+    # +raw+ as written in config (llm_context.budget_tokens, a models: or
+    # hosts: entry's llm_context_budget_tokens), read as /llm-context
+    # budget reads it (.budget_tokens); nil for unset, 0 or off. Anything
+    # else warns, naming +where+, and is unset.
     # @return [Integer, nil]
     def parse_budget(raw, where)
       return nil if raw.nil? || raw.to_s.strip.empty?
 
-      tokens = Integer(raw.to_s.strip, exception: false)
-      return nil if tokens&.zero?
-      return tokens if tokens&.positive?
-
-      warn_once "Warning: #{where}: llm_context budget_tokens must be a positive number of tokens; ignored"
+      tokens = budget_tokens(raw)
+      tokens.zero? ? nil : tokens
+    rescue ArgumentError => e
+      warn_once "Warning: #{where}: #{e.message}; ignored"
       nil
     end
 
+    # The smallest and largest budget a session or the config may set.
+    MIN_BUDGET = 4_000
+    MAX_BUDGET = 10_000_000
+    BUDGET_OFF_WORDS = %w[off 0].freeze
+
+    # A budget in tokens: an Integer, "64000", "64_000", "64k", or "off"
+    # (0); the one grammar for /llm-context budget, chi
+    # --llm-context-budget and the config.
+    # @return [Integer] 0 for off
+    # @raise [ArgumentError] not a budget, or one out of MIN_BUDGET..MAX_BUDGET
+    def budget_tokens(raw)
+      return check_budget(raw) if raw.is_a?(Integer)
+
+      text = raw.to_s.strip
+      return 0 if BUDGET_OFF_WORDS.include?(text.downcase)
+
+      match = /\A(\d[\d_]*)(k)?\z/i.match(text)
+      raise ArgumentError, "a budget is a number of tokens (64000 or 64k) or off" unless match
+
+      check_budget(match[1].delete("_").to_i * (match[2] ? 1000 : 1))
+    end
+
+    # +tokens+, when 0 (off) or between MIN_BUDGET and MAX_BUDGET.
+    # @return [Integer]
+    # @raise [ArgumentError]
+    def check_budget(tokens)
+      return tokens if tokens.zero? || tokens.between?(MIN_BUDGET, MAX_BUDGET)
+
+      raise ArgumentError, "a budget of #{tokens} tokens is out of range: #{MIN_BUDGET} (4k) to #{MAX_BUDGET} (10000k), or off"
+    end
+
     # Where one value came from: :session, :model_setting, :host_setting
     # or :config, and the place as a warning names it ("the session",
     # "models: deepseek", "hosts entry 'box'", "llm_context.apply").
@@ -143,7 +174,7 @@ module Samagotchi
     # The strategy for +target+'s turn.
     # @param target [HostRegistry::ModelTarget, nil]
     # @param names [Array<String>] HostRegistry#lookup_names
-    # @param models [Hash, nil] ConfigFile.model_settings (specs)
+    # @param models [Hash{String => ModelSettings}, nil] ConfigFile.model_settings (specs)
     # @param session [Array<Symbol>, nil] the session's own layers ([]: none)
     # @param session_apply [Symbol, nil] the session's own apply rule
     # @param session_budget [Integer, nil] the session's own budget (0: off)
@@ -210,8 +241,9 @@ module Samagotchi
     def budget_for(target, names, models, session_budget)
       return [session_budget.positive? ? session_budget : nil, SESSION_ORIGIN] unless session_budget.nil?
 
-      key, budget = ConfigFile.model_setting(names, :llm_context_budget_tokens, models: models)
-      return [budget, Origin.new(source: :model_setting, where: "models: #{key}")] if budget
+      if (setting = ConfigFile.model_setting(names, :llm_context_budget_tokens, models: models))
+        return [setting.value, Origin.new(source: :model_setting, where: "models: #{setting.key}")]
+      end
 
       budget = target&.entry&.llm_context_budget_tokens
       return [budget, Origin.new(source: :host_setting, where: "hosts entry '#{target.entry.name}'")] if budget
@@ -222,8 +254,9 @@ module Samagotchi
     def layers_for(target, names, models, session)
       return [session, :session, SESSION_ORIGIN.where] if session
 
-      key, layers = ConfigFile.model_setting(names, :llm_context_strategy, models: models)
-      return [layers, :model_setting, "models: #{key}"] if layers
+      if (setting = ConfigFile.model_setting(names, :llm_context_strategy, models: models))
+        return [setting.value, :model_setting, "models: #{setting.key}"]
+      end
 
       layers = target&.entry&.llm_context_strategy
       return [layers, :host_setting, "hosts entry '#{target.entry.name}'"] if layers
@@ -235,8 +268,9 @@ module Samagotchi
     def apply_for(target, names, models, session_apply)
       return [session_apply, SESSION_ORIGIN] if session_apply
 
-      key, apply = ConfigFile.model_setting(names, :llm_context_apply, models: models)
-      return [apply, Origin.new(source: :model_setting, where: "models: #{key}")] if apply
+      if (setting = ConfigFile.model_setting(names, :llm_context_apply, models: models))
+        return [setting.value, Origin.new(source: :model_setting, where: "models: #{setting.key}")]
+      end
 
       apply = target&.entry&.llm_context_apply
       return [apply, Origin.new(source: :host_setting, where: "hosts entry '#{target.entry.name}'")] if apply

data/lib/samagotchi/memory_bundle/builder.rb

@@ -3,6 +3,7 @@
 require "digest"
 require "fileutils"
 require "tmpdir"
+require_relative "bundle_hook"
 require_relative "manifest"
 require_relative "placeholder"
 require_relative "../context_providers"
@@ -50,6 +51,8 @@ module Samagotchi
         validate_version!(resolved_version)
         raise BuildError, "invalid scope: #{@scope}" unless %w[system project].include?(@scope)
 
+        refuse_profile!(resolved_name)
+
         # Collect *.md files, excluding index.md and hidden files
         all_md = Dir.glob(File.join(target_dir, "*.md")).sort
         candidates = all_md.reject { |p| File.basename(p) == "index.md" }
@@ -110,20 +113,9 @@ module Samagotchi
             # Skip if hook file missing on disk
             next unless File.exist?(src)
 
-            # meta may be symbol-keyed
-            m = meta.is_a?(Hash) ? meta.transform_keys(&:to_s) : {}
-            sha = (m["sha256"] || m["checksum"] || "").to_s
-            if sha.empty?
-              sha = "sha256:#{Digest::SHA256.hexdigest(File.read(src))}"
-            elsif !sha.start_with?("sha256:")
-              sha = "sha256:#{sha}"
-            end
-            hooks_map[basename] = {
-              "sha256" => sha,
-              "event" => (m["event"] || "").to_s,
-              "on_error" => (m["on_error"] || "skip").to_s,
-              "priority" => (m["priority"] || 100).to_i
-            }
+            hook = BundleHook.parse(meta)
+            hook = hook.with(sha256: BundleHook.of_file(src).sha256) if hook.sha256.empty?
+            hooks_map[basename] = hook
             hooks_to_copy << [src, basename]
           end
         else
@@ -132,13 +124,7 @@ module Samagotchi
           if Dir.exist?(local_hooks_dir)
             Dir.glob(File.join(local_hooks_dir, "*.rb")).sort.each do |src|
               basename = File.basename(src)
-              sha = Digest::SHA256.hexdigest(File.read(src))
-              hooks_map[basename] = {
-                "sha256" => "sha256:#{sha}",
-                "event" => "",
-                "on_error" => "skip",
-                "priority" => 100
-              }
+              hooks_map[basename] = BundleHook.of_file(src)
               hooks_to_copy << [src, basename]
             end
           end
@@ -268,6 +254,22 @@ module Samagotchi
 
       private
 
+      # An installed profile (meta bundle) ships only its includes: a build
+      # under its name would make a plain bundle of the scope's memories,
+      # without the includes, carrying the profile's trust_level.
+      def refuse_profile!(name)
+        require_relative "profile"
+        data = Provenance.new(name: name).read
+        return unless Profile.installed_meta?(name, data)
+
+        shipped = File.join(SourceNormalizer::SHIPPED_DIR, name)
+        members = Profile.recorded(data, File.file?(File.join(shipped, "manifest.yml")) ? Manifest.read(dir: shipped) : nil)
+        raise BuildError, "#{name} is an installed profile (includes: #{members.join(", ")}): it ships only its includes, " \
+                          "so a build can't remake it; pick another --name for these memories"
+      rescue JSON::ParserError, SystemCallError, Manifest::ValidationError
+        nil
+      end
+
       # The installed bundle's scripts its record lists, file name => path
       # in its scripts/ (a missing one is left out); {} without a record.
       def installed_scripts(prov, prov_data)

data/lib/samagotchi/memory_bundle/bundle_hook.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Samagotchi
+  module MemoryBundle
+    # One hook's metadata, as a bundle's manifest.yml declares it and its
+    # installed record (manifest.json) keeps it: the file's sha256
+    # ("sha256:<hex>", "" when none is recorded), the event it registers
+    # for ("" when none: it isn't loaded), on_error (skip, log or
+    # fail_closed) and priority. The one place the defaults live.
+    class BundleHook < Data.define(:sha256, :event, :on_error, :priority)
+      DEFAULT_ON_ERROR = "skip"
+      DEFAULT_PRIORITY = 100
+
+      def initialize(sha256: "", event: "", on_error: DEFAULT_ON_ERROR, priority: DEFAULT_PRIORITY)
+        super
+      end
+
+      # @param raw [Hash, BundleHook, nil] string keys (manifest.yml) or
+      #   symbol keys (a read record); missing or blank values get the
+      #   defaults
+      def self.parse(raw)
+        return raw if raw.is_a?(BundleHook)
+
+        h = raw.is_a?(Hash) ? raw.transform_keys(&:to_s) : {}
+        on_error = h["on_error"].to_s.strip
+        new(sha256: prefixed(h["sha256"]), event: h["event"].to_s.strip,
+            on_error: on_error.empty? ? DEFAULT_ON_ERROR : on_error,
+            priority: (h["priority"] || DEFAULT_PRIORITY).to_i)
+      end
+
+      # A hook known only by its file (no declared event): its sha, the defaults.
+      def self.of_file(path)
+        new(sha256: "sha256:#{Digest::SHA256.hexdigest(File.binread(path))}")
+      end
+
+      # "sha256:<hex>" from either form, "" for none.
+      def self.prefixed(sha)
+        sha = sha.to_s.strip
+        sha.empty? || sha.start_with?("sha256:") ? sha : "sha256:#{sha}"
+      end
+
+      # The sha's hex, "" when none is recorded.
+      def hex = sha256.delete_prefix("sha256:")
+
+      # The string-keyed form manifest.yml and manifest.json hold.
+      def to_record = to_h.transform_keys(&:to_s)
+    end
+  end
+end

data/lib/samagotchi/memory_bundle/installer.rb

@@ -3,6 +3,7 @@
 require "fileutils"
 require "digest"
 require_relative "../memory_paths"
+require_relative "bundle_hook"
 require_relative "provenance"
 require_relative "manifest"
 require_relative "source"
@@ -180,7 +181,7 @@ module Samagotchi
             discovered = Dir.glob(File.join(normalized_dir, "hooks", "*.rb")).map { |p| File.basename(p) }
             discovered.each do |bn|
               # Build minimal metadata so copy still happens (event unknown -> skipped by loader but copied for integrity)
-              hook_entries[bn] = { sha256: "", event: "", on_error: "skip", priority: 100 }
+              hook_entries[bn] = BundleHook.new
             end
           end
 
@@ -206,7 +207,7 @@ module Samagotchi
             if @upgrade && existing_provenance && File.exist?(dest) && !@force
               prev_meta = existing_provenance[:hooks] ? (existing_provenance[:hooks][basename.to_sym] || existing_provenance[:hooks][basename]) : nil
               if prev_meta
-                prev_sha = prev_meta[:sha256] || prev_meta["sha256"]
+                prev_sha = BundleHook.parse(prev_meta).sha256
                 if File.exist?(dest) && !Provenance.recorded_sha(prev_sha).empty? && !Provenance.sha_matches?(dest, prev_sha)
                   @warnings << "Hook #{basename} was locally modified; overwriting"
                 end
@@ -403,8 +404,7 @@ module Samagotchi
             hooks_files_for_provenance.each do |basename, path|
               next unless File.exist?(path)
 
-              sha = Digest::SHA256.hexdigest(File.read(path))
-              hooks_for_provenance[basename] = { "sha256" => "sha256:#{sha}", "event" => "", "on_error" => "skip", "priority" => 100 }
+              hooks_for_provenance[basename] = BundleHook.of_file(path)
             end
           end
           Provenance.new(name: @name).write(

data/lib/samagotchi/memory_bundle/manifest.rb

@@ -4,6 +4,7 @@ require "yaml"
 require "digest"
 require "fileutils"
 require_relative "../context_providers"
+require_relative "bundle_hook"
 
 module Samagotchi
   module MemoryBundle
@@ -53,7 +54,8 @@ module Samagotchi
       BUNDLE_NAME = /\A[A-Za-z0-9][A-Za-z0-9_-]*\z/
 
       # files: name → "sha256:<hex>" (both forms); file_descriptions: name →
-      # the description a mapping gave, for the files that have one.
+      # the description a mapping gave, for the files that have one; hooks:
+      # name → BundleHook.
       attr_reader :name, :version, :scope, :description, :files, :file_descriptions, :hooks, :trust_level, :plugin, :requires_chi, :needs, :includes,
                   :scripts, :context_providers
 
@@ -99,13 +101,7 @@ module Samagotchi
 
       # Returns sha256 hex for a hook basename (e.g. "guardrails.rb").
       def checksum_for_hook(basename)
-        raw = @hooks[basename]
-        return nil unless raw
-
-        sha = raw[:sha256] || raw["sha256"]
-        return nil unless sha
-
-        sha.to_s.start_with?("sha256:") ? sha.to_s[7..] : sha.to_s
+        @hooks[basename]&.hex
       end
 
       # @return [String, nil] the plugin's sha256 hex, "sha256:" stripped
@@ -142,14 +138,7 @@ module Samagotchi
           text = file_descriptions[key].to_s.strip
           [key, text.empty? ? sha : { "sha256" => sha, "description" => text }]
         end
-        if hooks && !hooks.empty?
-          # Normalize hooks to string-keyed with sha256 prefix preserved
-          manifest["hooks"] = hooks.transform_keys(&:to_s).transform_values do |v|
-            h = v.transform_keys(&:to_s)
-            h["sha256"] = h["sha256"].to_s.start_with?("sha256:") ? h["sha256"].to_s : "sha256:#{h["sha256"]}" if h["sha256"]
-            h
-          end
-        end
+        manifest["hooks"] = hooks.to_h { |k, v| [k.to_s, BundleHook.parse(v).to_record] } if hooks && !hooks.empty?
         manifest["trust_level"] = trust_level.to_s if trust_level && !trust_level.to_s.empty?
         if plugin
           sha = plugin[:sha256].to_s
@@ -306,18 +295,7 @@ module Samagotchi
           next unless k.is_a?(String) && !k.empty?
           next unless v.is_a?(Hash)
 
-          sha = (v["sha256"] || v[:sha256] || "").to_s
-          sha = "sha256:#{sha}" unless sha.empty? || sha.start_with?("sha256:")
-          event = (v["event"] || v[:event] || "").to_s.strip
-          on_error = (v["on_error"] || v[:on_error] || "skip").to_s.strip
-          on_error = "skip" if on_error.empty?
-          priority = (v["priority"] || v[:priority] || 100).to_i
-          acc[k] = {
-            sha256: sha,
-            event: event,
-            on_error: on_error,
-            priority: priority
-          }
+          acc[k] = BundleHook.parse(v)
         end
       end
     end

data/lib/samagotchi/memory_bundle/placeholder.rb

@@ -18,11 +18,6 @@ module Samagotchi
         new(content: content).placeholders
       end
 
-      # Returns a sorted list of unique placeholder names found.
-      def unique_names
-        @placeholders.map(&:strip).uniq.sort
-      end
-
       def any?
         !@placeholders.empty?
       end

data/lib/samagotchi/memory_bundle/provenance.rb

@@ -6,6 +6,7 @@ require "date"
 require "fileutils"
 require_relative "../atomic_file"
 require_relative "../memory_paths"
+require_relative "bundle_hook"
 
 module Samagotchi
   module MemoryBundle
@@ -177,22 +178,14 @@ module Samagotchi
         hooks_map = {}
         # existing hooks for pruning
         existing_hooks = existing && existing[:hooks] ? existing[:hooks] : {}
-        # Normalize incoming hooks (basename => metadata hash)
+        # Incoming hooks: basename => BundleHook (or its metadata hash)
         normalized_hooks = {}
         if hooks.is_a?(Hash)
           hooks.each do |k, v|
             next unless k.is_a?(String) && !k.empty?
-            next unless v.is_a?(Hash)
-
-            hv = v.transform_keys(&:to_sym)
-            sha = (hv[:sha256] || "").to_s
-            sha = "sha256:#{sha}" unless sha.empty? || sha.start_with?("sha256:")
-            normalized_hooks[k] = {
-              sha256: sha,
-              event: (hv[:event] || "").to_s,
-              on_error: (hv[:on_error] || "skip").to_s,
-              priority: (hv[:priority] || 100).to_i
-            }
+            next unless v.is_a?(Hash) || v.is_a?(BundleHook)
+
+            normalized_hooks[k] = BundleHook.parse(v)
           end
         end
         # Prune stale hook bases
@@ -210,12 +203,10 @@ module Samagotchi
         # compares against it, and a declared sha can be wrong (installing
         # only warns about that).
         hooks_files = {} unless hooks_files.is_a?(Hash)
-        normalized_hooks.each do |k, meta|
+        normalized_hooks.each do |k, hook|
           src = hooks_files[k] || hooks_files[k.to_sym]
-          if src && File.exist?(src.to_s)
-            meta = meta.merge(sha256: "sha256:#{Digest::SHA256.hexdigest(File.read(src.to_s))}")
-          end
-          hooks_map[k] = meta.transform_keys(&:to_s)
+          hook = hook.with(sha256: BundleHook.of_file(src.to_s).sha256) if src && File.exist?(src.to_s)
+          hooks_map[k] = hook.to_record
           next unless src && File.exist?(src.to_s)
 
           begin

data/lib/samagotchi/model_profile.rb

@@ -227,7 +227,7 @@ module Samagotchi
       host = parsed.host_name
       return nil unless host
       # Declared under hosts.<name>.models: served whatever the host lists.
-      return nil if hosts[host.to_s.strip.downcase]&.dig(:models)&.key?(parsed.id.to_s.strip.downcase)
+      return nil if hosts[host.to_s.strip.downcase]&.models&.key?(parsed.id.to_s.strip.downcase)
 
       list = lists.read(env: env)[host.to_s.strip.downcase]
       return nil if list.nil? || list.stale? || list.known?(parsed.id)
@@ -433,10 +433,10 @@ module Samagotchi
       end
 
       names.map(&:downcase).uniq.each do |key|
-        setting = models[key]
-        next unless setting && setting[:profile]
+        configured_profile = models[key]&.profile
+        next unless configured_profile
 
-        profile = configured(setting[:profile], "models: #{key}")
+        profile = configured(configured_profile, "models: #{key}")
         return Resolution.new(profile: profile, source: :config, detail: "models: #{key}", retry: false) if profile
       end
 

data/lib/samagotchi/model_settings.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "config"
+require_relative "llm_context_strategy"
+
+module Samagotchi
+  # One config.yml models: entry (per-model settings keyed by model id or
+  # alias), parsed and checked; ConfigFile.model_settings holds them by
+  # downcased key. Each field is nil when unset: profile kept as written
+  # (downcased; ModelProfile.resolve validates it), vision true/false,
+  # sampling a request-field map, thinking a level, window_tokens, and the
+  # LLM context strategy, apply rule and budget (LLMContextStrategy). The
+  # same per-model fields a hosts: entry carries (HostConfig).
+  ModelSettings = Data.define(:profile, :vision, :sampling, :thinking, :window_tokens,
+                              :llm_context_strategy, :llm_context_apply, :llm_context_budget_tokens) do
+    # Every field may be left out (nil).
+    def initialize(**fields)
+      super(**members.to_h { |m| [m, nil] }, **fields)
+    end
+
+    # A models: entry as written, or nil when it is not a map (or the key is
+    # blank). A bad value warns, naming the entry, and is left unset.
+    # @param key [String] the downcased model id or alias
+    # @param raw [Hash] string or symbol keys
+    # @return [ModelSettings, nil]
+    def self.parse(key, raw)
+      return nil if key.to_s.empty? || !raw.is_a?(Hash)
+
+      value = ->(name) { raw.key?(name.to_s) ? raw[name.to_s] : raw[name.to_sym] }
+      where = "models: #{key}"
+      profile = value.call(:profile).to_s.strip.downcase
+      new(profile: profile.empty? ? nil : profile,
+          vision: ConfigFile.vision_flag(value.call(:vision), where),
+          sampling: ConfigFile.sampling_map(value.call(:sampling), where),
+          thinking: Thinking.level(value.call(:thinking), where),
+          window_tokens: ConfigFile.window_tokens(value.call(:window_tokens), where),
+          llm_context_strategy: LLMContextStrategy.parse(value.call(LLMContextStrategy::KEY), where),
+          llm_context_apply: LLMContextStrategy.parse_apply(value.call(LLMContextStrategy::APPLY_KEY), where),
+          llm_context_budget_tokens: LLMContextStrategy.parse_budget(value.call(LLMContextStrategy::BUDGET_KEY), where))
+    end
+  end
+
+  # One field ConfigFile.model_setting found: the models: key that set it
+  # and its value.
+  ModelSetting = Data.define(:key, :value)
+end

data/lib/samagotchi/plugin/context.rb

@@ -20,15 +20,15 @@ module Samagotchi
     # the answer text.
     # +messages_partial+ says whether +messages+ leaves out a running turn;
     # +model_name+ (the session's resolved model ref, live after /model) and
-    # +state_dir+ are what ctx.sessions forks with, and +llm_context+ (the
-    # session's own LLMContextOverride, nil without one), which a fork copies; +model_key+ is the
+    # +state_dir+ are what ctx.sessions forks with, and +setup+ (the
+    # session's own SessionSetup), which a fork copies; +model_key+ is the
     # model's memory overlay key (ctx.model, ctx.model_key).
     # +steer+ takes (text, label), +stop_turn+ and +stop_generation+
     # (reason, label), each true when it acted on a running turn.
     # +frontend+ returns the Engine's interface (:repl, :worker,
     # :non_interactive), which ctx.frontend names for plugins.
     Host = Struct.new(:session_id, :cwd, :messages, :messages_partial, :notify, :ask_user, :cancelled, :card,
-                      :ask_model, :model_name, :model_key, :state_dir, :scratch, :llm_context, :steer, :stop_turn, :stop_generation,
+                      :ask_model, :model_name, :model_key, :state_dir, :scratch, :setup, :steer, :stop_turn, :stop_generation,
                       :frontend, keyword_init: true)
 
     # ctx.ask_model failed: the model couldn't be reached, timed out, or

data/lib/samagotchi/plugin/sessions.rb

@@ -32,7 +32,7 @@ module Samagotchi
       # Start a child session from +messages+ (usually ctx.messages plus
       # more). With no prompt the child waits idle for the user; with one it
       # runs it as its first turn, and counts against session.max_children.
-      # It keeps this session's own llm_context values (Session#llm_context).
+      # It keeps this session's own setup (SessionSetup: its llm_context values).
       # Each image a message names is copied into the child, or dropped with
       # a note in its message when its file is gone.
       # @param messages [Array<Hash>] the child's conversation to start with
@@ -54,7 +54,7 @@ module Samagotchi
           prompt: prompt, working_directory: @host.cwd.call || Dir.pwd, model_name: @host.model_name&.call,
           parent_id: parent_id, messages: Array(messages).map { |message| unfrozen(message) }, title: title,
           images_from: Session.session_dir(parent_id, state_dir: state_dir), state_dir: state_dir,
-          llm_context: @host.llm_context&.call
+          setup: @host.setup&.call || SessionSetup.new
         )
         child.id
       end

data/lib/samagotchi/queued_command.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Samagotchi
+  # A session command on its way from the Bridge (POST /command, a command
+  # sent as a message, the worker's own Bridge#queue_command) to the
+  # worker's command queue. +card+: a card's action (the step-limit
+  # question's answer), whose line the UIs leave out. The worker adds
+  # where it waits (Worker#on_command): +mid_turn+ (the policy it got:
+  # :queue, :refuse, :loop), +after_seq+ (the event count then, so a
+  # turn's end knows it came before) and +after_file+ (the input file it
+  # runs after, a basename).
+  QueuedCommand = Data.define(:command_id, :client_id, :line, :card, :mid_turn, :after_seq, :after_file) do
+    def initialize(command_id:, line:, client_id: nil, card: false, mid_turn: nil, after_seq: nil, after_file: nil) = super
+
+    # A new command with a fresh id.
+    def self.mint(line, client_id: nil, card: false)
+      new(command_id: SecureRandom.uuid, client_id: client_id, line: line, card: card ? true : false)
+    end
+
+    # The fields its command_queued and command_ran name: card only when
+    # it is a card's.
+    # @return [Hash]
+    def event_fields
+      fields = { command_id: command_id, client_id: client_id, line: line }
+      fields[:card] = true if card
+      fields
+    end
+
+    # Whether it waits for the running turn's end (its line was shown at
+    # its command_queued).
+    def waits_for_turn_end? = mid_turn == :queue
+  end
+end

data/lib/samagotchi/reminder_store.rb

@@ -104,21 +104,6 @@ module Samagotchi
       end
     end
 
-    # Mark a reminder as fired — resets its next_fire_at to now + interval.
-    # Called by Engine after a due reminder has been delivered.
-    # @param name [String] the reminder name
-    def mark_fired(name)
-      name = name.to_s.strip
-      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      @mutex.synchronize do
-        r = @reminders[name]
-        if r
-          r[:last_fire_at] = now
-          r[:next_fire_at] = now + (r[:interval_minutes] * 60)
-        end
-      end
-    end
-
     # Mark multiple reminders as fired — resets each next_fire_at to now + interval.
     # Called by Engine after injecting multiple due reminders (batch operation).
     # Thread-safe, single lock acquisition.
@@ -137,18 +122,6 @@ module Samagotchi
       end
     end
 
-    # Get the description of a due reminder (for injection into the system prompt).
-    # Called by Engine during run_turn. Thread-safe.
-    # @param name [String] the reminder name
-    # @return [String, nil] the description, or nil if not found
-    def get_description(name)
-      name = name.to_s.strip
-      @mutex.synchronize do
-        r = @reminders[name]
-        r[:description] if r
-      end
-    end
-
     # Clear all reminders.
     # Called when the session ends or the engine is reset.
     def clear_all