active_harness 0.3.7 → 0.3.9

data/lib/active_harness/core/errors.rb

@@ -1,4 +1,15 @@
 module ActiveHarness
+  # Matches a client that went away mid-stream: IOError anywhere, plus
+  # ActionController::Live::ClientDisconnected when Rails is loaded.
+  # Usable in `rescue ActiveHarness::ClientGone`; never raises NameError outside Rails.
+  module ClientGone
+    def self.===(error)
+      return true if IOError === error
+      defined?(::ActionController::Live::ClientDisconnected) &&
+        ::ActionController::Live::ClientDisconnected === error
+    end
+  end
+
   module Errors
     Error = Class.new(StandardError)
 

data/lib/active_harness/http/client.rb

@@ -4,35 +4,82 @@ module ActiveHarness
   module Http
     # Thin Net::HTTP wrapper — no external dependencies.
     class Client
-      # @param url     [URI]
+      METHODS = {
+        get:    Net::HTTP::Get,
+        post:   Net::HTTP::Post,
+        put:    Net::HTTP::Put,
+        patch:  Net::HTTP::Patch,
+        delete: Net::HTTP::Delete
+      }.freeze
+
+      # @param method  [Symbol]   :get, :post, :put, :patch or :delete
+      # @param url     [URI]      https (default) or http — TLS follows the URL scheme
       # @param headers [Hash{String => String}]
-      # @param body    [String]   JSON-serialized body
+      # @param body    [String, nil] request body (usually JSON-serialized); omit for GET/DELETE
       # @param timeout [Integer]  seconds (open + read)
       # @return        [String]   raw response body; also responds to #http_status
       #                           (Integer) so providers can classify errors by
       #                           status without changing the return type
+      def request(method, url, headers: {}, body: nil, timeout: 30)
+        klass = METHODS[method.to_sym] or raise ArgumentError, "Unsupported HTTP method: #{method.inspect}"
+
+        begin
+          res = build_http(url, timeout).request(build_request(klass, url, headers, body))
+        rescue Net::OpenTimeout, Net::ReadTimeout
+          raise Errors::TimeoutError, "Request to #{url.host} timed out"
+        rescue => e
+          raise Errors::ProviderUnavailableError, "#{url.host} unreachable: #{e.message}"
+        end
+
+        with_http_status(res)
+      end
+
       def post(url, headers:, body:, timeout: 30)
+        request(:post, url, headers: headers, body: body, timeout: timeout)
+      end
+
+      def get(url, headers: {}, timeout: 30)
+        request(:get, url, headers: headers, timeout: timeout)
+      end
+
+      def put(url, headers:, body:, timeout: 30)
+        request(:put, url, headers: headers, body: body, timeout: timeout)
+      end
+
+      def patch(url, headers:, body:, timeout: 30)
+        request(:patch, url, headers: headers, body: body, timeout: timeout)
+      end
+
+      def delete(url, headers: {}, timeout: 30)
+        request(:delete, url, headers: headers, timeout: timeout)
+      end
+
+      private
+
+      def build_http(url, timeout)
         http              = Net::HTTP.new(url.host, url.port)
-        http.use_ssl      = true
+        http.use_ssl      = url.scheme == "https"
         http.open_timeout = timeout
         http.read_timeout = timeout
+        http
+      end
 
-        req = Net::HTTP::Post.new(url)
+      def build_request(klass, url, headers, body)
+        req = klass.new(url)
         headers.each { |k, v| req[k] = v }
-        req.body = body
+        req.body = body if body
+        req
+      end
 
-        res  = http.request(req)
+      # Returns the response body with an #http_status accessor attached.
+      def with_http_status(res)
         body = res.body
         return body if body.nil?
 
-        body = body.dup
+        body   = body.dup
         status = res.code.to_i
         body.define_singleton_method(:http_status) { status }
         body
-      rescue Net::OpenTimeout, Net::ReadTimeout
-        raise Errors::TimeoutError, "Request to #{url.host} timed out"
-      rescue => e
-        raise Errors::ProviderUnavailableError, "#{url.host} unreachable: #{e.message}"
       end
     end
   end

data/lib/active_harness/http/streaming_client.rb

