samagotchi 0.78.0 → 0.80.0

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/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?)
@@ -349,7 +352,7 @@ module Samagotchi
         @pending = pending = pending.with(relayed_to: relayed_to)
         if session
           session.pending_question = pending
-          begin; session.save(state_dir: state_dir); rescue StandardError; nil; end
+          save_session(session)
         end
         pending.id
       end
@@ -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
@@ -439,7 +441,7 @@ module Samagotchi
       end
       if session
         session.pending_question = pending
-        begin; session.save(state_dir: state_dir); rescue StandardError; nil; end
+        save_session(session)
       end
       event = { type: :question_requested, pending_question: pending.to_h }
       event[:standing] = true if standing
@@ -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+.
@@ -559,12 +560,19 @@ module Samagotchi
     def cancel_controller = @cancel_controller_lookup.call
     def emit(event) = @emit.call(event)
 
+    def save_session(session)
+      session.save(state_dir: state_dir)
+    rescue StandardError => e
+      Log.warn(:turn, "question_save_failed", sid: session.id, error: e.class.name, msg: e.message.to_s[0, 200])
+      nil
+    end
+
     # The session file no longer holds a pending question.
     def clear_saved_question
       return unless session
 
       session.pending_question = nil
-      begin; session.save(state_dir: state_dir); rescue StandardError; nil; end
+      save_session(session)
     end
   end
 end

data/lib/samagotchi/reasoning_history.rb

@@ -2,6 +2,7 @@
 
 require_relative "config"
 require_relative "setting_explained"
+require_relative "llm/anthropic_wire"
 
 module Samagotchi
   # Which of its own reasoning a chat host's model gets back
@@ -125,7 +126,7 @@ module Samagotchi
         next false unless entry[:role].to_s == "model"
 
         (entry[:thinking].is_a?(String) && !entry[:thinking].strip.empty?) ||
-          Array(entry[:anthropic_content]).any? { |block| block.is_a?(Hash) && %w[thinking redacted_thinking].include?(block["type"].to_s) }
+          Array(entry[:anthropic_content]).any? { |block| LLM::AnthropicWire.thinking_block?(block) }
       end
     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

