ollama_agent 0.3.0 → 1.0.0

data/lib/ollama_agent/core/action_envelope.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module OllamaAgent
+  module Core
+    # Wraps every structured response from the planner.
+    # Enforces a fixed contract so the runner stays deterministic.
+    #
+    # Types:
+    #   :tool_call        — execute a tool with args
+    #   :final            — model is done; surface content to the user
+    #   :ask_clarification— model needs more info before proceeding
+    #   :error            — unrecoverable error in the action
+    #   :handoff          — delegate to another agent
+    class ActionEnvelope
+      VALID_TYPES = %i[tool_call final ask_clarification error handoff].freeze
+
+      attr_reader :type, :payload, :confidence, :envelope_id
+
+      def initialize(type:, payload:, confidence: nil, envelope_id: nil)
+        raise ArgumentError, "Unknown action type: #{type}" unless VALID_TYPES.include?(type.to_sym)
+
+        @type        = type.to_sym
+        @payload     = payload
+        @confidence  = confidence
+        @envelope_id = envelope_id || generate_id
+      end
+
+      # --- Factory constructors ---
+
+      def self.tool_call(tool:, args:, confidence: nil)
+        new(type: :tool_call, payload: { tool: tool.to_s, args: args || {} }, confidence: confidence)
+      end
+
+      def self.final(content:)
+        new(type: :final, payload: { content: content.to_s })
+      end
+
+      def self.ask_clarification(question:)
+        new(type: :ask_clarification, payload: { question: question.to_s })
+      end
+
+      def self.error(message:, cause: nil)
+        new(type: :error, payload: { message: message.to_s, cause: cause })
+      end
+
+      def self.handoff(agent:, query:)
+        new(type: :handoff, payload: { agent: agent.to_s, query: query.to_s })
+      end
+
+      # --- Predicate helpers ---
+
+      def tool_call?        = @type == :tool_call
+      def final?            = @type == :final
+      def ask_clarification? = @type == :ask_clarification
+      def error?            = @type == :error
+      def handoff?          = @type == :handoff
+
+      # --- Accessors for common payload fields ---
+
+      def tool    = @payload[:tool]
+      def args    = @payload[:args] || {}
+      def content = @payload[:content]
+      def question = @payload[:question]
+      def message = @payload[:message]
+
+      def to_h
+        { type: @type, payload: @payload, confidence: @confidence, envelope_id: @envelope_id }
+      end
+
+      def to_s
+        "#<ActionEnvelope type=#{@type} id=#{@envelope_id}>"
+      end
+
+      private
+
+      def generate_id
+        require "securerandom"
+        "env_#{SecureRandom.hex(6)}"
+      end
+    end
+  end
+end

