samagotchi 0.152.0 → 0.154.0

data/lib/samagotchi/bridge.rb

@@ -9,6 +9,7 @@ require "openssl"
 require "time"
 require_relative "atomic_file"
 require_relative "bridge_secret"
+require_relative "degrade"
 require_relative "delivery"
 require_relative "session_inbox"
 require_relative "turn_anchors"
@@ -156,6 +157,9 @@ module Samagotchi
       # Open streams by the client_id a stream named (`?client_id=`); web
       # tabs, through the `chi web` proxy, name none.
       @streams_by_client = Hash.new(0)
+      # Streams served since the start, open or closed (a scratch worker
+      # leaves once its terminal's has gone: Worker#scratch_unattended?).
+      @streams_served = 0
       @last_client_activity_at = monotonic_now
     end
 
@@ -178,6 +182,11 @@ module Samagotchi
       @mutex.synchronize { @open_streams }
     end
 
+    # @return [Integer] SSE streams served since the Bridge started
+    def streams_served
+      @mutex.synchronize { @streams_served }
+    end
+
     # Streams held by anyone but +client_id+: a client's own stream (or two,
     # while it reconnects and the old one isn't noticed dead yet) doesn't
     # count. A closed stream stops counting once its writer reads the
@@ -236,7 +245,7 @@ module Samagotchi
       @mutex.synchronize { @stopped = true }
       begin
         @server&.close
-      rescue StandardError
+      rescue StandardError # degrade-ok: stopping: a server socket already closed is fine
         nil
       end
       wake_acceptor
@@ -254,7 +263,7 @@ module Samagotchi
       @mutex.synchronize { @stopped = true }
       begin
         @server&.close
-      rescue StandardError
+      rescue StandardError # degrade-ok: stopping: a server socket already closed is fine
         nil
       end
       wake_acceptor
@@ -268,13 +277,13 @@ module Samagotchi
       # the web, which then queues the prompt again from the input file.
       await_answers(REQUEST_GRACE_SECONDS)
       remove_sidecar
-      @connection_threads.each { |t| t.kill rescue nil }
+      @connection_threads.each { |t| t.kill rescue nil } # degrade-ok: stopping: a thread already gone is fine
       @connection_threads.clear
       # Its relay watchers (RelayWatcher) end with it.
       watchers = @mutex.synchronize { (@relay_watchers || []).tap { @relay_watchers = [] } }
       watchers.each { |thread| thread.kill.join(RELAY_WATCHER_JOIN_SECONDS) }
       @accept_thread&.join(2)
-      [@wake_reader, @wake_writer].each { |io| io&.close rescue nil }
+      [@wake_reader, @wake_writer].each { |io| io&.close rescue nil } # degrade-ok: stopping: a closed pipe is fine
       nil
     end
 
@@ -399,9 +408,10 @@ module Samagotchi
     # O(1) and non-blocking.
     def capture_observer
       @capture_proc ||= proc do |event|
-        @ring.push(seq: event[:event_seq], data: event)
-      rescue StandardError
-        nil
+        # Per event: the first failure warns, the rest log at debug.
+        Degrade.call(:bridge, "event_capture_failed") do
+          @ring.push(seq: event[:event_seq], data: event)
+        end
       end
     end
 
@@ -527,7 +537,7 @@ module Samagotchi
       Thread.current[:bridge_answering] = false
       begin
         io.close
-      rescue StandardError
+      rescue StandardError # degrade-ok: the client may be gone already; closing is all that's left
         nil
       end
     end
@@ -555,6 +565,7 @@ module Samagotchi
       )
       @mutex.synchronize do
         @open_streams += 1
+        @streams_served += 1
         @streams_by_client[client_id] += 1 if client_id
       end
       begin
@@ -860,7 +871,7 @@ module Samagotchi
       end
     end
 