@@ -18,7 +18,7 @@ module ActiveHarness
       # @return [Hash]  { content: String, usage: Hash|nil }
       def post(url, headers:, body:, timeout: 60, on_token:, parse_chunk: nil)
         http              = Net::HTTP.new(url.host, url.port)
-        http.use_ssl      = true
+        http.use_ssl      = url.scheme == "https"
         http.open_timeout = timeout
         http.read_timeout = timeout
 
@@ -31,6 +31,10 @@ module ActiveHarness
         usage   = {}
 
         http.request(req) do |response|
+          # Non-2xx: the body is a plain JSON error, not SSE — read it whole and
+          # raise instead of silently returning an empty stream.
+          raise_for_status!(response.code.to_i, response.read_body) unless response.is_a?(Net::HTTPSuccess)
+
           response.read_body do |chunk|
             buffer += chunk
             while (line_end = buffer.index("\n"))
@@ -55,12 +59,40 @@ module ActiveHarness
         { content: content, usage: usage.empty? ? nil : usage }
       rescue Net::OpenTimeout, Net::ReadTimeout
         raise Errors::TimeoutError, "Request to #{url.host} timed out"
+      rescue Errors::ProviderError
+        raise
       rescue => e
         raise Errors::ProviderUnavailableError, "#{url.host} unreachable: #{e.message}"
       end
 
       private
 
+      # Maps an HTTP error status + body to the same error classes the
+      # non-streaming providers raise. The message is pulled from the common
+      # error shapes ({error:{message}}, {message}, {detail}), else the raw body.
+      def raise_for_status!(status, body)
+        msg  = error_message(body)
+        code = status.to_s
+
+        case status
+        when 401, 403 then raise Errors::InvalidApiKeyError.new(msg,       error_code: code)
+        when 429      then raise Errors::RateLimitError.new(msg,           error_code: code)
+        when 503      then raise Errors::ProviderUnavailableError.new(msg, error_code: code)
+        when 500..599 then raise Errors::ServerError.new(msg,              error_code: code)
+        else               raise Errors::InvalidRequestError.new(msg,      error_code: code)
+        end
+      end
+
+      def error_message(body)
+        data = JSON.parse(body.to_s)
+        msg  = data.dig("error", "message") if data["error"].is_a?(Hash)
+        msg ||= data["error"] if data["error"].is_a?(String)
+        msg ||= data["message"] || data["detail"]
+        (msg.is_a?(String) ? msg : data.to_json)
+      rescue JSON::ParserError, NoMethodError, TypeError
+        body.to_s.strip.empty? ? "HTTP error with empty body" : body.to_s.strip[0, 500]
+      end
+
       def default_chunk(parsed)
         token = parsed.dig("choices", 0, "delta", "content")
         raw_u = parsed["usage"]

data/lib/active_harness/pipeline/hooks.rb

@@ -63,7 +63,7 @@ module ActiveHarness
     def fire(event, step_name, data, config)
       run_hooks(config[:hooks], event, step_name, data)
       @stream&.call(:pipeline, event, step_name, data)
-    rescue IOError, ActionController::Live::ClientDisconnected
+    rescue ClientGone
       nil
     end
 

data/lib/active_harness/providers/anthropic.rb

@@ -8,7 +8,11 @@ module ActiveHarness
       ANTHROPIC_VERSION = "2023-06-01"
       DEFAULT_MAX_TOKENS = 1024
 
-      def call(model:, messages:, temperature: 0.7, stream: nil)
+      def supports_tools?
+        true
+      end
+
+      def call(model:, messages:, temperature: 0.7, stream: nil, tools: nil)
         system_msg, chat_messages = extract_system(messages)
 
         body = {
@@ -18,6 +22,7 @@ module ActiveHarness
           messages:    chat_messages
         }
         body[:system] = system_msg if system_msg
