samagotchi 0.79.0 → 0.80.0

data/lib/samagotchi/engine.rb

@@ -27,6 +27,7 @@ require_relative "tools/tool_index"
 require_relative "peer_sources"
 require_relative "session_commands"
 require_relative "plugin/loader"
+require_relative "plugin/card"
 require_relative "extension_load"
 require_relative "log"
 require_relative "log_subscriber"
@@ -784,9 +785,6 @@ module Samagotchi
 
     # ── Cards ───────────────────────────────────────────────────────────────
 
-    CARD_LEVELS = %i[info warn].freeze
-    MAX_CARD_ACTIONS = 6
-
     # Show a card in every UI (docs/plugins.md, Cards): {type: :card, id:,
     # source:, title:, body:, level:, actions: [{label:, command:}], in_turn:}.
     # Where it goes (held while the plugins load, an anytime command's, an
@@ -799,7 +797,7 @@ module Samagotchi
     # @return [String] the card's id
     # @raise [ArgumentError] a card without a title, or a bad action
     def show_card(source:, title:, body: "", actions: [], level: :info, id: nil)
-      card = build_card(source: source, title: title, body: body, actions: actions, level: level, id: id)
+      card = Plugin::Card.build(source: source, title: title, body: body, actions: actions, level: level, id: id)
       @event_routes.route(card, **EventRoutes::CARD_MARKS)
       card[:id]
     end
@@ -963,32 +961,6 @@ module Samagotchi
     end
     private :announce_or_hold
 
-    def build_card(source:, title:, body:, actions:, level:, id:)
-      title = title.to_s.strip
-      raise ArgumentError, "a card needs a title" if title.empty?
-
-      level = level.to_s.to_sym
-      raise ArgumentError, "card level must be one of #{CARD_LEVELS.join(", ")}" unless CARD_LEVELS.include?(level)
-
-      actions = Array(actions)
-      raise ArgumentError, "a card has at most #{MAX_CARD_ACTIONS} actions" if actions.size > MAX_CARD_ACTIONS
-
-      actions = actions.map do |action|
-        raise ArgumentError, "a card action is a Hash {label:, command:}" unless action.is_a?(Hash)
-
-        action = action.transform_keys(&:to_sym)
-        command = action[:command].to_s.strip
-        raise ArgumentError, "a card action needs a command" if command.empty? || command.include?("\n")
-
-        label = action[:label].to_s.strip
-        { label: label.empty? ? command : label, command: command }
-      end
-      id = id.to_s.strip
-      { type: :card, id: id.empty? ? SecureRandom.hex(4) : id, source: source.to_s, title: title, body: body.to_s,
-        level: level, actions: actions }
-    end
-    private :build_card
-
     # ── Model switching ────────────────────────────────────────────────────────
 
     # @param typed [String, nil] the name the model was typed as when
@@ -1452,6 +1424,7 @@ module Samagotchi
         emit_event(turn.on_event, turn.tag(event))
       end
       turn.ended = true
+      @turn_state.ended!
       save_quietly(turn.session) if save
       @metrics.persist(state_dir: session_state_dir)
     end
@@ -1582,7 +1555,8 @@ module Samagotchi
     # @param fields [Hash] question:, options:, header:, multi_select:, allow_freeform:, …
     #   (as a Hash or as keywords)
     # @param watch [#call, nil] closes the question with the reason it returns
-    # @return [Hash, String] the answer, or {error:, …}
+    # @return [QuestionAnswer, Hash, String] the answer, or {error:, …}, or a
+    #   sync handler's text
     def open_question(fields = nil, watch: nil, **more)
       @question_desk.open_question({ **fields.to_h, **more }, watch: watch)
     end
@@ -1601,7 +1575,7 @@ module Samagotchi
     end
 
     # Answer the pending question (called from UI thread; QuestionDesk#answer).
