ollama_agent 0.1.0 → 0.3.0

data/lib/ollama_agent/external_agents/argv_interp.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module OllamaAgent
+  module ExternalAgents
+    # Expands %{name} placeholders in argv templates (no shell).
+    module ArgvInterp
+      class << self
+        def expand(tokens, subs)
+          return [] unless tokens.is_a?(Array)
+
+          tokens.map do |tok|
+            tok.to_s.gsub(/%\{(\w+)\}/) do
+              k = Regexp.last_match(1)
+              subs[k] || subs[k.to_sym]&.to_s || ""
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ollama_agent/external_agents/default_agents.yml

@@ -0,0 +1,60 @@
+# Default external CLI agents (override via ~/.config/ollama_agent/agents.yml or OLLAMA_AGENT_EXTERNAL_AGENTS_CONFIG).
+# argv uses placeholders: binary, task_file, root — subshell interpolation is not supported (argv array only).
+version: 1
+agents:
+  - id: claude_cli
+    binary: claude
+    env_path: OLLAMA_AGENT_CLAUDE_CLI_PATH
+    capabilities:
+      - code_edit
+      - large_context
+    argv:
+      - "%{binary}"
+      - "-p"
+      - "%{task_file}"
+    version_argv:
+      - "%{binary}"
+      - "--version"
+    timeout_sec: 600
+
+  - id: gemini_cli
+    binary: gemini
+    env_path: OLLAMA_AGENT_GEMINI_CLI_PATH
+    capabilities:
+      - code_edit
+    argv:
+      - "%{binary}"
+      - "-p"
+      - "%{task_file}"
+    version_argv:
+      - "%{binary}"
+      - "--version"
+    timeout_sec: 600
+
+  - id: codex_cli
+    binary: codex
+    env_path: OLLAMA_AGENT_CODEX_CLI_PATH
+    capabilities:
+      - code_edit
+    argv:
+      - "%{binary}"
+      - "exec"
+      - "%{task_file}"
+    version_argv:
+      - "%{binary}"
+      - "--version"
+    timeout_sec: 600
+
+  - id: cursor_cli
+    binary: cursor
+    env_path: OLLAMA_AGENT_CURSOR_CLI_PATH
+    capabilities:
+      - code_edit
+    argv:
+      - "%{binary}"
+      - "-p"
+      - "%{task_file}"
+    version_argv:
+      - "%{binary}"
+      - "--version"
+    timeout_sec: 600

data/lib/ollama_agent/external_agents/delegate_logger.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "env_helpers"
+
+module OllamaAgent
+  module ExternalAgents
+    # STDERR logging for delegate runs and shared debug lines (namespaced to avoid Ruby's ::Logger).
+    module DelegateLogger
+      class << self
+        def log_delegate_event(payload)
+          return unless delegate_log_enabled?
+
+          warn("ollama_agent_delegate: #{JSON.generate(payload)}")
+        rescue StandardError
+          nil
+        end
+
+        def debug(message)
+          warn("ollama_agent: #{message}") if EnvHelpers.env_bool?("OLLAMA_AGENT_DEBUG", default: false)
+        end
+
+        def delegate_log_enabled?
+          EnvHelpers.env_bool?("OLLAMA_AGENT_DELEGATE_LOG", default: false) ||
+            EnvHelpers.env_bool?("OLLAMA_AGENT_DEBUG", default: false)
+        end
+      end
+    end
+  end
+end

data/lib/ollama_agent/external_agents/delegate_timeout_status.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module OllamaAgent
+  module ExternalAgents
+    # Stand-in Process::Status when Open3 does not return (Timeout).
+    class DelegateTimeoutStatus
+      def exitstatus
+        124
+      end
+    end
+  end
+end