+        body[:tools]  = anthropic_tools(tools) if tools && !tools.empty?
 
         headers = {
           "Content-Type"      => "application/json",
@@ -32,30 +37,74 @@ module ActiveHarness
           stream: stream,
           provider: :anthropic,
           model: model
-        ) if stream
+        ) if stream && !(tools && !tools.empty?)
 
         raw  = post_json(URI(config.anthropic_api_url), headers: headers, body: body)
         data = parse!(raw)
         handle_error!(data)
 
         {
-          content:  data.dig("content", 0, "text").to_s.strip,
+          content:  Array(data["content"]).select { |b| b["type"] == "text" }.map { |b| b["text"] }.join.strip,
           provider: :anthropic,
           model:    data["model"] || model,
-          usage:    extract_usage_anthropic(data)
+          usage:    extract_usage_anthropic(data),
+          **anthropic_tool_calls_entry(data)
         }
       end
 
       private
 
       # Anthropic keeps system prompt separate from the messages array.
+      # Also maps the neutral tool-calling message shape to Anthropic content blocks.
       def extract_system(messages)
-        system = messages.find { |m| m[:role] == "system" || m["role"] == "system" }
-        chat   = messages.reject { |m| m[:role] == "system" || m["role"] == "system" }
-                         .map { |m| { role: m[:role] || m["role"], content: m[:content] || m["content"] } }
+        role_of = ->(m) { (m[:role] || m["role"]).to_s }
+        system  = messages.find { |m| role_of.call(m) == "system" }
+        chat    = messages.reject { |m| role_of.call(m) == "system" }.map { |m| anthropic_message(m) }
 
         system_text = system && (system[:content] || system["content"])
-        [system_text, chat]
+        [system_text, merge_tool_results(chat)]
+      end
+
+      def anthropic_message(m)
+        role    = (m[:role] || m["role"]).to_s
+        content = m[:content] || m["content"]
+        calls   = m[:tool_calls] || m["tool_calls"]
+
+        if role == "assistant" && calls && !calls.empty?
+          blocks = []
+          blocks << { type: "text", text: content.to_s } unless content.to_s.empty?
+          calls.each { |c| blocks << { type: "tool_use", id: c[:id], name: c[:name], input: c[:arguments] || {} } }
+          { role: "assistant", content: blocks }
+        elsif role == "tool"
+          { role: "user", content: [{ type: "tool_result", tool_use_id: m[:tool_call_id] || m["tool_call_id"], content: content.to_s }] }
+        else
+          { role: role, content: content }
+        end
+      end
+
+      # Consecutive tool results must live in one user message.
+      def merge_tool_results(chat)
+        chat.each_with_object([]) do |m, out|
+          prev = out.last
+          if prev && prev[:role] == "user" && m[:role] == "user" &&
+             prev[:content].is_a?(Array) && m[:content].is_a?(Array) &&
+             prev[:content].all? { |b| b[:type] == "tool_result" } && m[:content].all? { |b| b[:type] == "tool_result" }
+            prev[:content].concat(m[:content])
+          else
+            out << m
+          end
+        end
+      end
+
+      def anthropic_tools(tools)
+        Array(tools).map { |t| { name: t[:name], description: t[:description].to_s, input_schema: t[:parameters] } }
+      end
+
+      def anthropic_tool_calls_entry(data)
+        calls = Array(data["content"]).select { |b| b["type"] == "tool_use" }
+        return {} if calls.empty?
+
+        { tool_calls: calls.map { |b| { id: b["id"], name: b["name"], arguments: b["input"] || {}, raw_arguments: JSON.generate(b["input"] || {}) } } }
       end
 
       def api_key

data/lib/active_harness/providers/base.rb

@@ -6,6 +6,12 @@ module ActiveHarness
       HTTP            = ActiveHarness::Http::Client.new
       STREAMING_HTTP  = ActiveHarness::Http::StreamingClient.new
 
+      # Providers that can send `tools:` and return `tool_calls:` override this
+      # (see Providers::ToolCalling). Everything else is rejected by Request.
+      def supports_tools?
+        false
+      end
+
       private
 
       def config

data/lib/active_harness/providers/deepseek.rb

@@ -5,11 +5,14 @@ module ActiveHarness
     # DeepSeek — OpenAI-compatible API.
     # https://platform.deepseek.com/api-docs
     class DeepSeek < Base
-      def call(model:, messages:, temperature: 0.7, stream: nil)
+      include ToolCalling
+
+      def call(model:, messages:, temperature: 0.7, stream: nil, tools: nil)
         headers = { "Content-Type" => "application/json", "Authorization" => "Bearer #{api_key}" }