-    # @return [Hash] normalized answer
+    # @return [QuestionAnswer]
     def answer_question(id:, selected:, freeform: nil, client_id: nil, parent_agent: nil)
       @question_desk.answer(id: id, selected: selected, freeform: freeform, client_id: client_id,
                             parent_agent: parent_agent)
@@ -2569,8 +2543,10 @@ module Samagotchi
         toolkit: -> { @toolkit_binding.name },
         declared_tools: -> { toolkit_explained.declared.map(&:name) },
         use_toolkit: ->(name) { use_toolkit(name) },
-        ask_model: lambda { |request, timeout:, max_tokens:, cancel_controller:|
-          ask_side_model(request, timeout: timeout, max_tokens: max_tokens, cancel_controller: cancel_controller)
+        cancel_controller: ->(handler: false) { plugin_cancel_controller(handler: handler) },
+        ask_model: lambda { |request, timeout:, max_tokens:, cancel_controller:, model: nil|
+          ask_side_model(request, timeout: timeout, max_tokens: max_tokens, cancel_controller: cancel_controller,
+                                  model: model)
         },
         model_name: -> { effective_model_ref },
         model_key: -> { @model_key },
@@ -2585,6 +2561,15 @@ module Samagotchi
       )
     end
 
+    # The controller a plugin's ctx.http call without cancel: stops with
+    # (docs/plugins.md): an init task's own, else the running turn's for the
+    # turn's own work until the turn has ended (TurnState#own_controller); nil
+    # for an anytime command, a service or a thread of the plugin's.
+    def plugin_cancel_controller(handler:)
+      (task = current_init_task) ? task.cancel : @turn_state.own_controller(handler: handler)
+    end
+    private :plugin_cancel_controller
+
     # A plugin's ctx.messages: the conversation without the system prompt
     # (the REPL's starts with it, a worker's new session doesn't), and,
     # while a turn runs, the turn so far from the Bridge (plan O1). Read
@@ -2601,14 +2586,15 @@ module Samagotchi
     private :plugin_messages
 
     # ctx.ask_model's request: the session's current model on its host, as
-    # a turn resolves them (a /model switch counts), through its own
+    # a turn resolves them (a /model switch counts), or a configured +model+
+    # (a host:id ref, an alias, a bare id one of a host's models), through its own
     # IdleClient, so it shares nothing with the turn's backend. The client
     # is kept while the target and timeout stay (what it learned, e.g. a
     # refused thinking-off, holds for the next request); the session's id
     # goes with the request.
     # @return [String] the answer
-    def ask_side_model(request, timeout:, max_tokens:, cancel_controller:)
-      target = session_model_recap_target
+    def ask_side_model(request, timeout:, max_tokens:, cancel_controller:, model: nil)
+      target = model.nil? ? session_model_recap_target : configured_side_target(model)
       client = side_model_client(target, timeout)
       started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       answer = client.ask(request, max_tokens: max_tokens, cancel_controller: cancel_controller, session_id: @session&.id)
@@ -2618,6 +2604,23 @@ module Samagotchi
     end
     private :ask_side_model
 
+    # The target of ctx.ask_model(model:): +model+ as a turn resolves it,
+    # once it is known to name something configured. IdleTarget.of_model
+    # never raises (an unknown host falls to the default host, an unknown id
+    # to the default entry), so a typo would silently ask another model.
+    # @raise [ArgumentError] +model+ names no configured host and is no
+    #   host's model (cached, declared or saved lists; nothing is asked)
+    def configured_side_target(model)
+      ref = @host_registry.model_ref(model)
+      unless ref.host_name || ref.alias_name || @host_registry.hosts_with_model(ref.id).any?
+        raise ArgumentError, "ask_model: unknown model #{model.to_s.inspect} (use a configured host:id, an alias, " \
+                             "or a model id one of your hosts lists)"
+      end
+
+      IdleTarget.of_model(@host_registry, model)
+    end
+    private :configured_side_target
+
     # The IdleClient for +target+ at +timeout+: the last one when both are
     # the same, else a new one.
     def side_model_client(target, timeout)