-    # Dismiss the pending question (an empty answer, as in the REPL): the
+    # Dismiss the pending question (an empty answer at a terminal): the
     # tool returns without an answer and every UI gets :question_cancelled.
     # Only the question the client saw, and only while nobody has answered
     # it: Engine#cancel_question checks both under the question lock. A past
@@ -1425,44 +1436,44 @@ module Samagotchi
     # else fall back to the explicit `?from_seq=` query param used by clients
     # that remember their own cursor.
     def reconnect_cursor(headers, query)
-      cursor = headers["last-event-id"]
-      return cursor if cursor && !cursor.empty?
+      Degrade.call(:bridge, "sse_cursor_unparsable") do
+        cursor = headers["last-event-id"]
+        return cursor if cursor && !cursor.empty?
 
-      return nil unless query
+        return nil unless query
 
-      URI.decode_www_form(query).to_h["from_seq"]
-    rescue StandardError
-      nil
+        URI.decode_www_form(query).to_h["from_seq"]
+      end
     end
 
     # `?snapshot=1`: join with a snapshot frame instead of a replay.
     def snapshot_requested?(query)
-      return false unless query
+      Degrade.call(:bridge, "snapshot_query_unparsable", fallback: false) do
+        return false unless query
 
-      URI.decode_www_form(query).to_h["snapshot"].to_s == "1"
-    rescue StandardError
-      false
+        URI.decode_www_form(query).to_h["snapshot"].to_s == "1"
+      end
     end
 
     # `?raw=1`: events as the engine emitted them (a chunk's provider
     # payload), not as clients get them (ClientEvent). For debugging on the
     # worker's port: chi web never passes it on.
     def raw_requested?(query)
-      return false unless query
+      Degrade.call(:bridge, "raw_query_unparsable", fallback: false) do
+        return false unless query
 
-      URI.decode_www_form(query).to_h["raw"].to_s == "1"
-    rescue StandardError
-      false
+        URI.decode_www_form(query).to_h["raw"].to_s == "1"
+      end
     end
 
     # `?client_id=`: whose stream it is (see #open_streams_except).
     def stream_client_id(query)
-      return nil unless query
+      Degrade.call(:bridge, "client_id_query_unparsable") do
+        return nil unless query
 
-      id = URI.decode_www_form(query).to_h["client_id"].to_s
-      id.empty? ? nil : id
-    rescue StandardError
-      nil
+        id = URI.decode_www_form(query).to_h["client_id"].to_s
+        id.empty? ? nil : id
+      end
     end
 
     def close_after_request?(headers)
@@ -1534,11 +1545,11 @@ module Samagotchi
     # same session may have written its own since (a file without an epoch
     # is only ever an older worker's).
     def remove_sidecar
-      return unless @server
+      Degrade.call(:bridge, "sidecar_remove_failed") do
+        return unless @server
 
-      File.unlink(WorkerSidecar.path(session_dir)) if WorkerSidecar.read(session_dir)&.epoch == @epoch.to_s
-    rescue StandardError
-      nil
+        File.unlink(WorkerSidecar.path(session_dir)) if WorkerSidecar.read(session_dir)&.epoch == @epoch.to_s
+      end
     end
 
     def session_dir

data/lib/samagotchi/bridge_client.rb

@@ -4,6 +4,7 @@ require "digest"
 require "json"
 require "socket"
 
+require_relative "degrade"
 require_relative "worker_sidecar"
 require_relative "bridge_secret"
 require_relative "delivery"
@@ -329,17 +330,17 @@ module Samagotchi
       body = response.split("\r\n\r\n", 2)[1] || ""
       Response.new(status: status.to_i, body: body)
     ensure
-      sock&.close rescue nil
+      sock&.close rescue nil # degrade-ok: done with the socket; one already closed is fine
     end
 
     # Monotonic SSE cursor of the live Engine, from GET /session/:id/state.
     # @return [Integer, nil]
     def event_seq