-        body    = { model: model, messages: messages, temperature: temperature }
+        body    = { model: model, messages: openai_messages(messages), temperature: temperature }
+        body[:tools] = openai_tools(tools) if tools?(tools)
 
-        return call_streaming(url: config.deepseek_api_url, headers: headers, body: body, stream: stream, provider: :deepseek, model: model) if stream
+        return call_streaming(url: config.deepseek_api_url, headers: headers, body: body, stream: stream, provider: :deepseek, model: model) if stream && !tools?(tools)
 
         raw  = post_json(URI(config.deepseek_api_url), headers: headers, body: body)
         data = parse!(raw)
@@ -19,7 +22,7 @@ module ActiveHarness
           content:  data.dig("choices", 0, "message", "content").to_s.strip,
           provider: :deepseek,
           model:    data["model"] || model,
-          usage:    extract_usage_openai(data)
+          usage:    extract_usage_openai(data), **openai_tool_calls_entry(data)
         }
       end
 

data/lib/active_harness/providers/gpustack.rb

@@ -13,20 +13,23 @@ module ActiveHarness
     #     use provider: :gpustack, model: "Qwen/Qwen2.5-7B-Instruct-GGUF"
     #   end
     class GPUStack < Base
-      def call(model:, messages:, temperature: 0.7, stream: nil)
+      include ToolCalling
+
+      def call(model:, messages:, temperature: 0.7, stream: nil, tools: nil)
         url     = "#{api_base}/v1/chat/completions"
         headers = { "Content-Type" => "application/json" }
         key     = api_key
         headers["Authorization"] = "Bearer #{key}" if key
-        body    = { model: model, messages: messages, temperature: temperature }
+        body    = { model: model, messages: openai_messages(messages), temperature: temperature }
+        body[:tools] = openai_tools(tools) if tools?(tools)
 
-        return call_streaming(url: url, headers: headers, body: body, stream: stream, provider: :gpustack, model: model) if stream
+        return call_streaming(url: url, headers: headers, body: body, stream: stream, provider: :gpustack, model: model) if stream && !tools?(tools)
 
         raw  = post_json(URI(url), headers: headers, body: body)
         data = parse!(raw)
         handle_error!(data)
 
-        { content: data.dig("choices", 0, "message", "content").to_s.strip, provider: :gpustack, model: data["model"] || model, usage: extract_usage_openai(data) }
+        { content: data.dig("choices", 0, "message", "content").to_s.strip, provider: :gpustack, model: data["model"] || model, usage: extract_usage_openai(data), **openai_tool_calls_entry(data) }
       end
 
       private

data/lib/active_harness/providers/groq.rb

@@ -5,17 +5,20 @@ module ActiveHarness
     # Groq — OpenAI-compatible API with fast inference.
     # https://console.groq.com/docs/openai
     class Groq < Base
-      def call(model:, messages:, temperature: 0.7, stream: nil)
+      include ToolCalling
+
+      def call(model:, messages:, temperature: 0.7, stream: nil, tools: nil)
         headers = { "Content-Type" => "application/json", "Authorization" => "Bearer #{api_key}" }
-        body    = { model: model, messages: messages, temperature: temperature }
+        body    = { model: model, messages: openai_messages(messages), temperature: temperature }
+        body[:tools] = openai_tools(tools) if tools?(tools)
 
-        return call_streaming(url: config.groq_api_url, headers: headers, body: body, stream: stream, provider: :groq, model: model) if stream
+        return call_streaming(url: config.groq_api_url, headers: headers, body: body, stream: stream, provider: :groq, model: model) if stream && !tools?(tools)
 
         raw  = post_json(URI(config.groq_api_url), headers: headers, body: body)
         data = parse!(raw)
         handle_error!(data)
 
-        { content: data.dig("choices", 0, "message", "content").to_s.strip, provider: :groq, model: data["model"] || model, usage: extract_usage_openai(data) }
+        { content: data.dig("choices", 0, "message", "content").to_s.strip, provider: :groq, model: data["model"] || model, usage: extract_usage_openai(data), **openai_tool_calls_entry(data) }
       end
 
       private

data/lib/active_harness/providers/hetzner.rb