data/lib/samagotchi/guardrails/approval.rb

@@ -2,6 +2,8 @@
 
 require "json"
 
+require_relative "../question_answer"
+
 module Samagotchi
   module Guardrails
     # An ask as a question for the user (Engine#open_question), and the
@@ -67,22 +69,22 @@ module Samagotchi
       end
 
       # Settle +verdict+ from open_question's result.
-      # @param answer [Hash, String] {selected_indices:, freeform:} or {error:}
+      # @param answer [QuestionAnswer, Hash, String] the answer, or {error:} (anything else is a cancel)
       # @param scopes [Array<String>] the offered scopes, in option order
       # @return [Verdict]
       def settle(verdict, answer, scopes)
-        unless answer.is_a?(Hash) && !answer[:error]
+        unless answer.is_a?(QuestionAnswer)
           return verdict.settle!(:deny, decided_by: "user", note: "The approval was cancelled.")
         end
 
-        index = Array(answer[:selected_indices]).first
+        index = answer.selected_indices.first
         if index && index < scopes.size
           verdict.settle!(:allow, decided_by: "user")
           verdict.scope = scopes[index]
           return verdict
         end
 
-        freeform = answer[:freeform].to_s.strip
+        freeform = answer.freeform.to_s.strip
         note = freeform.empty? ? "The user declined this call." : "The user declined this call: #{freeform.inspect}."
         verdict.settle!(:deny, decided_by: "user", note: note)
       end

data/lib/samagotchi/guardrails/gate.rb

@@ -49,10 +49,14 @@ module Samagotchi
       # @param call [Hash] the parsed tool call
       # @param iteration [Integer]
       # @param params [String] the call's one-line preview
+      # @param verdict [Verdict, nil] the one the voters vote on (the test
+      #   kit's recording one, maybe with a vote already in); default a new
+      #   one for +call+
       # @return [Verdict]
-      def evaluate(call, iteration:, params:)
+      def evaluate(call, iteration:, params:, verdict: nil)
         context = @context_lookup.call
-        verdict = Verdict.new(call: call)
+        verdict ||= Verdict.new(call: call)
+        verdict.call = call
         if @cancelled_lookup.call
           verdict.deny!("the turn was stopped", decided_by: "core")
           verdict.context = context
@@ -60,7 +64,7 @@ module Samagotchi
           return verdict
         end
         before = { type: :before_tool_call, iteration: iteration, call: call.dup, params: params,
-                   blocked: false, block_reason: nil, guardrail: verdict,
+                   blocked: verdict.deny?, block_reason: (verdict.reason if verdict.deny?), guardrail: verdict,
                    context: context.to_h, targets: targets_for(call, context).to_h }
         fire_each(:before_tool_call, before) do |event|
           verdict.legacy_deny!(event[:block_reason]) if event[:blocked]

data/lib/samagotchi/hooks/bundle_loader.rb

@@ -70,10 +70,7 @@ module Samagotchi
             # A hook with no declared event cannot be auto-registered.
             next if hook.event.empty?
 
-            event_sym = hook.event.to_sym
-            on_error = hook.on_error
-            priority = hook.priority
-            fail_closed = on_error == "fail_closed" && event_sym == :before_tool_call
+            fail_closed = hook.on_error == "fail_closed" && hook.event == "before_tool_call"
             what = "hook #{basename} (bundle #{bundle_name})"
             file = hooks_dir && File.join(hooks_dir, basename)
             unless file && File.exist?(file)
@@ -87,15 +84,7 @@ module Samagotchi
             end
 
             begin
-              plugin = instantiate(bundle_name, basename, file, settings: settings)
-              policy = if fail_closed then :deny
-                       elsif 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: priority, &handler)
+              load_hook_file(bundle_name, basename, file, hook, registry, settings: settings)
               loaded += 1
             rescue Exception => e # rubocop:disable Lint/RescueException -- a hook's SyntaxError or exit must not stop chi
               raise if e.is_a?(SignalException) # Ctrl-C and kill signals are the user's