-      state = get_json("state")
-      seq = state && state.dig("session_state_snapshot", "event_seq")
-      seq.nil? ? nil : seq.to_i
-    rescue StandardError
-      nil
+      Degrade.call(:bridge, "event_seq_unreadable") do
+        state = get_json("state")
+        seq = state && state.dig("session_state_snapshot", "event_seq")
+        seq.nil? ? nil : seq.to_i
+      end
     end
 
     # Open GET /session/:id/stream and classify the response before the
@@ -358,7 +359,7 @@ module Samagotchi
         if connection
           sock, status, headers = connection
           unless !block_given? || yield(sock)
-            sock.close rescue nil
+            sock.close rescue nil # degrade-ok: the stream is given up; a socket already closed is fine
             return StreamOpen::Unreachable.new(attempts: count)
           end
           return StreamOpen.classify(sock, status, headers)
@@ -389,7 +390,7 @@ module Samagotchi
           break
         end
       ensure
-        sock&.close rescue nil
+        sock&.close rescue nil # degrade-ok: done with the socket; one already closed is fine
       end
     end
 
@@ -435,7 +436,7 @@ module Samagotchi
       body = read_body ? reply.split("\r\n\r\n", 2)[1] : nil
       Response.new(status: reply[STATUS_LINE, 1].to_i, body: body)
     ensure
-      sock&.close rescue nil
+      sock&.close rescue nil # degrade-ok: done with the socket; one already closed is fine
     end
 
     # The reply up to the Bridge's close (or its first line only), within

data/lib/samagotchi/broadcast/recipients.rb

@@ -12,7 +12,7 @@ module Samagotchi
     # A session a broadcast may concern.
     # @!attribute project [String, nil] its git project's root
     # @!attribute live [Boolean] a worker runs it now
-    # @!attribute owner [String, nil] "worker", "tui" (a chi REPL, which
+    # @!attribute owner [String, nil] "worker", "tui" (a one-turn chi run, which
     #   takes no notes) or nil
     Recipient = Data.define(:id, :short_id, :project, :cwd, :desc, :live, :owner) do
       def repl? = owner == "tui"
@@ -20,7 +20,7 @@ module Samagotchi
 
     # Who a broadcast goes to: the user's own sessions, not delegate
     # children (their parent relays what concerns them) and not scratch
-    # ones, that a worker or a chi REPL runs now or that ended a turn in
+    # ones, that a worker or a one-turn chi run runs now or that ended a turn in
     # the last +active_hours+. Forks count: they are the user's sessions.
     # Archived sessions don't; test runs only when chi runs as one.
     module Recipients

data/lib/samagotchi/broadcast/triage.rb

@@ -23,7 +23,7 @@ module Samagotchi
       # @!attribute by [String] who decided: "tags" (a shared tag),
       #   "model", "fallback" (delivered unchecked: deadline, error, an
       #   answer that is no yes or no), "scope" (the note's first line
-      #   names another project), "all" (--all) or "repl" (a chi REPL owns
+      #   names another project), "all" (--all) or "repl" (a one-turn chi run owns
       #   it: no notes)
       # @!attribute match [Match, nil] the shared tag (by "tags")
       Verdict = Data.define(:relevant, :p, :reason, :by, :match) do

data/lib/samagotchi/broadcast_command.rb

@@ -46,7 +46,7 @@ module Samagotchi
         note from "broadcast": background the model sees on its next turn,
         not a prompt. It starts no turn.
         Recipients: your own sessions (not delegate children, not scratch
-        ones) that a worker or a chi REPL runs now, or that ended a turn in
+        ones) that a worker or a one-turn chi run runs now, or that ended a turn in
         the last broadcast.active_hours (8). One gets the note when it shares
         a tag with it: a ticket id (PAY-123) in its branch or your prompts
         there, a pull request (PR #42, its URL) attached to it, a link in
@@ -190,13 +190,13 @@ module Samagotchi
                                                    corrections: []), decisions, cards)
     end
 