@@ -13,11 +13,14 @@ module ActiveHarness
     #     use provider: :hetzner, model: "meta-llama/Llama-3.3-70B-Instruct"
     #   end
     class Hetzner < Base
-      def call(model:, messages:, temperature: 0.7, stream: nil)
+      include ToolCalling
+
+      def call(model:, messages:, temperature: 0.7, stream: nil, tools: nil)
         headers = { "Content-Type" => "application/json", "Authorization" => "Bearer #{api_key}" }
-        body    = { model: model, messages: messages, temperature: temperature }
+        body    = { model: model, messages: openai_messages(messages), temperature: temperature }
+        body[:tools] = openai_tools(tools) if tools?(tools)
 
-        return call_streaming(url: config.hetzner_api_url, headers: headers, body: body, stream: stream, provider: :hetzner, model: model) if stream
+        return call_streaming(url: config.hetzner_api_url, headers: headers, body: body, stream: stream, provider: :hetzner, model: model) if stream && !tools?(tools)
 
         raw  = post_json(URI(config.hetzner_api_url), headers: headers, body: body)
         data = parse!(raw)
@@ -27,7 +30,7 @@ module ActiveHarness
           content:  data.dig("choices", 0, "message", "content").to_s.strip,
           provider: :hetzner,
           model:    data["model"] || model,
-          usage:    extract_usage_openai(data)
+          usage:    extract_usage_openai(data), **openai_tool_calls_entry(data)
         }
       end
 

data/lib/active_harness/providers/mistral.rb

@@ -5,11 +5,14 @@ module ActiveHarness
     # Mistral AI — OpenAI-compatible API.
     # https://docs.mistral.ai/api
     class Mistral < Base
-      def call(model:, messages:, temperature: 0.7, stream: nil)
+      include ToolCalling
+
+      def call(model:, messages:, temperature: 0.7, stream: nil, tools: nil)
         headers = { "Content-Type" => "application/json", "Authorization" => "Bearer #{api_key}" }
-        body    = { model: model, messages: messages, temperature: temperature }
+        body    = { model: model, messages: openai_messages(messages), temperature: temperature }
+        body[:tools] = openai_tools(tools) if tools?(tools)
 
-        return call_streaming(url: config.mistral_api_url, headers: headers, body: body, stream: stream, provider: :mistral, model: model) if stream
+        return call_streaming(url: config.mistral_api_url, headers: headers, body: body, stream: stream, provider: :mistral, model: model) if stream && !tools?(tools)
 
         raw  = post_json(URI(config.mistral_api_url), headers: headers, body: body)
         data = parse!(raw)
@@ -19,7 +22,7 @@ module ActiveHarness
           content:  data.dig("choices", 0, "message", "content").to_s.strip,
           provider: :mistral,
           model:    data["model"] || model,
-          usage:    extract_usage_openai(data)
+          usage:    extract_usage_openai(data), **openai_tool_calls_entry(data)
         }
       end
 

data/lib/active_harness/providers/ollama.rb

@@ -13,20 +13,23 @@ module ActiveHarness
     #     use provider: :ollama, model: "llama3.2"
     #   end
     class Ollama < Base
-      def call(model:, messages:, temperature: 0.7, stream: nil)
+      include ToolCalling
+
+      def call(model:, messages:, temperature: 0.7, stream: nil, tools: nil)
         url     = "#{api_base}/v1/chat/completions"
         headers = { "Content-Type" => "application/json" }
         key     = api_key
         headers["Authorization"] = "Bearer #{key}" if key
-        body    = { model: model, messages: messages, temperature: temperature }
+        body    = { model: model, messages: openai_messages(messages), temperature: temperature }
+        body[:tools] = openai_tools(tools) if tools?(tools)
 
-        return call_streaming(url: url, headers: headers, body: body, stream: stream, provider: :ollama, model: model) if stream
+        return call_streaming(url: url, headers: headers, body: body, stream: stream, provider: :ollama, model: model) if stream && !tools?(tools)
 
         raw  = post_json(URI(url), headers: headers, body: body)
         data = parse!(raw)
         handle_error!(data)
 