@@ -107,6 +96,31 @@ 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
+        # check: #load makes them; the test kit loads a bundle's source
+        # this way.
+        # @param hook [MemoryBundle::BundleHook] its manifest entry
+        # @param namespace [Module, nil] the module the file is evaluated
+        #   in (default: the bundle's, #namespace_for)
+        # @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)
+          nil
+        end
+
         # Why the file doesn't match the sha256 recorded at install, or nil.
         # With none recorded, only a required hook counts as a mismatch.
         def sha_mismatch(file, recorded, required:)
@@ -119,12 +133,13 @@ module Samagotchi
           "its sha256 #{actual[0, 12]}… differs from the installed #{expected[0, 12]}… (edited after install? reinstall the bundle)"
         end
 
-        # Evaluate a plugin file inside the bundle's namespace module and
+        # Evaluate a plugin file inside the bundle's namespace module (or
+        # +namespace+) and
         # return an instance that responds to #call. A class whose
         # initialize takes an argument gets the settings (one Hash, string
         # keys); one that takes none is built bare.
-        def instantiate(bundle_name, basename, file, settings: {})
-          ns = namespace_for(bundle_name)
+        def instantiate(bundle_name, basename, file, settings: {}, namespace: nil)
+          ns = namespace || namespace_for(bundle_name)
           content = File.read(file)
           ns.module_eval(content, file, 1)
           klass = Hooks.class_for(basename, ns)

data/lib/samagotchi/hooks/registry.rb

@@ -49,6 +49,31 @@ module Samagotchi
       namespace.const_get(File.basename(file.to_s, ".rb").split("_").map(&:capitalize).join, false)
     end
 
+    # A hook that raised: its label, event and error (#capture_failures).
+    Failure = Data.define(:hook, :event, :error)
+
+    # Thread.current key: the Array #capture_failures fills, or nil.
+    FAILURES = :samagotchi_hook_failures
+
+    # Collect into +sink+ every hook that raises on this thread while the
+    # block runs, whatever its policy (:skip ones log nothing, a stream
+    # hook's log is rate-limited): the bundle test kit raises them. The
+    # policy still applies. Nests; threads the block starts don't inherit it.
+    # @param sink [Array<Failure>]
+    def self.capture_failures(sink)
+      previous = Thread.current[FAILURES]
+      Thread.current[FAILURES] = sink
+      yield
+    ensure
+      Thread.current[FAILURES] = previous
+    end
+
+    # Add a raising hook to the sink #capture_failures set, if any.
+    def self.record_failure(hook, event, error)
+      Thread.current[FAILURES]&.push(Failure.new(hook: hook.to_s, event: event.to_s, error: error))
+      nil
+    end
+
     # A hook's block wrapped in its error policy: what a loader registers.
     # When the block raises,
     #   :deny  denies the call (event[:guardrail], the Gate's Verdict),
@@ -70,6 +95,7 @@ module Samagotchi
       rescue Exception => e # rubocop:disable Lint/RescueException -- :deny fails closed on anything
         raise unless policy == :deny || e.is_a?(StandardError) || e.is_a?(ScriptError)
 
+        Hooks.record_failure(label, event, e)
         failed = "#{e.class}: #{e.message}"
         if policy == :deny
           payload[:guardrail]&.deny!("#{label} raised #{failed}", rule: "guardrail-load", source: "core", decided_by: "core") if payload.is_a?(Hash)
@@ -273,6 +299,7 @@ module Samagotchi
             hook_proc.call(event)
           rescue StandardError => e
             # A failing hook must not break the turn.
+            Hooks.record_failure(label, name, e)
             Log.exception(:hooks, "hook_failed", e, echo: "[samagotchi:hooks] #{label} failed: #{e.class}: #{e.message}",
                                                 hook: label, event: name.to_s)
           end
