samagotchi 0.79.0 → 0.81.0

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_config.rb

@@ -23,11 +23,6 @@ module Samagotchi
                            :first_token_timeout, :vision, :sampling, :thinking, :reasoning_history, :remote,
                            :window_tokens, :steer_cut_after, :llm_context_strategy, :llm_context_apply, :llm_context_budget_tokens,
                            :models) do
-    # An api: anthropic host without url/host talks to Anthropic's own API.
-    ANTHROPIC_URL = "https://api.anthropic.com"
-    # auth: as written => the LLM::ApiKey scheme.
-    AUTH_SCHEMES = { "bearer" => :bearer, "x-api-key" => :x_api_key }.freeze
-
     # Every field but name may be left out: nil, models {}.
     def initialize(**fields)
       super(**members.to_h { |m| [m, nil] }, models: {}, **fields)
@@ -77,8 +72,8 @@ module Samagotchi
       end
 
       auth = value.call(:auth).to_s.strip.downcase
-      fields[:auth] = AUTH_SCHEMES[auth] unless auth.empty?
-      return invalid(name, "auth must be one of #{AUTH_SCHEMES.keys.join(", ")}") if !auth.empty? && fields[:auth].nil?
+      fields[:auth] = HostConfig::AUTH_SCHEMES[auth] unless auth.empty?
+      return invalid(name, "auth must be one of #{HostConfig::AUTH_SCHEMES.keys.join(", ")}") if !auth.empty? && fields[:auth].nil?
 
       if fields[:auth] && fields[:api_key_env].nil?
         ConfigFile.warn_once "Warning: #{where}: auth has no effect without api_key_env (no key is sent)"
@@ -121,7 +116,7 @@ module Samagotchi
       host = value.call(:host)
       port = value.call(:port)
       url = value.call(:url).to_s.strip
-      url = ANTHROPIC_URL if url.empty? && api == :anthropic && host.to_s.strip.empty? && port.to_s.strip.empty?
+      url = HostConfig::ANTHROPIC_URL if url.empty? && api == :anthropic && host.to_s.strip.empty? && port.to_s.strip.empty?
       scheme = "http"
       unless url.empty?
         return invalid(name, "give url or host/port, not both") unless host.to_s.strip.empty? && port.to_s.strip.empty?
@@ -178,4 +173,9 @@ module Samagotchi
     end
     private_class_method :invalid
   end
+
+  # An api: anthropic host without url/host talks to Anthropic's own API.
+  HostConfig::ANTHROPIC_URL = "https://api.anthropic.com"
+  # auth: as written => the LLM::ApiKey scheme.
+  HostConfig::AUTH_SCHEMES = { "bearer" => :bearer, "x-api-key" => :x_api_key }.freeze
 end

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/idle_client.rb

@@ -3,6 +3,7 @@
 require "json"
 require_relative "llm/adapters"
 require_relative "log"
+require_relative "side_usage"
 
 module Samagotchi
   # Standalone summarizer for the idle session-recap feature.
@@ -54,9 +55,12 @@ module Samagotchi
     # @param api [Symbol] the wire to talk (LLM::Adapters; IdleTarget#api)
     # @param auth [Symbol, nil] the header the key goes in (IdleTarget#auth)
     # @param dialect [String, nil] a Messages host's dialect (IdleTarget#dialect)
+    # @param price [ModelPrice, nil] the model's price on its host
+    #   (IdleTarget#price), on each SideUsage the on_usage callbacks get
     def initialize(model:, base_url: nil, api_key_env: nil, timeout: DEFAULT_TIMEOUT_SECONDS, env: ENV, purpose: "recap",
-                   api: :openai, auth: nil, dialect: nil)
+                   api: :openai, auth: nil, dialect: nil, price: nil)
       @model = model
+      @price = price
       # A recap is best-effort: one short attempt, no retries. The idle job
       # tries again after the next activity, never on its own. Only the
       # Messages adapter takes a dialect.
@@ -70,7 +74,7 @@ module Samagotchi
     # @return [IdleClient]
     def self.for(target, **)
       new(model: target.model, base_url: target.base_url, api_key_env: target.api_key_env, api: target.api,
-          auth: target.auth, dialect: target.dialect, **)
+          auth: target.auth, dialect: target.dialect, price: target.price, **)
     end
 
     THINK_RE = /<\|think\|.*?\|think\|>/m
