samagotchi 0.96.0 → 0.98.0

data/lib/samagotchi/bundle_command/check.rb

@@ -51,8 +51,9 @@ module Samagotchi
 
       LIB_DIR = File.expand_path("../..", __dir__)
       TRUSTED = %w[reviewed trusted].freeze
-      # A call of the plugin API, or a name SINCE lists, in the source.
-      API_CALL = /\b(?:chi|ctx)\.[a-z_]+\b|\bfallback_for:|\bSamagotchi::AtomicFile\b/
+      # A call of the plugin API (with one member after it: ctx.sessions.children),
+      # or a name SINCE lists, in the source.
+      API_CALL = /\b(?:chi|ctx)\.[a-z_]+(?:\.[a-z_]+)?\b|\bfallback_for:|\bSamagotchi::AtomicFile\b/
       # A requirement's lower bound: >= X, > X, ~> X or = X.
       LOWER_BOUND = /\A(?:>=|>|~>|=)?\s*(\d+(?:\.\d+)*)\z/
 
@@ -213,7 +214,8 @@ module Samagotchi
         floor = lower_bound(manifest.requires_chi)
         return unless floor && File.file?(path(manifest.plugin[:file]))
 
-        calls = File.read(path(manifest.plugin[:file])).scan(API_CALL).uniq.select { |call| Plugin::Api::SINCE.key?(call) }
+        calls = File.read(path(manifest.plugin[:file])).scan(API_CALL).flat_map { |call| [call, call.split(".").first(2).join(".")] }
+                    .uniq.select { |call| Plugin::Api::SINCE.key?(call) }
         call = calls.max_by { |c| Gem::Version.new(Plugin::Api::SINCE[c]) } or return
         version = Plugin::Api::SINCE[call]
         return unless Gem::Version.new(version) > floor

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

@@ -2,6 +2,7 @@
 
 require "open3"
 require "rbconfig"
+require_relative "../../cli/exit"
 require_relative "../../process_group"
 
 module Samagotchi
@@ -54,7 +55,7 @@ module Samagotchi
               end
               trap_state[:pid] = nil
               out, err = finish_readers(readers, streams)
-              code = timed_out ? CLI::Exit::FAILED : process_exit_status(status)
+              code = timed_out ? CLI::Exit::FAILED : exit_code(status, trap_state)
               Result.new(exit_status: code, stdout: out, stderr: err, session_id: err[/^Session: (\S+)/, 1],
                          timed_out: timed_out)
             end
@@ -91,13 +92,16 @@ module Samagotchi
         end
 
         def trap_forwarding
-          state = { pid: nil, wait: nil, pending: nil }
+          state = { pid: nil, wait: nil, pending: nil, interrupted: false }
           old = {}
           %w[INT TERM].each do |signal|
             old[signal] = Signal.trap(signal) do
               if state[:pid]
                 # Not once its waiter reaped it: that group may be gone.
-                ProcessGroup.signal(state[:pid], signal) if state[:wait]&.alive?
+                if state[:wait]&.alive?
+                  state[:interrupted] ||= signal == "INT"
+                  ProcessGroup.signal(state[:pid], signal)
+                end
               else
                 state[:pending] ||= signal
               end
@@ -111,7 +115,10 @@ module Samagotchi
           state[:pid] = pid
           pending = state[:pending]
           state[:pending] = nil
-          ProcessGroup.signal(pid, pending) if pending
+          return unless pending
+
+          state[:interrupted] ||= pending == "INT"
+          ProcessGroup.signal(pid, pending)
         end
 
         def restore_traps(old)
@@ -171,6 +178,14 @@ module Samagotchi
           readers.each(&:join)
         end
 
+        # A Ctrl-C forwarded to the child is an interrupted run, however it
+        # ended: a Ruby still booting (before chi's INT handler) exits 1.
+        def exit_code(status, trap_state)
+          return CLI::Exit::INTERRUPTED if trap_state[:interrupted] && !status.success?
+
+          process_exit_status(status)
+        end
+
         def process_exit_status(status)
           status.exitstatus || (128 + status.termsig.to_i)
         end

