samagotchi 0.6.0 → 0.8.0

data/lib/samagotchi/bundle_command.rb

@@ -94,6 +94,9 @@ module Samagotchi
         return 1
       end
       expanded_source = expand_source(source)
+      if Samagotchi::MemoryBundle::Profile.shipped_meta?(expanded_source)
+        return install_profile(expanded_source, scope: scope, force: force, dry_run: false, word: "Install")
+      end
       bundle_name = begin
         bundle_name_for(expanded_source)
       rescue Samagotchi::MemoryBundle::SourceNormalizer::UnknownSourceError => e
@@ -139,6 +142,9 @@ module Samagotchi
         return 1
       end
       expanded_source = expand_source(source)
+      if Samagotchi::MemoryBundle::Profile.shipped_meta?(expanded_source)
+        return install_profile(expanded_source, scope: scope, force: force, dry_run: dry_run, word: "Upgrade")
+      end
       bundle_name = begin
         bundle_name_for(expanded_source)
       rescue Samagotchi::MemoryBundle::SourceNormalizer::UnknownSourceError => e
@@ -238,6 +244,9 @@ module Samagotchi
       # Propagate overrides
       Samagotchi::MemoryBundle::Uninstaller.system_dir_override = Samagotchi::MemoryBundle::Installer.system_dir_override
       Samagotchi::MemoryBundle::Uninstaller.project_dir_base_override = Samagotchi::MemoryBundle::Installer.project_dir_base_override
+      data = Samagotchi::MemoryBundle::Provenance.new(name: bundle_name).read
+      return uninstall_profile(bundle_name, force: force) if Samagotchi::MemoryBundle::Profile.installed_meta?(bundle_name, data)
+
       uninstaller = Samagotchi::MemoryBundle::Uninstaller.new(name: bundle_name, scope: scope, force: force)
       begin
         uninstaller.run
@@ -252,6 +261,47 @@ module Samagotchi
       end
     end
 
+    # install/upgrade of a shipped profile: its new members (Profile).
+    def install_profile(dir, scope:, force:, dry_run:, word:)
+      name = File.basename(dir)
+      if scope.to_s.strip.downcase == "project"
+        @stderr.puts "#{word} failed: #{name} is a profile: its bundles install system-wide (drop --scope project)"
+        return 1
+      end
+      result = Samagotchi::MemoryBundle::Profile.install(dir, dry_run: dry_run, force: force)
+      @stdout.puts "#{result.name} v#{result.version} (profile)"
+      lines = []
+      lines << "#{dry_run ? "would install" : "installed"}: #{result.installed.join(", ")}" unless result.installed.empty?
+      lines << "already installed: #{result.already.join(", ")}" unless result.already.empty?
+      result.skipped.each { |member, why| lines << "skipped #{member}: #{why}" }
+      result.failed.each { |member, why| lines << "failed #{member}: #{why}" }
+      lines << "nothing new to install" if lines.empty?
+      lines.each { |line| @stdout.puts "  #{line}" }
+      @stdout.puts "(dry-run: no changes written)" if dry_run
+      result.failed? ? 1 : 0
+    rescue Samagotchi::MemoryBundle::Manifest::ValidationError => e
+      @stderr.puts "#{word} failed: #{e.message}"
+      1
+    end
+
+    # uninstall of a profile: its recorded members, then itself (Profile).
+    def uninstall_profile(name, force:)
+      result = Samagotchi::MemoryBundle::Profile.uninstall(name, force: force)
+      if result.gone
+        @stdout.puts "Uninstalled bundle '#{name}'"
+        @stdout.puts "Removed: #{result.removed.join(", ")}" unless result.removed.empty?
+        return 0
+      end
+      @stdout.puts "Removed from #{name}: #{result.removed.join(", ")}" unless result.removed.empty?
+      result.blocked.each { |member, why| @stdout.puts "Kept #{member}: #{why}" }
+      @stderr.puts "Uninstall failed: #{name} stays installed until #{result.blocked.keys.join(", ")} goes " \
+                   "(chi bundle uninstall #{name} --force)"
+      1
+    rescue Samagotchi::MemoryBundle::Uninstaller::UninstallError => e
+      @stderr.puts "Uninstall failed: #{e.message}"
+      1
+    end
+
     def status(rest)
       name = rest.find { |a| !a.start_with?("--") }
       require "json"
@@ -297,26 +347,26 @@ module Samagotchi
           @stdout.puts "    not loaded: #{plugin[:requires_failure]}" if plugin[:requires_failure]
         end
         st[:needs].each { |need| @stdout.puts "  #{Samagotchi::MemoryBundle::Status.need_line(need)}" }