data/lib/ollama_agent/external_agents/env_helpers.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module OllamaAgent
+  module ExternalAgents
+    # Shared ENV parsing for delegate / external agent code paths.
+    module EnvHelpers
+      class << self
+        def env_present?(key)
+          v = ENV.fetch(key, nil)
+          return false if v.nil?
+
+          !v.to_s.strip.empty?
+        end
+
+        def env_bool?(key, default: false)
+          ENV.fetch(key, default ? "1" : "0").to_s == "1"
+        end
+
+        def env_positive_int(key, default)
+          v = ENV.fetch(key, nil)
+          return default if v.nil? || v.to_s.strip.empty?
+
+          Integer(v)
+        rescue ArgumentError, TypeError
+          default
+        end
+
+        def integer_or_default(raw, default)
+          return default if raw.nil?
+
+          Integer(raw)
+        rescue ArgumentError, TypeError
+          default
+        end
+      end
+    end
+  end
+end

data/lib/ollama_agent/external_agents/path_validator.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module OllamaAgent
+  module ExternalAgents
+    # Ensures paths stay under a project root (expanded, absolute).
+    module PathValidator
+      class << self
+        def validate_within_root!(root, paths)
+          root = File.expand_path(root)
+          Array(paths).each do |p|
+            next if p.to_s.strip.empty?
+
+            abs = File.expand_path(p, root)
+            next if within_root?(abs, root)
+
+            if ENV["OLLAMA_AGENT_DEBUG"] == "1"
+              warn "ollama_agent: PathValidator rejected path outside project root (#{p.inspect})"
+            end
+            raise ArgumentError, "path outside project root"
+          end
+        end
+
+        # Both arguments should already be expanded absolute paths (e.g. from Pathname or File.expand_path).
+        def within_root?(absolute_path, expanded_root)
+          expanded_root = File.expand_path(expanded_root)
+          abs = absolute_path.to_s
+          abs == expanded_root || abs.start_with?(expanded_root + File::SEPARATOR)
+        end
+      end
+    end
+  end
+end

data/lib/ollama_agent/external_agents/probe.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "open3"
+
+require_relative "argv_interp"
+require_relative "env_helpers"
+
+module OllamaAgent
+  module ExternalAgents
+    # Resolves executables and optional --version for registry entries.
+    module Probe
+      class << self
+        # rubocop:disable Metrics/AbcSize
+        def resolve_executable(agent)
+          env_key = agent["env_path"]
+          if env_key && EnvHelpers.env_present?(env_key)
+            path = File.expand_path(ENV[env_key].to_s.strip)
+            return path if File.file?(path)
+          end
+
+          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?
+
+          nil
+        end
+        # rubocop:enable Metrics/AbcSize
+
+        # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+        def fetch_status(agent)
+          cache_key = status_cache_key(agent)
+          cached = status_cache[cache_key]
+          return cached.dup if cached
+
+          exe = resolve_executable(agent)
+          if exe.nil?
+            status = {
+              "id" => agent["id"].to_s,
+              "available" => false,
+              "path" => nil,
+              "version" => nil,
+              "capabilities" => agent["capabilities"] || [],
+              "error" => "executable not found (set #{agent["env_path"] || "PATH"})"
+            }
+            status_cache[cache_key] = status
+            return status.dup
+          end
+
+          status = {
+            "id" => agent["id"].to_s,
+            "available" => true,
+            "path" => exe,
+            "version" => capture_version(agent, exe),
+            "capabilities" => agent["capabilities"] || [],
+            "error" => nil
+          }
+          status_cache[cache_key] = status
+          status.dup
+        end
+        # rubocop:enable Metrics/MethodLength, Metrics/AbcSize
+
+        # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+        def capture_version(agent, exe)
+          argv_templ = agent["version_argv"]
+          return nil unless argv_templ.is_a?(Array) && !argv_templ.empty?
+
+          argv = ArgvInterp.expand(argv_templ, "binary" => exe, "task_file" => "", "root" => "")
+          out, err, status = Open3.capture3(*argv)
+          return nil unless status.success?
+
+          s = out.to_s.strip
+          s = err.to_s.strip if s.empty?
+          return nil if s.empty?
+
+          s.lines.first&.strip
+        rescue StandardError
+          nil
+        end
+        # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+
+        # rubocop:disable Metrics/MethodLength
+        def print_table(registry, io: $stdout)
+          io.puts "id\tok?\tpath\tversion\tcapabilities"
+          registry.agents.each do |a|
+            r = fetch_status(a)
+            io.puts [
+              r["id"],
+              r["available"] ? "yes" : "no",
+              r["path"] || "-",
+              (r["version"] || "-").to_s[0, 80],
+              (r["capabilities"] || []).join(",")
+            ].join("\t")
+          end
+        end
+        # rubocop:enable Metrics/MethodLength
+
+        def clear_cache!
+          status_cache.clear
+        end
+
+        def status_cache_key(agent)
+          env_key = agent["env_path"].to_s
+          env_val = env_key.empty? ? "" : ENV.fetch(env_key, "")
+          [
+            agent["id"].to_s,
+            agent["binary"].to_s,
+            env_key,
+            env_val
+          ].join("|")
+        end
+
+        private
+
+        def status_cache
+          @status_cache ||= {}
+        end
+      end
+    end
+  end
+end