data/lib/samagotchi/bundle_command.rb

@@ -476,7 +476,7 @@ module Samagotchi
           hooks.each do |hk, hook|
             hook_path = File.join(Samagotchi::MemoryBundle::Provenance.new(name: name).hooks_dir, hk)
             exists = File.exist?(hook_path) ? "ok" : "missing"
-            @stdout.puts "    #{hk}: event=#{hook.event} on_error=#{hook.on_error} priority=#{hook.priority} [#{exists}]"
+            @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 "    not loaded: #{st[:hooks_requires_failure]}" if st[:hooks_requires_failure]
@@ -658,7 +658,7 @@ module Samagotchi
     end
 
     def hook_metadata_line(hook)
-      "--- metadata: event=#{hook.event} on_error=#{hook.on_error} priority=#{hook.priority} sha256=#{hook.sha256}"
+      "--- metadata: #{hook.events_field} on_error=#{hook.on_error} priority=#{hook.priority} sha256=#{hook.sha256}"
     end
 
     def build(rest)

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

@@ -1,10 +1,10 @@
 ---
 name: dev
-version: 0.7.0
+version: 0.7.1
 scope: system
 description: "Developer tools"
 trust_level: reviewed
-requires_chi: ">= 0.72.0"
+requires_chi: ">= 0.98.0"
 includes:
 - known-names
 - mcp

data/lib/samagotchi/bundles/source-links/hooks/source_links.rb

@@ -4,8 +4,8 @@
 require "open3"
 require "samagotchi/ref"
 
-# An after_turn hook that links the source refs the model's answer
-# mentions — a JIRA ticket, a GitHub issue, an internal wiki page. In the
+# An after_turn (and question_asked) hook that links the source refs the
+# model's answer mentions — a JIRA ticket, a GitHub issue, an internal wiki page. In the
 # web, each ref in the answer becomes a link (`[JIRA-123](https://…)`,
 # through event[:present]: display only, the model's text stays as it was,
 # and it survives a reload). Every UI also gets one line right after the
@@ -58,6 +58,14 @@ require "samagotchi/ref"
 # action, "Open in <name>", the ref's URL. A URL that isn't http(s) stays a
 # markdown link only. The web's ref menu shows the action.
 #
+# The hook is on :question_asked too (the manifest's events:, chi newer than
+# 0.97.0): while a question of the model's (or an approval of its call)
+# waits, the refs in the reply that asks it, and in the question's text and
+# options, are refs on that reply, the same as an answer's. The web pairs
+# them in the stage's asking slot, on the question's card and on that step
+# in the history (a ref only in the question's text pairs there alone). No
+# links in the text and no note line for it: the turn's end has those.
+#
 # The note is not stored in the conversation: it is an event, replayed by a
 # UI with the session's cards (a reload keeps it, after the worker stopped
 # too: cards.json). The links are stored as the answer's display. A ref in
@@ -120,10 +128,20 @@ class SourceLinks
   end
 
   def call(event)
-    return unless event.is_a?(Hash) && event[:type] == :after_turn
-    return unless event[:status].to_s == "completed"
+    return unless event.is_a?(Hash)
     return if @sources.empty?
 
+    case event[:type]
+    when :after_turn then after_turn(event)
+    when :question_asked then question_asked(event)
+    end
+  end
+
+  private
+
+  def after_turn(event)
+    return unless event[:status].to_s == "completed"
+
     text = last_model_text(event[:messages])
     return if text.nil? || text.empty?
 
@@ -141,7 +159,23 @@ class SourceLinks
     event[:notify]&.call(line(found), level: :info, fallback_for: covered ? :display : nil)
   end
 
