samagotchi 0.79.0 → 0.81.0

data/lib/samagotchi/bootstrap_command.rb

@@ -14,9 +14,10 @@ require_relative "redacted_inspect"
 
 module Samagotchi
   # `chi bootstrap [TARGET]`: the first setup. It names a model server, works
-  # out what it is (llama.cpp's native API or an OpenAI-compatible one),
-  # picks the model, sends one test request and writes config.yml: a fresh
-  # file, or a hosts: entry added to an existing one. Then it installs the
+  # out what it is (llama.cpp's native API, an OpenAI-compatible one or
+  # Anthropic's Messages API, Bootstrap::Probe), picks the model, sends one
+  # test request and writes config.yml: a fresh file, or a hosts: entry
+  # added to an existing one. Then it installs the
   # system bundle and the core profile, and on a terminal asks about dev.
   # Prompts only on a terminal; a script gets the list and exit 2 instead.
   class BootstrapCommand
@@ -24,11 +25,14 @@ module Samagotchi
     include RedactedInspect
 
     USAGE = <<~TEXT
-      Usage: chi bootstrap [TARGET] [--name NAME] [--model ID] [--key-env VAR] [--no-test] [--dry-run]
+      Usage: chi bootstrap [TARGET] [--name NAME] [--model ID] [--key-env VAR] [--api API] [--dialect NAME]
+                           [--no-test] [--dry-run]
         Finds the model server at TARGET and writes config.yml for it.
           chi bootstrap 192.168.1.29:8081          llama.cpp on the LAN
           chi bootstrap localhost:11434            Ollama
           chi bootstrap https://openrouter.ai/api/v1 --key-env OPENROUTER_API_KEY
+          chi bootstrap https://api.anthropic.com --key-env ANTHROPIC_API_KEY
+          chi bootstrap https://api.fireworks.ai/inference/v1 --key-env FIREWORKS_API_KEY --api anthropic
           chi bootstrap                            look on this machine's usual ports
         TARGET        host[:port] (port 8080 when none), or a URL; a URL's
                       path is the OpenAI API base
@@ -37,6 +41,12 @@ module Samagotchi
         --model ID    the model, when the server has several
         --key-env VAR the environment variable holding the API key (the
                       key itself is never written)