@@ -302,6 +329,7 @@ module Samagotchi
             hook_proc.call(event)
           rescue StandardError => e
             # A failing hook must not break the turn.
+            Hooks.record_failure(label, name, e)
             Log.exception(:hooks, "hook_failed", e, echo: "[samagotchi:hooks] #{label} failed: #{e.class}: #{e.message}",
                                                 hook: label, event: name.to_s)
           end
@@ -309,6 +337,16 @@ module Samagotchi
         end
       end
 
+      # The bundle hooks registered for +name+, in the order #fire calls
+      # them (priority, bundle, hook name).
+      # @param name [Symbol]
+      # @return [Array<Array(String, String, Integer)>] [bundle, hook_name, priority]
+      def bundle_hook_names(name)
+        @mutex.synchronize do
+          sorted_bundle_hooks(name).map { |h| [h[:bundle], h[:hook_name], h[:priority]] }
+        end
+      end
+
       # @return [Integer] total number of registered hooks (bundle + plain)
       def size
         @mutex.synchronize do
@@ -323,15 +361,18 @@ module Samagotchi
       # turn-scoped hooks, each in registration order.
       def ordered_procs(name)
         @mutex.synchronize do
-          bundle_procs = (@bundle_hooks[name] || [])
-            .sort_by { |h| [h[:priority].to_i, h[:bundle].to_s, h[:hook_name].to_s] }
-            .map { |h| ["#{h[:hook_name]} (bundle #{h[:bundle]})", h[:proc]] }
+          bundle_procs = sorted_bundle_hooks(name).map { |h| ["#{h[:hook_name]} (bundle #{h[:bundle]})", h[:proc]] }
           config_procs = (@persistent_hooks[name] || []).map { |h| [h[:label], h[:proc]] }
           turn_procs = (@hooks[name] || []).map { |hook_proc| [TURN_HOOK_LABEL, hook_proc] }
           bundle_procs + config_procs + turn_procs
         end
       end
 
+      # The bundle hooks for an event in fire order; call under @mutex.
+      def sorted_bundle_hooks(name)
+        (@bundle_hooks[name] || []).sort_by { |h| [h[:priority].to_i, h[:bundle].to_s, h[:hook_name].to_s] }
+      end
+
       # The helpers, once per fire; a fire site's own keys stay.
       def with_runtime(event)
         return unless event.is_a?(Hash)

data/lib/samagotchi/host_registry.rb

@@ -229,15 +229,23 @@ module Samagotchi
       # ModelRef names a host only when it is one of ours
       return [find_entry(ref.host_name), ref.id] if ref.host_name
 
-      down = ref.id.to_s.strip.downcase
-      listed = @mutex.synchronize { @model_index }&.fetch(down, nil) || []
-      candidates = @entries.values.select { |e| listed.include?(e.name) || e.models&.key?(down) }.map(&:name)
-      candidates = saved_hosts_for(down) if candidates.empty?
+      candidates = hosts_with_model(ref.id)
       default = default_entry
       name = candidates.include?(default.name) ? default.name : candidates.first
       [(name && find_entry(name)) || default, ref.id]
     end
 
+    # The hosts that list or declare the model id +id+, in hosts: order: by
+    # the cached lists and hosts.<name>.models, else by the saved lists
+    # (ModelListStore). None asked: no discovery here.
+    # @return [Array<String>] host names, empty when no host has it
+    def hosts_with_model(id)
+      down = id.to_s.strip.downcase
+      listed = @mutex.synchronize { @model_index }&.fetch(down, nil) || []
+      names = @entries.values.select { |e| listed.include?(e.name) || e.models&.key?(down) }.map(&:name)
+      names.empty? ? saved_hosts_for(down) : names
+    end
+
     # The chat adapter for a host (one per host, so its cached model list
     # serves the context window), as LLM::Adapters builds it for the host's
     # api. Only chat hosts use it for turns.

data/lib/samagotchi/llm/adapter_common.rb