-  private
+  # A question of the model's (or an approval of its call) is about to
+  # open: the refs in the reply that asks it and in the question's own text
+  # and options, each scanned on its own (a code span never runs from one
+  # into the next), as refs on that reply. No present (a mid-turn text has
+  # no display) and no note line (the after-turn one stays the terminals').
+  def question_asked(event)
+    refs = event[:refs]
+    return unless refs
+
+    question = event[:question].is_a?(Hash) ? event[:question] : {}
+    field = ->(key) { question.key?(key) ? question[key] : question[key.to_s] }
+    parts = [event[:text], field.call(:question), *Array(field.call(:options))]
+    parts.each do |part|
+      text = part.is_a?(String) ? part : ""
+      add_refs(refs, occurrences(text[0, MAX_SCAN])) unless text.empty?
+    end
+  end
 
   # Links the refs in the answer as shown: the model's text unless an
   # earlier hook changed it (then its offsets differ, so it is scanned

data/lib/samagotchi/bundles/source-links/manifest.yml

@@ -1,15 +1,15 @@
 ---
 name: source-links
-version: 0.5.1
+version: 0.6.0
 scope: system
-description: Links source refs (JIRA tickets, GitHub issues, …) in the model's answer — inline links in the web, and a one-line note after the turn (note false turns it off); sources are configured patterns
+description: Links source refs (JIRA tickets, GitHub issues, …) in the model's answer — inline links in the web, refs in a waiting question's reply, and a one-line note after the turn (note false turns it off); sources are configured patterns
 trust_level: reviewed
-requires_chi: ">= 0.61.0"
+requires_chi: ">= 0.98.0"
 files:
   source_links.md: sha256:ace01a0f7c308a0ae54ece714c31c0e6d7a49c372d98111030e6d268320bed3a
 hooks:
   source_links.rb:
-    sha256: sha256:c41249ec0bbb708ec7827e1d0f66689dfbbc415c1da5fe33f5d3a8ec8e5eaa2f
-    event: after_turn
+    sha256: sha256:84c0bef064fb1ea76749a61e758eba612662aaf0f05f18a18ab4228497078fa2
+    events: [after_turn, question_asked]
     on_error: log
     priority: 90

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

@@ -1,6 +1,6 @@
 ---
 name: samagotchi-system
-version: 0.96.0
+version: 0.98.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:

data/lib/samagotchi/engine.rb

@@ -77,6 +77,7 @@ require_relative "answer_display"
 require_relative "answer_refs"
 require_relative "edit_preview"
 require_relative "question_desk"
+require_relative "question_asked"
 require_relative "child_reports"
 require_relative "relay_desk"
 require_relative "guardrail_wiring"
@@ -187,49 +188,13 @@ module Samagotchi
       @question_desk = build_question_desk
       # Built here, not on first use: the turn thread and the Bridge's read it.
       @relay_desk = RelayDesk.new
-      @extension_load = ExtensionLoad.new(hook_failures: @guardrail_failures)
-      @hooks = @extension_load.hooks
-      # The tools this session offers (the prompts' declarations and the
-      # kernel's dispatch): the built-ins, per Engine. execute.description
-      # off: execute offers no description parameter. +task_finish_notes+:
-      # a worker's, whose finish wake reports a task left running (the
-      # Worker's TaskWatch): execute and task_create say so.
-      @tools = Tools::Builtins.registry(command_description: Config.get("execute.description") != false,
-                                        policy: Config.get(LLMContextStrategy::POLICY_SETTING),
-                                        task_finish_notes: task_finish_notes)
-      restrict_scratch_tools! if @scratch
-      # Likewise the slash commands its SessionCommands run.
-      @command_registry = SessionCommands.register_builtins(Commands::Registry.new)
-      # Installed bundles' plugins add commands, tools and hooks to these
-      # (docs/plugins.md); one that fails is announced with the load
-      # failures, and the rest still load.
-      # Their services (chi.service), which #shutdown stops, and the anytime
-      # commands running now (#spawn_anytime), which it waits for.
-      @services = Plugin::Services.new
-      @anytime_threads = []
-      # chi.init tasks (#add_init_task), started by #start_init_tasks!, and
-      # plugins' tool sets from chi.replace_tools until the turn thread
-      # applies them (#apply_staged_tools!). Built before the plugins load.
-      @plugin_tasks = build_plugin_tasks
-      # The session's toolkit: the kits (the plugins' too, chi.toolkit),
-      # what its next turn declares, the turn-start apply.
-      @toolkit_binding = build_toolkit_binding
       # The notices a turn's thinking level leads to (once per session and host).
       @thinking_notices = ThinkingNotices.new(session: -> { @session }, profile: -> { self.profile },
                                               notify: ->(text, level, source) { hook_notify(text, level, source) })