-        { content: data.dig("choices", 0, "message", "content").to_s.strip, provider: :ollama, model: data["model"] || model, usage: extract_usage_openai(data) }
+        { content: data.dig("choices", 0, "message", "content").to_s.strip, provider: :ollama, model: data["model"] || model, usage: extract_usage_openai(data), **openai_tool_calls_entry(data) }
       end
 
       private

data/lib/active_harness/providers/ollama_cloud.rb

@@ -12,11 +12,14 @@ module ActiveHarness
     #     use provider: :ollama_cloud, model: "gpt-oss:120b"
     #   end
     class OllamaCloud < Base
-      def call(model:, messages:, temperature: 0.7, stream: nil)
+      include ToolCalling
+
+      def call(model:, messages:, temperature: 0.7, stream: nil, tools: nil)
         headers = { "Content-Type" => "application/json", "Authorization" => "Bearer #{api_key}" }
-        body    = { model: model, messages: messages, temperature: temperature }
+        body    = { model: model, messages: openai_messages(messages), temperature: temperature }
+        body[:tools] = openai_tools(tools) if tools?(tools)
 
-        return call_streaming(url: config.ollama_cloud_api_url, headers: headers, body: body, stream: stream, provider: :ollama_cloud, model: model) if stream
+        return call_streaming(url: config.ollama_cloud_api_url, headers: headers, body: body, stream: stream, provider: :ollama_cloud, model: model) if stream && !tools?(tools)
 
         raw  = post_json(URI(config.ollama_cloud_api_url), headers: headers, body: body)
         data = parse!(raw)
@@ -26,7 +29,7 @@ module ActiveHarness
           content:  data.dig("choices", 0, "message", "content").to_s.strip,
           provider: :ollama_cloud,
           model:    data["model"] || model,
-          usage:    extract_usage_openai(data)
+          usage:    extract_usage_openai(data), **openai_tool_calls_entry(data)
         }
       end
 

data/lib/active_harness/providers/openai.rb

@@ -3,21 +3,24 @@ require "uri"
 module ActiveHarness
   module Providers
     class OpenAI < Base
+      include ToolCalling
+
       # @param model    [String]
       # @param messages [Array<Hash>]  [{role:, content:}, ...]
       # @param temperature [Float]
       # @return [Hash]  { content:, provider:, model: }
-      def call(model:, messages:, temperature: 0.7, stream: nil)
+      def call(model:, messages:, temperature: 0.7, stream: nil, tools: nil)
         headers = { "Content-Type" => "application/json", "Authorization" => "Bearer #{api_key}" }
-        body    = { model: model, messages: messages, temperature: temperature }
+        body    = { model: model, messages: openai_messages(messages), temperature: temperature }
+        body[:tools] = openai_tools(tools) if tools?(tools)
 
-        return call_streaming(url: config.openai_api_url, headers: headers, body: body, stream: stream, provider: :openai, model: model) if stream
+        return call_streaming(url: config.openai_api_url, headers: headers, body: body, stream: stream, provider: :openai, model: model) if stream && !tools?(tools)
 
         raw  = post_json(URI(config.openai_api_url), headers: headers, body: body)
         data = parse!(raw)
         handle_error!(data)
 
-        { content: data.dig("choices", 0, "message", "content").to_s.strip, provider: :openai, model: data["model"] || model, usage: extract_usage_openai(data) }
+        { content: data.dig("choices", 0, "message", "content").to_s.strip, provider: :openai, model: data["model"] || model, usage: extract_usage_openai(data), **openai_tool_calls_entry(data) }
       end
 
       private

data/lib/active_harness/providers/openrouter.rb

@@ -4,20 +4,23 @@ module ActiveHarness
   module Providers
     # OpenRouter — OpenAI-compatible API that proxies many models.
     class OpenRouter < Base
+      include ToolCalling
+
       # @param model    [String]
       # @param messages [Array<Hash>]  [{role:, content:}, ...]
       # @param temperature [Float]
       # @param stream   [Proc, nil]  if given, called with each token as it arrives
       # @return [Hash]  { content:, provider:, model: }
-      def call(model:, messages:, temperature: 0.7, stream: nil)
+      def call(model:, messages:, temperature: 0.7, stream: nil, tools: nil)
         headers = {
           "Content-Type"  => "application/json",
           "Authorization" => "Bearer #{api_key}",
           "HTTP-Referer"  => config.openrouter_http_referer
         }