@@ -24,11 +24,13 @@ module Samagotchi
 
       # The adapter's LLM::HTTP: the timeouts (#timeouts), one attempt when
       # +retries+ is false and no +retry_policy+ is given.
-      def build_http(timeout:, open_timeout:, retries:, retry_policy:, sleeper:, first_token_timeout:, api_key:)
+      def build_http(timeout:, open_timeout:, retries:, retry_policy:, sleeper:, first_token_timeout:, api_key:,
+                     diagnosis_header: nil)
         open_timeout, read_timeout = timeouts(timeout, open_timeout)
         policy = retry_policy || (retries ? nil : HTTP::RetryPolicy.none)
         HTTP.new(label: @host_name, open_timeout: open_timeout, read_timeout: read_timeout, retry_policy: policy,
-                 sleeper: sleeper, first_token_timeout: first_token_timeout, api_key: api_key)
+                 sleeper: sleeper, first_token_timeout: first_token_timeout, api_key: api_key,
+                 diagnosis_header: diagnosis_header)
       end
 
       # [open, read] seconds: server.open_timeout / server.read_timeout,

data/lib/samagotchi/llm/anthropic_binding_recovery.rb

@@ -27,6 +27,9 @@ module Samagotchi
       # The only drop the loop settles: a model_binding_mismatch (a /model
       # downgrade) keeps its blocks, a switch back reads them again.
       PREFIX_DROP = "prefix_binding_mismatch"
+      # The 400's undocumented diagnosis header, kept on the ProviderError and
+      # logged as `diagnosis`.
+      DIAGNOSIS_HEADER = "anthropic-thinking-prefix-mismatch"
 
       # One request's binding recovery (#advance): the step taken
       # (nil, :drop_block or :strip), the steps tried, where a strip starts

data/lib/samagotchi/llm/anthropic_messages.rb

@@ -116,7 +116,8 @@ module Samagotchi
         @binding = AnthropicBindingRecovery.new(refusals: @refusals, host_name: @host_name, budget_form: method(:budget_form?))
         @http = build_http(timeout: timeout, open_timeout: open_timeout, retries: retries, retry_policy: retry_policy,
                            sleeper: sleeper, first_token_timeout: first_token_timeout,
-                           api_key: ApiKey.for(api_key_env, host: @host_name, env: env, scheme: auth || @dialect.auth))
+                           api_key: ApiKey.for(api_key_env, host: @host_name, env: env, scheme: auth || @dialect.auth),
+                           diagnosis_header: AnthropicBindingRecovery::DIAGNOSIS_HEADER)
       end
 
       # The same contract as OpenAIChat#chat; +messages+ are ChatLoop's

data/lib/samagotchi/llm/http.rb

@@ -43,8 +43,9 @@ module Samagotchi
 
       # Requests of these purposes are the ones a turn waits on (or, for the
       # turn-end warm-up, prepares the next one): INFO lines (and ERROR when
-      # they fail). Probes and model lists are DEBUG.
-      LOGGED_PURPOSES = %w[chat recap warmup].freeze
+      # they fail); so are a plugin's ctx.http calls ("plugin"). Probes and
+      # model lists are DEBUG.
+      LOGGED_PURPOSES = %w[chat recap warmup plugin].freeze
 
       # Exponential backoff: base_delay * 2^(attempt-1), capped at max_delay,
       # for up to +max+ retries (max + 1 attempts).
@@ -103,10 +104,13 @@ module Samagotchi
       #   show something (see #stream_lines); nil: no limit
       # @param api_key [ApiKey, nil] sent on every request; nil: no
       #   Authorization header (a local server)
+      # @param diagnosis_header [String, nil] a response header the adapter
+      #   wants kept on a ProviderError as its diagnosis; nil: none
       def initialize(label:, open_timeout:, read_timeout:, retry_policy: nil, sleeper: nil, first_token_timeout: nil,
-                     api_key: nil)
+                     api_key: nil, diagnosis_header: nil)
         @label = label
         @api_key = api_key
