samagotchi 0.151.0 → 0.153.0

data/lib/samagotchi/bundle_command.rb

@@ -16,11 +16,14 @@ module Samagotchi
           Install a memory bundle from a directory, zip, tar archive, or git URL.
           Source is the path/URL to the bundle (dir/zip/tar.gz/git).
           --force overwrites existing entries (one that differs is copied to the trash first); default skips them.
+          A bundle whose requires_chi this chi doesn't meet is refused; --force installs it anyway.
 
-        upgrade <source> [--scope system|project] [--force] [--dry-run] [--agent|--no-agent]
+        upgrade <source|name> [--scope system|project] [--force] [--dry-run] [--agent|--no-agent]
           Upgrade a bundle (3-way: a file you didn't edit updates; one you edited takes a text
           merge, the old file in the bundle trash; a real conflict leaves it as it is).
+          A bare NAME upgrades the bundle installed under that name from the source it came from.
           --dry-run shows what would change. --agent launches interactive session on conflict.
+          A bundle whose requires_chi this chi doesn't meet is refused; --force installs it anyway.
 
         uninstall <bundle> [--scope system|project] [--force]
           Remove a bundle and its index entries (--force moves a locally edited file to the trash).
@@ -69,13 +72,19 @@ module Samagotchi
           Install a memory bundle from a directory, zip, tar archive, or git URL,
           or a bundle shipped with chi by name (see: chi bundle list).
           --force overwrites existing entries (one that differs is copied to the trash first); default skips them.
+          It also installs a bundle whose requires_chi this chi doesn't meet: without --force that install is
+          refused, and the bundle is not written anywhere.
         install --dev PATH
           Install the bundle in the local directory PATH as a link to it: its plugin, hooks, rules and scripts
           are PATH's own files (an edit applies at the next worker or chi web restart, with no re-install) and
           their sha256 isn't checked, for this bundle only. Its memories are copied; re-install with --force to
           pick up memory edits. Upgrade refuses it; uninstall removes the link, never PATH's files.
     TEXT
-    UPGRADE_HELP = "Usage: chi bundle upgrade <source> [--scope system|project] [--force] [--dry-run] [--agent|--no-agent]"
+    UPGRADE_HELP = <<~TEXT
+      Usage: chi bundle upgrade <source|name> [--scope system|project] [--force] [--dry-run] [--agent|--no-agent]
+        --force takes the bundle's file over an edited one, and installs a bundle whose requires_chi this chi
+        doesn't meet (without it such a bundle is refused).
+    TEXT
     UNINSTALL_HELP = "Usage: chi bundle uninstall <bundle> [--scope system|project] [--force]"
     BUILD_HELP = <<~TEXT
       Usage: chi bundle build [--scope system|project] [--name NAME] [--version VER] [--description DESC] [--out PATH] [FILES...]
@@ -210,7 +219,13 @@ module Samagotchi
         @stderr.puts UPGRADE_HELP
         return CLI::Exit::USAGE
       end
-      expanded_source = expand_source(source)
+      expanded_source, record = upgrade_source(source)
+      return 1 if expanded_source.nil?
+
+      # The record's source: said once, so it is clear which bundle and where
+      # it comes from when the name alone was given.
+      @stdout.puts "Upgrading #{record.name} from #{expanded_source}" if record
+
       if Samagotchi::MemoryBundle::Profile.shipped_meta?(expanded_source)
         return install_profile(expanded_source, scope: scope, force: force, dry_run: dry_run, word: "Upgrade")
       end
@@ -305,7 +320,11 @@ module Samagotchi
 
     def print_hooks_and_plugin(manifest, plugin: true)
       @stdout.puts "Hooks: #{manifest.hooks.size} hook(s) (#{manifest.hooks.keys.join(", ")})" if manifest&.hooks&.any?
-      @stdout.puts "Plugin: #{manifest.plugin[:file]} (loads at the next chi start)" if plugin && manifest&.plugin
+      return unless plugin && manifest&.plugin
+
+      # Installed with --force past its requires_chi: the Engine won't load it.
+      failure = Samagotchi::MemoryBundle::Manifest.requires_chi_failure(manifest.requires_chi, Samagotchi::VERSION)
+      @stdout.puts "Plugin: #{manifest.plugin[:file]} (#{failure ? "won't load on this chi: #{failure}" : "loads at the next chi start"})"
     end
 
     # @return [Integer] 0