-      else
-        bundles_dir = Samagotchi::MemoryBundle::Provenance.bundles_dir
-        unless File.directory?(bundles_dir)
-          @stdout.puts "No installed bundles."; return 0
+        (st[:provenance][:includes] || []).each do |member|
+          state = Samagotchi::MemoryBundle::Provenance.new(name: member.to_s).installed? ? "installed" : "not installed: chi bundle install #{member}"
+          @stdout.puts "  includes #{member} [#{state}]"
         end
-        entries = Dir.entries(bundles_dir).reject { |e| e.start_with?(".") }
-        if entries.empty?
-          @stdout.puts "No installed bundles."
-        else
-          entries.sort.each do |bname|
-            st = Samagotchi::MemoryBundle::Status.bundle_status(bname)
-            next unless st
-            mods = st[:files].values.count { |v| v[:modified] || v[:missing] }
-            hooks_count = (st[:provenance][:hooks] || {}).size
-            hook_info = hooks_count > 0 ? " hooks=#{hooks_count}" : ""
-            plugin = st[:plugin]
-            mods += 1 if plugin && (plugin[:state] != "ok" || plugin[:requires_failure])
-            plugin_info = plugin ? " plugin=#{plugin[:file]}" : ""
-            @stdout.puts "  #{bname} v#{st[:provenance][:version]} scope=#{st[:scope]} files=#{st[:files].size}#{hook_info}#{plugin_info} issues=#{mods}"
-          end
+      else
+        bundles = Samagotchi::MemoryBundle::Provenance.each_installed.to_a
+        @stdout.puts "No installed bundles." if bundles.empty?
+        bundles.each do |bname, data|
+          next @stdout.puts("  #{bname} (manifest.json unreadable)") if data[:error]
+
+          st = Samagotchi::MemoryBundle::Status.bundle_status(bname)
+          mods = st[:files].values.count { |v| v[:modified] || v[:missing] }
+          hooks_count = (st[:provenance][:hooks] || {}).size
+          hook_info = hooks_count > 0 ? " hooks=#{hooks_count}" : ""
+          plugin = st[:plugin]
+          mods += 1 if plugin && (plugin[:state] != "ok" || plugin[:requires_failure])
+          plugin_info = plugin ? " plugin=#{plugin[:file]}" : ""
+          includes = st[:provenance][:includes]
+          includes_info = includes ? " includes=#{includes.join(",")}" : ""
+          @stdout.puts "  #{bname} v#{st[:provenance][:version]} scope=#{st[:scope]} files=#{st[:files].size}#{hook_info}#{plugin_info}#{includes_info} issues=#{mods}"
         end
       end
       return 0
@@ -432,7 +482,8 @@ module Samagotchi
         @stdout.puts "Installed:"
         installed.each do |b|
           next @stdout.puts("  #{b.name.ljust(name_w)}  (#{b.error})") if b.error
-          line = "  #{b.name.ljust(name_w)}  #{"v#{b.version || "?"}".ljust(ver_w)}  scope=#{b.scope || "?"}  files=#{b.files}  installed=#{b.installed_at || "?"}"
+          line = "  #{b.name.ljust(name_w)}  #{"v#{b.version || "?"}".ljust(ver_w)}  scope=#{b.scope || "?"}  " \
+                 "#{b.includes ? profile_members(b.includes, installed) : "files=#{b.files}"}  installed=#{b.installed_at || "?"}"
           line += "  (shipped v#{b.upgrade.version}: chi bundle upgrade #{b.upgrade.source})" if b.upgrade
           @stdout.puts line
         end
@@ -442,12 +493,21 @@ module Samagotchi
         @stdout.puts ""
         @stdout.puts "Available (shipped with chi, install with: chi bundle install <name>):"
         available.each do |s|
-          @stdout.puts "  #{s.source.ljust(name_w)}  #{"v#{s.version}".ljust(ver_w)}  #{s.description}".rstrip
+          members = s.includes.empty? ? "" : " (#{s.includes.join(", ")})"
+          @stdout.puts "  #{s.source.ljust(name_w)}  #{"v#{s.version}".ljust(ver_w)}  #{s.description}#{members}".rstrip
         end
       end
       return 0
     end
 
+    # An installed profile's list cell: its recorded members still
+    # installed, and the ones left out (uninstalled by the user).
+    def profile_members(members, installed)
+      names = installed.map(&:name)
+      here, gone = members.partition { |m| names.include?(m) }
+      "includes=#{here.join(",")}#{gone.empty? ? "" : "  left out=#{gone.join(",")}"}"
+    end
+
     def build(rest)
       scope = nil
       name = nil