data/lib/ollama_agent/core/budget.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module OllamaAgent
+  module Core
+    # Tracks and enforces token, step, and cost budgets for an agent run.
+    # Instantiate once per run; call #record_step! after each model round-trip.
+    class Budget
+      DEFAULT_MAX_STEPS     = 64
+      DEFAULT_MAX_TOKENS    = 32_768
+      DEFAULT_MAX_COST_USD  = nil
+
+      attr_reader :steps, :tokens_used, :cost_usd,
+                  :max_steps, :max_tokens, :max_cost_usd
+
+      def initialize(max_steps: nil, max_tokens: nil, max_cost_usd: nil)
+        @max_steps    = max_steps    || env_int("OLLAMA_AGENT_MAX_TURNS", DEFAULT_MAX_STEPS)
+        @max_tokens   = max_tokens   || env_int("OLLAMA_AGENT_MAX_TOKENS", DEFAULT_MAX_TOKENS)
+        @max_cost_usd = max_cost_usd || env_float("OLLAMA_AGENT_MAX_COST_USD", DEFAULT_MAX_COST_USD)
+
+        reset!
+      end
+
+      # Record one agent step. Call after each model response.
+      # @param tokens [Integer] tokens consumed in this step (prompt + completion)
+      # @param cost_usd [Float] estimated cost in USD (0.0 for local models)
+      def record_step!(tokens: 0, cost_usd: 0.0)
+        @steps       += 1
+        @tokens_used += tokens.to_i
+        @cost_usd    += cost_usd.to_f
+        nil
+      end
+
+      def steps_exceeded?   = @steps >= @max_steps
+      def tokens_exceeded?  = @tokens_used >= @max_tokens
+      def cost_exceeded?    = !@max_cost_usd.nil? && @cost_usd >= @max_cost_usd
+
+      # True when any limit has been hit.
+      def exceeded?
+        steps_exceeded? || tokens_exceeded? || cost_exceeded?
+      end
+
+      # Human-readable reason for the first exceeded limit, or nil if none.
+      def exceeded_reason
+        return "step limit (#{@max_steps})"        if steps_exceeded?
+        return "token limit (#{@max_tokens})"       if tokens_exceeded?
+        return "cost limit ($#{@max_cost_usd})"     if cost_exceeded?
+
+        nil
+      end
+
+      def reset!
+        @steps       = 0
+        @tokens_used = 0
+        @cost_usd    = 0.0
+      end
+
+      def to_h
+        {
+          steps: @steps,       max_steps: @max_steps,
+          tokens_used: @tokens_used, max_tokens: @max_tokens,
+          cost_usd: @cost_usd, max_cost_usd: @max_cost_usd
+        }
+      end
+
+      def remaining_steps
+        [@max_steps - @steps, 0].max
+      end
+
+      private
+
+      def env_int(key, default)
+        v = ENV.fetch(key, nil)
+        return default if v.nil? || v.strip.empty?
+
+        Integer(v)
+      rescue ArgumentError, TypeError
+        default
+      end
+
+      def env_float(key, default)
+        v = ENV.fetch(key, nil)
+        return default if v.nil? || v.strip.empty?
+
+        Float(v)
+      rescue ArgumentError, TypeError
+        default
+      end
+    end
+  end
+end

data/lib/ollama_agent/core/loop_detector.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module OllamaAgent
+  module Core
+    # Detects when the agent is stuck in a repeating tool-call loop.
+    #
+    # Strategy: keep a sliding window of (tool_name + args_fingerprint) tokens.
+    # If the most-recent window pattern appears THRESHOLD or more times in the
+    # accumulated history, we declare a loop.
+    class LoopDetector
+      DEFAULT_WINDOW    = 4   # number of consecutive calls to treat as one pattern
+      DEFAULT_THRESHOLD = 2   # how many times the pattern must repeat
+
+      attr_reader :history
+
+      def initialize(window: DEFAULT_WINDOW, threshold: DEFAULT_THRESHOLD)
+        @window    = window.to_i.clamp(1, 32)
+        @threshold = threshold.to_i.clamp(2, 16)
+        @history   = []
+      end
+
+      # Record a tool call. Should be called before executing each tool.
+      # @param tool_name [String]
+      # @param args [Hash, String]
+      def record!(tool_name, args = {})
+        @history << fingerprint(tool_name, args)
+      end
+
+      # Returns true when the recent pattern has repeated enough times.
+      def loop_detected?
+        return false if @history.size < @window * @threshold
+
+        pattern = @history.last(@window)
+        matches = 0
+
+        (@history.size - @window + 1).times do |i|
+          matches += 1 if @history[i, @window] == pattern
+        end
+
+        matches >= @threshold
+      end
+
+      # Human-readable description of the detected loop.
+      def loop_summary
+        return nil unless loop_detected?
+
+        pattern = @history.last(@window)
+        "Loop detected: pattern [#{pattern.join(" → ")}] repeated #{@threshold}+ times"
+      end
+
+      def reset!
+        @history.clear
+      end
+
+      private
+
+      def fingerprint(tool_name, args)
+        stable = case args
+                 when Hash  then args.sort.map { |k, v| "#{k}=#{v}" }.join(",")
+                 when Array then args.map(&:to_s).join(",")
+                 else        args.to_s
+                 end
+        "#{tool_name}(#{stable[0, 80]})"
+      end
+    end
+  end
+end

