samagotchi 0.2.0

data/lib/samagotchi/tool_runner.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require_relative "tool_activity"
+require_relative "guardrails"
+require_relative "vision_context"
+require_relative "log"
+
+module Samagotchi
+  # The single per-call path both loops use: the tool_call_started and
+  # tool_call_completed events, the guardrail gate (before_tool_call hooks
+  # and their veto), dispatch through KernelLoop, the after_tool_call hook
+  # and the output cap. Each loop picks what the model gets back: native
+  # feeds the full `output:`, the chat loop feeds `capped_output:` (the cap
+  # on the event applies to both).
+  class ToolRunner
+    # More images in one result are left out, each with a line (a tool
+    # that returns many screenshots can't flood the context).
+    MAX_IMAGES_PER_RESULT = 4
+
+    # @param kernel [KernelLoop] read lazily: Engine sets its hooks after
+    #   the kernel is built.
+    def initialize(kernel)
+      @kernel = kernel
+    end
+
+    # @param call_index [Integer] 1-based position of the call in its batch
+    # @return [Hash] output:, capped_output:, truncated:, activity:,
+    #   images: (refs) when the tool returned images the model gets to see, and
+    #   shown_params: the params line the live row showed, and shown_label:
+    #   its label ("chrome: screenshot"), only for a tool that isn't built in
+    #   (the loops save them with the result, so a reload without the plugin
+    #   shows the same row)
+    def run(call, iteration:, call_index:, call_count:, on_stream_event:, max_tool_output_chars:)
+      params = ToolActivity.tool_activity_params(call[:name], call, registry: tools)
+      # The gate runs first, so tool_call_started shows the call that runs.
+      verdict = evaluate(call, iteration, params)
+      call = verdict.call
+      params = ToolActivity.tool_activity_params(call[:name], call, registry: tools)
+      label = plugin_label(call[:name])
+      started = { type: :tool_call_started, iteration: iteration, call_count: call_count, call_index: call_index,
+                  tool: call[:name], call: call.dup, params: params }
+      started[:label] = label if label
+      emit(on_stream_event, started)
+
+      # The ask comes after tool_call_started: the UI shows the tool line,
+      # then the approval under it.
+      settle_ask(verdict) if verdict.ask?
+      result = verdict.deny? ? denied(call, verdict) : dispatch(call)
+      result = approved(result, verdict) if verdict.allow? && verdict.decided_by
+      result, images = attach_images(call, result) if result[:images]
+
+      output = scrub(result[:output].to_s)
+      capped = output
+      truncated = false
+      if max_tool_output_chars && output.length > max_tool_output_chars
+        truncated = true
+        capped = output[0, max_tool_output_chars]
+      end
+
+      fire(:after_tool_call, { type: :after_tool_call, iteration: iteration, tool: call[:name], output: capped })
+      completed = { type: :tool_call_completed, iteration: iteration, call_count: call_count, call_index: call_index,
+                    tool: call[:name], output: capped, output_truncated: truncated, activity: result[:activity] }
+      completed[:images] = images if images&.any?
+      emit(on_stream_event, completed)
+
+      run = { output: output, capped_output: capped, truncated: truncated, activity: result[:activity] }
+      run[:images] = images if images&.any?
+      run[:shown_params] = params if params && plugin_tool?(call[:name])
+      run[:shown_label] = label if label
+      run
+    end
+
+    private
+
+    # A tool's output can hold bytes that aren't UTF-8 (`printf '\xff'`, a
+    # binary file). They become "?" here, before the output reaches the
+    # conversation, the events and the saved session: JSON.generate raises
+    # on them, and the session would fail to save.
+    def scrub(text)
+      text = text.dup.force_encoding(Encoding::UTF_8) unless text.encoding == Encoding::UTF_8
+      text.valid_encoding? ? text : text.scrub("?")
+    end
+
+    # A tool returned images (read an image file, or a plugin's
+    # ToolResult): store each with the session (the turn's VisionContext)
+    # so the loop sends it. One that can't be sent adds a line saying why
+    # and keeps the text and the other images; for read, whose text only
+    # says the image is attached, that line replaces the text.
+    # @return [Array(Hash, Array<Hash>)] the result and its refs
+    def attach_images(call, result)
+      vision = @kernel.vision if @kernel.respond_to?(:vision)
+      reason = if vision.nil? then "images can't be attached here"
+               elsif !vision.sendable? then ImagePlan::CANT_SEE
+               end
+      refs = []
+      notes = []
+      Array(result[:images]).each_with_index do |entry, index|
+        entry = ImageStore.symbolize(entry)
+        unless valid_image_entry?(entry)
+          notes << "Error: image #{index + 1} is not {path:} or {bytes:, name:}"
+          next
+        end
+
+        description = entry[:description] || entry[:name] || (entry[:path] && File.basename(entry[:path])) || "image #{index + 1}"
+        if reason
+          notes << "#{description} is an image; #{reason}"
+        elsif refs.size >= MAX_IMAGES_PER_RESULT
+          notes << "#{description} is not attached: at most #{MAX_IMAGES_PER_RESULT} images per tool result"
+        else
+          refs << vision.ingest(entry[:path], name: entry[:name], bytes: entry[:bytes])
+        end
+      rescue ImageStore::Error => e
+        notes << "Error: #{e.message}"
+      end
+      unless refs.empty?
+        Log.info(:turn, "tool_images_attached", tool: call[:name], count: refs.size,
+                                                bytes: refs.sum { |ref| ref[:bytes].to_i }, left_out: notes.size)
+      end
+      [result.merge(output: images_output(call, result, notes)), refs]
+    end
+
+    def valid_image_entry?(entry)
+      return false unless entry.is_a?(Hash)
+
+      (entry[:path].is_a?(String) && !entry[:path].empty?) || (entry[:bytes].is_a?(String) && !entry[:bytes].empty?)
+    end
+
+    def images_output(call, result, notes)
+      return result[:output] if notes.empty?
+      return "[#{call[:name]}] #{notes.first}" if result[:image_only] && notes.first.start_with?("Error: ")
+      return "[#{call[:name]}]\n#{notes.first}" if result[:image_only]
+
+      [result[:output], *notes].join("\n")
+    end
+
+    # The kernel's tools, for the activity line of a tool that isn't built in.
+    def tools = @kernel.respond_to?(:tools) ? @kernel.tools : nil
+
+    # A tool the registry has from a plugin (not core, not unknown).
+    def plugin_tool?(name)
+      entry = tools && !name.nil? ? tools[name] : nil
+      !entry.nil? && !entry.core?
+    end
+
+    # A plugin tool's label, what the UIs show for its raw name.
+    def plugin_label(name) = ToolActivity.plugin_label(name, registry: tools)
+
+    # The Engine sets the kernel's gate (its context, later the approval
+    # flow); a bare kernel (specs) gets one that only runs the hooks.
+    def gate
+      given = @kernel.guardrail_gate if @kernel.respond_to?(:guardrail_gate)
+      given || (@gate ||= Guardrails::Gate.new(-> { @kernel.hooks if @kernel.respond_to?(:hooks) }, tools_lookup: -> { tools }))
+    end
+
+    # A gate that fails denies the call (fail closed).
+    def evaluate(call, iteration, params)
+      gate.evaluate(call, iteration: iteration, params: params)
+    rescue StandardError => e
+      Guardrails::Verdict.new(call: call).deny!("the guardrail check failed: #{e.class}: #{e.message}",
+                                                decided_by: "core")
+    end
+
+    def settle_ask(verdict)
+      gate.settle_ask(verdict)
+    rescue StandardError => e
+      verdict.settle!(:deny, decided_by: "core", note: "The approval failed (#{e.class}: #{e.message}).")
+    end
+
+    # An allowed ask: the activity says who allowed it, and for what scope.
+    def approved(result, verdict)
+      activity = result[:activity]
+      activity = activity.merge(guardrail: verdict.to_activity) if activity.is_a?(Hash)
+      result.merge(activity: activity)
+    end
+
+    # A legacy veto keeps its old text; a verdict's deny tells the model
+    # who decided and not to route around it.
+    def denied(call, verdict)
+      output = if verdict.legacy?
+                 reason = verdict.reason.to_s.strip
+                 "[#{call[:name]}] Error: blocked by guardrail: #{reason.empty? ? "blocked by hook" : reason}"
+               else
+                 "[#{call[:name]}] Error: #{verdict.deny_text}"
+               end
+      activity = ToolActivity.tool_activity_event(call[:name], call, output, registry: tools)
+      { output: output, activity: activity.merge(status: "blocked", guardrail: verdict.to_activity) }
+    end
+
+    # KernelLoop#dispatch turns tool errors into "[name] Error: …" itself;
+    # this rescue only catches a failing dispatcher.
+    def dispatch(call)
+      @kernel.dispatch_tool_call(call)
+    rescue StandardError => e
+      { output: "[#{call[:name]}] Error: #{e.class}: #{e.message}", activity: nil }
+    end
+
+    # A failing hook must not break the turn.
+    def fire(name, event)
+      hooks = @kernel.hooks if @kernel.respond_to?(:hooks)
+      hooks&.fire(name, event)
+    rescue StandardError
+      nil
+    end
+
+    def emit(callback, event)
+      callback&.call(event)
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/samagotchi/tools/args.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Samagotchi
+  module Tools
+    # A registry (plugin) tool's structured arguments. The parsers put what
+    # the model gave on call[:args] (string keys) for any tool that is not a
+    # built-in; .coerce then types the values by the tool's schema, since
+    # Qwen's <parameter=…> values are all text and Gemma's bare ones may be.
+    module Args
+      module_function
+
+      # Gemma 4's native call body (+text:<|"|>hi<|"|>,n:3,tags:[…],opt:{…}+,
+      # without the outer braces) as a Hash; nil when it doesn't parse.
+      # @param raw [String]
+      # @param delim [String] the profile's string delimiter (<|"|>)
+      def parse_gemma(raw, delim)
+        GemmaReader.new(raw.to_s, delim).object_body
+      rescue GemmaReader::Invalid
+        nil
+      end
+
+      # +args+ with each value typed by its property in +parameters+ (a JSON
+      # Schema object): integer, number and boolean from their text, array
+      # and object from JSON text, and a scalar given for a string as text.
+      # A value that doesn't fit its type stays as it came; keys the schema
+      # doesn't name pass through.
+      # @param args [Hash] string keys
+      # @param parameters [Hash, nil] {type: "object", properties: {…}}
+      # @return [Hash] string keys
+      def coerce(args, parameters)
+        properties = field(parameters, :properties)
+        return args.to_h { |key, value| [key.to_s, value] } unless properties.is_a?(Hash)
+
+        args.to_h do |key, value|
+          spec = field(properties, key)
+          [key.to_s, spec.is_a?(Hash) ? coerce_value(value, spec) : value]
+        end
+      end
+
+      def coerce_value(value, spec)
+        case type_of(spec)
+        when "integer" then to_integer(value)
+        when "number" then to_number(value)
+        when "boolean" then to_boolean(value)
+        when "string" then value.is_a?(Numeric) || value == true || value == false ? value.to_s : value
+        when "array"
+          list = from_json(value, Array)
+          items = field(spec, :items)
+          list.is_a?(Array) && items.is_a?(Hash) ? list.map { |item| coerce_value(item, items) } : list
+        when "object"
+          hash = from_json(value, Hash)
+          hash.is_a?(Hash) ? coerce(hash, spec) : hash
+        else value
+        end
+      end
+
+      # The first non-null type ("type": ["string", "null"] is common in MCP).
+      def type_of(spec)
+        Array(field(spec, :type)).map(&:to_s).find { |type| type != "null" }
+      end
+
+      def to_integer(value)
+        case value
+        when String then value.strip.match?(/\A-?\d+\z/) ? Integer(value.strip, 10) : value
+        when Float then value == value.floor ? value.to_i : value
+        else value
+        end
+      end
+
+      def to_number(value)
+        return value unless value.is_a?(String)
+
+        text = value.strip
+        return Integer(text, 10) if text.match?(/\A-?\d+\z/)
+
+        Float(text)
+      rescue ArgumentError
+        value
+      end
+
+      def to_boolean(value)
+        return value unless value.is_a?(String)
+
+        case value.strip.downcase
+        when "true" then true
+        when "false" then false
+        else value
+        end
+      end
+
+      def from_json(value, klass)
+        return value unless value.is_a?(String)
+
+        parsed = JSON.parse(value)
+        parsed.is_a?(klass) ? parsed : value
+      rescue JSON::ParserError
+        value
+      end
+
+      def field(hash, key)
+        return nil unless hash.is_a?(Hash)
+
+        hash.key?(key.to_sym) ? hash[key.to_sym] : hash[key.to_s]
+      end
+
+      # A small reader for Gemma's value syntax: <|"|>text<|"|>, "text" or
+      # 'text', numbers, true/false/null, [a, b] and {key: value}; a bare
+      # word runs to the next , ] or }.
+      class GemmaReader
+        class Invalid < StandardError; end
+
+        def initialize(text, delim)
+          @text = text
+          @delim = delim
+          @pos = 0
+        end
+
+        # The whole text as an object's pairs.
+        def object_body
+          skip_space
+          return {} if @pos == @text.length
+
+          hash = pairs(nil)
+          skip_space
+          raise Invalid unless @pos == @text.length
+
+          hash
+        end
+
+        private
+
+        def pairs(close)
+          hash = {}
+          skip_space
+          return hash if close && peek == close
+
+          loop do
+            key = read_key
+            skip_space
+            raise Invalid unless peek == ":"
+
+            @pos += 1
+            hash[key] = read_value
+            skip_space
+            break unless peek == ","
+
+            @pos += 1
+            skip_space
+            break if close && peek == close # a trailing comma
+          end
+          hash
+        end
+
+        def read_key
+          skip_space
+          return read_string if string_start?
+
+          start = @pos
+          @pos += 1 while @pos < @text.length && @text[@pos].match?(/\w/)
+          raise Invalid if @pos == start
+
+          @text[start...@pos]
+        end
+
+        def read_value
+          skip_space
+          return read_string if string_start?
+
+          case peek
+          when "[" then read_list
+          when "{"
+            @pos += 1
+            hash = pairs("}")
+            expect("}")
+            hash
+          else read_bare
+          end
+        end
+
+        def read_list
+          @pos += 1
+          list = []
+          skip_space
+          until peek == "]"
+            list << read_value
+            skip_space
+            break unless peek == ","
+
+            @pos += 1
+            skip_space
+          end
+          expect("]")
+          list
+        end
+
+        def string_start? = @text[@pos, @delim.length] == @delim || peek == '"' || peek == "'"
+
+        def read_string
+          if @text[@pos, @delim.length] == @delim
+            start = @pos + @delim.length
+            close = @text.index(@delim, start) or raise Invalid
+            @pos = close + @delim.length
+            return @text[start...close]
+          end
+
+          quote = peek
+          @pos += 1
+          out = +""
+          while @pos < @text.length
+            char = @text[@pos]
+            if char == "\\" && @pos + 1 < @text.length
+              nxt = @text[@pos + 1]
+              out << { "n" => "\n", "t" => "\t" }.fetch(nxt, nxt)
+              @pos += 2
+            elsif char == quote
+              @pos += 1
+              return out
+            else
+              out << char
+              @pos += 1
+            end
+          end
+          raise Invalid
+        end
+
+        def read_bare
+          start = @pos
+          @pos += 1 while @pos < @text.length && !",]}".include?(@text[@pos])
+          word = @text[start...@pos].strip
+          raise Invalid if word.empty?
+
+          case word
+          when "true" then true
+          when "false" then false
+          when "null" then nil
+          when /\A-?\d+\z/ then Integer(word, 10)
+          when /\A-?\d+\.\d+(?:[eE][-+]?\d+)?\z/ then Float(word)
+          else word
+          end
+        end
+
+        def expect(char)
+          skip_space
+          raise Invalid unless peek == char
+
+          @pos += 1
+        end
+
+        def peek = @text[@pos]
+
+        def skip_space
+          @pos += 1 while @pos < @text.length && @text[@pos].match?(/\s/)
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/tools/ask_user_question.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Samagotchi
+  module Tools
+    # Structured user qualification tool.
+    #
+    # The model invokes this via tool_call when it needs a structured choice from the user
+    # instead of a free-form numbered list in plain text. The harness intercepts the call,
+    # renders a UI-agnostic question (TUI prompt / WEB buttons / future UIs via the same
+    # Engine event), blocks until the user answers, and returns the normalized selection
+    # as the tool_response. No direct terminal/web coupling lives here — callers provide
+    # the blocking handler via Engine (or fallback to a plain error).
+    #
+    # Single tool covers single + multi + freeform via flags: multi_select, allow_freeform.
+    class AskUserQuestion
+      NAME        = "ask_user_question"
+
+      def self.name        = NAME
+
+      # Direct invocation (used in specs / headless fallback).
+      # When a blocking handler is not injected, return an instructional error so the
+      # model falls back to plain text rather than hanging.
+      def self.call(question, options: nil, header: nil, multi_select: nil, allow_freeform: nil)
+        question = question.to_s.strip
+        return "Error: question is required" if question.empty?
+
+        opts = normalize_options(options)
+        return "Error: options must be an array of 2-8 non-empty strings" if opts.nil?
+
+        header = header.to_s.strip
+        header = nil if header.empty?
+        ms = to_bool(multi_select)
+        af = to_bool(allow_freeform)
+
+        payload = {
+          question: question,
+          options: opts,
+          header: header,
+          multi_select: ms,
+          allow_freeform: af
+        }.compact
+
+        JSON.pretty_generate(payload)
+      end
+
+      # Normalize options param: accept Array or JSON string; strip, reject empty.
+      # Dumb-model tolerant: handles JSON arrays, quoted CSV, bracket noise, single strings.
+      def self.normalize_options(raw)
+        arr = extract_options_array(raw)
+        return nil unless arr
+
+        cleaned = arr.map { |v| sanitize_option(v) }.reject { |v| v.nil? || v.empty? }
+        # Strict: 2-8, but lenient wrapper allows 1 for dumb-model salvage — keeps strict nil here
+        return nil unless cleaned.size.between?(2, 8)
+
+        cleaned
+      end
+
+      def self.extract_options_array(raw)
+        case raw
+        when Array
+          raw.dup
+        when String
+          s = raw.to_s.strip
+          return nil if s.empty?
+
+          # 1) Try JSON parse (most common: '["a","b"]')
+          begin
+            parsed = JSON.parse(s)
+            return parsed.dup if parsed.is_a?(Array)
+            # If parsed is a String like "a, b", fall through to split
+            if parsed.is_a?(String)
+              s = parsed
+            end
+          rescue JSON::ParserError
+            nil
+          end
+
+          # 2) If it looks like a JSON array but JSON parse failed due to single quotes or trailing commas, extract quoted strings
+          if s.strip.start_with?("[") && s.strip.end_with?("]")
+            quoted = s.scan(/"((?:[^"\\]|\\.)*)"/).flatten
+            unless quoted.empty?
+              # Unescape and strip
+              unescaped = quoted.map { |v| v.gsub('\\"', '"').gsub("\\\\", "\\").strip }
+              # Filter out pure bracket noise
+              filtered = unescaped.reject { |v| v.empty? || v.match?(/\A[\[\],\s]+\z/) }
+              return filtered unless filtered.empty?
+            end
+            # Also try single-quote variant
+            quoted2 = s.scan(/'((?:[^'\\]|\\.)*)'/).flatten
+            unless quoted2.empty?
+              unescaped2 = quoted2.map { |v| v.gsub("\\'", "'").gsub("\\\\", "\\").strip }
+              filtered2 = unescaped2.reject { |v| v.empty? || v.match?(/\A[\[\],\s]+\z/) }
+              return filtered2 unless filtered2.empty?
+            end
+          end
+
+          # 3) Fallback: remove outer brackets then split on comma/semicolon/newline, respecting quotes
+          t = s.strip
+          t = t.sub(/\A\s*\[/, "").sub(/\]\s*\z/, "")
+          # Split on comma/semicolon/newline not inside quotes (simple)
+          parts = t.split(/[,;\n]+/).map(&:strip)
+          # Strip surrounding quotes from each part
+          parts.map { |p| p.gsub(/\A["'\s]+|["'\s]+\z/, "").strip }
+        else
+          return nil
+        end
+      end
+
+      def self.sanitize_option(v)
+        s = v.to_s.strip
+        return nil if s.empty?
+
+        # Remove surrounding quotes/brackets that dumb models include
+        s = s.gsub(/\A["'\s\[\]]+|["'\s\[\]]+\z/, "").strip
+        # Drop wire control tokens (<|...|> and stray <| / |> fragments) that
+        # can bleed into labels when the model wraps options in tool_call markup.
+        s = s.gsub(/<\|[^|]*\|>/, "").gsub(/<\||\|>/, "")
+        # Unescape inner
+        s = s.gsub('\\"', '"').gsub("\\'", "'").gsub("\\\\", "\\")
+        s = s.strip
+        return nil if s.empty?
+        return nil if s.match?(/\A[\[\],\s]+\z/)
+        return nil if s == "]" || s == "["
+
+        s
+      end
+
+      # Public tolerant wrapper used by Engine/KernelLoop/Normalizer (no size check, always returns array)
+      def self.normalize_options_lenient(raw)
+        arr = extract_options_array(raw)
+        return [] unless arr
+
+        arr.map { |v| sanitize_option(v) }.reject { |v| v.nil? || v.empty? }
+      end
+
+      def self.to_bool(v)
+        return nil if v.nil?
+        return v if v == true || v == false
+
+        s = v.to_s.strip.downcase
+        return true if %w[1 true yes on].include?(s)
+        return false if %w[0 false no off].include?(s)
+
+        nil
+      end
+      private_class_method :to_bool
+    end
+  end
+end