data/lib/samagotchi/bundle_needs.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "json"
-
 module Samagotchi
   autoload :MutedMemories, File.expand_path("muted_memories", __dir__)
   autoload :Log, File.expand_path("log", __dir__)
@@ -67,15 +65,8 @@ module Samagotchi
     # entry name → marker, for the installed bundles of +scope+ with a
     # missing need. A manifest.json or needs: that doesn't parse is skipped.
     def self.entry_markers(scope, path:, bundles_dir:)
-      return {} unless Dir.exist?(bundles_dir)
-
-      Dir[File.join(bundles_dir, "*", "manifest.json")].sort.each_with_object({}) do |mjson, acc|
-        data = begin
-          JSON.parse(File.read(mjson), symbolize_names: true)
-        rescue JSON::ParserError, SystemCallError
-          next
-        end
-        next unless data.is_a?(Hash) && data[:scope].to_s == scope.to_s
+      MemoryBundle::Provenance.each_installed(dir: bundles_dir).each_with_object({}) do |(_name, data), acc|
+        next if data[:error] || data[:scope].to_s != scope.to_s
         next unless data[:needs].is_a?(Array) && !data[:needs].empty?
 
         needs = begin

data/lib/samagotchi/bundles/core/manifest.yml

@@ -0,0 +1,11 @@
+---
+name: core
+version: 0.1.0
+scope: system
+description: "Recommended safety set"
+trust_level: reviewed
+requires_chi: ">= 0.8.0"
+includes:
+- loop-guard
+- check-in
+- guardrails

data/lib/samagotchi/bundles/dev/manifest.yml

@@ -0,0 +1,13 @@
+---
+name: dev
+version: 0.1.0
+scope: system
+description: "Developer tools"
+trust_level: reviewed
+requires_chi: ">= 0.8.0"
+includes:
+- known-names
+- mcp
+- btw
+- skills
+- source-links

data/lib/samagotchi/bundles/system/identity.md

@@ -10,3 +10,4 @@
   Before a task that a `skill_*` in the memory index matches, read it and follow it.
   When a step turned out different (a renamed command, an extra step, a gotcha), update the skill in the same turn: fix those steps, keep the rest as it was, add a dated Changelog line.
   When a skill's step fails or its file/command is missing, find out why (look around, read nearby READMEs) before skipping it; a step that says stop means stop and ask.