-    # Every recipient's verdict: a chi REPL takes no notes, --all takes the
+    # Every recipient's verdict: a one-turn chi run takes no notes, --all takes the
     # rest, else Broadcast::Triage (tags, the scope line, the model).
     # @return [Array<Decision>] in +recipients+' order
     def decide(text, recipients, cards, note_tags, all:)
       fixed = recipients.to_h do |r|
         verdict = if r.repl?
-                    Broadcast::Triage::Verdict.new(relevant: false, p: nil, reason: "open in a chi REPL", by: "repl")
+                    Broadcast::Triage::Verdict.new(relevant: false, p: nil, reason: OwnerLock::TUI_BUSY, by: "repl")
                   elsif all
                     Broadcast::Triage::Verdict.new(relevant: true, p: nil, reason: "--all", by: "all")
                   end
@@ -254,7 +254,7 @@ module Samagotchi
 
         result = NoteDelivery.deliver(d.recipient.id, text: body(broadcast.text, d.verdict), source: SOURCE,
                                                       state_dir: @state_dir)
-        next [d, "skipped", "open in a chi REPL"] unless result.delivered?
+        next [d, "skipped", OwnerLock::TUI_BUSY] unless result.delivered?
 
         [d, "delivered", "#{d.verdict.reason}#{"; waits for its next start" if result.status == :waits}"]
       rescue SessionInbox::NoteRejected, SystemCallError => e
@@ -369,7 +369,7 @@ module Samagotchi
 
       result = NoteDelivery.deliver(id, text: passed_on_body(record), source: SOURCE, state_dir: @state_dir)
       unless result.delivered?
-        @stdout.puts(line_for(id, "skipped", "open in a chi REPL"))
+        @stdout.puts(line_for(id, "skipped", OwnerLock::TUI_BUSY))
         return Broadcast::TriageLog::Delivery.new(session: id, result: "refused")
       end
 

data/lib/samagotchi/bundle_command/try/command.rb

@@ -42,7 +42,7 @@ module Samagotchi
           f.switch "--json"
           f.switch "--keep"
           f.value "--timeout"
-          f.refuse "--attach", "--shared", "chi bundle try can't use --attach or --shared"
+          f.refuse "--attach", "chi bundle try can't use --attach"
         end
         DEFAULT_TIMEOUT = 300
         # The sandbox's cost-cap bundle setting (--set cost-cap.cap=N).

data/lib/samagotchi/bundle_command/try/run.rb

@@ -30,7 +30,7 @@ module Samagotchi
 
         def run(prompt:, options:, timeout:)
           command = [RbConfig.ruby, "-I", Sandbox::LIB_DIR, Sandbox::CHI,
-                     "--no-shared", "--non-interactive", "-p", prompt, *child_options(options)]
+                     "--non-interactive", "-p", prompt, *child_options(options)]
           trap_state, old_traps = trap_forwarding
           pid = nil
           streams = []

data/lib/samagotchi/bundle_command.rb

@@ -367,8 +367,8 @@ module Samagotchi
       prompt = build_conflict_prompt(bundle_name, installer.conflicts, expanded_source)
       before = installer.conflicts.to_h { |key, info| [key, Samagotchi::MemoryBundle::Merger.digest(info[:current])] }
       @stdout.puts "Launching an interactive session to merge them… (/exit when done)"
-      require "samagotchi/terminal_ui"
-      Samagotchi::TerminalUI.new(prompt: prompt).run
+      require "samagotchi/terminal_ui/attach_launcher"
+      Samagotchi::TerminalUI::AttachLauncher.run(prompt: prompt)
       settle_conflicts(installer.conflicts, before, bundle_name)
     ensure
       # An owned source (git/zip/tar) was kept for the incoming files above;

data/lib/samagotchi/bundles/decision-card/manifest.yml

@@ -1,13 +1,13 @@
 ---
 name: decision-card
-version: 0.2.0
+version: 0.2.1
 scope: system
 description: "In a session with objectives, a long answer ending in a question gets a card: a short summary and the question, answered in the composer"
 trust_level: reviewed
 plugin:
   file: plugin.rb