data/lib/ollama_agent/core/schema_validator.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module OllamaAgent
+  module Core
+    # Lightweight JSON-schema validator for tool arguments.
+    # Supports: type, required, properties, enum, minimum, maximum, minLength, maxLength.
+    # Does NOT require the json-schema gem — all validation is hand-rolled for zero dependencies.
+    class SchemaValidator
+      ValidationError = Class.new(StandardError)
+
+      # Validate +data+ against +schema+.
+      # @param schema [Hash] JSON schema (symbol or string keys)
+      # @param data   [Hash] data to validate
+      # @return [Array<String>] list of error messages (empty = valid)
+      def validate(schema, data)
+        @errors = []
+        schema  = stringify_keys(schema)
+        data    = stringify_keys(data || {})
+
+        check_type(schema, data)
+        check_required(schema, data)
+        check_properties(schema, data)
+
+        @errors.dup
+      end
+
+      # Raises ValidationError if any errors found.
+      def validate!(schema, data)
+        errors = validate(schema, data)
+        raise ValidationError, errors.join("; ") if errors.any?
+
+        true
+      end
+
+      private
+
+      def check_type(schema, data)
+        expected = schema["type"]
+        return if expected.nil?
+
+        actual = ruby_type(data)
+        unless type_match?(expected, actual, data)
+          @errors << "expected type #{expected}, got #{actual}"
+        end
+      end
+
+      def check_required(schema, data)
+        required = schema["required"]
+        return unless required.is_a?(Array)
+
+        required.each do |field|
+          @errors << "missing required field: #{field}" unless data.key?(field.to_s)
+        end
+      end
+
+      def check_properties(schema, data)
+        props = schema["properties"]
+        return unless props.is_a?(Hash)
+
+        props.each do |prop_name, prop_schema|
+          next unless data.key?(prop_name.to_s)
+
+          value = data[prop_name.to_s]
+          prop_errors = self.class.new.validate(prop_schema, value)
+          prop_errors.each { |e| @errors << "#{prop_name}: #{e}" }
+          check_constraints(prop_name, prop_schema, value)
+        end
+      end
+
+      def check_constraints(name, schema, value)
+        check_enum(name, schema, value)
+        check_string_length(name, schema, value)
+        check_numeric_range(name, schema, value)
+      end
+
+      def check_enum(name, schema, value)
+        allowed = schema["enum"]
+        return unless allowed.is_a?(Array)
+        return if allowed.include?(value)
+
+        @errors << "#{name}: must be one of #{allowed.inspect}, got #{value.inspect}"
+      end
+
+      def check_string_length(name, schema, value)
+        return unless value.is_a?(String)
+
+        min_len = schema["minLength"]
+        max_len = schema["maxLength"]
+
+        if min_len && value.length < min_len
+          @errors << "#{name}: length #{value.length} is less than minLength #{min_len}"
+        end
+        if max_len && value.length > max_len
+          @errors << "#{name}: length #{value.length} exceeds maxLength #{max_len}"
+        end
+      end
+
+      def check_numeric_range(name, schema, value)
+        return unless value.is_a?(Numeric)
+
+        minimum = schema["minimum"]
+        maximum = schema["maximum"]
+
+        @errors << "#{name}: #{value} is less than minimum #{minimum}"    if minimum && value < minimum
+        @errors << "#{name}: #{value} exceeds maximum #{maximum}"          if maximum && value > maximum
+      end
+
+      def ruby_type(value)
+        case value
+        when Hash    then "object"
+        when Array   then "array"
+        when String  then "string"
+        when Integer then "integer"
+        when Float   then "number"
+        when TrueClass, FalseClass then "boolean"
+        when NilClass then "null"
+        else "unknown"
+        end
+      end
+
+      def type_match?(expected, actual, data)
+        return actual == expected unless expected == "number"
+
+        data.is_a?(Numeric)
+      end
+
+      def stringify_keys(obj)
+        return obj unless obj.is_a?(Hash)
+
+        obj.transform_keys(&:to_s).transform_values do |v|
+          v.is_a?(Hash) ? stringify_keys(v) : v
+        end
+      end
+    end
+  end
+end