-      # The tools plugins publish without declaring (chi.tool_source), and
-      # the search and call tools that reach them (Tools::ToolIndex).
-      @tool_index = Tools::ToolIndex.new
-      # The context sources the peer bundles declare as a peer agent's
-      # answers (chi.peer_source); the worker's ContextAbsorber asks it.
-      @peer_sources = PeerSources.new
       @lifecycle_mutex = Mutex.new
       @shut_down = false
-      load_plugins if plugins
-      # Registered from what the sources published while they loaded, and
-      # with no plugins too: a toolkit's left-out built-ins are reachable
-      # either way (declared per toolkit, Tools::Registry).
-      @tool_index.declare(@tools, failures: @plugin_failures)
+      # The built-ins, the commands, and the plugins that add to them.
+      build_tools_and_plugins(load: plugins, task_finish_notes: task_finish_notes)
       guardrail_rules
       # The Engine owns the reminder store; its kernel (built here, or a
       # spec's) gets it, so tool calls via KernelLoop and reminder injection
@@ -277,6 +242,52 @@ module Samagotchi
 
     # ── initialize's collaborators ──────────────────────────────────────────
 
+    # The Engine as the plugins' host: the tools and slash commands this
+    # session offers, what plugins add to them (services, init tasks, the
+    # toolkit, the tool index, peer sources), then the plugins themselves
+    # unless +load+ is false (see #initialize for when).
+    def build_tools_and_plugins(load:, task_finish_notes:)
+      @extension_load = ExtensionLoad.new(hook_failures: @guardrail_failures)
+      @hooks = @extension_load.hooks
+      # The tools this session offers (the prompts' declarations and the
+      # kernel's dispatch): the built-ins, per Engine. execute.description
+      # off: execute offers no description parameter. +task_finish_notes+:
+      # a worker's, whose finish wake reports a task left running (the
+      # Worker's TaskWatch): execute and task_create say so.
+      @tools = Tools::Builtins.registry(command_description: Config.get("execute.description") != false,
+                                        policy: Config.get(LLMContextStrategy::POLICY_SETTING),
+                                        task_finish_notes: task_finish_notes)
+      restrict_scratch_tools! if @scratch
+      # Likewise the slash commands its SessionCommands run.
+      @command_registry = SessionCommands.register_builtins(Commands::Registry.new)
+      # Installed bundles' plugins add commands, tools and hooks to these
+      # (docs/plugins.md); one that fails is announced with the load
+      # failures, and the rest still load.
+      # Their services (chi.service), which #shutdown stops, and the anytime
+      # commands running now (#spawn_anytime), which it waits for.
+      @services = Plugin::Services.new
+      @anytime_threads = []
+      # chi.init tasks (#add_init_task), started by #start_init_tasks!, and
+      # plugins' tool sets from chi.replace_tools until the turn thread
+      # applies them (#apply_staged_tools!). Built before the plugins load.
+      @plugin_tasks = build_plugin_tasks
+      # The session's toolkit: the kits (the plugins' too, chi.toolkit),
+      # what its next turn declares, the turn-start apply.
+      @toolkit_binding = build_toolkit_binding
+      # The tools plugins publish without declaring (chi.tool_source), and
+      # the search and call tools that reach them (Tools::ToolIndex).
+      @tool_index = Tools::ToolIndex.new
+      # The context sources the peer bundles declare as a peer agent's
+      # answers (chi.peer_source); the worker's ContextAbsorber asks it.
+      @peer_sources = PeerSources.new
+      load_plugins if load
+      # Registered from what the sources published while they loaded, and
+      # with no plugins too: a toolkit's left-out built-ins are reachable
+      # either way (declared per toolkit, Tools::Registry).
+      @tool_index.declare(@tools, failures: @plugin_failures)
+    end
+    private :build_tools_and_plugins
+
     # The tools a scratch session doesn't offer, and its memory_write.
     def restrict_scratch_tools!
       # A scratch session's children would outlive it, and so would a