-  sha256: sha256:e628d84ab9521f7e8e5f3bc69da97fe00e574082412ea24e9f3f1c6234ad31a9
-# ctx.objectives and ctx.turn_running? are new after 0.148.0
-requires_chi: ">= 0.149.0"
+  sha256: sha256:b85fd2162e41d1ea059ff6ca89ce6bb543e4f283d18337e9d4ac6936477d3770
+# ctx.last_answer is new after 0.153.0 (ctx.objectives, ctx.turn_running? after 0.148.0)
+requires_chi: ">= 0.154.0"
 # config.yml bundles: decision-card: (another key warns; an older chi ignores this)
 settings: [min_chars, tail_chars, model, timeout, max_tokens]

data/lib/samagotchi/bundles/decision-card/plugin.rb

@@ -135,7 +135,7 @@ class Plugin
     return SHORT_BUSY if ctx.turn_running?
 
     messages = ctx.messages
-    answer = last_answer(messages) or return "no answer to shorten yet"
+    answer = ctx.last_answer or return "no answer to shorten yet"
 
     id = ctx.card(title: SHORT_TITLE, body: "…")
     @mutex.synchronize { @shorts[id] = ctx }
@@ -158,14 +158,6 @@ class Plugin
     ctx.card(id: id, title: SHORT_TITLE, body: body)
   end
 
-  # @return [String, nil] the newest non-empty answer's text
-  def last_answer(messages)
-    found = Array(messages).reverse_each.find do |message|
-      %w[model assistant].include?(field(message, :role).to_s) && !field(message, :content).to_s.strip.empty?
-    end
-    found && field(found, :content).to_s
-  end
-
   def turn_ended(event, ctx)
     return unless event[:status].to_s == "completed"
     # A participant's question is for the participant, on the owner's model; a

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

@@ -1,10 +1,10 @@
 ---
 name: dev
-version: 0.7.6
+version: 0.7.7
 scope: system
 description: "Developer tools"
 trust_level: reviewed
-requires_chi: ">= 0.150.0"
+requires_chi: ">= 0.154.0"
 includes:
 - known-names
 - mcp

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