data/lib/ollama_agent/external_agents/registry.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module OllamaAgent
+  module ExternalAgents
+    # Loads merged default + user agent definitions (YAML).
+    class Registry
+      DEFAULT_FILE = File.join(__dir__, "default_agents.yml")
+      USER_FILE = File.join(Dir.home, ".config", "ollama_agent", "agents.yml")
+
+      attr_reader :agents
+
+      def initialize(agents)
+        @agents = agents
+        @by_id = agents.to_h { |a| [a["id"].to_s, a] }
+      end
+
+      def self.load
+        base = safe_read_yaml(DEFAULT_FILE)
+        user_path = ENV.fetch("OLLAMA_AGENT_EXTERNAL_AGENTS_CONFIG", nil)
+        user_path = USER_FILE if user_path.to_s.strip.empty? && File.file?(USER_FILE)
+        user = user_path && File.file?(user_path.to_s) ? safe_read_yaml(user_path) : {}
+        merged = merge_agents(base["agents"] || [], user["agents"] || [])
+        new(merged)
+      end
+
+      def self.safe_read_yaml(path)
+        YAML.safe_load(
+          File.read(path, encoding: Encoding::UTF_8),
+          permitted_classes: [],
+          aliases: true
+        ) || {}
+      end
+
+      def self.merge_agents(base, extra)
+        by_id = base.to_h { |a| [a["id"].to_s, a] }
+        extra.each do |a|
+          id = a["id"].to_s
+          by_id[id] = by_id[id] ? by_id[id].merge(a) : a
+        end
+        by_id.values
+      end
+
+      def find(id)
+        @by_id[id.to_s]
+      end
+    end
+  end
+end