+        @diagnosis_header = diagnosis_header
         @open_timeout = open_timeout
         @read_timeout = read_timeout
         @first_token_timeout = first_token_timeout&.positive? ? first_token_timeout : nil
@@ -187,11 +191,11 @@ module Samagotchi
       # @raise [RequestCancelled] when +cancel_controller+ cancels (with or
       #   without retries)
       def fetch(uri, request, retries: true, check_status: true, open_timeout: nil, read_timeout: nil,
-                cancel_controller: nil, log_fields: {})
+                write_timeout: nil, cancel_controller: nil, log_fields: {})
         identify(request)
         current = new_attempt_state(uri, request, log_fields, stream: false)
         attempt = lambda do |state|
-          start(uri, open_timeout: open_timeout, read_timeout: read_timeout, max_retries: 0) do |http|
+          start(uri, open_timeout: open_timeout, read_timeout: read_timeout, write_timeout: write_timeout, max_retries: 0) do |http|
             state[:http] = http
             http.request(request).tap do |response|
               state[:status] = response.code.to_i
@@ -221,8 +225,9 @@ module Samagotchi
         @api_key&.authorize(request)
       end
 
-      def start(uri, open_timeout: nil, read_timeout: nil, max_retries: nil, &)
+      def start(uri, open_timeout: nil, read_timeout: nil, write_timeout: nil, max_retries: nil, &)
         options = { open_timeout: open_timeout || @open_timeout, read_timeout: read_timeout || @read_timeout }
+        options[:write_timeout] = write_timeout if write_timeout
         # Net::HTTP retries an idempotent request once on its own (max_retries
         # defaults to 1) when the connection drops before an answer: chi's
         # RetryPolicy owns retries (and the log line says how many were sent),
@@ -418,7 +423,7 @@ module Samagotchi
 
         error = ProviderErrors.from_response(status: status, body: response.body.to_s, host: @label,
                                              retry_after: response["Retry-After"],
-                                             diagnosis: response["anthropic-thinking-prefix-mismatch"])
+                                             diagnosis: @diagnosis_header && response[@diagnosis_header])
         error.hint ||= @api_key ? @api_key.hint : ApiKey.missing_hint(@label) if error.is_a?(AuthError)
         raise error
       end

data/lib/samagotchi/plugin/card.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Samagotchi
+  module Plugin
+    # A card's checked event (docs/plugins.md, Cards): what Engine#show_card
+    # routes and the bundle test kit records.
+    module Card
+      LEVELS = %i[info warn].freeze
+      MAX_ACTIONS = 6
+
+      module_function
+
+      # @return [Hash] {type: :card, id:, source:, title:, body:, level:,
+      #   actions: [{label:, command:}]}; a new id when none is given
+      # @raise [ArgumentError] a card without a title, a bad level or action
+      def build(source:, title:, body:, actions:, level:, id:)
+        title = title.to_s.strip
+        raise ArgumentError, "a card needs a title" if title.empty?
+
+        level = level.to_s.to_sym
+        raise ArgumentError, "card level must be one of #{LEVELS.join(", ")}" unless LEVELS.include?(level)
+
+        actions = Array(actions)
+        raise ArgumentError, "a card has at most #{MAX_ACTIONS} actions" if actions.size > MAX_ACTIONS
+
+        actions = actions.map do |action|
+          raise ArgumentError, "a card action is a Hash {label:, command:}" unless action.is_a?(Hash)
+
+          action = action.transform_keys(&:to_sym)
+          command = action[:command].to_s.strip
+          raise ArgumentError, "a card action needs a command" if command.empty? || command.include?("\n")
+
+          label = action[:label].to_s.strip
+          { label: label.empty? ? command : label, command: command }
+        end
+        id = id.to_s.strip
+        { type: :card, id: id.empty? ? SecureRandom.hex(4) : id, source: source.to_s, title: title, body: body.to_s,
+          level: level, actions: actions }
+      end
+    end
+  end
+end