@@ -18,7 +18,7 @@ Single registry `Samagotchi::Config` (`Config::ENTRIES` in `lib/samagotchi/confi
 
 Sections forbid `_`/`-` (`SECTION_RE` `/\A[a-z0-9]+\z/`), since an env or CLI name is derived from them; a config-only section (`system_one`: `expose: [:config]`, no derived name) may carry `_`. Leaves keep `snake_case` in YAML (`base_url`) and become kebab in CLI (`base-url`) via registry derivation — no generic string split, registry lookup avoids flat vs nested collision.
 
-**Universal entries** (`expose: [:env,:config,:cli]`): `default.model`, `server.host/port/open_timeout/read_timeout`, `server.first_token_timeout` (env and config only), `recap.model/base_url/host_ref/inactivity/timeout/min_user_turns/sentences`, `session.retention_days/max_count/keep_status/sweep_interval_hours/idle_exit_minutes`, `session.shared/keep_empty/max_children` (env and config only), `log.file/disable`, `status.line`, `context.status/window_tokens/chars_per_token/status_thresholds`, `memory.index_warn_tokens/entry_warn_tokens/read_max_chars`, `default.max_tokens`, `max_tool_output_chars`, `retry.max/base_delay/max_delay`, `read.*`, `execute.*`, `web.port/host`, `no_interrupt`, `no_default_input` etc. (`Config::ENTRIES`; `expose` says which of env/config/cli each takes). Precedence is `CLI > ENV > file > default`.
+**Universal entries** (`expose: [:env,:config,:cli]`): `default.model`, `server.host/port/open_timeout/read_timeout`, `server.first_token_timeout` (env and config only), `recap.model/base_url/host_ref/inactivity/timeout/min_user_turns/sentences`, `session.retention_days/max_count/keep_status/sweep_interval_hours/idle_exit_minutes`, `session.keep_empty/max_children` (env and config only), `log.file/disable`, `status.line`, `context.status/window_tokens/chars_per_token/status_thresholds`, `memory.index_warn_tokens/entry_warn_tokens/read_max_chars`, `default.max_tokens`, `max_tool_output_chars`, `retry.max/base_delay/max_delay`, `read.*`, `execute.*`, `web.port/host`, `no_interrupt`, `no_default_input` etc. (`Config::ENTRIES`; `expose` says which of env/config/cli each takes). Precedence is `CLI > ENV > file > default`.
 
 Example `config.yml` (new nested form, preferred):
 
@@ -40,10 +40,9 @@ recap:
 session:
   retention_days: 14
   max_count: 500
-  keep_status: ""        # the default: no status protects a session from pruning; a live worker or REPL always does
+  keep_status: ""        # the default: no status protects a session from pruning; a live worker or a one-turn run always does
   sweep_interval_hours: 24
   idle_exit_minutes: 30   # a background worker nobody uses exits; 0 = never
-  shared: true            # the default: plain `chi` runs its session in a background worker and attaches (as `chi --shared`); false keeps the in-process REPL (env SAMAGOTCHI_SESSION_SHARED; no CLI flag, `--no-shared` opts out per run)
   keep_empty: false       # the default: a session nothing happened in (no prompt, default model, no note/image) is deleted when left; true keeps it (env SAMAGOTCHI_SESSION_KEEP_EMPTY)
   max_children: 4         # running child sessions one session may have delegated at a time (the delegate tool; env SAMAGOTCHI_SESSION_MAX_CHILDREN)
 log:
@@ -77,7 +76,7 @@ guardrails:
   disable: [guardrails:git-rebase]
 ```
 
-- `bundles:` map of installed bundle name → its settings (one Hash, string keys, handed to the bundle's hook/plugin `initialize(settings)`). Read when a session's Engine starts: after a change restart the session's worker (`chi sessions stop <id>`) or the REPL. Unknown keys are ignored by the bundle, not validated. `chi bundle list` names the bundles; each bundle's keys are in `docs/bundles.md` / `docs/guardrails.md`.
+- `bundles:` map of installed bundle name → its settings (one Hash, string keys, handed to the bundle's hook/plugin `initialize(settings)`). Read when a session's Engine starts: after a change restart the session's worker (`chi sessions stop <id>`). Unknown keys are ignored by the bundle, not validated. `chi bundle list` names the bundles; each bundle's keys are in `docs/bundles.md` / `docs/guardrails.md`.
 
 ```yaml
 bundles:

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

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.152.0
+version: 0.154.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
+  self_map.md: sha256:709bd52710bf6c50334a89a10742ea1554c5985cc2d7c4e7571e526cc4479526
+  config_modification_protocol.md: sha256:f3f6545c93d59b624a2bf1766e26059520ffc7b236470dd9f1b51ab77312376d
   memory_guide.md: sha256:8b7727b939b9c04486ca59859561023dcc319a73e0f5b47b3fcf5741edaa69e2
   delegated.md: sha256:a0d6ddcd4a8be06526d964898611775fd251cfd9d145a9d16afaccaa503597bd

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

@@ -67,7 +67,7 @@
   `docs/bundle-authoring.md` in my source dir first.
 
 ## Where things live (relative to the source dir)
-- `docs/`: `cli.md` (flags, subcommands, REPL commands), `configuration.md` (config.yml keys,
+- `docs/`: `cli.md` (flags, subcommands, the terminal's commands), `configuration.md` (config.yml keys,
   hosts, the server api), `hooks.md` (hook events table), `plugins.md` (plugin API), `bundles.md` (each shipped bundle: btw, mcp, cost-cap…),
   `guardrails.md`, `memory.md`, `sessions.md`. `README.md` is only the quickstart.
 - `lib/samagotchi/tools/<tool>.rb`: each tool's real limits and defaults (e.g. `execute.rb`,

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