data/lib/ollama_agent/external_agents/runner.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+require "securerandom"
+require "timeout"
+
+require_relative "argv_interp"
+require_relative "delegate_logger"
+require_relative "delegate_timeout_status"
+require_relative "env_helpers"
+require_relative "path_validator"
+
+module OllamaAgent
+  module ExternalAgents
+    # Runs external CLIs with cwd = project root; argv only (no shell).
+    module Runner
+      DEFAULT_MAX_OUTPUT = 100_000
+
+      class << self
+        # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/ParameterLists
+        def run(agent_def:, root:, executable:, task:, context_summary:, paths:, timeout_sec:, max_output_bytes: nil)
+          started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          task_path = nil
+          paths = Array(paths).compact.map(&:to_s)
+          PathValidator.validate_within_root!(root, paths)
+
+          max_b = max_output_bytes || EnvHelpers.env_positive_int(
+            "OLLAMA_AGENT_DELEGATE_MAX_OUTPUT_BYTES",
+            DEFAULT_MAX_OUTPUT
+          )
+
+          handoff = build_handoff(task, context_summary, paths)
+          task_path = write_handoff(root, handoff)
+          argv = ArgvInterp.expand(
+            agent_def["argv"] || [],
+            "binary" => executable,
+            "task_file" => task_path,
+            "root" => root
+          )
+          return "Error: empty argv for agent #{agent_def["id"]}" if argv.empty?
+
+          out, err, status = capture_with_timeout(argv, root, timeout_sec)
+          code = status&.exitstatus
+          DelegateLogger.log_delegate_event(
+            {
+              event: "delegate_to_agent",
+              agent_id: agent_def["id"].to_s,
+              cwd: root.to_s,
+              argv: argv,
+              timeout_seconds: timeout_sec,
+              exit_code: code,
+              duration_ms: elapsed_ms(started_at),
+              env_keys: delegate_env_keys(agent_def)
+            }
+          )
+          combined = "exit:#{code}\n"
+          combined << "stdout:\n#{truncate(out.to_s, max_b)}\n"
+          combined << "stderr:\n#{truncate(err.to_s, max_b)}\n"
+          combined
+        ensure
+          File.unlink(task_path) if task_path && File.file?(task_path)
+        end
+        # rubocop:enable Metrics/MethodLength, Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/ParameterLists
+
+        def interpolate_argv(tokens, subs)
+          ArgvInterp.expand(tokens, subs)
+        end
+
+        def build_handoff(task, context_summary, paths)
+          parts = []
+          parts << "Task:\n#{task.to_s.strip}"
+          parts << "\nContext:\n#{context_summary.to_s.strip}" unless context_summary.to_s.strip.empty?
+          unless paths.empty?
+            path_lines = paths.map { |p| "- #{p}" }.join("\n")
+            parts << "\nRelevant paths (under project root):\n#{path_lines}"
+          end
+          parts.join("\n")
+        end
+
+        def write_handoff(root, text)
+          dir = File.join(root, ".ollama_agent")
+          FileUtils.mkdir_p(dir)
+          path = File.join(dir, "handoff-#{SecureRandom.hex(8)}.txt")
+          File.write(path, text, encoding: Encoding::UTF_8)
+          path
+        end
+
+        def capture_with_timeout(argv, root, timeout_sec)
+          Timeout.timeout(timeout_sec) do
+            Open3.capture3(*argv, chdir: root)
+          end
+        rescue Timeout::Error
+          ["", "ollama_agent: delegate timed out after #{timeout_sec}s", DelegateTimeoutStatus.new]
+        end
+
+        def truncate(str, max_bytes)
+          s = str.to_s
+          return s if s.bytesize <= max_bytes
+
+          "#{s.byteslice(0, max_bytes)}…\n[truncated: output exceeded #{max_bytes} bytes]"
+        end
+
+        def delegate_env_keys(agent_def)
+          keys = []
+          env_key = agent_def["env_path"].to_s
+          keys << env_key unless env_key.empty?
+          keys.concat(ENV.keys.grep(/\AOLLAMA_AGENT_/))
+          keys.uniq.sort
+        end
+
+        def elapsed_ms(started_at)
+          ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000.0).round
+        end
+      end
+    end
+  end
+end

data/lib/ollama_agent/external_agents.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "external_agents/env_helpers"
+require_relative "external_agents/path_validator"
+require_relative "external_agents/delegate_logger"
+require_relative "external_agents/argv_interp"
+require_relative "external_agents/registry"
+require_relative "external_agents/probe"
+require_relative "external_agents/runner"

data/lib/ollama_agent/global_dotenv.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "dotenv"
+
+module OllamaAgent
+  # The ollama-client gem runs +Dotenv.overload+ against the current working directory +.env+.
+  # When a global config file exists (XDG path or +OLLAMA_AGENT_DOTENV_PATH+), restore the
+  # environment from before that load and apply only that file so API keys are not picked up
+  # from arbitrary project trees.
+  module GlobalDotenv
+    module_function
+
+    def reconcile_after_ollama_client!(snapshot)
+      return if use_local_dotenv?
+      return unless (path = resolved_path) && File.file?(path)
+
+      ENV.replace(snapshot)
+      Dotenv.overload(path)
+    end
+
+    def use_local_dotenv?
+      ENV["OLLAMA_AGENT_USE_LOCAL_DOTENV"] == "1"
+    end
+
+    def resolved_path
+      custom = ENV["OLLAMA_AGENT_DOTENV_PATH"].to_s.strip
+      return File.expand_path(custom) unless custom.empty?
+
+      File.join(xdg_config_home, "ollama_agent", ".env")
+    end
+
+    def xdg_config_home
+      base = ENV["XDG_CONFIG_HOME"].to_s.strip
+      return File.expand_path(base) unless base.empty?
+
+      File.expand_path(File.join(Dir.home, ".config"))
+    end
+  end
+end