-        body = { model: model, messages: messages, temperature: temperature }
+        body = { model: model, messages: openai_messages(messages), temperature: temperature }
+        body[:tools] = openai_tools(tools) if tools?(tools)
 
-        return call_streaming(url: config.openrouter_api_url, headers: headers, body: body, stream: stream, provider: :openrouter, model: model) if stream
+        return call_streaming(url: config.openrouter_api_url, headers: headers, body: body, stream: stream, provider: :openrouter, model: model) if stream && !tools?(tools)
 
         raw  = post_json(URI(config.openrouter_api_url), headers: headers, body: body)
         data = parse!(raw)
@@ -27,7 +30,7 @@ module ActiveHarness
           content:  data.dig("choices", 0, "message", "content").to_s.strip,
           provider: :openrouter,
           model:    data["model"] || model,
-          usage:    extract_usage_openai(data)
+          usage:    extract_usage_openai(data), **openai_tool_calls_entry(data)
         }
       end
 

data/lib/active_harness/providers/tool_calling.rb

@@ -0,0 +1,95 @@
+require "json"
+
+module ActiveHarness
+  module Providers
+    # Tool-calling support shared by OpenAI-compatible providers.
+    #
+    # ActiveHarness speaks to providers in a neutral shape:
+    #
+    #   tools:    [{ name: "os__ls", description: "...", parameters: { type: "object", ... } }]
+    #   messages: [{ role: :user, content: "..." },
+    #              { role: :assistant, content: "", tool_calls: [{ id:, name:, arguments: {} }] },
+    #              { role: :tool, tool_call_id: "...", name: "os__ls", content: "..." }]
+    #
+    # and receives tool calls back as [{ id:, name:, arguments: Hash|nil, raw_arguments: String }].
+    # This module maps that shape to and from the OpenAI wire format.
+    module ToolCalling
+      def supports_tools?
+        true
+      end
+
+      private
+
+      def tools?(tools)
+        !tools.nil? && !tools.empty?
+      end
+
+      def openai_tools(tools)
+        Array(tools).map do |t|
+          {
+            type:     "function",
+            function: { name: t[:name], description: t[:description].to_s, parameters: t[:parameters] }
+          }
+        end
+      end
+
+      def openai_messages(messages)
+        messages.map { |m| openai_message(m) }
+      end
+
+      def openai_message(message)
+        role  = (message[:role] || message["role"]).to_s
+        calls = message[:tool_calls] || message["tool_calls"]
+
+        if role == "assistant" && calls && !calls.empty?
+          content = message[:content] || message["content"]
+          {
+            role:       "assistant",
+            content:    content.to_s.empty? ? nil : content,
+            tool_calls: calls.map do |c|
+              {
+                id:       c[:id],
+                type:     "function",
+                function: { name: c[:name], arguments: JSON.generate(c[:arguments] || {}) }
+              }
+            end
+          }
+        elsif role == "tool"
+          {
+            role:         "tool",
+            tool_call_id: message[:tool_call_id] || message["tool_call_id"],
+            content:      (message[:content] || message["content"]).to_s
+          }
+        else
+          message
+        end
+      end
+
+      # { tool_calls: [...] } when the response contains tool calls, {} otherwise.
+      # Meant to be splatted into the provider's response hash.
+      def openai_tool_calls_entry(data)
+        raw = data.dig("choices", 0, "message", "tool_calls")
+        return {} if raw.nil? || raw.empty?
+
+        { tool_calls: raw.map { |c| parse_openai_tool_call(c) } }
+      end
+
+      def parse_openai_tool_call(call)
+        raw_args = call.dig("function", "arguments")
+        args =
+          case raw_args
+          when Hash   then raw_args
+          when String then raw_args.strip.empty? ? {} : (JSON.parse(raw_args) rescue nil)
+          else {}
+          end
+
+        {
+          id:            call["id"],
+          name:          call.dig("function", "name"),
+          arguments:     args.is_a?(Hash) ? args : nil,
+          raw_arguments: raw_args.is_a?(String) ? raw_args : raw_args.to_s
+        }
+      end
+    end
+  end
+end