samagotchi 0.79.0 → 0.81.0

data/lib/samagotchi/plugin/context.rb

@@ -5,19 +5,34 @@ require_relative "../log"
 require_relative "../paths"
 require_relative "../guardrails/context"
 require_relative "../idle_client"
+require_relative "service"
 require_relative "side_question"
-require_relative "sessions"
-require_relative "attached_context"
 
 module Samagotchi
+  # Context#saved_session reads it; Sessions and AttachedContext load it too.
+  autoload :Session, File.expand_path("../session", __dir__)
+
   module Plugin
+    # Loaded on first ctx.sessions / ctx.context (or a bundle naming
+    # Sessions::Error): they pull in the session, delivery and bridge
+    # client files (~150), which a plugin that never calls them, and the
+    # bundle test kit, don't need.
+    autoload :Sessions, File.expand_path("sessions", __dir__)
+    autoload :AttachedContext, File.expand_path("attached_context", __dir__)
+    # ctx.http's file needs only json and uri (net/http loads with the first
+    # real request); autoloaded so a bundle can name HttpError at load time.
+    autoload :Http, File.expand_path("http", __dir__)
+    autoload :HttpError, File.expand_path("http", __dir__)
+    autoload :HttpCancelled, File.expand_path("http", __dir__)
+
     # The Engine's side of a Context: callables, so the Engine itself is
     # never handed out. +messages+ returns the conversation, +notify+ takes
     # (text, level, label, fallback_for:), +ask_user+ takes (question:, options:, header:,
     # allow_freeform:, hook:) like the hook runtime's, +card+ takes
     # Engine#show_card's keywords and returns the id, +ask_model+ takes
-    # (chat messages, timeout:, max_tokens:, cancel_controller:) and returns
-    # the answer text.
+    # (chat messages, timeout:, max_tokens:, cancel_controller:, model:: a
+    # configured model ref, nil for the session's) and returns the answer
+    # text.
     # +messages_partial+ says whether +messages+ leaves out a running turn;
     # +prompt_files+ returns the files whose text the built system prompt
     # holds (SystemPrompt#prompt_files, [] before a build); +model_name+
@@ -32,10 +47,14 @@ module Samagotchi
     # +toolkit+ returns the session's toolkit name, +declared_tools+ the
     # tool names its next turn declares, +use_toolkit+ takes a name and
     # returns whether it staged it (Engine#use_toolkit).
+    # +cancel_controller+ takes (handler:) and returns the controller a
+    # ctx.http call without cancel: uses, nil for none: an init task's own,
+    # else the running turn's for work done for it (the turn's thread, or a
+    # plugin handler: +handler+) until the turn has ended.
     Host = Struct.new(:session_id, :cwd, :messages, :messages_partial, :notify, :ask_user, :cancelled, :card,
                       :ask_model, :model_name, :model_key, :state_dir, :scratch, :setup, :prompt_files,
                       :steer, :stop_turn, :stop_generation, :frontend, :toolkit, :declared_tools, :use_toolkit,
-                      keyword_init: true)
+                      :cancel_controller, keyword_init: true)
 
     # ctx.ask_model failed: the model couldn't be reached, timed out, or
     # sent nothing usable. The message says why, for the user.
@@ -58,7 +77,7 @@ module Samagotchi
     # handler started) they act on the session now, through the Host.
     class Context
       # Thread.current key: {Context => the event its handler runs for}.
-      CURRENT_EVENTS = :samagotchi_plugin_current_events
+      CURRENT_EVENTS = Service::CURRENT_EVENTS
       # Debug-log records tagged plugins, with bundle=<bundle> (tags are a
       # closed list, LogLine::TAGS).
       class Logger
@@ -85,7 +104,12 @@ module Samagotchi
       # @param label [String] "<file> (bundle <name>)", what notices and
       #   questions are labelled by
       # @param host [Host]