data/lib/ollama_agent/core/trace_logger.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "securerandom"
+
+module OllamaAgent
+  module Core
+    # Structured observability logger for agent runs.
+    # Tracks: run_id, step_id, tool_call_id, latency, token usage,
+    # retry count, fallback usage, schema failures, user approvals.
+    #
+    # Supports three output modes (set via :format):
+    #   :human  — colored, readable (default)
+    #   :json   — NDJSON file under log_dir
+    #   :debug  — human + full payload dump
+    class TraceLogger
+      FORMATS = %i[human json debug].freeze
+
+      attr_reader :run_id
+
+      def initialize(log_dir: nil, format: :human, hooks: nil)
+        @log_dir = log_dir
+        @format  = FORMATS.include?(format.to_sym) ? format.to_sym : :human
+        @hooks   = hooks
+        @run_id  = "run_#{SecureRandom.hex(8)}"
+        @step    = 0
+
+        attach_to_hooks if @hooks
+      end
+
+      # Emit a structured trace event.
+      # @param event [Symbol] event name
+      # @param payload [Hash]
+      def trace(event, payload = {})
+        entry = build_entry(event, payload)
+        write_entry(entry)
+        entry
+      end
+
+      def start_run(query: nil)
+        trace(:run_start, { query: query, run_id: @run_id })
+      end
+
+      def end_run(turns:, budget: nil)
+        trace(:run_end, { turns: turns, budget: budget&.to_h, run_id: @run_id })
+      end
+
+      def tool_call(name:, args:, turn:, call_id: nil)
+        @step += 1
+        trace(:tool_call, { name: name, args: args, turn: turn,
+                            step: @step, call_id: call_id || step_id })
+      end
+
+      def tool_result(name:, result:, turn:, latency_ms: nil, call_id: nil)
+        trace(:tool_result, { name: name, bytes: result.to_s.bytesize,
+                              turn: turn, latency_ms: latency_ms, call_id: call_id })
+      end
+
+      def schema_failure(tool:, errors:)
+        trace(:schema_failure, { tool: tool, errors: errors })
+      end
+
+      def user_approval(tool:, approved:)
+        trace(:user_approval, { tool: tool, approved: approved })
+      end
+
+      def retry_attempt(attempt:, delay_ms:, error:)
+        trace(:http_retry, { attempt: attempt, delay_ms: delay_ms,
+                             error: error.class.name, message: error.message })
+      end
+
+      def fallback_used(from_provider:, to_provider:, reason:)
+        trace(:provider_fallback, { from: from_provider, to: to_provider, reason: reason })
+      end
+
+      def loop_detected(summary:)
+        trace(:loop_detected, { summary: summary })
+      end
+
+      def budget_exceeded(reason:)
+        trace(:budget_exceeded, { reason: reason })
+      end
+
+      private
+
+      def attach_to_hooks
+        @hooks.on(:on_tool_call)   { |p| tool_call(name: p[:name], args: p[:args], turn: p[:turn]) }
+        @hooks.on(:on_tool_result) { |p| tool_result(name: p[:name], result: p[:result], turn: p[:turn]) }
+        @hooks.on(:on_retry)       { |p| retry_attempt(attempt: p[:attempt], delay_ms: p[:delay_ms], error: p[:error]) }
+        @hooks.on(:on_complete)    { |p| end_run(turns: p[:turns]) }
+        @hooks.on(:on_error)       { |p| trace(:agent_error, { error: p[:error].class.name, message: p[:error].message }) }
+      end
+
+      def build_entry(event, payload)
+        { ts: timestamp, run_id: @run_id, event: event }.merge(payload)
+      end
+
+      def write_entry(entry)
+        case @format
+        when :json  then write_json(entry)
+        when :debug then write_debug(entry)
+        else             write_human(entry)
+        end
+      rescue StandardError
+        nil
+      end
+
+      def write_json(entry)
+        return unless @log_dir
+
+        FileUtils.mkdir_p(@log_dir)
+        path = File.join(@log_dir, "#{Date.today}.trace.ndjson")
+        File.open(path, "a", encoding: Encoding::UTF_8) { |f| f.puts(JSON.generate(entry)) }
+      end
+
+      def write_human(entry)
+        event  = entry[:event].to_s.ljust(20)
+        detail = entry.reject { |k, _| %i[ts run_id event].include?(k) }
+                      .map { |k, v| "#{k}=#{v.inspect}" }.join(" ")
+        warn "[#{entry[:ts]}] #{event} #{detail}" if ENV["OLLAMA_AGENT_TRACE"] == "1"
+      end
+
+      def write_debug(entry)
+        warn "[TRACE] #{JSON.generate(entry)}" if ENV["OLLAMA_AGENT_DEBUG"] == "1"
+        write_json(entry) if @log_dir
+      end
+
+      def timestamp
+        Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%3NZ")
+      end
+
+      def step_id
+        "step_#{@run_id}_#{@step}"
+      end
+    end
+  end
+end