@@ -354,7 +365,8 @@ module Samagotchi
         model_key: -> { @model_key },
         model_name: -> { guardrail_model_name },
         cancelled: -> { !!active_cancel_controller&.cancelled? },
-        ask: ->(fields) { open_question(fields) },
+        # An approval of the model's call: :question_asked first (QuestionAsked).
+        ask: ->(fields) { open_question(question_asked(QuestionAsked::KIND_APPROVAL, fields)) },
         notify: ->(message) { guardrail_notify(message) }
       )
     end
@@ -1260,6 +1272,7 @@ module Samagotchi
         muted_memory_names: @muted_memory_names.dup,
         prompt_notes: prompt_notes.map(&:to_h),
         parent_id: @session&.parent_id,
+        title: @session&.title,
         model_name: effective_model_ref,
         served_model: served_pair[0],
         served_model_for: served_pair[1],
@@ -1565,13 +1578,35 @@ module Samagotchi
 
     # Ask the model's question (ask_user_question): the kernel's
     # question_handler, called on the turn thread with the payload
-    # Tools::AskUserQuestion.validate made (QuestionDesk#request).
+    # Tools::AskUserQuestion.validate made (QuestionDesk#request), after
+    # the :question_asked hooks (QuestionAsked) gave the step its refs; a
+    # --non-interactive run has no one to ask, so they don't fire there.
     # @param payload [Hash] {question:, options:, header:, multi_select:, allow_freeform:}
     # @return [String] normalized answer JSON
     def request_question(payload)
+      payload = question_asked(QuestionAsked::KIND_QUESTION, payload) unless interface == :non_interactive
       @question_desk.request(payload)
     end
 
+    # The :question_asked hooks for a question of the model's about to
+    # open: the fields with the asking step's refs (QuestionAsked.fire).
+    # @return [Hash]
+    def question_asked(kind, fields)
+      QuestionAsked.fire(hooks: @hooks, conversation: live_conversation, kind: kind, fields: fields,
+                         cwd: @session&.working_directory, synchronize: ->(&block) { synchronize_events(&block) },
+                         visible: ->(content) { question_step_text(content) })
+    end
+    private :question_asked
+
+    # A step's text as the asking slot shows it: the native loop's raw
+    # response without its thoughts and tool-call bodies (a chat step has
+    # neither), then the markup's tokens (OutputFormatter.strip_markup).
+    def question_step_text(content)
+      parser = @kernel.parser
+      OutputFormatter.strip_markup(parser.strip_tool_calls(parser.strip_thought(content)))
+    end
+    private :question_step_text
+
     # Open a question for the UIs and wait for its answer
     # (QuestionDesk#open_question: BLOCKS until answered or cancelled).
     # @param fields [Hash] question:, options:, header:, multi_select:, allow_freeform:, …

data/lib/samagotchi/hooks/bundle_loader.rb

@@ -69,9 +69,9 @@ module Samagotchi
 
             hook = MemoryBundle::BundleHook.parse(raw_meta)
             # A hook with no declared event cannot be auto-registered.
-            next if hook.event.empty?
+            next if hook.events.empty?
 
-            fail_closed = hook.on_error == "fail_closed" && hook.event == "before_tool_call"
+            fail_closed = hook.events.any? { |event| hook.fail_closed?(event) }
             what = "hook #{basename} (bundle #{bundle_name})"
             file = hooks_dir && File.join(hooks_dir, basename)
             unless file && File.exist?(file)
@@ -98,9 +98,10 @@ module Samagotchi
           loaded
         end
 
-        # Build one hook file and register it in +registry+ under its
-        # event, priority and error policy (a fail_closed before_tool_call
-        # one denies when it raises). No missing-file, sha or requires_chi
+        # Build one hook file and register it in +registry+ under each of
+        # its events (one instance for all: its state is shared), with its
+        # priority and error policy (a fail_closed before_tool_call one
+        # denies when it raises). No missing-file, sha or requires_chi
         # check: #load makes them; the test kit loads a bundle's source
         # this way.
         # @param hook [MemoryBundle::BundleHook] its manifest entry