+        --api API     openai or anthropic (Anthropic's Messages API) instead
+                      of detecting it; detection takes anthropic only when
+                      the OpenAI model list is refused
+        --dialect NAME the Messages API's dialect: standard or fireworks
+                      (implies --api anthropic; default: fireworks when the
+                      host or the model ids say so)
         --no-test     skip the test request
         --dry-run     show what would be written; write nothing
         With no config.yml it writes one; an existing one gets a hosts:
@@ -50,10 +60,13 @@ module Samagotchi
       f.value "--name"
       f.value "--model"
       f.value "--key-env"
+      f.value "--api"
+      f.value "--dialect"
       f.switch "--no-test"
       f.switch "--dry-run"
     end
 
+    APIS = %i[openai anthropic].freeze
     PICK_SHOWN = 20
     # A test request slower than this says it is waiting (a model loading).
     LOADING_AFTER = 3
@@ -92,6 +105,8 @@ module Samagotchi
         return @exit
       end
 
+      @api = options[:api]
+      @dialect = options[:dialect]
       result = find(options, key_env) or return @exit
       unlocked = with_key(result, key_env) or return @exit
       result, key_env = unlocked
@@ -124,7 +139,25 @@ module Samagotchi
         return usage_error("--key-env takes the variable's name (e.g. OPENROUTER_API_KEY), not the key")
       end
 
-      options
+      parse_api(options)
+    end
+
+    # --api as a Symbol, --dialect downcased (implying --api anthropic).
+    def parse_api(options)
+      if options[:api]
+        api = options[:api].strip.downcase.to_sym
+        return usage_error("--api must be #{APIS.join(" or ")} (got #{options[:api]})") unless APIS.include?(api)
+
+        options[:api] = api
+      end
+      return options unless options[:dialect]
+
+      dialect = options[:dialect].strip.downcase
+      names = LLM::Dialect::BY_NAME.keys
+      return usage_error("--dialect must be #{names.join(" or ")} (got #{options[:dialect]})") unless names.include?(dialect)
+      return usage_error("--dialect is for --api anthropic, not --api openai") if options[:api] == :openai
+
+      options.merge(dialect: dialect, api: :anthropic)
     end
 
     # The server's Probe::Result, or nil with @exit set.
@@ -137,17 +170,26 @@ module Samagotchi
         @exit = usage_error(e.message)
         return nil
       end
-      result = @probe.classify_target(candidates, key_env: key_env)
+      result = @probe.classify_target(candidates, key_env: key_env, api: @api, dialect: @dialect)
       case result.kind
       when :unreachable
         fail!("can't reach #{result.candidate.label} (#{result.reason})")
       when :unknown
         detail = result.status ? "HTTP #{result.status}" : result.reason
-        fail!("reached #{result.candidate.label} but it answers neither llama.cpp /props nor /v1/models (#{detail})")
+        fail!("reached #{result.candidate.label} but it answers #{unknown_asked} (#{detail})")
       else result
       end
     end
 
+    # What an :unknown server didn't answer, by what --api let the probe ask.
+    def unknown_asked
+      case @api
+      when :anthropic then "no Anthropic /v1/models"
+      when :openai then "neither llama.cpp /props nor /v1/models"
+      else "neither llama.cpp /props, /v1/models nor the Anthropic /v1/models"
+      end
+    end
+
     def scan
       found = @probe.scan_local
       ports = Bootstrap::Probe::LOCAL_PORTS.keys.join(", ")
@@ -190,7 +232,7 @@ module Samagotchi
       return fail!("#{key_env} isn't a variable name") unless key_env.match?(ConfigFile::ENV_NAME_RE)
       return fail!("#{key_env} is not set; #{export_hint(key_env, "and run chi bootstrap again")}") if unset?(key_env)
 
-      result = @probe.classify(result.candidate, key_env: key_env)
+      result = @probe.classify(result.candidate, key_env: key_env, api: @api, dialect: @dialect)
       return fail!("#{host} refused the key in #{key_env} (HTTP #{result.status})") if result.kind == :needs_key
       return fail!("can't reach #{host} (#{result.reason || "HTTP #{result.status}"})") unless result.reached?
 
@@ -201,8 +243,15 @@ module Samagotchi
       if result.native?
         build = result.props["build_info"].to_s
         @stdout.puts("found: llama.cpp at #{result.candidate.root}#{" (build #{build})" unless build.empty?}")
+      elsif result.anthropic?
+        dialect = " (dialect: #{result.dialect})" if result.dialect
+        @stdout.puts("found: an Anthropic Messages API at #{Bootstrap::Probe.api_root(result.candidate)}#{dialect}")
       else
         @stdout.puts("found: an OpenAI-compatible API at #{result.candidate.base}")
+        # By the host only: a proxy listing accounts/fireworks/ ids may not serve /v1/messages.
+        if @api.nil? && Bootstrap::Probe.fireworks_host?(result.candidate.host)
+          @stdout.puts("Fireworks also serves the Anthropic Messages API: --api anthropic")
+        end
       end
     end
 
@@ -248,17 +297,28 @@ module Samagotchi
                     @stdout.puts("test: waiting for an answer (loading the model?)…") if done.pop(timeout: LOADING_AFTER).nil?
                   end
                 end
-      seconds = @probe.test_turn(result.candidate, model, key_env: key_env)
+      seconds = @probe.test_turn(result.candidate, model, key_env: key_env, api: result.anthropic? ? :anthropic : :openai,
+                                                          dialect: result.dialect, auth: result.auth)
       @stdout.puts(format("test: answered in %.1f s", seconds))
       true
     rescue StandardError => e
-      @stdout.puts("test: failed: #{e.message}")
+      @stdout.puts("test: failed: #{e.message}#{messages_hint(result, e)}")
       false
     ensure
       done&.push(true)
       waiting&.join
     end
 
+    # A detected OpenAI server whose model list worked but whose
+    # /chat/completions is 404: maybe a Messages-only url (a gateway's
+    # Anthropic route that also lists the OpenAI way).
+    def messages_hint(result, error)
+      return "" unless @api.nil? && result.kind == :openai && error.is_a?(Bootstrap::Probe::TestFailed)
+      return "" unless error.status == 404 && error.path.to_s.end_with?("/chat/completions")
+
+      " (an Anthropic Messages API? try --api anthropic)"
+    end
+
     # The "loading the model?" hint fits a local server (a llama.cpp loading
     # weights); a remote provider's slow answer is the network, not a load.
     def loading_hint?(result)
@@ -268,7 +328,7 @@ module Samagotchi
     # 0 written, 1 written but not as planned, nil with @exit on a refusal.
     def write(result, model, key_env, options)
       writer = Bootstrap::ConfigWriter.new(path: @config_path, env: @env)
-      fields = host_fields(result.candidate, result.native?, key_env)
+      fields = host_fields(result, key_env)
       ids = result.models.map(&:id)
       base = Bootstrap::ConfigWriter.derived_name(result.candidate.host)
       name, reason = begin
@@ -277,8 +337,8 @@ module Samagotchi
         @exit = usage_error(e.message)
         return nil
       end
-      explain_name(base, name, reason)
       outcome = writer.write(name: name, fields: fields, model: model, dry_run: options[:dry_run])
+      explain_name(base, name, reason) unless outcome.kind == :exists
       code = report(outcome, model)
       return code unless INSTALLS_BUNDLES.include?(outcome.kind)
 
@@ -350,18 +410,35 @@ module Samagotchi
     end
 
     # The hosts entry: host/port for a plain http server (api: openai when it
-    # isn't llama.cpp), url for https or a URL with its own path.
-    def host_fields(candidate, native, key_env)
+    # isn't llama.cpp), url for https or a URL with its own path (an
+    # Anthropic one without /v1: the API root, as the hand-written claude
+    # host has it). Then api, dialect, auth (Bearer only when the dialect's
+    # own header isn't), api_key_env.
+    def host_fields(result, key_env)
+      candidate = result.candidate
       fields = if candidate.url || candidate.scheme == "https"
-                 { "url" => native ? candidate.root : candidate.base }
+                 { "url" => url_field(result) }
                else
                  { "host" => candidate.host, "port" => candidate.port }
                end
-      fields["api"] = "openai" unless native
+      if result.anthropic?
+        fields["api"] = "anthropic"
+        fields["dialect"] = result.dialect if result.dialect
+        fields["auth"] = result.auth.to_s if result.auth && result.auth != LLM::Dialect.for(result.dialect).auth
+      elsif !result.native?
+        fields["api"] = "openai"
+      end
       fields["api_key_env"] = key_env if key_env
       fields
     end
 
+    def url_field(result)
+      return result.candidate.root if result.native?
+      return Bootstrap::Probe.api_root(result.candidate) if result.anthropic?
+
+      result.candidate.base
+    end
+
     def report(outcome, model)
       path = outcome.path
       case outcome.kind

data/lib/samagotchi/bridge.rb

@@ -658,7 +658,7 @@ module Samagotchi
 
       begin
         result = @engine.answer_question(id: qid, selected: selected, freeform: freeform, client_id: client_id)
-        [{}, 200, { status: "answered", session_id: session_id, answer: result }]
+        [{}, 200, { status: "answered", session_id: session_id, answer: result.to_h }]
       rescue Engine::QuestionNotPending => e
         # Another client answered first, or the question was cancelled.
         [{}, 409, { error: "question_not_pending", detail: e.message }]

data/lib/samagotchi/bundles/guardrails/guardrails/rules.yml

@@ -176,12 +176,12 @@ rules:
   # ── answering chi's own questions around chi answer ───────────────────
   # A parent agent answers a child's approval with chi answer, which holds it
   # to guardrails.parent_approvals. These shapes go around that: chi --attach
-  # or chi -p with stdin from a pipe, a here-string or a file (a chi after 0.12 treats
-  # those as a parent too, but an older child doesn't), and a POST to the
-  # Bridge's or the web's answer route.
+  # or chi -p with stdin from a pipe, a here-string or a file other than
+  # /dev/null (a chi after 0.12 treats those as a parent too, but an older
+  # child doesn't), and a POST to the Bridge's or the web's answer route.
   - id: chi-answer-piped
     tool: shell
-    command: '(\|[^;&|\n]*\bchi\s([^;&|\n]*\s)?(--attach|--prompt|-p)\b|\bchi\s([^;&|\n]*\s)?(--attach|--prompt|-p)\b[^;&|\n]*<)'
+    command: '(\|[^;&|\n]*\bchi\s([^;&|\n]*\s)?(--attach|--prompt|-p)\b|\bchi\s([^;&|\n]*\s)?(--attach|--prompt|-p)\b[^;&|\n]*<(?!\s*/dev/null(?![\w./-])))'
     verdict: ask
     scopes: [once, session]
     reason: answers chi's questions from a pipe or a file, around chi answer

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

@@ -1,6 +1,6 @@
 ---
 name: guardrails
-version: 0.9.0
+version: 0.9.1
 scope: system
 description: Optional default guardrail rules (git push/rewrites, rm -rf wide, curl | sh, git hooks, chi's own config and attached context from the shell, chi context add --cmd, chi broadcast, answering chi around chi answer, removing a memory, writing a memory that reaches the system prompt (identity, model notes) or a model overlay; in strict mode also git rebase and writes and git in another checkout outside the session's repo), asks only small models get (git checkout --/restore, git stash drop), and a note for the model
 trust_level: reviewed

data/lib/samagotchi/bundles/slow-commands/manifest.yml

@@ -1,12 +1,12 @@
 ---
 name: slow-commands
-version: 0.2.2
+version: 0.2.3
 scope: system
 description: "Remembers commands that ran past the execute limit in a project; the next identical execute is denied once a turn with advice to run it with task_create and task_wait; /slow-commands lists and forgets them"
 trust_level: reviewed
 plugin:
   file: plugin.rb
-  sha256: sha256:6bf5da2501a6404cda01c95975b005fce179f756c56222771c5ee857d7ba4b98
+  sha256: sha256:249615f1d8529ab020ea9872bb42b00463594f20a9ec44fecc4e0f58d34dce91
 # Execute::HANDED_OVER, read when the plugin loads (0.59.0); after_tool_call's
 # call:, elapsed_ms: and result: (0.57.0)
 requires_chi: ">= 0.59.0"

data/lib/samagotchi/bundles/slow-commands/plugin.rb

@@ -21,7 +21,8 @@
 # `env X=… cmd` is `X=… cmd`, an `env` with -C/-i/-u (or any other option)
 # stays as typed. The entry's `shown` is the last run as typed. Input that ends inside a quote, $(…)
 # or heredoc is never recorded, nor one with a $(…), backticks or a heredoc
-# cat/tee read as data: ShellLex makes those one placeholder, so different
+# a data reader reads as data (ShellLex: cat, tee, git commit -F -, gh …
+# --body-file -): ShellLex makes those one placeholder, so different
 # commands would share a key.
 #
 # after_tool_call records: timed out (killed at the limit), handed over as

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

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.79.0
+version: 0.81.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:
   identity.md: sha256:29c2f7df9f6c5acbc5ec17000a4490741e55e426af15ca0d81c8706edd9bd027
-  self_map.md: sha256:b5b3166c91f6f2af2563dd9db5f9959cda66747d907017acd0776fcd2fe29049
+  self_map.md: sha256:4ff5708e51f55089de47b107643ae0b74aee04cb96111226823a8d44fb4bc33d
   config_modification_protocol.md: sha256:66792f788cdbb8ee0252f2c387c96bd75266817bb75f721aaa181b602db97137
   memory_guide.md: sha256:c48eea744db69e4f3e9bb415e9a03a8c78bbcaa1205ad3b1fb157a079f92d22e
   delegated.md: sha256:a0d6ddcd4a8be06526d964898611775fd251cfd9d145a9d16afaccaa503597bd

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

@@ -48,7 +48,7 @@
   approvals (I see only how each was answered); see `docs/sessions.md` "Delegating".
 - Bundles extend me: memories, `hooks/*.rb`, `guardrails/*.yml`, and a `plugin.rb` that adds slash
   commands (`anytime:` ones run mid-turn), model tools (they can return images I see), hooks,
-  cards, side answers (`ask_model`),
+  cards, side answers (`ask_model`), HTTP calls (`ctx.http`),
   child sessions and services (e.g. MCP server processes). Shipped: `btw` (`/btw` side question),
   `mcp` (MCP server tools, searched with find_tools and called with call_tool; a screenshot comes as a picture; a toolkit's undeclared built-ins too, as chi/<tool>), `guardrails` (rules), `known-names` (typo guard), `source-links`
   (turns source refs like JIRA-123 in an answer into links in the web, and a one-line note), `loop-guard`

data/lib/samagotchi/continue_offer.rb

@@ -211,13 +211,13 @@ module Samagotchi
     def answered(answer, client_id:)
       # The /continue line takes the text on one line; the steer keeps its
       # line breaks.
-      text = answer[:freeform].to_s.gsub(/\s+/, " ").strip
+      text = answer.freeform.to_s.gsub(/\s+/, " ").strip
       @continue_steer = nil
-      if Array(answer[:selected]).include?(CONTINUE) && !text.empty?
-        @continue_steer = { text: answer[:freeform].to_s.strip,
-                            source: answer[:by] == "parent_agent" ? "parent_agent" : "user" }
+      if answer.selected.include?(CONTINUE) && !text.empty?
+        @continue_steer = { text: answer.freeform.to_s.strip,
+                            source: answer.parent_agent? ? "parent_agent" : "user" }
       end
-      line = if Array(answer[:selected]).include?(CONTINUE) then "/continue yes"
+      line = if answer.selected.include?(CONTINUE) then "/continue yes"
              elsif text.empty? then "/continue no"
              else "/continue no, #{text}"
              end

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"
@@ -551,6 +552,30 @@ module Samagotchi
       @session_observer.notify(type: :recap_ready, recap: recap, generation: generation, covered: covered)
     end
 
+    # Count one side request (a recap, a plugin's ctx.ask_model: IdleClient's
+    # on_usage) in the session's side line, apart from its turns' totals.
+    # Folded and announced as :side_usage under the event lock, so the side
+    # blocks reach the UIs in fold order (the lock order event lock →
+    # metrics mutex is the existing one); then, between turns, saved to
+    # analytics.json (a running turn's end or checkpoint saves it), unless
+    # the session is gone (no session file: a late recap thread must not
+    # recreate a deleted session's folder; the folder itself may not exist
+    # yet before a first turn). Safe from any thread: the recap's, a
+    # plugin's, the turn's.
+    # @param usage [SideUsage]
+    # @return [void]
+    def note_side_usage(usage)
+      synchronize_events do
+        block = @metrics.add_side(usage)
+        @session_observer.notify(type: :side_usage, kind: usage.kind, side: block)
+      end
+      sid = @session&.id
+      return if sid.nil? || turn_running?
+      return unless File.exist?(Session.session_file(sid, state_dir: session_state_dir))
+
+      @metrics.persist(state_dir: session_state_dir)
+    end
+
     # @return [SessionMetrics] the per-session analytics collector
     attr_reader :metrics
 
@@ -784,9 +809,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 +821,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 +985,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 +1448,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 +1579,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 +1599,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 +2567,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, source: nil|
+          ask_side_model(request, timeout: timeout, max_tokens: max_tokens, cancel_controller: cancel_controller,
+                                  model: model, source: source)
         },
         model_name: -> { effective_model_ref },
         model_key: -> { @model_key },
@@ -2585,6 +2585,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,23 +2610,43 @@ 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.
+    # goes with the request. Its usage counts in the session's side line
+    # (#note_side_usage) under +source+, the asking bundle's name.
     # @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, source: 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)
+      answer = client.ask(request, max_tokens: max_tokens, cancel_controller: cancel_controller, session_id: @session&.id,
+                                   kind: source.to_s.empty? ? "ask" : source.to_s, on_usage: method(:note_side_usage))
       Log.info(:plugins, "ask_model", model: target.label, answer_model: answer.model, chars: answer.text.length,
                                       ms: ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round)
       answer.text
     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