data/lib/ollama_agent/model_env.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "ollama_client"
+
+module OllamaAgent
+  # Resolves the default chat model from the environment (after global dotenv reconciliation,
+  # these values come from ~/.config/ollama_agent/.env or the shell, not the project tree).
+  module ModelEnv
+    module_function
+
+    # @return [String, nil] model id from ENV when set (used to sync +Ollama::Config+ for Ollama Cloud).
+    def resolved_model_from_env
+      %w[OLLAMA_AGENT_MODEL OLLAMA_MODEL].each do |name|
+        value = ENV[name].to_s.strip
+        return value unless value.empty?
+      end
+
+      nil
+    end
+
+    # @return [String] model id from ENV or ollama-client default (+Ollama::Config.new.model+).
+    def default_chat_model
+      resolved_model_from_env || Ollama::Config.new.model
+    end
+  end
+end

data/lib/ollama_agent/ollama_chat_thinking_stream.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "chat_stream_thinking_format"
+require_relative "chat_stream_carry"
+
+# ollama-client streams `message.content` via hooks[:on_token] but only appends `message.thinking`
+# to a buffer. Forward thinking deltas so the CLI can render reasoning separately (Cursor-like).
+module OllamaAgent
+  # Prepends {Ollama::Client::Chat} to invoke optional +hooks[:on_thinking]+ with each thinking chunk.
+  module OllamaChatThinkingStreamPatch
+    # rubocop:disable Metrics/ParameterLists -- signature must match ollama-client
+    def process_chat_stream_chunk(obj, hooks, full_content, full_thinking, full_logprobs, last_data)
+      normalize_stream_thinking_payload!(obj)
+      emit_streaming_thinking(hooks, obj)
+      ChatStreamCarry.stitch_done_message_tool_calls!(obj, last_data)
+      carry = ChatStreamCarry.next_last_data(last_data, obj)
+      super(obj, hooks, full_content, full_thinking, full_logprobs, carry)
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    private
+
+    def normalize_stream_thinking_payload!(obj)
+      return unless obj.is_a?(Hash) && obj["message"].is_a?(Hash)
+
+      ChatStreamThinkingFormat.normalize_message_thinking!(obj["message"])
+    end
+
+    def emit_streaming_thinking(hooks, obj)
+      return unless obj.is_a?(Hash) && obj["message"].is_a?(Hash)
+
+      th = obj["message"]["thinking"]
+      hooks[:on_thinking]&.call(th) if th.is_a?(String) && !th.empty?
+    end
+  end
+end
+
+if defined?(Ollama::Client::Chat) &&
+   Ollama::Client::Chat.private_method_defined?(:process_chat_stream_chunk, false)
+  Ollama::Client::Chat.prepend(OllamaAgent::OllamaChatThinkingStreamPatch)
+end

data/lib/ollama_agent/ollama_connection.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+require_relative "model_env"
+
 module OllamaAgent
-  # Maps OLLAMA_BASE_URL / OLLAMA_API_KEY into Ollama::Config (ollama-client convention for local vs cloud).
+  # Maps OLLAMA_BASE_URL / OLLAMA_API_KEY / chat model ENV into Ollama::Config (local vs Ollama Cloud).
   module OllamaConnection
     def self.apply_env_to_config(config)
       url = ENV.fetch("OLLAMA_BASE_URL", nil)
@@ -9,6 +11,9 @@ module OllamaAgent
 
       key = ENV.fetch("OLLAMA_API_KEY", nil)
       config.api_key = key if key && !key.strip.empty?
+
+      model = ModelEnv.resolved_model_from_env
+      config.model = model if model
     end
   end
 end