@@ -109,17 +110,19 @@ module Samagotchi
         # @raise [Exception] what loading or building the file raised;
         #   nothing is registered then
         def load_hook_file(bundle_name, basename, file, hook, registry, settings: {}, namespace: nil)
-          event_sym = hook.event.to_sym
-          fail_closed = hook.on_error == "fail_closed" && event_sym == :before_tool_call
           plugin = instantiate(bundle_name, basename, file, settings: settings, namespace: namespace)
-          policy = if fail_closed then :deny
-                   elsif hook.on_error == "log" then :log
-                   else :skip
-                   end
-          label = "#{"guardrail " if fail_closed}#{basename} (bundle #{bundle_name})"
-          handler = Hooks.wrap(label: label, event: event_sym, policy: policy, log: [:hooks, "bundle_hook_failed"],
-                               fields: { bundle: bundle_name }) { |event| plugin.call(event) }
-          registry.register_bundle(bundle_name, event_sym, hook_name: basename, priority: hook.priority, &handler)
+          hook.events.each do |event_name|
+            event_sym = event_name.to_sym
+            fail_closed = hook.fail_closed?(event_sym)
+            policy = if fail_closed then :deny
+                     elsif hook.on_error == "log" then :log
+                     else :skip
+                     end
+            label = "#{"guardrail " if fail_closed}#{basename} (bundle #{bundle_name})"
+            handler = Hooks.wrap(label: label, event: event_sym, policy: policy, log: [:hooks, "bundle_hook_failed"],
+                                 fields: { bundle: bundle_name }) { |event| plugin.call(event) }
+            registry.register_bundle(bundle_name, event_sym, hook_name: basename, priority: hook.priority, &handler)
+          end
           nil
         end
 

data/lib/samagotchi/hooks.rb

@@ -24,12 +24,15 @@ module Samagotchi
   #   :before_tool_call   — before a tool is dispatched: vote with event[:guardrail].deny!/ask!
   #                         (or the older event[:blocked]=true + event[:block_reason]); the
   #                         event also has context: and targets: (docs/guardrails.md)
+  #   :question_asked     — a question of the model's (ask_user_question) or an approval of its
+  #                         call is about to open: event[:refs] attaches refs to the asking
+  #                         reply (QuestionAsked)
   #   :after_tool_call    — after tool execution, before result injection
   module Hooks
     # Every event a hook can be registered for, in a turn's order
     # (docs/hooks.md). Plugin::Api#on takes any symbol: `chi bundle check`
     # warns on one not here.
     EVENTS = %i[session_start before_turn before_generation generation_progress after_generation before_tool_call
-                after_tool_call after_turn session_end].freeze
+                question_asked after_tool_call after_turn session_end].freeze
   end
 end

data/lib/samagotchi/llm/errors.rb

@@ -191,12 +191,24 @@ module Samagotchi
         elsif tools_unsupported?
           "host #{host} rejected the request: #{tools_detail}; #{TOOLS_HINT}"
         else
-          "host #{host} rejected the request: #{detail}#{"; #{hint}" if hint}"
+          "host #{host} rejected the request: #{hinted_detail}"
         end
       end
 
       private
 
+      # The detail with the hint, ahead of a model list the detail has (a
+      # 404's "Available models: …", cut at the message's limit), else at
+      # its end.
+      def hinted_detail
+        return detail unless hint
+
+        list_at = detail.index(ProviderErrors::AVAILABLE_MODELS_START_RE)
+        return "#{detail}; #{hint}" unless list_at
+
+        "#{detail[0...list_at].sub(/[\s.;:]+\z/, "")}; #{hint} #{detail[list_at..].lstrip}"
+      end
+
       # The detail up to the end of the sentence that says the model takes no
       # tools: what a provider adds after it (OpenRouter: "Try disabling
       # "execute"…" and a routing docs link) is advice for its own UI.