data/lib/samagotchi/testing/boundary.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module Testing
+    # What a bundle's Ruby may reach of chi (docs/plugins.md, "Stable for
+    # bundles"): ALLOWED is the checked copy of that list. #scan finds a
+    # bundle's other references to Samagotchi:: and requires of chi's files;
+    # EXCEPTIONS is what the shipped bundles reach today anyway, each with
+    # why: the APIs to design before that bundle could leave chi's repo
+    # (spec/samagotchi/testing/boundary_spec.rb keeps both exact).
+    module Boundary
+      # A name a bundle may use, and the file that defines it (a require of
+      # it is fine too). A name allows itself, its methods (".x") and what
+      # it holds ("::X"); one ending in a method or constant allows only that.
+      Allowed = Data.define(:name, :file)
+
+      ALLOWED = [
+        Allowed.new(name: "Samagotchi::Plugin::Api", file: "samagotchi/plugin/api"),
+        Allowed.new(name: "Samagotchi::Plugin::ToolResult", file: "samagotchi/plugin/tool_result"),
+        Allowed.new(name: "Samagotchi::Plugin::ModelError", file: "samagotchi/plugin/context"),
+        Allowed.new(name: "Samagotchi::Plugin::ModelCancelled", file: "samagotchi/plugin/context"),
+        Allowed.new(name: "Samagotchi::Plugin::HttpError", file: "samagotchi/plugin/http"),
+        Allowed.new(name: "Samagotchi::Plugin::HttpCancelled", file: "samagotchi/plugin/http"),
+        Allowed.new(name: "Samagotchi::Plugin::Http::Response", file: "samagotchi/plugin/http"),
+        Allowed.new(name: "Samagotchi::Plugin::Service::Stopped", file: "samagotchi/plugin/service"),
+        Allowed.new(name: "Samagotchi::Plugin::Sessions::Error", file: "samagotchi/plugin/sessions"),
+        Allowed.new(name: "Samagotchi::Plugin::AttachedContext::Error", file: "samagotchi/plugin/attached_context"),
+        Allowed.new(name: "Samagotchi::Plugin::Peer", file: "samagotchi/plugin/peer"),
+        Allowed.new(name: "Samagotchi::Tools::ToolIndex::Tool", file: "samagotchi/tools/tool_index"),
+        Allowed.new(name: "Samagotchi::Tools::ToolIndex::Group", file: "samagotchi/tools/tool_index"),
+        Allowed.new(name: "Samagotchi::Tools::ToolIndex.schema_note", file: "samagotchi/tools/tool_index"),
+        Allowed.new(name: "Samagotchi::Tools::ToolIndex.spec_tokens", file: "samagotchi/tools/tool_index"),
+        Allowed.new(name: "Samagotchi::Tools::Execute::NAME", file: "samagotchi/tools/execute"),
+        Allowed.new(name: "Samagotchi::Tools::Execute::TIMEOUT_PREFIX", file: "samagotchi/tools/execute"),
+        Allowed.new(name: "Samagotchi::Tools::Execute::HANDED_OVER", file: "samagotchi/tools/execute"),
+        Allowed.new(name: "Samagotchi::Tools::Execute.timeout_seconds", file: "samagotchi/tools/execute"),
+        Allowed.new(name: "Samagotchi::Tools::TaskRuntime::TASKS_DIR", file: "samagotchi/tools/task_runtime"),
+        Allowed.new(name: "Samagotchi::Tools::TaskRuntime::EXIT_CODE_FILENAME", file: "samagotchi/tools/task_runtime"),
+        Allowed.new(name: "Samagotchi::AtomicFile.write", file: "samagotchi/atomic_file"),
+        Allowed.new(name: "Samagotchi::Log.warn", file: "samagotchi/log"),
+        Allowed.new(name: "Samagotchi::Log.debug", file: "samagotchi/log"),
+        Allowed.new(name: "Samagotchi::Config.get", file: "samagotchi/config"),
+        Allowed.new(name: "Samagotchi::VERSION", file: "samagotchi/version"),
+        # The kit itself, for a bundle's own specs.
+        Allowed.new(name: "Samagotchi::Testing", file: "samagotchi/testing")
+      ].freeze
+
+      # The kit's adapters, required by a bundle's specs.
+      ALLOWED_REQUIRES = (ALLOWED.map(&:file) + %w[samagotchi/testing/rspec samagotchi/testing/minitest]).uniq.freeze
+
+      SESSION = "a saved session (context sources are keyed by its id): needs a kit helper that saves one"
+      SOURCES = "the session's context sources (the peer's inbox / outbox): needs a kit helper that attaches one"
+      REF_LIMITS = "a ref's kinds and limits (event[:refs] checks them too): could be stable constants"
+      # The peers' specs pair a session through its context sources.
+      PEER_SPEC = {
+        'require "samagotchi/context_sources"' => "spec: #{SOURCES}",
+        "Samagotchi::Session.new_session" => "spec: #{SESSION}",
+        "Samagotchi::ContextSources.session_location" => "spec: #{SOURCES}",
+        "Samagotchi::ContextSources::Source.new" => "spec: #{SOURCES}",
+        "Samagotchi::ContextSources::Fetched.new" => "spec: an outbox answer as the context poller records it"
+      }.freeze
+
+      # bundle => {reference => why}: what each shipped bundle reaches
+      # beyond ALLOWED today, its specs' (why "spec: …") included.
+      EXCEPTIONS = {
+        "agents-md" => {
+          'require "samagotchi/guardrails/context"' => "for GitInfo: a ctx helper for the checkout's files could replace it",
+          "Samagotchi::Guardrails::GitInfo.new" => "the work tree's top for the AGENTS.md chain (ctx.repo_root covers the top only)"
+        },
+        "claude-peer" => PEER_SPEC,
+        "codex-peer" => PEER_SPEC,
+        "coordinator" => {
+          "Samagotchi::MemoryPaths.scope_dir" => "where the coordinator's memories live: needs a ctx memory-path API",
+          "Samagotchi::MemoryPaths" => "spec: checks /coordinate end reads no memories (MemoryPaths.scope_dir isn't called)"
+        },
+        "github-pr" => {
+          "Samagotchi::Session.new_session" => "spec: #{SESSION} (ctx.delegate?, ctx.fork?, ctx.context read it)",
+          "Samagotchi::ContextSources.session_location" => "spec: reads and removes the session's sources (added_by), " \
+                                                            "which ctx.context.list doesn't show",
+          'require "samagotchi/memory_bundle/installer"' => "spec: for Installer",
+          "Samagotchi::MemoryBundle::Installer.new" => "spec: installs the bundle so its context provider resolves: " \
+                                                       "needs a kit install helper",
+          'require "samagotchi/context_providers"' => "spec: for ContextProviders",
+          "Samagotchi::ContextProviders.resolve" => "spec: the manifest's URL provider through chi's own resolver",
+          'require "samagotchi/answer_display"' => "spec: for AnswerDisplay",
+          "Samagotchi::AnswerDisplay.new" => "spec: after_turn's present: helper, as chi's fire site builds it: " \
+                                             "the kit could supply after_turn's fire-site keys",
+          'require "samagotchi/answer_refs"' => "spec: for AnswerRefs",
+          "Samagotchi::AnswerRefs.new" => "spec: after_turn's refs: helper, as chi's fire site builds it",
+          "Samagotchi::Log" => "spec: stubs Log to check what ctx.log recorded: a kit log recorder could replace it"
+        },
+        "loop-guard" => {
+          'require "samagotchi/llm/native_tool_normalizer"' => "spec: for NativeToolNormalizer",
+          "Samagotchi::LLM::NativeToolNormalizer.normalize" => "spec: replays recorded calls in the shape chi's parser gives",
+          "Samagotchi::Hooks::StreamWatch::EVERY_CHARS" => "spec: the stream watch's batch size (a ctx or kit value later)"
+        },
+        "skills" => {
+          "Samagotchi::Tools::MemoryRead.memories_dir" => "lists the skill memories: needs a ctx memory-path API"
+        },
+        "mcp" => {
+          'require "samagotchi/process_group"' => "for ProcessGroup.stop",
+          "Samagotchi::ProcessGroup.stop" => "stops a server's process group: needs a ctx process API",
+          'require "samagotchi/token_usage"' => "for CHARS_PER_TOKEN",
+          "Samagotchi::TokenUsage::CHARS_PER_TOKEN" => "estimates a tool's tokens: could be a stable constant",
+          'require "samagotchi/tool_declarations"' => "loaded for Api.tool_spec's schemas"
+        },
+        "slow-commands" => {
+          'require "samagotchi/guardrails/shell_lex"' => "for ShellLex",
+          "Samagotchi::Guardrails::ShellLex" => "splits a command into its parts: needs a stable shell-parsing helper",
+          "Samagotchi::Tools::Execute.const_defined?" => "reads execute's limits that older chis lack, by reflection",
+          "Samagotchi::Tools::Execute.const_get" => "reads execute's limits that older chis lack, by reflection"
+        },
+        "source-links" => {
+          'require "samagotchi/ref"' => "for the Ref / RefAction limits",
+          "Samagotchi::Ref::FILE" => REF_LIMITS,
+          "Samagotchi::Ref::KIND.match?" => REF_LIMITS,
+          "Samagotchi::Ref::MAX_LABEL" => REF_LIMITS,
+          "Samagotchi::RefAction::MAX_LABEL" => REF_LIMITS,
+          "Samagotchi::RefAction.http_url?" => "which URLs an action may open: could be a stable helper"
+        }
+      }.freeze
+
+      # A Samagotchi:: name with what follows it (::X, .method).
+      REFERENCE = /\bSamagotchi(?:::[A-Z]\w*)+(?:\.[a-z_]\w*[?!]?)?/
+      # A require of one of chi's files.
+      REQUIRE = %r{\brequire\s*\(?\s*["'](samagotchi(?:/[\w/]+)?)["']}
+
+      # One reference outside ALLOWED, in a file of the bundle.
+      Finding = Data.define(:reference, :file)
+
+      module_function
+
+      # The bundle's references to chi outside ALLOWED (its plugin, hooks,
+      # scripts and specs: every .rb under +dir+), one per reference and
+      # file, sorted.
+      # @param dir [String] the bundle's folder
+      # @return [Array<Finding>]
+      def scan(dir)
+        Dir.glob(File.join(dir, "**", "*.rb")).sort.flat_map do |path|
+          text = File.read(path)
+          refs = text.scan(REFERENCE).reject { |name| allowed?(name) }
+          refs += text.scan(REQUIRE).flatten.reject { |file| ALLOWED_REQUIRES.include?(file) }.map { |file| %(require "#{file}") }
+          file = path.delete_prefix("#{File.expand_path(dir)}/")
+          refs.uniq.map { |reference| Finding.new(reference: reference, file: file) }
+        end
+      end
+
+      # Whether a bundle may use +name+ ("Samagotchi::X::Y", maybe ".method").
+      def allowed?(name)
+        ALLOWED.any? do |entry|
+          name == entry.name || name.start_with?("#{entry.name}.", "#{entry.name}::")
+        end
+      end
+    end
+  end
+end