-      def initialize(bundle:, label:, settings:, host:, env: ENV)
+      # @param sessions [Object, nil] what #sessions returns instead of a
+      #   Sessions over +host+ (the test kit's recording one)
+      # @param http_transport [#call, nil] what #http sends through instead
+      #   of the network (the test kit's FakeHttp); the default cancel
+      #   lookup stays the Context's own
+      def initialize(bundle:, label:, settings:, host:, env: ENV, sessions: nil, http_transport: nil)
         @bundle = bundle.to_s
         @label = label
         @settings = deep_freeze(settings.is_a?(Hash) ? settings : {})
@@ -94,6 +118,9 @@ module Samagotchi
         @log = Logger.new(@bundle)
         @git = Guardrails::GitInfo.new
         @data_dir = nil
+        @sessions = sessions
+        @http_transport = http_transport
+        @http = nil
       end
 
       # The bundle, never the environment it holds (every API key in it).
@@ -254,15 +281,21 @@ module Samagotchi
       #   ASK_MAX_TOKENS); an answer cut off ends with "…"
       # @param cancel [CancellationController, nil] cancelling it aborts
       #   the request
+      # @param model [String, nil] a configured model ("host:id", an alias,
+      #   or a model id one of the hosts lists) instead of the session's:
+      #   keys stay chi's config, a plugin never names a URL or a key
       # @return [String] the answer ("" when the model said nothing)
+      # @raise [ArgumentError] no prompt, or a +model+ that names nothing configured
       # @raise [ModelError] the request failed or timed out
       # @raise [ModelCancelled] +cancel+ was cancelled
-      def ask_model(messages:, prompt:, system: nil, timeout: 120, max_tokens: nil, cancel: nil)
+      def ask_model(messages:, prompt:, system: nil, timeout: 120, max_tokens: nil, cancel: nil, model: nil)
         raise ArgumentError, "ask_model needs a prompt" if prompt.to_s.strip.empty?
+        raise ArgumentError, "ask_model's model: is a String like \"host:id\"" unless model.nil? || (model.is_a?(String) && !model.strip.empty?)
 
         request = SideQuestion.request(messages: messages, prompt: prompt, system: system)
         limit = max_tokens.nil? ? ASK_MAX_TOKENS : Integer(max_tokens)
-        @host.ask_model.call(request, timeout: Float(timeout), max_tokens: limit, cancel_controller: cancel).to_s
+        @host.ask_model.call(request, timeout: Float(timeout), max_tokens: limit, cancel_controller: cancel,
+                                      model: model&.strip, source: @bundle).to_s
       rescue IdleClient::SummarizeError => e
         raise ModelError, e.message
       rescue LLM::RequestCancelled
@@ -279,6 +312,16 @@ module Samagotchi
         @sessions ||= Sessions.new(@host)
       end
 
+      # An HTTP client for calling services (Http, docs/plugins.md). A call
+      # made for the turn (a tool, a handler) stops when the turn is stopped;
+      # one from a command, a service or your own thread has only its
+      # timeout unless it passes cancel:.
+      # @return [Http]
+      def http
+        @http ||= Http.new(bundle: @bundle, transport: @http_transport,
+                           cancel_lookup: -> { http_cancel_controller })
+      end
+
       # This session's attached context: attach a URL or a command, list
       # (AttachedContext).
       # @return [AttachedContext]
@@ -342,6 +385,15 @@ module Samagotchi
 
       private
 
+      # Whether this plugin's handler runs on this thread (#with_event).
+      def in_handler? = !!Thread.current[CURRENT_EVENTS]&.key?(self)
+
+      # The controller a ctx.http call without cancel: stops with: nil inside
+      # a service's start block, even on the turn's thread.
+      def http_cancel_controller
+        Service.starting? ? nil : @host.cancel_controller&.call(handler: in_handler?)
+      end
+
       # The event[:x] helper of the event this plugin's handler runs for on
       # this thread, or nil (not in a handler).
       def event_helper(name)