@@ -384,6 +396,28 @@ module Samagotchi
       # Seconds to wait before retrying a CreditsHeld without a Retry-After.
       CREDITS_SETTLE_DELAY = 20.0
       RETRYABLE_SERVER_STATUSES = [500, 502, 503, 504, 529].freeze
+      # How much of a server's error message the summary keeps.
+      MESSAGE_LIMIT = 500
+      # The 404 model hint's bounds (the message is the server's): how much
+      # of the message it reads, the longest model id, how many listed ids.
+      HINT_SCAN_CHARS = 64 * 1024
+      HINT_ID_MAX = 200
+      HINT_IDS_MAX = 2000
+      # A typo the hint forgives: at most this many edits, fewer than a
+      # third of the name, in a name at least HINT_FUZZY_MIN long.
+      HINT_MAX_EDITS = 2
+      HINT_FUZZY_MIN = 6
+      # The most ids a hint names.
+      HINT_SUGGESTIONS = 3
+      # A 404's model it couldn't find: "Model 'X' not found", "model `X`
+      # does not exist", "model X-1 not found" (unquoted, an id-like word,
+      # checked after the match). Bounded quantifiers: a server's long token
+      # can't make the match quadratic (Ruby 3.3 has no regex memoization).
+      MODEL_NOT_FOUND_RE = /model\s+(?:["'`]([^"'`\s]{1,#{HINT_ID_MAX}})["'`]|([^"'`\s]{1,#{HINT_ID_MAX}}))\s+(?:was\s+)?(?:not found|does not exist)/i
+      # The ids a 404 lists after "Available models:".
+      AVAILABLE_MODELS_RE = /available models?:\s*(.+)\z/im
+      # Where that list starts, for the summary to put its hint ahead of it.
+      AVAILABLE_MODELS_START_RE = /\s*\bavailable models?:/i
       # The HTTP status an Anthropic error.type stands for, for an error
       # object that carries no numeric code (a Messages stream's error event,
       # an OpenAI error whose code is null or a name).
@@ -426,6 +460,7 @@ module Samagotchi
           else
             OutOfCredits.new(text, **options)
           end
+        when 404 then bad_request(text, status, message, options.merge(hint: model_hint(error_message(body, limit: nil))))
         when 400..499 then bad_request(text, status, message, options)
         when 500..599
           ServerError.new(text, retryable: RETRYABLE_SERVER_STATUSES.include?(status),
@@ -492,7 +527,7 @@ module Samagotchi
       # upstream failure (OpenRouter) often says only "Provider returned
       # error" and puts the upstream's words in error.metadata.raw and its
       # name in metadata.provider_name; both are added when present.
-      def error_message(body)
+      def error_message(body, limit: MESSAGE_LIMIT)
         parsed = parse_json(body.to_s)
         message =
           if parsed.is_a?(Hash)
@@ -502,9 +537,106 @@ module Samagotchi
         message = body.to_s if message.nil? || message.to_s.strip.empty?
         message = message.to_s.strip
         message = with_upstream(message, parsed["error"]["metadata"]) if parsed.is_a?(Hash) && parsed["error"].is_a?(Hash)
-        message.empty? ? "(empty body)" : message[0, 500]
+        return "(empty body)" if message.empty?
+
+        limit ? message[0, limit] : message
+      end
+
+      # "did you mean 'ID'?" for a 404 that names the model it couldn't find
+      # and lists the ones it has (oMLX: "Model 'X' not found. Available
+      # models: a, b, …"), naming up to HINT_SUGGESTIONS ids
+      # (#closest_model_ids: "did you mean 'A' or 'B'?"). Read from the
+      # message past the summary's cut (MESSAGE_LIMIT), within the HINT_*
+      # bounds; nil when there is no list or nothing close.
+      def model_hint(message)
+        message = message[0, HINT_SCAN_CHARS]
+        match = MODEL_NOT_FOUND_RE.match(message)
+        requested = match && (match[1] || match[2])
+        return nil unless requested && (match[1] || requested.match?(%r{[-/.:_\d]}))
+
+        list = message[AVAILABLE_MODELS_RE, 1]
+        return nil unless list
+
+        ids = list.split(/,\s*|\s+/, HINT_IDS_MAX + 1).first(HINT_IDS_MAX)
+                  .map { |id| id.delete("[]\"'`").sub(/[.;]+\z/, "") }
+                  .reject { |id| id.empty? || id.length > HINT_ID_MAX }.uniq
+        return nil if ids.empty? || ids.include?(requested)
+
+        close = closest_model_ids(requested, ids)
+        "did you mean #{close.map { |id| "'#{id}'" }.join(" or ")}?" unless close.empty?
+      end
+
+      # The listed ids closest to +requested+, at most HINT_SUGGESTIONS, in
+      # the first tier that has any: the ids that are +requested+ but for
+      # case, or whose last segment (after "/" or "--") is; else the ids a
+      # typo away (#typo_distance, whole or last segment), the nearest
+      # only; else the ids that contain +requested+ (HINT_FUZZY_MIN
+      # characters or more) or whose last segment it contains, the
+      # shortest first.
+      def closest_model_ids(requested, ids)
+        probe = requested.downcase
+        exact = ids.select { |id| id.downcase == probe || last_segment(id) == probe }
+        return exact.first(HINT_SUGGESTIONS) unless exact.empty?
+
+        scored = ids.filter_map do |id|
+          distance = [id.downcase, last_segment(id)].uniq.filter_map { |name| typo_distance(probe, name) }.min
+          [distance, id] if distance
+        end
+        unless scored.empty?
+          best = scored.map(&:first).min
+          return scored.select { |distance, _| distance == best }.map(&:last).first(HINT_SUGGESTIONS)
+        end
+
+        containing_ids(probe, ids)
       end
 
+      # The ids that contain +probe+ or whose last segment +probe+ contains
+      # (either one HINT_FUZZY_MIN characters or more), closest in length
+      # first, at most HINT_SUGGESTIONS.
+      def containing_ids(probe, ids)
+        return [] if probe.length < HINT_FUZZY_MIN
+
+        ids.select do |id|
+          segment = last_segment(id)
+          id.downcase.include?(probe) || (segment.length >= HINT_FUZZY_MIN && probe.include?(segment))
+        end.each_with_index.sort_by { |id, index| [(id.length - probe.length).abs, index] }
+           .first(HINT_SUGGESTIONS).map(&:first)
+      end
+
+      # The edit distance of +a+ and +b+ when it is a typo's: at most
+      # HINT_MAX_EDITS and under a third of the shorter one, which has
+      # HINT_FUZZY_MIN characters or more; else nil. A banded Levenshtein:
+      # linear in the length.
+      def typo_distance(a, b)
+        shorter = [a.length, b.length].min
+        return nil if shorter < HINT_FUZZY_MIN || (a.length - b.length).abs > HINT_MAX_EDITS
+
+        distance = banded_distance(a, b, HINT_MAX_EDITS)
+        distance if distance && distance * 3 < shorter
+      end
+
+      # Levenshtein distance of +a+ and +b+ if at most +limit+, else nil;
+      # only cells within +limit+ of the diagonal are computed.
+      def banded_distance(a, b, limit)
+        far = limit + 1
+        prev = Hash.new(far)
+        (0..[limit, b.length].min).each { |j| prev[j] = j }
+        a.each_char.with_index(1) do |ca, i|
+          cur = Hash.new(far)
+          cur[0] = i if i <= limit
+          ([i - limit, 1].max..[i + limit, b.length].min).each do |j|
+            cost = ca == b[j - 1] ? 0 : 1
+            cur[j] = [prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + cost, far].min
+          end
+          return nil if cur.empty? || cur.values.min > limit
+
+          prev = cur
+        end
+        prev[b.length] <= limit ? prev[b.length] : nil
+      end
+
+      def last_segment(id) = id.downcase.split(%r{/|--}).last
+
       # error.metadata.reason of a JSON error body (OpenRouter), or nil.
       def error_reason(body)
         parsed = parse_json(body.to_s)