+  While following a skill, when anything looks unexpected (a check fails, output differs from what a step says, a warning the skill doesn't mention): stop, don't improvise a fix, tell the user what you saw and ask how to go on. Read each command's whole output, including warnings, before the next step.

data/lib/samagotchi/bundles/system/manifest.yml

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.6.0
+version: 0.8.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:
-  identity.md: sha256:b7d59a1e824f0918c28a38d40105e8abd1ff68ebab1810fd1dcf52cd3b72e7c0
+  identity.md: sha256:d6f40d5e44096537d337c4ffda86823446f8b59eb8b8cc47014e97ec16f019c9
   self_map.md: sha256:93c788fadaf98adeb8946b4a357d2372bd6ebb439042d7cef8dda8fb44187315
   config_modification_protocol.md: sha256:24e95727488daa80ac3008e020d8be098c7a1882153b7a61aba35450f72b86b7
-  memory_guide.md: sha256:43be77156562f1eac369c248045e35ccd89e87d1f7f95a9286be72521b058e87
+  memory_guide.md: sha256:50c076fb6bda7ed010877ff664bb2e9e904418fe08b058ebaa911d4e82e9a683
   delegated.md: sha256:0a71d5dfa7127df2d51cb5f0e7214240ed88777e36559430a8724c796d7ae561

data/lib/samagotchi/bundles/system/memory_guide.md

@@ -66,7 +66,7 @@ Shape (plain Markdown, no frontmatter):
 - **When to use it** is the `description:` of `memory_write`: one line starting with the task ("Release a new version of this repo: verify, tag, push"). It is what the index shows, so it is how you find the skill later.
 - **Scope**: `project` by default; `system` when the user asks, or when the skill is clearly not about this project.
 - **Saving**: on a request to keep how something was done ("let's memorize this", "save this as a skill", `/skill save`), write it at once, then show it briefly. On an ambiguous one ("I like how we did that") you may ask whether to save it.
-- **Following**: before a task a `skill_*` index line matches, `memory_read` it and follow its steps. A step that fails or names a missing file or command: find out why (look around, read nearby READMEs) before skipping it; a step that says stop means stop and ask.
+- **Following**: before a task a `skill_*` index line matches, `memory_read` it and follow its steps. A step that fails or names a missing file or command: find out why (look around, read nearby READMEs) before skipping it; a step that says stop means stop and ask. When anything looks unexpected (a check fails, output differs from what a step says, a warning the skill doesn't mention): stop, don't improvise a fix, tell the user what you saw and ask. Read each command's whole output, including warnings, before the next step.
 - **Updating**: when a step turned out different, rewrite the skill with `memory_write` in the same turn: fix those steps, keep the rest as it was, add a dated Changelog line. No confirmation needed.
 - **The `skills` bundle** (`chi bundle install skills`, optional) adds `/skill save [name] [--system]`, `/skill list`, `/skill show <name>`, `/skill diff <name> [N]`; it keeps older versions and shows a short diff line after each update.
 
@@ -78,6 +78,7 @@ Bundles are versioned directories/zips/tar.gz/git URLs with a `manifest.yml` and
 - Integrity: each file's sha256 is recorded at install; a hook/plugin/rule file changed afterwards is not loaded (rules: every call denied) until reinstalled. It is an integrity check, not proof of authorship.
 - Installing = trusting its Ruby code (hooks, plugin), like a gem. Install only copies; the code runs at the next session start (`Engine.new`), so a running worker needs a restart to pick it up.
 - A bundle without `*.md` (btw, mcp, loop-guard) adds no line to the prompt's memory index.
+- Profiles are shipped bundles with only `includes:` (bundle names): `core` (loop-guard, check-in, guardrails; `chi bootstrap` installs it) and `dev` (known-names, mcp, btw, skills, source-links). `chi bundle install core` installs the ones not installed and records them; a bundle the user uninstalled stays out on a later install, upgrade or `chi update`, which install only bundles new to the profile. `chi bundle uninstall core` removes its recorded bundles, then core (`docs/memory.md` "Bundle profiles").
 
 ### CLI — `chi bundle`
 
@@ -88,7 +89,7 @@ Bundles are versioned directories/zips/tar.gz/git URLs with a `manifest.yml` and
 | `uninstall <bundle> [--force]` | Removes bundle files (skips locally edited files unless `--force`) and `index.md` lines, deletes provenance dir. |
 | `status [<bundle>]` | Provenance + per-file `ok|modified|missing|no-index` vs stored checksum and base snapshot. |
 | `diff <bundle> [file]` | Prints `base` (provenance snapshot) vs `current` (on-disk) for each file. |
-| `list` | Lists installed bundles (`name v<version> scope files installed_at`, plus the shipped version when newer) and the bundles shipped with chi that are not installed (`install <name>` installs one). |
+| `list` | Lists installed bundles (`name v<version> scope files installed_at`, plus the shipped version when newer) and the bundles shipped with chi that are not installed (`install <name>` installs one), grouped under their profile; an installed profile shows `includes=` and `left out=`. |
 | `build [--scope system\|project] [--name NAME] [--version VER] [--description DESC] [--out PATH] [FILES...]` | **Inverse of install** — builds a shareable bundle from local memories and installed hooks. Infers `zip` vs `dir`/`tar.gz` from `--out` extension; default `chi_system_memories.zip` (system) or `chi_<repo>_memories.zip` (project, named after the project root) v`1.0.0` in `Dir.pwd`. `FILES...` is an optional allowlist of memory basenames (`identity` or `identity.md`); if omitted, all `*.md` except `index.md`/hidden/non-md are included. Installed hooks are copied to `hooks/` with their manifest metadata. Computes `sha256:` checksums and writes `manifest.yml` via `Manifest.write`. No provenance write. |
 
 **Scope resolution for install/build:**

data/lib/samagotchi/client.rb

@@ -6,6 +6,7 @@ require "uri"
 require_relative "config"
 require_relative "cancellation_controller"
 require_relative "llm/http"
+require_relative "llm/utf8_scrub"
 require_relative "vision_context"
 require_relative "vision_support"
 require_relative "sampling_settings"
@@ -203,7 +204,7 @@ module Samagotchi
                  images: [], sampling: {})
       images = Array(images)
       request = { stop: stop, n_predict: n_predict, model: model, sampling: sampling }
-      return stream_completion(scrub_utf8(prompt), request, on_chunk, cancel_controller, on_retry) if images.empty?
+      return stream_completion(LLM::Utf8Scrub.call(prompt), request, on_chunk, cancel_controller, on_retry) if images.empty?
 
       # The media marker is random per server process: a restart between the
       # /props read and the request makes the prompt fail to tokenize, so
@@ -211,7 +212,7 @@ module Samagotchi
       attempts = 0
       begin
         attempts += 1
-        payload_prompt = { prompt_string: scrub_utf8(prompt.gsub(ImagePlan::NATIVE_PLACEHOLDER, media_marker!(model))),
+        payload_prompt = { prompt_string: LLM::Utf8Scrub.call(prompt.gsub(ImagePlan::NATIVE_PLACEHOLDER, media_marker!(model))),
                            multimodal_data: images }
         stream_completion(payload_prompt, request, on_chunk, cancel_controller, on_retry)
       rescue LLM::BadRequest => e
@@ -403,27 +404,6 @@ module Samagotchi
       (sampling || {}).reject { |key, value| value.nil? || ConfigFile::SAMPLING_RESERVED_KEYS.include?(key.to_s) }
     end
 
-    # Conversation content (system prompt + tool responses + model output) can
-    # contain invalid UTF-8 — e.g. a shell/file op writes a garbled multibyte
-    # sequence (a truncated em-dash, a stray replacement byte). `JSON#to_json`
-    # raises `JSON::GeneratorError` on such input, which would abort the whole
-    # turn. Scrub the payload first: only offending bytes are replaced with "?",
-    # every valid UTF-8 string passes through untouched. Non-UTF-8 encodings are
-    # left alone because `#to_json` already handles them without raising.
-    def scrub_utf8(obj)
-      case obj
-      when String
-        str = obj.to_s
-        str.encoding == Encoding::UTF_8 && !str.valid_encoding? ? str.scrub("?") : str
-      when Array
-        obj.map { |element| scrub_utf8(element) }
-      when Hash
-        obj.each_with_object({}) { |(key, value), memo| memo[scrub_utf8(key)] = scrub_utf8(value) }
-      else
-        obj
-      end
-    end
-
     # Resolve a user-facing SAMAGOTCHI_DEFAULT_MODEL selector to the exact id oMLX
     # expects in the request body (an id from its `/v1/models` list).
     #

data/lib/samagotchi/config.rb

@@ -5,7 +5,9 @@ require "json"
 require "fileutils"
 require "uri"
 require "set"
+require_relative "atomic_file"
 require_relative "log"
+require_relative "paths"
 
 module Samagotchi
   # Parses the thinking: levels of host and model entries (it needs Config).
@@ -88,7 +90,7 @@ module Samagotchi
       Entry.new(key: "session.idle_exit_minutes",     yaml_path: %w[session idle_exit_minutes],     type: :float,   default: 30.0, expose: %i[env config cli]),
       # Plain `chi` runs like `chi --shared` (bin/chi, LaunchMode); false, or --no-shared per run, keeps the plain REPL. No CLI flag: that would duplicate --shared.
       Entry.new(key: "session.shared",                yaml_path: %w[session shared],                type: :bool,    default: true,  expose: %i[env config]),
-      # false: a session nothing happened in is deleted when it is left (SessionManager.empty_session?).
+      # false: a session nothing happened in is deleted when it is left (SessionManager.discardable?).
       Entry.new(key: "session.keep_empty",            yaml_path: %w[session keep_empty],            type: :bool,    default: false, expose: %i[env config]),
       # The most sessions one session may have delegated and still running (the delegate tool); a guard against a runaway model.
       Entry.new(key: "session.max_children",          yaml_path: %w[session max_children],          type: :integer, default: 4,     expose: %i[env config]),
@@ -135,6 +137,11 @@ module Samagotchi
       Entry.new(key: "update.gem",               yaml_path: %w[update gem],               type: :bool,    default: true,            expose: %i[env config]),
       Entry.new(key: "update.bundles",           yaml_path: %w[update bundles],           type: :bool,    default: true,            expose: %i[env config]),
       Entry.new(key: "update.desktop",           yaml_path: %w[update desktop],           type: :bool,    default: true,            expose: %i[env config]),
+      # The desktop helper's kitty targets (Desktop::MacOS.kitty_settings): listen_on copied from kitty.conf (unset = none),
+      # the kitty binary, and the foreground programs listed, "|"-separated (a YAML list works too; "*" = every window).
+      Entry.new(key: "kitty.listen_on",          yaml_path: %w[kitty listen_on],          type: :string, default: nil,              expose: %i[env config]),
+      Entry.new(key: "kitty.binary",             yaml_path: %w[kitty binary],             type: :string, default: "/Applications/kitty.app/Contents/MacOS/kitty", expose: %i[env config]),
+      Entry.new(key: "kitty.agents",             yaml_path: %w[kitty agents],             type: :string, default: "claude|codex|gemini|aider|opencode|cursor-agent|amp|goose", expose: %i[env config]),
 
       Entry.new(key: "read.truncate_at_bytes",        yaml_path: %w[read truncate_at_bytes],        type: :integer, default: 65_536,   expose: %i[env config cli]),
       Entry.new(key: "read.preview_bytes",            yaml_path: %w[read preview_bytes],            type: :integer, default: 12_288,   expose: %i[env config cli]),
@@ -504,7 +511,6 @@ module Samagotchi
   # (hosts, model_aliases) and the recap section resolution. All of it
   # shares Config's precedence (CLI > ENV > file > default) for scalars.
   module ConfigFile
-    XDG_CONFIG_HOME_ENV = "XDG_CONFIG_HOME"
     CONFIG_DIR = "samagotchi"
     CONFIG_FILE = "config.yml"
     MODEL_ALIASES_KEY = "model_aliases"
@@ -630,9 +636,7 @@ module Samagotchi
     end
 
     def config_dir(env: ENV)
-      config_home = env.fetch(XDG_CONFIG_HOME_ENV, "").to_s.strip
-      base_dir = config_home.empty? ? File.expand_path("~/.config") : config_home
-      File.join(base_dir, CONFIG_DIR)
+      File.join(Paths.config_home(env: env), CONFIG_DIR)
     end
 
     def global_path(env: ENV)
@@ -911,9 +915,7 @@ module Samagotchi
         raw_data["default"] = { "model" => resolved }
       end
       FileUtils.mkdir_p(File.dirname(path))
-      tmp = "#{path}.tmp"
-      File.write(tmp, YAML.dump(raw_data))
-      File.rename(tmp, path)
+      AtomicFile.write(path, YAML.dump(raw_data))
       clear_yaml_cache!(path)
       Samagotchi::Config.reload!(cli_overrides: Samagotchi::Config.cli_overrides)
       true
@@ -1038,9 +1040,7 @@ module Samagotchi
       normalized[lowered_key] = resolved_model
 
       FileUtils.mkdir_p(File.dirname(path))
-      tmp = "#{path}.tmp"
-      File.write(tmp, YAML.dump(raw_data))
-      File.rename(tmp, path)
+      AtomicFile.write(path, YAML.dump(raw_data))
       clear_yaml_cache!(path)
       previous
     end

data/lib/samagotchi/context_note.rb

@@ -15,7 +15,7 @@ module Samagotchi
 
     module_function
 
-    # Takes SessionManager.read_note's keys.
+    # Takes SessionInbox.read_note's keys.
     # @return [Hash] the conversation message
     def message(note_id:, text:, source:, created_at: nil, from_session: nil, from_cwd: nil, **)
       { role: "system", kind: KIND, note_id: note_id, source: source, from_session: from_session,

data/lib/samagotchi/context_status.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+require_relative "config"
+require_relative "context_usage"
+require_relative "context_window"
+
+module Samagotchi
+  # One turn's context tracking for KernelLoop#run: how full the window is
+  # before each request (the server's last prompt count plus an estimate for
+  # what the turn appended since, else a chars-per-token estimate), the
+  # bucket that puts it in, and what comes of that:
+  #
+  # - the status line's value (#display), every request and again from the
+  #   server's final counts after each generation;
+  # - a :context_status stream event (#observe's return), on a bucket change
+  #   or every context.status_cadence requests;
+  # - the model's own short line (#take_guidance), once per rise into a
+  #   bucket whose guidance asks for a change (the second threshold up).
+  #
+  # The context.* settings are read once, when the tracker is built (one per
+  # run, so a changed setting counts from the next turn).
+  class ContextStatus
+    STATUS_PREFIX = "CONTEXT_STATUS"
+    # The model's own line about its context (a tail system message, kind
+    # LINE_KIND).
+    LINE_PREFIX = "[CONTEXT: "
+    LINE_KIND = "context"
+    GUIDANCE_FROM_RANK = 2
+
+    DEFAULT_CHARS_PER_TOKEN = 4.0
+    DEFAULT_THRESHOLDS = [20, 40, 60, 80].freeze
+
+    def self.enabled?
+      Config.get("context.status") != false
+    end
+
+    # Healthy to critical; the top configured bucket gets the last, the
+    # ones below it the ones before, and the first bucket (and the one
+    # under it) is always healthy.
+    GUIDANCE = [
+      "context healthy — proceed normally",
+      "context moderate — prefer targeted and range reads over full-file dumps",
+      "context elevated — be concise, prefer range reads, avoid re-reading large files",
+      "context critical — summarize aggressively, avoid large outputs, delegate broad work to subagents"
+    ].freeze
+
+    # @param bucket [String] "under<N>" or "<N>plus"
+    # @param thresholds [Array<Integer>] the configured ones, sorted
+    def self.guidance(bucket, thresholds = DEFAULT_THRESHOLDS)
+      rank = bucket_rank(bucket, thresholds)
+      level = rank < GUIDANCE_FROM_RANK ? 0 : GUIDANCE.size - 1 - (thresholds.size - rank)
+      GUIDANCE[level.clamp(0, GUIDANCE.size - 1)]
+    end
+
+    # 0 for the bucket under the first threshold, then one per threshold.
+    def self.bucket_rank(bucket, thresholds)
+      return 0 if bucket.nil? || bucket.to_s.start_with?("under")
+
+      (thresholds.index(bucket.to_s.delete_suffix("plus").to_i) || -1) + 1
+    end
+
+    # The bucket of the last status line +conversation+ holds: the model's
+    # own line, or a legacy session's injected telemetry.
+    def self.last_bucket(conversation)
+      message = conversation.reverse.find do |entry|
+        content = entry[:content].to_s
+        entry[:role] == "system" && (content.start_with?(STATUS_PREFIX) || content.start_with?(LINE_PREFIX))
+      end
+      return nil unless message
+
+      match = message[:content].match(/\bbucket=([a-z0-9_]+)/)
+      match && match[1]
+    end
+
+    # @param conversation [Array<Hash>] the turn's conversation so far (its
+    #   last status line's bucket is where rises count from)
+    def initialize(conversation: [])
+      @enabled = self.class.enabled?
+      chars_per_token = Config.get("context.chars_per_token").to_f
+      @chars_per_token = chars_per_token.positive? ? chars_per_token : DEFAULT_CHARS_PER_TOKEN
+      parsed = Config.get("context.status_thresholds").to_s.split(",").map { |value| value.strip.to_i }
+                     .select { |value| value.between?(1, 99) }.uniq.sort
+      @thresholds = parsed.empty? ? DEFAULT_THRESHOLDS : parsed
+      @cadence = [Config.get("context.status_cadence").to_i, 0].max
+      @last_bucket = self.class.last_bucket(conversation)
+      @server_usage = nil
+      @counted = nil
+      @display = nil
+      @guidance = nil
+    end
+
+    # @return [Hash, nil] the status line's value ({est_pct:, bucket:});
+    #   nil with context.status off or before the first request
+    attr_reader :display
+
+    def enabled? = @enabled
+
+    # Before a request: estimate +prompt+'s usage against +window+ (this
+    # request's ContextWindow::Resolved) and update the status line's
+    # value. A rise into a bucket that asks the model for a change leaves
+    # a line for #take_guidance.
+    # +image_tokens+: the images' estimate (their base64 is not in +prompt+).
+    #
+    # @return [Hash, nil] the :context_status event's fields (without
+    #   :type/:iteration) when the emit gate fires, else nil
+    def observe(prompt, iteration_index:, window:, image_tokens: 0)
+      return nil unless @enabled
+
+      usage = estimate(prompt, server_usage: @server_usage, window: window, image_tokens: image_tokens, counted: @counted)
+      bucket = bucket_for(usage[:estimated_pct])
+      # The status line's value, every iteration; the gate below decides
+      # only the event and the model's guidance line.
+      @display = { est_pct: usage[:estimated_pct], bucket: bucket }
+      emit = emit?(bucket: bucket, iteration_index: iteration_index)
+      previous_bucket = @last_bucket
+      @last_bucket = bucket
+      return nil unless emit
+
+      @guidance = guidance_message(usage: usage, bucket: bucket) if guidance_due?(previous_bucket, bucket)
+      { status: status_message(usage: usage, bucket: bucket), usage: usage, bucket: bucket, source: usage[:source] }
+    end
+
+    # @return [Hash, nil] the model's line from the last #observe (once)
+    def take_guidance
+      line = @guidance
+      @guidance = nil
+      line
+    end
+
+    # A stream payload's counts, kept for the next estimate.
+    # @return [Hash, nil] the payload's normalized counts, when it has any
+    def capture(payload)
+      normalized = ContextUsage.normalize(payload)
+      @server_usage = normalized if normalized
+      normalized
+    end
+
+    # After a generation: +usage+ is its own server counts (nil: none), for
+    # +prompt_chars+/+image_tokens+ as sent. The next estimate adds only
+    # what the turn appended since (answer, tool results), and the status
+    # line's value counts the answer. Without counts the pre-generation
+    # estimate stays.
+    def generation_done(usage, prompt_chars:, image_tokens:, window:)
+      return unless usage
+
+      @counted = { chars: prompt_chars, image_tokens: image_tokens }
+      value = display_for(used_tokens: usage[:total_tokens], window_tokens: usage[:context_window_tokens] || window&.tokens)
+      @display = value if value
+    end
+
+    # The status line's value ({est_pct:, bucket:}) for +used_tokens+ of
+    # +window_tokens+; nil without both, or with context.status off.
+    def display_for(used_tokens:, window_tokens:)
+      return nil unless @enabled
+      return nil unless ContextWindow.positive_integer?(used_tokens) && ContextWindow.positive_integer?(window_tokens)
+
+      pct = (used_tokens.to_f / window_tokens) * 100.0
+      { est_pct: pct, bucket: bucket_for(pct) }
+    end
+
+    # `window` is this request's ContextWindow::Resolved. A window the
+    # stream payload reports itself still wins.
+    # +counted+: the prompt the server's prompt_tokens counted ({chars:,
+    # image_tokens:}); what +prompt+ has on top of it (the answer, tool
+    # results since) is added as an estimate, so the value doesn't read low
+    # during a long tool loop. A prompt shorter than that one (trimmed) or
+    # none known: the server's count alone.
+    def estimate(prompt, window:, server_usage: nil, image_tokens: 0, counted: nil)
+      window_source = window.source
+      window_source = :server if server_usage && server_usage[:context_window_tokens]
+
+      if server_usage && server_usage[:prompt_tokens]
+        window_tokens = server_usage[:context_window_tokens] || window.tokens
+        used_tokens = server_usage[:prompt_tokens] + appended_tokens(prompt, image_tokens, counted)
+        source = "server"
+      else
+        window_tokens = window.tokens
+        used_tokens = (prompt.length / @chars_per_token).ceil + image_tokens
+        source = "estimate"
+      end
+
+      {
+        window_tokens: window_tokens,
+        window_source: window_source,
+        estimated_used_tokens: used_tokens,
+        estimated_remaining_tokens: [window_tokens - used_tokens, 0].max,
+        estimated_pct: (used_tokens.to_f / window_tokens) * 100.0,
+        source: source
+      }
+    end
+
+    private
+
+    # The estimate for what +prompt+ added since the +counted+ one.
+    def appended_tokens(prompt, image_tokens, counted)
+      return 0 unless counted
+
+      chars = prompt.length - counted[:chars]
+      return 0 unless chars.positive?
+
+      (chars / @chars_per_token).ceil + [image_tokens - counted[:image_tokens].to_i, 0].max
+    end
+
+    def bucket_for(estimated_pct)
+      bucket = "under#{@thresholds.first}"
+      @thresholds.each do |threshold|
+        bucket = "#{threshold}plus" if estimated_pct >= threshold
+      end
+      bucket
+    end
+
+    def bucket_rank(bucket) = self.class.bucket_rank(bucket, @thresholds)
+
+    # A rise (never a fall or a cadence tick) into a bucket whose guidance
+    # asks for a change. With no previous bucket (a first turn, a resumed
+    # session with no line yet), the first bucket counts as a rise from 0.
+    def guidance_due?(previous, bucket)
+      rank = bucket_rank(bucket)
+      rank >= GUIDANCE_FROM_RANK && rank > bucket_rank(previous)
+    end
+
+    def emit?(bucket:, iteration_index:)
+      bucket_changed = if @last_bucket.nil?
+                         bucket != "under#{@thresholds.first}"
+                       else
+                         bucket != @last_bucket
+                       end
+      cadence_due = @cadence.positive? && ((iteration_index + 1) % @cadence).zero?
+      bucket_changed || cadence_due
+    end
+
+    def guidance_message(usage:, bucket:)
+      how = usage[:source].to_s == "server" ? "as the server reports" : "estimated"
+      { role: "system", kind: LINE_KIND,
+        content: "#{LINE_PREFIX}about #{usage[:estimated_pct].to_f.round}% of the context window is in use " \
+                 "(#{how}; bucket=#{bucket}). #{self.class.guidance(bucket, @thresholds)}]" }
+    end
+
+    def status_message(usage:, bucket:)
+      format(
+        "%<prefix>s window_tokens=%<window>d window_src=%<window_src>s est_used_tokens=%<used>d est_remaining_tokens=%<remaining>d est_pct=%<pct>.1f bucket=%<bucket>s thresholds=%<thresholds>s src=%<src>s guidance=%<guidance>s",
+        prefix: STATUS_PREFIX,
+        window: usage[:window_tokens],
+        window_src: usage[:window_source] || "default",
+        used: usage[:estimated_used_tokens],
+        remaining: usage[:estimated_remaining_tokens],
+        pct: usage[:estimated_pct],
+        bucket: bucket,
+        thresholds: @thresholds.join(","),
+        src: usage[:source],
+        guidance: self.class.guidance(bucket, @thresholds)
+      )
+    end
+  end
+end