data/lib/samagotchi/plugin/http.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module Samagotchi
+  module Plugin
+    # ctx.http failed: the request didn't complete (refused, timed out, DNS,
+    # TLS, reset, a malformed response, a bad gzip body), or Response#json
+    # was called on a body that isn't JSON. The message says what and where,
+    # never headers or a body; the original error is the #cause.
+    class HttpError < StandardError; end
+
+    # A ctx.http request was cancelled (its cancel: controller, or the turn's
+    # Stop).
+    class HttpCancelled < HttpError; end
+
+    # An HTTP client for a plugin (ctx.http, docs/plugins.md): a few methods,
+    # a small Response, one error type (HttpError). It checks its arguments
+    # and builds the request; a transport (Http::NetTransport by default,
+    # the test kit's FakeHttp) puts it on the wire.
+    #
+    # Stateless apart from its bundle's name and its transport: any number of
+    # threads may call it.
+    #
+    # This file needs only json and uri: net/http and chi's HTTP layer load
+    # with the first real request (NetTransport).
+    class Http
+      # What a request is given as the timeout (open, and per read) when none is.
+      DEFAULT_TIMEOUT = 10
+      METHODS = %w[GET POST PUT PATCH DELETE HEAD].freeze
+
+      # One answer. +headers+ is frozen, with lower-case names and a repeated
+      # header's values joined with ", "; +body+ is never nil (HEAD and empty
+      # bodies are ""), tagged UTF-8 when its bytes are valid UTF-8, else
+      # left binary (scrub it before handing unknown text to the model).
+      Response = Data.define(:status, :headers, :body) do
+        # @return [Boolean] a 2xx status
+        def ok? = status.between?(200, 299)
+
+        # The body parsed as JSON, on each call (a Data keeps nothing).
+        # @raise [HttpError] the body isn't JSON
+        def json
+          JSON.parse(body)
+        rescue JSON::ParserError, EncodingError
+          raise HttpError, "not JSON: status #{status}, #{body.bytesize} bytes"
+        end
+      end
+
+      # @param bundle [String] the bundle's name (the log line's bundle=)
+      # @param cancel_lookup [#call] → the CancellationController a call
+      #   without cancel: uses (nil: none), read at call time
+      # @param transport [#call, nil] call(method:, uri:, headers:, body:,
+      #   timeout:, cancel:) → Response, or raises HttpError / HttpCancelled
+      def initialize(bundle:, cancel_lookup: -> {}, transport: nil)
+        @bundle = bundle.to_s
+        @cancel_lookup = cancel_lookup
+        @transport = transport
+      end
+
+      # @param url [String, URI] http or https
+      # @param headers [Hash] header name => value
+      # @param timeout [Numeric] seconds: open, and each read
+      # @param cancel [CancellationController, nil] overrides the default
+      #   (the turn's, for a call made for the turn)
+      # @return [Response] any status: a 4xx/5xx is returned, not raised
+      # @raise [ArgumentError] a bad URL, scheme, header or timeout
+      # @raise [HttpError] the request didn't complete
+      # @raise [HttpCancelled] it was cancelled
+      def get(url, headers: {}, timeout: DEFAULT_TIMEOUT, cancel: nil)
+        request("GET", url, headers: headers, timeout: timeout, cancel: cancel)
+      end
+
+      # POST +body+ encoded as JSON (Content-Type and Accept: application/json
+      # unless +headers+ name them).
+      # @param body [Object] anything JSON can encode
+      # @raise [ArgumentError] +body+ can't be encoded as JSON, and as #get
+      def post_json(url, body, headers: {}, timeout: DEFAULT_TIMEOUT, cancel: nil)
+        encoded = begin
+          JSON.generate(body)
+        rescue JSON::JSONError, EncodingError => e
+          raise ArgumentError, "can't encode the body as JSON: #{e.class}"
+        end
+        headers = { "Content-Type" => "application/json", "Accept" => "application/json" }
+                  .reject { |name, _| named?(headers, name) }.merge(headers)
+        request("POST", url, body: encoded, headers: headers, timeout: timeout, cancel: cancel)
+      end
+
+      # @param method [String, Symbol] GET POST PUT PATCH DELETE HEAD
+      # @param body [String, nil] sent as is (set your own Content-Type)
+      # @raise [ArgumentError] an unknown method, a body that isn't a String, and as #get
+      def request(method, url, body: nil, headers: {}, timeout: DEFAULT_TIMEOUT, cancel: nil)
+        verb = method.to_s.upcase
+        raise ArgumentError, "unknown HTTP method #{method.inspect} (#{METHODS.join(", ")})" unless METHODS.include?(verb)
+        raise ArgumentError, "the body must be a String (or nil), got #{body.class}" unless body.nil? || body.is_a?(String)
+
+        transport.call(method: verb, uri: parse_url(url), headers: header_hash(headers), body: body,
+                       timeout: timeout_seconds(timeout), cancel: cancel || @cancel_lookup.call)
+      end
+
+      private
+
+      def transport
+        @transport ||= begin
+          require_relative "http_transport"
+          NetTransport.new(bundle: @bundle)
+        end
+      end
+
+      def parse_url(url)
+        uri = url.is_a?(URI::Generic) ? url : URI.parse(url.to_s)
+        unless uri.is_a?(URI::HTTP) && !uri.host.to_s.empty?
+          raise ArgumentError, "the URL must be http:// or https:// with a host: #{quotable(url)}"
+        end
+
+        uri
+      rescue URI::InvalidURIError
+        raise ArgumentError, "not a URL: #{quotable(url)}"
+      end
+
+      # +url+ as an error message may quote it: its first 100 characters
+      # without the query, fragment and user info (a key in them would reach
+      # the logs with the message).
+      def quotable(url)
+        text = url.to_s.sub(/[?#].*\z/m, "").sub(%r{\A([a-z][a-z0-9+.-]*://)[^/@]*@}i, "\\1")
+        text[0, 100].inspect
+      end
+
+      def header_hash(headers)
+        raise ArgumentError, "headers must be a Hash" unless headers.is_a?(Hash)
+
+        headers.to_h do |name, value|
+          name = name.to_s
+          value = value.to_s
+          unless name.match?(/\A[!#$%&'*+\-.^_`|~0-9A-Za-z]+\z/) && !value.match?(/[\r\n\0]/)
+            raise ArgumentError, "bad header #{name[0, 40].inspect}: a name of token characters, a value on one line"
+          end
+
+          [name, value]
+        end
+      end
+
+      def named?(headers, name)
+        headers.keys.any? { |key| key.to_s.casecmp?(name) }
+      end
+
+      def timeout_seconds(timeout)
+        raise ArgumentError, "timeout must be a positive number of seconds" unless timeout.is_a?(Numeric) && timeout.positive?
+
+        timeout.to_f
+      end
+    end
+  end
+end

data/lib/samagotchi/plugin/http_transport.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "zlib"
+require_relative "http"
+require_relative "../llm/http"
+require_relative "../llm/errors"
+
+module Samagotchi
+  module Plugin
+    class Http
+      # Plugin::Http's wire: one LLM::HTTP request per call (chi's TLS,
+      # proxies, User-Agent, cancel by closing the socket, and one log line
+      # without query, headers or body), with chi's retries off. Every error
+      # but a cancel becomes an HttpError, so a plugin rescues one type.
+      #
+      # Loaded with the first real request (it pulls in net/http and the
+      # LLM layer). Stateless.
+      class NetTransport
+        # What went wrong, in words (a message never carries a response).
+        REASONS = {
+          Errno::ECONNREFUSED => "connection refused", Errno::ECONNRESET => "connection reset",
+          Errno::EHOSTUNREACH => "host unreachable", Errno::ENETUNREACH => "network unreachable",
+          Errno::ETIMEDOUT => "timed out", Errno::EPIPE => "connection closed",
+          Timeout::Error => "timed out", IO::TimeoutError => "timed out", EOFError => "connection closed",
+          SocketError => "can't resolve the host", OpenSSL::SSL::SSLError => "TLS error",
+          Net::HTTPBadResponse => "malformed response", Net::HTTPHeaderSyntaxError => "malformed response",
+          Net::ProtocolError => "protocol error", Zlib::Error => "bad compressed body"
+        }.freeze
+
+        def initialize(bundle:)
+          @bundle = bundle.to_s
+        end
+
+        # @return [Response]
+        # @raise [HttpError, HttpCancelled]
+        def call(method:, uri:, headers:, body:, timeout:, cancel:)
+          request = Net::HTTP.const_get(method.capitalize).new(uri, headers)
+          request.body = body if body
+          client = LLM::HTTP.new(label: "plugin:#{@bundle}", open_timeout: timeout, read_timeout: timeout,
+                                 retry_policy: LLM::HTTP::RetryPolicy.none)
+          response = client.fetch(uri, request, retries: false, check_status: false, write_timeout: timeout, cancel_controller: cancel,
+                                                log_fields: { purpose: "plugin", bundle: @bundle })
+          build_response(response)
+        rescue LLM::RequestCancelled
+          raise HttpCancelled, "#{method} #{where(uri)}: cancelled"
+        rescue HttpError
+          raise
+        rescue StandardError => e
+          raise HttpError, "#{method} #{where(uri)}: #{reason(e)}"
+        end
+
+        private
+
+        def build_response(response)
+          headers = {}
+          response.each_header { |name, value| headers[name.downcase] = text(value) }
+          Response.new(status: response.code.to_i, headers: headers.freeze, body: text(response.body))
+        end
+
+        # The bytes as UTF-8 when they are, else as they came.
+        def text(body)
+          text = body.to_s.dup
+          utf8 = text.dup.force_encoding(Encoding::UTF_8)
+          utf8.valid_encoding? ? utf8 : text.force_encoding(Encoding::BINARY)
+        end
+
+        def where(uri) = "#{uri.host}:#{uri.port}"
+
+        def reason(error)
+          REASONS.find { |klass, _| error.is_a?(klass) }&.last || "failed (#{error.class.name})"
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/plugin/loader.rb

@@ -65,22 +65,41 @@ module Samagotchi
         reason = bundle.error || unloadable_reason(file, bundle)
         return failed(bundle_name, basename, reason, failures) if reason
 
-        api = nil
-        plugin = instantiate(bundle_name, file, settings)
-        plugin_label = label(bundle_name, basename)
-        api = Api.new(bundle: bundle_name, label: plugin_label, registries: registries,
-                      context: registries.context_for&.call(bundle_name, settings, plugin_label))
-        plugin.register(api)
-        api.commit!
+        api = register_file(bundle_name, file, registries, settings: settings)
         Log.info(TAG, "plugin_loaded", bundle: bundle_name, file: basename, **api.counts)
         true
       rescue Exception => e # rubocop:disable Lint/RescueException -- a plugin's SyntaxError or exit must not stop chi
-        api&.abort!
         raise if e.is_a?(SignalException) # Ctrl-C and kill signals are the user's
 
         failed(bundle_name, basename, "#{e.class}: #{e.message}", failures)
       end
 
+      # Build +file+'s plugin with +settings+ and commit what its #register
+      # staged into +registries+ (no sha or requires_chi check: #load_bundle
+      # makes them; the test kit loads a bundle's source this way).
+      # @param namespace [Module, nil] the module the file is evaluated in
+      #   (default: a fresh one, #fresh_namespace)
+      # @param api_class [Class] what #register gets (Api; the test kit's
+      #   recording subclass)
+      # @yieldparam plugin [Object] the built plugin, before #register
+      # @return [Api] the committed Api (#counts)
+      # @raise [Exception] whatever the file, #register or #commit! raised,
+      #   after stopping the services it started; nothing is registered
+      def register_file(bundle_name, file, registries, settings: {}, namespace: nil, api_class: Api)
+        api = nil
+        plugin = instantiate(bundle_name, file, settings, namespace: namespace)
+        yield plugin if block_given?
+        plugin_label = label(bundle_name, File.basename(file))
+        api = api_class.new(bundle: bundle_name, label: plugin_label, registries: registries,
+                            context: registries.context_for&.call(bundle_name, settings, plugin_label))
+        plugin.register(api)
+        api.commit!
+        api
+      rescue Exception # rubocop:disable Lint/RescueException -- stop its services whatever it raised
+        api&.abort!
+        raise
+      end
+
       # What a plugin's hooks, notices and failures are named by.
       def label(bundle_name, basename) = "#{basename} (bundle #{bundle_name})"
 
@@ -98,8 +117,8 @@ module Samagotchi
       # classes, not the last load's reopened) and build its class
       # (plugin.rb → Plugin; my_plugin.rb → MyPlugin) as hooks are built:
       # an initialize that takes an argument gets the settings.
-      def instantiate(bundle_name, file, settings)
-        namespace = fresh_namespace(bundle_name)
+      def instantiate(bundle_name, file, settings, namespace: nil)
+        namespace ||= fresh_namespace(bundle_name)
         namespace.module_eval(File.read(file), file, 1)
         klass = Hooks.class_for(file, namespace)
         plugin = Hooks.build_plugin(klass, settings)

data/lib/samagotchi/plugin/service.rb

@@ -15,6 +15,16 @@ module Samagotchi
       # again.
       class Stopped < StandardError; end
 
+      # The thread-local Context#with_event keeps its handler events in;
+      # the start block runs with it cleared.
+      CURRENT_EVENTS = :samagotchi_plugin_current_events
+      # Thread.current key: true while a start block runs (the turn's own
+      # thread too: a ctx.http call there isn't the turn's).
+      STARTING = :samagotchi_plugin_service_starting
+
+      # Whether a service's start block runs on this thread.
+      def self.starting? = !!Thread.current[STARTING]
+
       # @return [String] "<bundle>:<name>"
       attr_reader :name
 
@@ -37,7 +47,7 @@ module Samagotchi
           return @value if @state == :running
 
           begin
-            @value = @start.call(self)
+            @value = start_outside_handler
             @state = :running
             Log.info(:plugins, "service_started", service: @name)
             @value
@@ -81,6 +91,19 @@ module Samagotchi
 
       private
 
+      # The start block is the service's, not the handler's whose first
+      # #value started it: no event helper or ctx.http turn cancel inside.
+      def start_outside_handler
+        events = Thread.current[CURRENT_EVENTS]
+        starting = Thread.current[STARTING]
+        Thread.current[CURRENT_EVENTS] = nil
+        Thread.current[STARTING] = true
+        @start.call(self)
+      ensure
+        Thread.current[CURRENT_EVENTS] = events
+        Thread.current[STARTING] = starting
+      end
+
       def run_on_stop
         callbacks = @on_stop.reverse
         @on_stop = []

data/lib/samagotchi/question_answer.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  # An answer to the pending question (QuestionDesk#answer's value, what
+  # Engine#answer_question returns): id: the question's id; selected: the
+  # chosen option labels; freeform: the typed text or nil; selected_indices:
+  # the chosen options' positions; by: "parent_agent" for a parent agent's
+  # answer, else nil.
+  #
+  # Crosses a process or a bundle as a Hash (#to_h, symbol keys): the
+  # :question_answered event, the Bridge's and RelayVerifier's JSON
+  # responses, the ask_user_question tool result and the hook/plugin
+  # ask_user result (built field by field in QuestionDesk#ask_for_hook).
+  # JSON.generate of a Data value writes its inspect string, so every JSON
+  # boundary calls #to_h first.
+  QuestionAnswer = Data.define(:id, :selected, :freeform, :selected_indices, :by) do
+    def initialize(id:, selected:, freeform: nil, selected_indices: [], by: nil)
+      super
+    end
+
+    # Whether a parent agent gave it (not the user).
+    def parent_agent? = by == "parent_agent"
+
+    # The event / JSON shape: symbol keys in member order; +by+ left out
+    # when nil, every other key kept even when nil.
+    # @return [Hash{Symbol => Object}]
+    def to_h = super.tap { |h| h.delete(:by) if h[:by].nil? }
+  end
+end

data/lib/samagotchi/question_desk.rb

@@ -8,6 +8,7 @@ require "time"
 require_relative "client_id"
 require_relative "log"
 require_relative "pending_question"
+require_relative "question_answer"
 require_relative "tools/ask_user_question"
 require_relative "guardrails/parent_approvals"
 require_relative "guardrails/parent_continue"
@@ -124,7 +125,7 @@ module Samagotchi
         result = { dismissed: true, id: result[:id], note: note }
       end
       # Who answered is for the relay, not the model's tool result.
-      result = result.except(:by) if result.is_a?(Hash)
+      result = result.to_h.except(:by) if result.is_a?(QuestionAnswer)
       result.is_a?(String) ? result : JSON.generate(result)
     end
 
@@ -139,8 +140,8 @@ module Samagotchi
     #   question waits (outside the lock): a String closes the question with
     #   that reason, announced and returned as a cancel; nil keeps waiting.
     #   An answer recorded first wins. Not on the sync-handler path.
-    # @return [Hash, String] the answer {id:, selected:, freeform:, selected_indices:},
-    #   or {error:, …}; a String when a sync handler returned text itself
+    # @return [QuestionAnswer, Hash, String] the answer, or {error:, …}; a
+    #   String when a sync handler returned text itself
     def open_question(fields, watch: nil)
       supersede_standing
       ask(fields, watch)
@@ -156,7 +157,7 @@ module Samagotchi
     # close (as a superseded one does). A standing one already up is
     # replaced (withdrawn, reason "replaced").
     # @param fields [Hash] as for #open_question
-    # @param on_answer [#call] (answer, client_id:)
+    # @param on_answer [#call] (answer [QuestionAnswer], client_id:)
     # @param on_superseded_close [#call, nil] called when a question that
     #   superseded it closes (its poster posts it again if it still
     #   stands); nil: posted again as it was
@@ -220,14 +221,16 @@ module Samagotchi
               @answer
             elsif sync_res.is_a?(Hash) && sync_res[:selected]
               # Treat returned hash as answer (handler rendered and parsed)
-              @answer = sync_res
+              @answer = QuestionAnswer.new(id: id.to_s, selected: Array(sync_res[:selected]),
+                                           freeform: sync_res[:freeform],
+                                           selected_indices: Array(sync_res[:selected_indices]))
               @pending = nil
-              sync_res
+              @answer
             end
           end
           if ans
             clear_saved_question
-            emit({ type: :question_answered, id: id, answer: ans })
+            emit({ type: :question_answered, id: id, answer: ans.to_h })
             return ans
           end
           if sync_res.is_a?(String) && !sync_res.strip.empty?
@@ -274,7 +277,7 @@ module Samagotchi
       end
 
       if answer
-        emit({ type: :question_answered, id: id, answer: answer })
+        emit({ type: :question_answered, id: id, answer: answer.to_h })
         answer
       else
         { error: "no answer", id: id }
@@ -289,7 +292,7 @@ module Samagotchi
     # @param parent_agent [Boolean, nil] the answer is a parent agent's, so
     #   it is held to guardrails.parent_approvals on an approval and doesn't
     #   bring the session back to the lists; nil: chi answer's client id says so
-    # @return [Hash] normalized answer; a parent agent's carries by: "parent_agent"
+    # @return [QuestionAnswer] the answer; a parent agent's carries by: "parent_agent"
     # @raise [NotPending, ArgumentError, Refused]
     def answer(id:, selected:, freeform: nil, client_id: nil, parent_agent: nil)
       sel = Array(selected).map { |v| v.to_s.strip }.reject(&:empty?)
@@ -398,7 +401,8 @@ module Samagotchi
     # web), single-select, kind "hook". A --non-interactive run has no one
     # to ask: nil at once. Anything but an answer (a sync handler's text, no
     # answer, cancelled) is nil too.
-    # @return [Hash, nil] {selected:, freeform:, selected_indices:}
+    # @return [Hash, nil] {selected:, freeform:, selected_indices:} (a plain
+    #   Hash: the bundle boundary)
     def ask_for_hook(question, options, header, allow_freeform, hook)
       return nil if @interface_lookup.call == :non_interactive
 
@@ -411,11 +415,9 @@ module Samagotchi
       fields = { question: question.to_s, options: opts, header: header, multi_select: false,
                  allow_freeform: !!allow_freeform, kind: "hook", hook: hook.to_s }.compact
       answer = open_question(fields)
-      return nil unless answer.is_a?(Hash) && answer[:selected]
+      return nil unless answer.is_a?(QuestionAnswer)
 
-      result = { selected: Array(answer[:selected]), freeform: answer[:freeform] }
-      result[:selected_indices] = answer[:selected_indices] if answer.key?(:selected_indices)
-      result
+      { selected: answer.selected, freeform: answer.freeform, selected_indices: answer.selected_indices }
     end
 
     private
@@ -483,7 +485,7 @@ module Samagotchi
     # handed to its poster with who answered.
     def settle_standing(standing, answer, client_id)
       clear_saved_question
-      emit({ type: :question_answered, id: answer[:id], answer: answer })
+      emit({ type: :question_answered, id: answer.id, answer: answer.to_h })
       standing[:on_answer].call(answer, client_id: client_id)
     rescue StandardError => e
       Log.warn(:turn, "standing_answer_failed", error: e.class.name, message: e.message)
@@ -493,7 +495,7 @@ module Samagotchi
     # == label in v1), one for a single-select, one or a text when required,
     # and a parent agent's within guardrails.parent_approvals. Under the
     # question lock: checked against the question pending now.
-    # @return [Hash] {id:, selected:, freeform:, selected_indices:, by:}
+    # @return [QuestionAnswer]
     # @raise [ArgumentError, Refused]
     def validated_answer(pending, sel, fm, parent_agent:, parent_setting:)
       opts = Array(pending.options)
@@ -508,9 +510,8 @@ module Samagotchi
         reason = Guardrails::ParentApprovals.refusal(pending, indices, setting: parent_setting)
         raise Refused, reason if reason
       end
-      answer = { id: pending.id.to_s, selected: sel, freeform: fm, selected_indices: indices.compact }
-      answer[:by] = "parent_agent" if parent_agent
-      answer
+      QuestionAnswer.new(id: pending.id.to_s, selected: sel, freeform: fm, selected_indices: indices.compact,
+                         by: parent_agent ? "parent_agent" : nil)
     end
 
     # Wait until the question is answered, cancelled or closed by +watch+.

data/lib/samagotchi/recap_setup.rb

@@ -66,7 +66,8 @@ module Samagotchi
         timeout: recap_number_setting(kwarg_config, :timeout, "recap.timeout", IdleRecap::DEFAULT_TIMEOUT_SECONDS, :float),
         sentences: recap_sentences(string_config(kwarg_config, :sentences) || registry_string("recap.sentences")),
         store: RecapStore.new(session_id_lookup: -> { session_id.call }, state_dir_lookup: -> { state_dir.call }),
-        session_id: -> { session_id.call }
+        session_id: -> { session_id.call },
+        on_usage: ->(usage) { engine.note_side_usage(usage) }
       )
     end
 

data/lib/samagotchi/relay_verifier.rb

@@ -54,7 +54,7 @@ module Samagotchi
       result = @engine.answer_question(id: question_id, selected: selected, freeform: answer["freeform"],
                                        client_id: client_id, parent_agent: parent_agent)
       log("relay_answered", relay_id, id: question_id, by: relay["by"])
-      [{}, 200, { status: "answered", question_id: question_id, answer: result }]
+      [{}, 200, { status: "answered", question_id: question_id, answer: result.to_h }]
     rescue QuestionDesk::NotPending
       not_pending(question_id)
     rescue QuestionDesk::Refused => e