@@ -499,9 +518,11 @@ module Samagotchi
           label += "; #{info[:merge_note].line}#{" (old copy in #{info[:merge_note].trash})" if info[:merge_note].trash}" if info[:merge_note]
           @stdout.puts "  #{k}: #{label}"
         end
+        @stdout.puts "  #{manifest_line(st.provenance)}"
         # Hooks
-        hooks = st.provenance.hooks
-        trust = st.provenance.trust_level || "experimental"
+        manifest = st.provenance.manifest
+        hooks = manifest.hooks
+        trust = manifest.trust_level || "experimental"
         commit = st.provenance.source_commit
         @stdout.puts "  trust_level: #{trust}" if hooks.any? || trust
         @stdout.puts "  source_commit: #{commit}" if commit
@@ -512,7 +533,7 @@ module Samagotchi
             exists = File.exist?(hook_path) ? "ok" : "missing"
             @stdout.puts "    #{hk}: #{hook.events_field} on_error=#{hook.on_error} priority=#{hook.priority} [#{exists}]"
           end
-          @stdout.puts "    requires_chi: #{st.provenance.requires_chi}" if st.hooks_requires_failure
+          @stdout.puts "    requires_chi: #{manifest.requires_chi}" if st.hooks_requires_failure
           @stdout.puts "    not loaded: #{st.hooks_requires_failure}" if st.hooks_requires_failure
         end
         if (plugin = st.plugin)
@@ -534,7 +555,7 @@ module Samagotchi
 
           st = Samagotchi::MemoryBundle::Status.bundle_status(bname)
           mods = st.files.values.count { |v| v[:behind] || v[:missing] || v[:unreadable] }
-          hooks_count = st.provenance.hooks.size
+          hooks_count = st.provenance.manifest.hooks.size
           hook_info = hooks_count > 0 ? " hooks=#{hooks_count}" : ""
           plugin = st.plugin
           mods += 1 if plugin && (plugin[:state] != "ok" || plugin[:requires_failure])
@@ -549,6 +570,14 @@ module Samagotchi
       0
     end
 
+    # "Manifest: [kept]", or "[from the install record]", and what its case
+    # says (MemoryBundle::ManifestStanding).
+    def manifest_line(record)
+      require_relative "memory_bundle/manifest_standing"
+      standing = Samagotchi::MemoryBundle::ManifestStanding
+      ["Manifest:", standing.label(record), standing.status_line(record)].compact.join(" ")
+    end
+
     # " dev → /path (missing)" when a dev install's source isn't there, else "".
     def dev_label(record)
       return "" unless record.dev
@@ -577,7 +606,7 @@ module Samagotchi
       rescue ArgumentError => e
         @stderr.puts "Bundle '#{bname}': #{e.message}"; return 1
       end
-      hooks = record.hooks
+      hooks = record.manifest.hooks
       plugin_path = prov.plugin_path(record)
       plugin_file = plugin_path && File.basename(plugin_path)
       if file_arg
@@ -612,6 +641,26 @@ module Samagotchi
 
     def diff_memory(prov, target_dir, key)
       print_base_and_current(key, prov.base_path(key), File.join(target_dir, key))
+      print_incoming(prov, key)
+    end
+
+    # The bundle's text a file stays behind (Provenance#incoming_path), so the
+    # sections the "stays behind" line names can be read. No saved copy: nothing.
+    def print_incoming(prov, key)
+      path = prov.incoming_path(key)
+      return unless File.exist?(path)
+
+      text = begin
+        File.read(path)
+      rescue SystemCallError
+        nil
+      end
+      if text
+        @stdout.puts "--- incoming (the bundle's #{prov.record.version}, which this file stays behind) ---"
+        @stdout.puts text
+      else
+        @stdout.puts "--- incoming: the bundle's saved copy can't be read ---"
+      end
     end
 
     def diff_hook(prov, key, hook)
@@ -622,7 +671,8 @@ module Samagotchi
     def diff_plugin(prov, record, plugin_path)
       file = File.basename(plugin_path)
       print_base_and_current("plugin/#{file}", prov.plugin_base_path(file), plugin_path)
-      @stdout.puts "--- metadata: sha256=#{record.plugin.sha256}#{" requires_chi=#{record.requires_chi}" if record.requires_chi}"
+      requires_chi = record.manifest.requires_chi
+      @stdout.puts "--- metadata: sha256=#{record.plugin.sha256}#{" requires_chi=#{requires_chi}" if requires_chi}"
     end
 
     def print_base_and_current(heading, base, current)
@@ -926,6 +976,34 @@ module Samagotchi
       Samagotchi::MemoryBundle::SourceNormalizer.shipped_bundle_dir(src) || File.expand_path(src)
     end
 
+    # Where an upgrade comes from: the source as given — a git URL, an
+    # existing path, a shipped bundle's name, as install takes them — or,
+    # for the bare name of an installed bundle, the source its record keeps.
+    # A dev install is refused (it already follows its source), and a record
+    # whose source is relative, empty or gone says so. nil after such a
+    # refusal, written to stderr.
+    # @return [Array(String, InstalledBundle, nil), nil] [the source, the
+    #   record that named it (nil for a source as given)]
+    def upgrade_source(source)
+      normalizer = Samagotchi::MemoryBundle::SourceNormalizer
+      given = normalizer.git_url?(source) || normalizer.shipped_bundle_dir(source) || File.exist?(File.expand_path(source))
+      return [expand_source(source), nil] if given
+
+      record = Samagotchi::MemoryBundle::Provenance.new(name: source.to_s.strip).record
+      return [expand_source(source), nil] if record.nil? || record.error?
+
+      if record.dev
+        @stderr.puts "Upgrade failed: #{Samagotchi::MemoryBundle::Installer.dev_install_line(record.name, record.source)}"
+        return nil
+      end
+
+      recorded = record.source.to_s.strip
+      return [recorded, record] if normalizer.git_url?(recorded) || (recorded.start_with?("/") && File.exist?(recorded))
+
+      @stderr.puts "Upgrade failed: #{Samagotchi::MemoryBundle::Installer.source_gone_line(record.name, recorded)}"
+      nil
+    end
+
     def build_conflict_prompt(bundle_name, conflicts, expanded_source)
       lines = []
       lines << "Memory bundle upgrade has conflicts that need interactive resolution."

data/lib/samagotchi/bundle_needs.rb

@@ -66,13 +66,11 @@ module Samagotchi
     # missing need. A manifest.json or needs: that doesn't parse is skipped.
     def self.entry_markers(scope, path:, bundles_dir:)
       MemoryBundle::Provenance.each_installed(dir: bundles_dir).each_with_object({}) do |(_name, bundle), acc|
-        next if bundle.error? || bundle.effective_scope != scope.to_s || !bundle.needs?
+        next if bundle.error? || bundle.effective_scope != scope.to_s
+
+        needs = bundle.manifest.needs
+        next if needs.empty?
 
-        needs = begin
-          MemoryBundle::Manifest.parse_needs(bundle.needs)
-        rescue MemoryBundle::Manifest::ValidationError
-          next
-        end
         marker = marker(missing(needs, path: path))
         next unless marker
 

data/lib/samagotchi/bundle_settings_check.rb

@@ -32,7 +32,7 @@ module Samagotchi
         next ["config.yml bundles: #{name}: #{SessionConfig.no_installed_bundle(name)}#{near(name, installed.keys)}"] unless bundle
         next [] if bundle.error?
 
-        record_warnings(bundle, values)
+        record_warnings(bundle.manifest, values)
       end
     end
 
@@ -62,23 +62,24 @@ module Samagotchi
       lines
     end
 
-    # One bundle's +values+ against its record (or a manifest as one); none
-    # while it declares no settings:.
-    # @param bundle [MemoryBundle::InstalledBundle]
+    # One bundle's +values+ against its manifest (an installed one's or a
+    # source's); none while it declares no settings:.
+    # @param manifest [MemoryBundle::InstalledManifest, MemoryBundle::Manifest]
+    #   name, settings, session_settings, setting_types
     # @return [Array<String>]
-    def record_warnings(bundle, values)
-      return [] if bundle.settings.nil?
+    def record_warnings(manifest, values)
+      return [] if manifest.settings.nil?
 
-      values.flat_map { |key, value| value_warnings(bundle, key.to_s, value) }
+      values.flat_map { |key, value| value_warnings(manifest, key.to_s, value) }
     end
 
-    def value_warnings(bundle, key, value)
-      where = "config.yml bundles: #{bundle.name}.#{key}"
-      known = bundle.settings | bundle.session_settings
-      return ["#{where}: #{SessionConfig.takes_keys(bundle.name, known)}#{near(key, known)}"] unless known.include?(key)
+    def value_warnings(manifest, key, value)
+      where = "config.yml bundles: #{manifest.name}.#{key}"
+      known = manifest.settings | manifest.session_settings
+      return ["#{where}: #{SessionConfig.takes_keys(manifest.name, known)}#{near(key, known)}"] unless known.include?(key)
 
-      takes, what = SessionConfig::TYPES[bundle.setting_types[key]]
-      takes && !takes.call(value) ? ["#{where}: #{SessionConfig.wrong_type(bundle.name, key, what, value)}"] : []
+      takes, what = SessionConfig::TYPES[manifest.setting_types[key]]
+      takes && !takes.call(value) ? ["#{where}: #{SessionConfig.wrong_type(manifest.name, key, what, value)}"] : []
     end
     private_class_method :value_warnings
 

data/lib/samagotchi/bundles/agents-md/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: agents-md
-version: 0.1.1
+version: 0.1.2
 scope: system
 description: "Steers a nested AGENTS.md into the conversation the first time a tool touches a file under its directory"
 trust_level: reviewed
@@ -8,6 +8,6 @@ plugin:
   file: plugin.rb
   sha256: sha256:56527b9d12cb9acd8f57ca00881ab159894ae2fb8def22bce66ac3774bb4187b
 # ctx.prompt_files, read when the plugin loads (0.60.0)
-requires_chi: ">= 0.60.0"
+requires_chi: ">= 0.143.0"
 # config.yml bundles: agents-md: (another key warns; an older chi ignores this)
 settings: [tools, max_chars]

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

@@ -1,12 +1,12 @@
 ---
 name: btw
-version: 0.1.3
+version: 0.1.4
 scope: system
 description: "/btw <question>: a side answer about the conversation, as a card in every UI, even mid-turn; Keep as session forks it into a child session"
 trust_level: reviewed
 plugin:
   file: plugin.rb
   sha256: sha256:6497129b06d1c3061c1d7d9d7a9c3dfdbcf790e8f2049addad0c26d24771015f
-requires_chi: ">= 0.1.30"
+requires_chi: ">= 0.143.0"
 # config.yml bundles: btw: (another key warns; an older chi ignores this)
 settings: [max_tokens, timeout]

data/lib/samagotchi/bundles/loop-guard/manifest.yml

@@ -1,12 +1,12 @@
 ---
 name: loop-guard
-version: 0.3.9
+version: 0.3.10
 scope: system
 description: "Breaks loops: the same tool call with the same result again and again in one turn is denied with advice (after a few denies the turn stops with a card), and thinking that repeats itself while it streams is cut and the model asked again"
 trust_level: reviewed
 plugin:
   file: plugin.rb
   sha256: sha256:a4ac7c48a903716b7e1c4fa35348439e90ac97d3ad421378ce7d3ac819229a09
-requires_chi: ">= 0.6.0"
+requires_chi: ">= 0.143.0"
 # config.yml bundles: loop-guard: (another key warns; an older chi ignores this)
 settings: [deny_after, stop_after, ignore_tools, mode, thinking]

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

@@ -1,6 +1,6 @@
 ---
 name: mcp
-version: 0.7.5
+version: 0.7.6
 scope: system
 description: "Tools from MCP servers (stdio): each server in config.yml bundles: mcp: servers: runs for the session; their tools go into chi's tool index: the model searches them with find_tools and calls one with call_tool (<server>/<tool>); /mcp lists them"
 trust_level: reviewed
@@ -9,6 +9,6 @@ plugin:
   file: plugin.rb
   sha256: sha256:718e53db877eacd2714e69427c69cfc6c551aaf3417bb760a27dac3331363db5
 # 0.67.0 is the release with chi.tool_source (the core tool index the bundle publishes into).
-requires_chi: ">= 0.121.0"
+requires_chi: ">= 0.143.0"
 # config.yml bundles: mcp: (another key warns; an older chi ignores this)
 settings: [servers, timeout, startup_timeout]

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

@@ -1,12 +1,12 @@
 ---
 name: skills
-version: 0.1.8
+version: 0.1.9
 scope: system
 description: "Skills (skill_<name> memories, the steps of a task done together): /skill save, list, show and diff; older versions kept with a short diff line on every update; a nudge when a followed skill's step fails"
 trust_level: reviewed
 plugin:
   file: plugin.rb
   sha256: sha256:781d943749d59ade0e24d04ba774449d31267eb8ca435835c36c67a3e523e632
-requires_chi: ">= 0.11.0"
+requires_chi: ">= 0.143.0"
 # config.yml bundles: skills: (another key warns; an older chi ignores this)
 settings: [history_keep, nudge]

data/lib/samagotchi/bundles/slow-commands/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: slow-commands
-version: 0.2.4
+version: 0.2.5
 scope: system
 description: "Remembers commands that ran past the execute limit in a project; the next identical execute is denied once a turn with advice to run it with task_create and task_wait; /slow-commands lists and forgets them"
 trust_level: reviewed
@@ -9,6 +9,6 @@ plugin:
   sha256: sha256:e51c099c1552bd0cd1fe46e4fd235a3fe8340693e6ca338eb7ed09d8398a6f0f
 # Execute::HANDED_OVER, read when the plugin loads (0.59.0); after_tool_call's
 # call:, elapsed_ms: and result: (0.57.0)
-requires_chi: ">= 0.59.0"
+requires_chi: ">= 0.143.0"
 # config.yml bundles: slow-commands: (another key warns; an older chi ignores this)
 settings: [mode, warn_ratio, ttl_days]

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

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.151.0
+version: 0.153.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:
   identity.md: sha256:29c2f7df9f6c5acbc5ec17000a4490741e55e426af15ca0d81c8706edd9bd027
   self_map.md: sha256:e695f78f858c29ccfef2ed6f9d6dd86d0ec067ed704a5a1956c01e53617948a1
   config_modification_protocol.md: sha256:8896d1d364ce835040f69b504518d43dbdf959b93fdd9b10f87a8de61cae84a8
-  memory_guide.md: sha256:bfe9f13e8a6c929056fe531c4c74c7e05d0f17f025191c1a111c8e7dfd224fd6
+  memory_guide.md: sha256:8b7727b939b9c04486ca59859561023dcc319a73e0f5b47b3fcf5741edaa69e2
   delegated.md: sha256:a0d6ddcd4a8be06526d964898611775fd251cfd9d145a9d16afaccaa503597bd

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

@@ -113,8 +113,8 @@ Bundles are versioned directories/zips/tar.gz/git URLs with a `manifest.yml` and
 
 | Command | Purpose |
 |---------|---------|
-| `install <source> [--scope system\|project] [--force]` | Install from dir/zip/tar.gz/git URL. `--force` overwrites existing entries, otherwise skips them; a skipped file stays the user's (not recorded, never upgraded or removed by the bundle). Writes provenance to `.bundles/<name>/` (base snapshots + `manifest.json`) and updates `index.md`. Warns on double-brace placeholders and checksum mismatches (strict mode). |
-| `upgrade <source> [--force] [--dry-run] [--agent]` | 3-way merge upgrade (base vs current vs incoming) per `Merger::Upgrade#outcome` (`Merger.classify`, then a text merge where both sides changed): `install` (new file), `noop` (current==incoming), `fast_forward` (current==base, not edited → auto-update), `keep` (incoming==base → preserve local edits), `merged` (both edited, a text merge with `git` comes out clean → the file takes it, the old one goes to the bundle trash, and entries both sides added under a `Changelog` heading are kept), `conflict` (both edited, a real conflict, or no `git` or base → the file stays untouched and marked, reported as `X stays behind 0.8.0: …` with why and what it missed, needs a retry, `--force`, which copies it to the trash first, or interactive `memory_write` resolution). A marked file is retried at the same version: the system bundle's at each chi start and on `chi update`, another shipped bundle's on `chi update`, any other bundle's on `chi bundle upgrade`. A file marked by an older chi merges normally when its recorded base is a version chi shipped (an installed samagotchi gem still has it); otherwise it merges only if the bundle takes out or rewords no line it still holds, and if it does, it stays behind until resolved by hand, with `--agent` or with `--force`, and the retry can't fix that. Pruned files (removed from new bundle) are kept if locally edited, otherwise warned. |
+| `install <source> [--scope system\|project] [--force]` | Install from dir/zip/tar.gz/git URL. `--force` overwrites existing entries, otherwise skips them; a skipped file stays the user's (not recorded, never upgraded or removed by the bundle). It also installs a bundle whose `requires_chi` this chi doesn't meet: without `--force` that install is refused (`NAME can't be installed: it requires chi …`). Writes provenance to `.bundles/<name>/` (base snapshots + `manifest.json`) and updates `index.md`. Warns on double-brace placeholders and checksum mismatches (strict mode). |
+| `upgrade <source\|name> [--force] [--dry-run] [--agent]` | A bare `name` is an installed bundle: chi upgrades it from the source its record keeps (its git URL with the `#ref` it recorded, its folder, or the archive it came from) — a dev install is refused, and a record whose source is gone says so and asks for the path or URL. Otherwise 3-way merge upgrade (base vs current vs incoming) per `Merger::Upgrade#outcome` (`Merger.classify`, then a text merge where both sides changed): `install` (new file), `noop` (current==incoming), `fast_forward` (current==base, not edited → auto-update), `keep` (incoming==base → preserve local edits), `merged` (both edited, a text merge with `git` comes out clean → the file takes it, the old one goes to the bundle trash, and entries both sides added under a `Changelog` heading are kept), `conflict` (both edited, a real conflict, or no `git` or base → the file stays untouched and marked, reported as `X stays behind 0.8.0: …` with why and what it missed, needs a retry, `--force`, which copies it to the trash first, or interactive `memory_write` resolution). A marked file is retried at the same version: the system bundle's at each chi start and on `chi update`, another shipped bundle's on `chi update`, any other bundle's on `chi bundle upgrade`. A file marked by an older chi merges normally when its recorded base is a version chi shipped (an installed samagotchi gem still has it); otherwise it merges only if the bundle takes out or rewords no line it still holds, and if it does, it stays behind until resolved by hand, with `--agent` or with `--force`, and the retry can't fix that. Pruned files (removed from new bundle) are kept if locally edited, otherwise warned. |
 | `uninstall <bundle> [--force]` | Moves the bundle's memory files to `.bundles/.trash/<bundle>-<time>/` (refuses locally edited ones unless `--force`; keeps a file another installed bundle also lists), removes their `index.md` lines, deletes the provenance dir. |
 | `status [<bundle>]` | Provenance + per-file `ok|modified|missing|unreadable|no-index` vs stored checksum and base snapshot, and what stays behind or merged at a chi start; `issues=` counts files behind, missing or unreadable, not edits; a model overlay (`<name>.<key>.md`) has no index line and reads `ok (model overlay)`. |
 | `diff <bundle> [file]` | Prints `base` (provenance snapshot) vs `current` (on-disk) for each file. |
@@ -146,7 +146,7 @@ chi bundle build --scope system --out updated.zip
 
 ### Provenance internals (for debugging)
 
-- Each installed bundle is recorded at `<system dir>/.bundles/<name>/manifest.json` + `bases/<file>.md` snapshots (`Provenance`). Used only for upgrade `Merger` and `status`/`diff`. Build does **not** write provenance.
+- Each installed bundle is recorded at `<system dir>/.bundles/<name>/manifest.json` + `bases/<file>.md` snapshots (`Provenance`), with the bundle's own `manifest.yml` kept beside it (chi reads the manifest from there at load). Used only for upgrade `Merger` and `status`/`diff`. Build does **not** write provenance.
 - A bundle records only the files it wrote. `index.md` updates aren't fatal: a failed one is a warning in the install/uninstall output.
 
 ## Best practices for the agent

data/lib/samagotchi/bundles/web-search/manifest.yml

@@ -0,0 +1,13 @@
+---
+name: web-search
+version: 0.1.0
+scope: system
+description: "web_search: the model searches the web through your SearXNG (its JSON API) and gets titles, URLs and snippets to read with web_fetch"
+trust_level: reviewed
+plugin:
+  file: plugin.rb
+  sha256: sha256:ff79881a370a10dfd1762b5fecb02833dd30c8c5e1f8578e3f1f1a214d6f78a5
+# settings: is new in chi 0.143.0 (ctx.http in 0.80.0)
+requires_chi: ">= 0.143.0"
+# config.yml bundles: web-search: (another key warns; an older chi ignores this)
+settings: {url: string, max_results: number, timeout: number, language: string, safesearch: number, categories: string, engines: string}

data/lib/samagotchi/bundles/web-search/plugin.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+# The web-search bundle (docs/bundles.md, The web-search bundle): one tool,
+# web_search, that asks a SearXNG instance through its JSON API and returns
+# a short list of results (title, URL, snippet). The model reads the ones it
+# wants with web_fetch. The query goes to that SearXNG and on to the engines
+# it is configured with.
+#
+# Settings (config.yml, bundles: web-search:), read at each call from
+# ctx.settings, never at load:
+#   url: http://127.0.0.1:8888   the SearXNG root (http/https with a host)
+#   max_results: 8               results listed, 1..20
+#   timeout: 10                  seconds, ctx.http's per-read timeout
+#   language: en                 optional, sent only when set
+#   safesearch: 0                optional, 0/1/2
+#   categories: general          optional, comma-separated
+#   engines: duckduckgo,brave    optional, comma-separated (SearXNG drops
+#                                names it doesn't know)
+#
+# SearXNG needs `json` in search.formats (else it answers 403) and, for a
+# local instance, server.limiter: false (else it may answer 429).
+require "json"
+require "uri"
+
+class Plugin
+  DEFAULT_URL = "http://127.0.0.1:8888"
+  DEFAULT_MAX = 8
+  MAX_RESULTS = 20
+  DEFAULT_TIMEOUT = 10
+  SNIPPET_CHARS = 300
+  TIME_RANGES = %w[day week month year].freeze
+  # Optional settings sent as query parameters, in this order, only when set.
+  OPTIONAL = %w[language safesearch categories engines].freeze
+
+  DESCRIPTION = "Search the web (through the user's SearXNG) and return a numbered list of results: title, URL and " \
+                "a short snippet. Snippets are partial and may be stale: when the details matter, read a result's " \
+                "URL with web_fetch before answering instead of answering from snippets alone. Use page for more " \
+                "results and time_range for recent ones."
+
+  # A setting that can't be used: the tool's answer, before any request.
+  class SettingError < StandardError; end
+
+  def initialize(_settings); end
+
+  def register(chi)
+    chi.tool "web_search", DESCRIPTION,
+             params: {
+               query: { type: "string", description: "The search terms", required: true },
+               time_range: { type: "string", enum: TIME_RANGES, description: "Only results from the last day, week, month or year" },
+               page: { type: "integer", description: "The results page, 1 for the first (the default)" }
+             },
+             label: "searching", preview: ->(args) { args["query"].to_s } do |args, ctx|
+      search(args, ctx)
+    end
+  end
+
+  private
+
+  def search(args, ctx)
+    query = args["query"].to_s.strip
+    return "Error: query is required" if query.empty?
+
+    settings = ctx.settings
+    root = root_url(settings["url"])
+    page = page_of(args["page"])
+    res = ctx.http.get("#{root}/search?#{URI.encode_www_form(pairs(query, page, args["time_range"], settings))}",
+                       timeout: timeout_of(settings["timeout"]))
+    answer(res, query, page, max_of(settings["max_results"]))
+  rescue SettingError => e
+    "Error: #{e.message}"
+  rescue Samagotchi::Plugin::HttpCancelled
+    "Error: search cancelled"
+  rescue Samagotchi::Plugin::HttpError => e
+    "Error: SearXNG is not reachable: #{e.message}. Is it running? (bundles: web-search: url)"
+  end
+
+  def answer(res, query, page, max)
+    return status_error(res.status) unless res.ok?
+
+    data = begin
+      JSON.parse(res.body.scrub)
+    rescue JSON::ParserError
+      nil
+    end
+    return "Error: SearXNG's answer isn't JSON (is url the SearXNG root?)" unless data.is_a?(Hash)
+
+    listing(data, query, page, max)
+  end
+
+  def status_error(status)
+    case status
+    when 403 then "Error: SearXNG refused the JSON format (403): add json to search.formats in its settings.yml"
+    when 429 then "Error: SearXNG rate-limited the request (429): turn its limiter off for a local instance (server.limiter: false)"
+    else "Error: SearXNG answered #{status}"
+    end
+  end
+
+  def listing(data, query, page, max)
+    results = Array(data["results"]).select { |entry| entry.is_a?(Hash) && !squash(entry["url"]).empty? }.first(max)
+    if results.empty?
+      failed = Array(data["unresponsive_engines"]).map { |pair| squash(Array(pair).first) }.reject(&:empty?)
+      return [%(No results for "#{query}".), (failed.empty? ? nil : "Engines that failed: #{failed.join(", ")}")].compact.join("\n")
+    end
+
+    lines = [%(SearXNG results for "#{query}" (page #{page}):)]
+    if (first = first_answer(data["answers"]))
+      lines << "Answer: #{first}"
+    end
+    results.each_with_index { |entry, index| lines.concat(result_lines(entry, index + 1)) }
+    suggestions = Array(data["suggestions"]).map { |text| squash(text) }.reject(&:empty?)
+    lines << "Suggestions: #{suggestions.join(", ")}" unless suggestions.empty?
+    lines.join("\n")
+  end
+
+  def result_lines(entry, number)
+    url = squash(entry["url"])
+    title = squash(entry["title"])
+    snippet = cut(squash(entry["content"]))
+    ["#{number}. #{title.empty? ? url : title}", "   #{url}", (snippet.empty? ? nil : "   #{snippet}")].compact
+  end
+
+  # answers: Strings (older SearXNG) or Hashes with the text under "answer".
+  def first_answer(answers)
+    Array(answers).each do |item|
+      text = cut(squash(item.is_a?(Hash) ? item["answer"] : item))
+      return text unless text.empty?
+    end
+    nil
+  end
+
+  def pairs(query, page, time_range, settings)
+    list = [["q", query], %w[format json], ["pageno", page.to_s]]
+    list << ["time_range", time_range.to_s] if TIME_RANGES.include?(time_range.to_s)
+    OPTIONAL.each do |key|
+      value = settings[key]
+      list << [key, value.to_s] unless value.nil? || value.to_s.strip.empty?
+    end
+    list
+  end
+
+  def root_url(value)
+    url = (value.nil? ? DEFAULT_URL : value.to_s).strip
+    uri = URI.parse(url)
+    raise SettingError, "bundles: web-search: url must be an http(s) URL" unless %w[http https].include?(uri.scheme) && !uri.host.to_s.empty?
+
+    url.chomp("/")
+  rescue URI::InvalidURIError
+    raise SettingError, "bundles: web-search: url must be an http(s) URL"
+  end
+
+  def page_of(value)
+    page = begin
+      Integer(value)
+    rescue ArgumentError, TypeError, FloatDomainError
+      1
+    end
+    [page, 1].max
+  end
+
+  def timeout_of(value) = value.is_a?(Numeric) && value.positive? ? value : DEFAULT_TIMEOUT
+
+  def max_of(value)
+    max = begin
+      Integer(value)
+    rescue ArgumentError, TypeError, FloatDomainError
+      DEFAULT_MAX
+    end
+    max.clamp(1, MAX_RESULTS)
+  end
+
+  def squash(value) = value.to_s.scrub.gsub(/\s+/, " ").strip
+
+  def cut(text) = text.length > SNIPPET_CHARS ? "#{text[0, SNIPPET_CHARS - 1]}…" : text
+end

data/lib/samagotchi/child_env.rb

@@ -48,6 +48,21 @@ module Samagotchi
     # @return [Hash]
     def scrub(env) = env.except(*spawner_keys(env))
 
+    # +env+ as a spawn argument that really removes what it leaves out. A Hash
+    # given to Process.spawn, Open3 or exec is merged onto the spawner's
+    # environment: a key only deleted from it is still inherited by the child.
+    # Every key +spawner+ has and +env+ doesn't is mapped to nil, which
+    # Process.spawn unsets, so the child sees exactly +env+ (and #scrub is
+    # safe to use with it). +env+ is not changed.
+    # @param env [Hash]
+    # @param spawner [Hash] the spawner's environment (default: ENV)
+    # @return [Hash]
+    def spawn_env(env, spawner: ENV)
+      out = env.dup
+      spawner.each_key { |key| out[key] = nil unless out.key?(key) }
+      out
+    end
+
     # In gem mode, what Bundler changed in +env+ mapped back
     # (InstalledGem.unbundled_env_changes): a child activates the installed
     # gem itself rather than inherit this app's bundle. {} in a checkout.