@@ -100,11 +104,13 @@ module Samagotchi
     # @return [Summary, nil]
     # +session_id+: the session it is about, sent as the turns send it
     # (Session-Id, a dialect's affinity header), nil for none.
-    def summarize(prompt, session_id: nil)
+    # +on_usage+: called with the request's SideUsage (kind "recap") once a
+    # reply came back, see #ask.
+    def summarize(prompt, session_id: nil, on_usage: nil)
       messages = prompt.is_a?(Array) ? prompt : [{ role: "user", content: prompt.to_s.strip }]
       return nil if messages.all? { |m| m[:content].to_s.strip.empty? }
 
-      response = generate(messages, session_id: session_id)
+      response = generate(messages, session_id: session_id, on_usage: on_usage)
       cleaned = response.text.to_s.strip
       cleaned.empty? ? nil : Summary.new(text: cleaned, model: response.model)
     rescue SummarizeError
@@ -121,14 +127,18 @@ module Samagotchi
     # @param options [Hash] more request body fields (logprobs: true,
     #   top_logprobs: 5)
     # @param session_id [String, nil] the session it is about (#summarize)
+    # @param on_usage [#call, nil] called with the request's SideUsage
+    #   (+kind+, the counts, the reported cost, the client's price) once a
+    #   reply came back, a billed one with no usable text too; never for a
+    #   request that got no reply. Its errors are logged, never raised.
     # @return [Summary] the answer ("" when the model said nothing)
     # @raise [SummarizeError] any failure but a cancel; its #cause is an
     #   LLM::BadRequest when the host refused the request (+options+ it
     #   doesn't take, say)
     # @raise [LLM::RequestCancelled] +cancel_controller+ was cancelled
-    def ask(messages, max_tokens: MAX_TOKENS, cancel_controller: nil, kind: "ask", options: {}, session_id: nil)
+    def ask(messages, max_tokens: MAX_TOKENS, cancel_controller: nil, kind: "ask", options: {}, session_id: nil, on_usage: nil)
       response = generate(messages, max_tokens: max_tokens, cancel_controller: cancel_controller, whole_sentences: false,
-                                    kind: kind, options: options, session_id: session_id)
+                                    kind: kind, options: options, session_id: session_id, on_usage: on_usage)
       Summary.new(text: response.text.to_s.strip, model: response.model, top_logprobs: response.top_logprobs)
     rescue SummarizeError, LLM::RequestCancelled
       raise
@@ -146,7 +156,7 @@ module Samagotchi
     # +max_tokens+, the text keeps its finished sentences (+whole_sentences+)
     # or all of it, with "…".
     def generate(messages, max_tokens: MAX_TOKENS, cancel_controller: nil, whole_sentences: true, kind: "recap", options: {},
-                 session_id: nil)
+                 session_id: nil, on_usage: nil)
       response = begin
         request(messages, max_tokens, cancel_controller, options, session_id)
       rescue LLM::BadRequest => e
@@ -156,6 +166,7 @@ module Samagotchi
         retry
       end
       log_usage(response, kind)
+      report_usage(on_usage, response, kind)
       content = response.text
       reasoning = response.reasoning
       raise SummarizeError, "server returned no parseable assistant content" if content.empty? && reasoning.empty?
@@ -176,14 +187,33 @@ module Samagotchi
       raise SummarizeError, "server returned no parseable assistant content (#{e.message})"
     end
 
-    # The request's prompt-cache counts (a side request on the session's
-    # host can evict the session's cached prompt there).
+    # The request's token counts and reported cost (a broadcast's triage
+    # has no session to count them in). The cache counts show whether the
+    # host reused a cached prefix. A side request evicts a session's cached
+    # prompt only on a llama.cpp with no host-memory cache (--cache-ram 0)
+    # or an old single-slot build, or when pinned to the session's slot,
+    # which chi never does; paid hosts and current llama.cpp aren't
+    # affected (docs/internals/prompt-caching.md).
     def log_usage(response, kind)