data/lib/ollama_agent/external_agents/probe.rb

@@ -21,10 +21,10 @@ module OllamaAgent
           name = agent["binary"].to_s
           return nil if name.empty?
 
-          out, status = Open3.capture2("command", "-v", name)
-          return out.strip if status.success? && !out.to_s.strip.empty?
+          resolved = resolve_via_command_v(name)
+          return resolved if resolved
 
-          nil
+          resolve_via_path_walk(name)
         end
         # rubocop:enable Metrics/AbcSize
 
@@ -113,6 +113,26 @@ module OllamaAgent
 
         private
 
+        # POSIX `command -v` when /usr/bin/command exists; rescues ENOENT when `command` is shell-only.
+        def resolve_via_command_v(name)
+          out, status = Open3.capture2("command", "-v", name)
+          return out.strip if status.success? && !out.to_s.strip.empty?
+
+          nil
+        rescue Errno::ENOENT
+          nil
+        end
+
+        def resolve_via_path_walk(name)
+          ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).each do |dir|
+            next if dir.empty?
+
+            abs = File.join(dir, name)
+            return abs if File.file?(abs) && File.executable?(abs)
+          end
+          nil
+        end
+
         def status_cache
           @status_cache ||= {}
         end

data/lib/ollama_agent/indexing/context_packer.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require_relative "repo_scanner"
+require_relative "file_indexer"
+
+module OllamaAgent
+  module Indexing
+    # Builds a compact, query-relevant context block from the repository.
+    # Used to inject surgical context into the system prompt instead of
+    # reading entire files blindly.
+    #
+    # @example
+    #   packer = OllamaAgent::Indexing::ContextPacker.new(root: Dir.pwd)
+    #   context = packer.pack(query: "fix the authentication module")
+    #   # => "# lib/auth/session.rb\n```ruby\n...\n```\n\n# lib/auth/token.rb\n..."
+    class ContextPacker
+      DEFAULT_MAX_FILES    = 15
+      DEFAULT_MAX_FILE_BYTES = 8_192     # 8 KB per file in context
+      DEFAULT_MAX_TOTAL_BYTES = 65_536   # 64 KB total context
+
+      def initialize(root:, max_files: DEFAULT_MAX_FILES,
+                     max_file_bytes: DEFAULT_MAX_FILE_BYTES,
+                     max_total_bytes: DEFAULT_MAX_TOTAL_BYTES,
+                     indexer: nil)
+        @root            = File.expand_path(root)
+        @max_files       = max_files
+        @max_file_bytes  = max_file_bytes
+        @max_total_bytes = max_total_bytes
+        @indexer         = indexer || FileIndexer.new(root: @root)
+      end
+
+      # Pack the most relevant files for a query.
+      # @param query    [String]       natural-language query for scoring
+      # @param files    [Array, nil]   explicit relative paths (bypasses scoring)
+      # @param languages [Array, nil]  filter to specific languages
+      # @return [String]  formatted context block (Markdown fenced code)
+      def pack(query: nil, files: nil, languages: nil)
+        candidates = if files
+                       files.map { |f| File.expand_path(f, @root) }
+                     elsif query
+                       relevant_paths(query, languages: languages)
+                     else
+                       recently_modified_paths
+                     end
+
+        build_context(candidates)
+      end
+
+      # Return a repo-summary block (structure, file counts, recent changes).
+      def repo_summary
+        scanner = RepoScanner.new(root: @root)
+        stats   = scanner.stats
+
+        lines = ["## Repository Summary", "Root: #{@root}", ""]
+        lines << "### File counts by language"
+        stats[:languages]
+          .sort_by { |_, v| -v[:files] }
+          .first(10)
+          .each { |lang, info| lines << "- #{lang}: #{info[:files]} files (#{human_bytes(info[:bytes])})" }
+
+        lines << ""
+        lines << "### Recently modified (top 10)"
+        scanner.recently_modified(n: 10).each do |f|
+          lines << "- #{f.relative_path} (#{human_bytes(f.size)})"
+        end
+
+        lines.join("\n")
+      end
+
+      private
+
+      def relevant_paths(query, languages: nil)
+        entries = @indexer.search(query, top_n: @max_files, languages: languages)
+        entries.map { |e| File.join(@root, e.relative_path) }
+      end
+
+      def recently_modified_paths
+        scanner = RepoScanner.new(root: @root)
+        scanner.recently_modified(n: @max_files).map(&:path)
+      end
+
+      def build_context(paths)
+        parts      = []
+        total_bytes = 0
+
+        paths.each do |abs_path|
+          break if total_bytes >= @max_total_bytes
+          break if parts.size >= @max_files
+
+          next unless File.file?(abs_path)
+
+          rel     = abs_path.sub("#{@root}/", "")
+          content = read_truncated(abs_path)
+          lang    = detect_fence_lang(abs_path)
+
+          block       = "### #{rel}\n```#{lang}\n#{content}\n```"
+          block_bytes = block.bytesize
+
+          break if total_bytes + block_bytes > @max_total_bytes
+
+          parts       << block
+          total_bytes += block_bytes
+        end
+
+        parts.empty? ? "" : parts.join("\n\n")
+      end
+
+      def read_truncated(path)
+        raw = File.read(path, encoding: "utf-8", invalid: :replace)
+        if raw.bytesize > @max_file_bytes
+          raw.byteslice(0, @max_file_bytes) + "\n# ... [truncated — #{human_bytes(raw.bytesize)} total]"
+        else
+          raw
+        end
+      rescue StandardError
+        "[unreadable]"
+      end
+
+      def detect_fence_lang(path)
+        ext_map = {
+          ".rb" => "ruby", ".js" => "javascript", ".ts" => "typescript",
+          ".py" => "python", ".go" => "go", ".rs" => "rust", ".java" => "java",
+          ".sh" => "bash", ".yml" => "yaml", ".yaml" => "yaml",
+          ".json" => "json", ".md" => "markdown", ".html" => "html",
+          ".css" => "css", ".sql" => "sql", ".ex" => "elixir", ".exs" => "elixir"
+        }
+        ext_map[File.extname(path).downcase] || ""
+      end
+
+      def human_bytes(n)
+        return "#{n} B" if n < 1024
+
+        n /= 1024.0
+        return "#{n.round(1)} KB" if n < 1024
+
+        "#{(n / 1024.0).round(1)} MB"
+      end
+    end
+  end
+end