-      fields = response.usage&.cache_fields || {}
+      usage = response.usage
+      fields = usage&.cache_fields || {}
       return if fields.empty?
 
       Log.info(:recap, "request_usage", kind: kind, model: @model, prompt: fields[:prompt_tokens],
-                                        cached: fields[:cached_tokens], cache_write: fields[:cache_write_tokens])
+                                        cached: fields[:cached_tokens], cache_write: fields[:cache_write_tokens],
+                                        # A cost as written: Log rounds Floats to 3 places.
+                                        completion: usage.completion_tokens, cost: usage.cost&.to_s)
+    end
+
+    # The request's SideUsage to +on_usage+ (a session counts it in its side
+    # line); a reply without counts is one request with zero tokens.
+    # Counting never fails the side answer: a callback's error is logged.
+    def report_usage(on_usage, response, kind)
+      return unless on_usage
+
+      on_usage.call(SideUsage.from_usage(response.usage, kind: kind, model: @model, price: @price))
+    rescue StandardError => e
+      Log.warn(:recap, "usage_callback_failed", kind: kind, model: @model, error: "#{e.class}: #{e.message}")
     end
 
     # After a host refused this step's thinking fields: the next step, kept

data/lib/samagotchi/idle_recap.rb

@@ -288,12 +288,17 @@ module Samagotchi
                    client: nil,
                    store: nil,
                    session_id: -> {},
+                   on_usage: nil,
                    clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
       raise ArgumentError, "IdleRecap requires an engine" unless engine
 
       @engine = engine
       # The recapped session's id, sent with the request (IdleClient#summarize).
       @session_id = session_id
+      # Called with each recap request's SideUsage (IdleClient#summarize),
+      # a dropped recap's too: it was billed (RecapSetup: the Engine's
+      # side line).
+      @on_usage = on_usage
       @target = target || lambda {
         IdleTarget.new(base_url: base_url, api_key_env: api_key_env, model: model, label: model)
       }
@@ -547,7 +552,7 @@ module Samagotchi
 
     def spawn_summarize(client, prompt)
       Thread.new do
-        client.summarize(prompt, session_id: @session_id.call)
+        client.summarize(prompt, session_id: @session_id.call, on_usage: @on_usage)
       rescue StandardError => e
         # No recap this time (the next idle window tries again); say why.
         Log.exception(:recap, "summarize_failed", e)

data/lib/samagotchi/idle_target.rb

@@ -14,8 +14,14 @@ module Samagotchi
   #   auth:, LLM::ApiKey::SCHEMES); nil: the api's own default
   # @!attribute dialect [String, nil] an api: anthropic host's dialect:
   #   (LLM::Dialect), so a side request gets its auth and fields
-  IdleTarget = Data.define(:base_url, :api_key_env, :model, :label, :api, :auth, :dialect) do
-    def initialize(api: :openai, auth: nil, dialect: nil, **) = super
+  # @!attribute price [ModelPrice, nil] the host's models: price for the
+  #   id asked for (as EffectiveModel#price), what a side request's cost is
+  #   estimated from; nil for none, and for a bare base_url target
+  IdleTarget = Data.define(:base_url, :api_key_env, :model, :label, :api, :auth, :dialect, :price) do
+    def initialize(api: :openai, auth: nil, dialect: nil, price: nil, **) = super
+
+    # +entry+'s models: price for +id+ (the id asked for, case-insensitively).
+    def self.price_of(entry, id) = entry.models&.dig(id.to_s.strip.downcase)&.price
 
     # The api a side request to +entry+ talks: a chat host's own, else the
     # OpenAI API (a raw host's llama.cpp serves /v1 too).
@@ -49,7 +55,8 @@ module Samagotchi
       resolved = host_registry.resolve(name)
       entry = resolved.entry
       new(base_url: entry.api_base_url, api_key_env: entry.api_key_env, model: resolved.bare_model,
-          label: name.to_s.strip, api: api_of(entry), auth: entry.auth, dialect: dialect_of(entry))
+          label: name.to_s.strip, api: api_of(entry), auth: entry.auth, dialect: dialect_of(entry),
+          price: price_of(entry, resolved.bare_model))
     end
 
     # A side model's settings (recap.*, broadcast.triage_*) as a target:
@@ -74,6 +81,7 @@ module Samagotchi
       api = :openai
       auth = nil
       dialect = nil
+      entry = nil
       if host_ref
         entry = host_registry.find_entry(host_ref)
         raise self::Unresolved.new(:host_ref_unknown, model: model, host_ref: host_ref) unless entry
@@ -95,7 +103,7 @@ module Samagotchi
       raise self::Unresolved.new(:incomplete, model: model, host_ref: host_ref) if blank(base_url).nil? || blank(model).nil?
 
       new(base_url: base_url.to_s.strip, api_key_env: api_key_env, model: model.to_s.strip, label: label.strip, api: api, auth: auth,
-          dialect: dialect)
+          dialect: dialect, price: entry && price_of(entry, model))
     end
 
     # Whether the settings fix a host (+base_url+, +host_ref+, or a model

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/llm/usage.rb

@@ -8,7 +8,11 @@ module Samagotchi
     # (:server), else zeros (:none). +cached_tokens+ is the prompt the server
     # reused from its cache, +cache_write_tokens+ what it wrote to it
     # (OpenRouter reports those for Anthropic models); 0 when not reported.
-    Usage = Data.define(:prompt_tokens, :completion_tokens, :source, :cached_tokens, :cache_write_tokens) do
+    # +reasoning_tokens+ is the completion's reasoning part (0 when not
+    # reported), +cost+ the provider's reported cost in USD (OpenRouter's
+    # usage.cost; nil when not reported, a reported 0 stays 0).
+    Usage = Data.define(:prompt_tokens, :completion_tokens, :source, :cached_tokens, :cache_write_tokens,
+                        :reasoning_tokens, :cost) do
       # @return [Usage, nil] nil when the payload carries no counts
       def self.from_payload(payload)
         counts = TokenUsage.from_payload(payload)
@@ -16,12 +20,14 @@ module Samagotchi
 
         new(prompt_tokens: counts.prompt_tokens.to_i, completion_tokens: counts.completion_tokens.to_i,
             source: :server, cached_tokens: counts.cached_tokens.to_i,
-            cache_write_tokens: counts.cache_write_tokens.to_i)
+            cache_write_tokens: counts.cache_write_tokens.to_i, reasoning_tokens: counts.reasoning_tokens.to_i,
+            cost: counts.cost)
       end
 
       def self.none = new(prompt_tokens: 0, completion_tokens: 0, source: :none)
 
-      def initialize(prompt_tokens:, completion_tokens:, source:, cached_tokens: 0, cache_write_tokens: 0)
+      def initialize(prompt_tokens:, completion_tokens:, source:, cached_tokens: 0, cache_write_tokens: 0,
+                     reasoning_tokens: 0, cost: nil)
         super
       end
 

data/lib/samagotchi/model_price.rb

@@ -34,6 +34,22 @@ module Samagotchi
     end
     private_class_method :warn_once
 
+    # The cost rule, one place for a turn's generation (SessionMetrics) and
+    # a side request (SessionMetrics::SideTotals): a reported cost wins; a
+    # reported 0, or none, with a price is estimated from the price (a
+    # gateway that doesn't bill per call reports 0). The reported cost
+    # itself is summed apart, a 0 included.
+    # @param price [ModelPrice, nil]
+    # @param reported_cost [Numeric, nil] the provider's cost (usage.cost)
+    # @return [Float, nil] the estimate, nil when none applies (no price, or
+    #   a positive reported cost), so a sum without one stays as it was
+    def self.estimate(price, reported_cost:, prompt_tokens:, cached_tokens:, cache_write_tokens:, completion_tokens:)
+      return nil unless price && (reported_cost.nil? || reported_cost.zero?)
+
+      price.cost(prompt_tokens: prompt_tokens, cached_tokens: cached_tokens, cache_write_tokens: cache_write_tokens,
+                 completion_tokens: completion_tokens)
+    end
+
     # USD for one generation, OpenAI usage semantics: +prompt_tokens+ holds
     # the cached reads and the cache writes (OpenRouter keeps that for
     # Anthropic models), and reasoning is inside +completion_tokens+.

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