rails_console_ai 0.35.0 → 0.36.0

data/lib/rails_console_ai/conversation_engine.rb

@@ -1,3 +1,5 @@
+require 'rails_console_ai/slash_commands'
+
 module RailsConsoleAi
   class ConversationEngine
     attr_reader :history, :total_input_tokens, :total_output_tokens,
@@ -19,6 +21,7 @@ module RailsConsoleAi
       @slack_channel_name = slack_channel_name
       @executor = Executor.new(binding_context, channel: channel)
       @provider = nil
+      @routing_session_id = SecureRandom.hex(8)
       @context_builder = nil
       @context = nil
       @history = []
@@ -255,6 +258,80 @@ module RailsConsoleAi
       execute_direct(code)
     end
 
+    # --- Slash-command invocation of skills and agents ---
+
+    # A skill is a recipe for *this* assistant, and its guard bypasses have to
+    # land on the live executor — so it runs as a normal turn with the recipe
+    # prepended, not in a sub-agent. Returns the user-turn text to send.
+    def skill_command_prompt(skill, request)
+      bypass_methods = Array(skill['bypass_guards_for_methods'])
+      @executor.activate_skill_bypasses(bypass_methods) unless bypass_methods.empty?
+
+      if skill['source'] == :db && skill['id']
+        RailsConsoleAi::Skill.record_use!(skill['id'])
+      end
+
+      @channel.display_status("  Activated skill: #{skill['name']}")
+
+      request = request.to_s.strip
+      task = request.empty? ? "Follow this skill now." : request
+
+      "The user invoked the \"#{skill['name']}\" skill. Follow its procedure.\n\n" \
+        "--- SKILL: #{skill['name']} ---\n#{skill['body']}\n--- END SKILL ---\n\n" \
+        "Their request: #{task}"
+    end
+
+    # An agent is a separate context by definition, so this mirrors delegate_task:
+    # run it, then fold only its summary back into the conversation.
+    def run_agent_command(agent, task)
+      require 'rails_console_ai/sub_agent'
+
+      task = task.to_s.strip
+      if task.empty?
+        @channel.display_warning("  /#{SlashCommands.slugify(agent['name'])} needs a task. Try: /#{SlashCommands.slugify(agent['name'])} <what to investigate>")
+        return
+      end
+
+      @interactive_query ||= "/#{SlashCommands.slugify(agent['name'])} #{task}"
+      log_interactive_turn(status: 'running')
+
+      if agent['source'] == :db && agent['id']
+        RailsConsoleAi::Agent.record_use!(agent['id'])
+      end
+
+      sub = SubAgent.new(
+        task: task,
+        agent_config: agent,
+        binding_context: @executor.binding_context,
+        parent_channel: @channel,
+        executor: @executor
+      )
+
+      begin
+        # Deliberately NOT wrapped in @channel.wrap_llm_call. That wrapper puts the
+        # terminal in raw mode to watch for Esc, which clears ONLCR — so anything
+        # printed inside it staircases down the screen. Everywhere else it wraps
+        # only the provider HTTP call, where nothing prints; a sub-agent run prints
+        # throughout. Ctrl-C still lands here as an Interrupt.
+        result = sub.run
+      rescue Interrupt
+        @channel.display_warning("  Cancelled.")
+        log_interactive_turn(status: 'ready')
+        return
+      end
+
+      record_sub_agent_usage(sub)
+
+      @history << {
+        role: :user,
+        content: "The user ran the \"#{agent['name']}\" agent with the task: #{task}\n\n" \
+                 "The agent reported back:\n#{result}"
+      }
+
+      @channel.display(result.to_s)
+      log_interactive_turn(status: 'ready')
+    end
+
     def execute_direct(raw_code)
       @interactive_query ||= "> #{raw_code}"
       log_interactive_turn(status: 'running')
@@ -424,6 +501,7 @@ module RailsConsoleAi
       end
 
       total_cost = 0.0
+      has_reported_cost = false
       $stdout.puts "\e[36m  Cost estimate:\e[0m"
 
       @token_usage.each do |model, usage|
@@ -432,13 +510,25 @@ module RailsConsoleAi
         input_str = "in: #{format_tokens(usage[:input])}"
         output_str = "out: #{format_tokens(usage[:output])}"
 
-        if pricing
+        # A provider that reports real dollars (OpenRouter) beats any estimate.
+        reported_cost = usage[:cost]
+        if reported_cost && reported_cost > 0
+          has_reported_cost = true
+          total_cost += reported_cost
+          cache_str = ""
           cache_read = usage[:cache_read] || 0
           cache_write = usage[:cache_write] || 0
-          cost = usage_cost(pricing, input: usage[:input], output: usage[:output],
-                                     cache_read: cache_read, cache_write: cache_write)
+          cache_str = "  cache r: #{format_tokens(cache_read)} w: #{format_tokens(cache_write)}" if cache_read > 0 || cache_write > 0
+          $stdout.puts "\e[2m    #{model}:  #{input_str}  #{output_str}#{cache_str}  $#{'%.4f' % reported_cost}\e[0m"
+        elsif pricing
+          cost = Configuration.estimate_cost(model,
+            input: usage[:input], output: usage[:output],
+            cache_read: usage[:cache_read] || 0, cache_write: usage[:cache_write] || 0,
+            cache_ttl: RailsConsoleAi.configuration.resolved_cache_ttl)
           total_cost += cost
           cache_str = ""
+          cache_read = usage[:cache_read] || 0
+          cache_write = usage[:cache_write] || 0
           cache_str = "  cache r: #{format_tokens(cache_read)} w: #{format_tokens(cache_write)}" if cache_read > 0 || cache_write > 0
           $stdout.puts "\e[2m    #{model}:  #{input_str}  #{output_str}#{cache_str}  ~$#{'%.2f' % cost}\e[0m"
         else
@@ -446,7 +536,8 @@ module RailsConsoleAi
         end
       end
 
-      $stdout.puts "\e[36m    Total: ~$#{'%.2f' % total_cost}\e[0m"
+      label = has_reported_cost ? "Total:" : "Total: ~"
+      $stdout.puts "\e[36m    #{label}$#{'%.2f' % total_cost}\e[0m"
     end
 
     def display_conversation
@@ -695,6 +786,19 @@ module RailsConsoleAi
 
     private
 
+    def record_sub_agent_usage(sub)
+      absorb_sub_agent_usage(input: sub.input_tokens, output: sub.output_tokens, model: sub.model_used, cost: sub.cost)
+    end
+
+    def absorb_sub_agent_usage(usage)
+      @total_input_tokens += usage[:input] || 0
+      @total_output_tokens += usage[:output] || 0
+      return unless usage[:model]
+      @token_usage[usage[:model]][:input] += usage[:input] || 0
+      @token_usage[usage[:model]][:output] += usage[:output] || 0
+      @token_usage[usage[:model]][:cost] = (@token_usage[usage[:model]][:cost] || 0) + usage[:cost] if usage[:cost]
+    end
+
     def safety_context
       guards = RailsConsoleAi.configuration.safety_guards
       return nil if guards.empty?
@@ -750,13 +854,15 @@ module RailsConsoleAi
 
     def provider
       @provider ||= begin
-        if @model_override
+        p = if @model_override
           config = RailsConsoleAi.configuration.dup
           config.model = @model_override
           Providers.build(config)
         else
           Providers.build
         end
+        p.routing_session_id = @routing_session_id if p.respond_to?(:routing_session_id=)
+        p
       end
     end
 
@@ -994,13 +1100,7 @@ module RailsConsoleAi
 
           # Aggregate sub-agent token usage into parent's cost tracking
           if tc[:name] == 'delegate_task' && tools.last_sub_agent_usage
-            sa = tools.last_sub_agent_usage
-            @total_input_tokens += sa[:input] || 0
-            @total_output_tokens += sa[:output] || 0
-            if sa[:model]
-              @token_usage[sa[:model]][:input] += sa[:input] || 0
-              @token_usage[sa[:model]][:output] += sa[:output] || 0
-            end
+            absorb_sub_agent_usage(tools.last_sub_agent_usage)
           end
 
           if RailsConsoleAi.configuration.debug
@@ -1134,6 +1234,7 @@ module RailsConsoleAi
       @token_usage[model][:output] += result.output_tokens || 0
       @token_usage[model][:cache_read] = (@token_usage[model][:cache_read] || 0) + (result.cache_read_input_tokens || 0)
       @token_usage[model][:cache_write] = (@token_usage[model][:cache_write] || 0) + (result.cache_write_input_tokens || 0)
+      @token_usage[model][:cost] = (@token_usage[model][:cost] || 0) + (result.cost || 0) if result.cost
     end
 
     def display_usage(result, show_session: false)
@@ -1196,18 +1297,6 @@ module RailsConsoleAi
       chars / 4
     end
 
-    # The four usage buckets each bill at their own rate. `input_tokens` from the
-    # API is the UNCACHED remainder — cached tokens are reported separately and are
-    # not part of it (total prompt size is input + cache_read + cache_write), so
-    # discounting cache_read out of input double-counts and can drive a cost
-    # negative. Every cost readout goes through here.
-    def usage_cost(pricing, input:, output:, cache_read: 0, cache_write: 0)
-      ((input || 0) * pricing[:input]) +
-        ((output || 0) * pricing[:output]) +
-        ((cache_read || 0) * (pricing[:cache_read] || 0)) +
-        ((cache_write || 0) * (pricing[:cache_write] || 0))
-    end
-
     def format_tokens(count)
       if count >= 1_000_000
         "#{(count / 1_000_000.0).round(1)}M"
@@ -1559,13 +1648,17 @@ module RailsConsoleAi
       cache_r = result.cache_read_input_tokens || 0
       cache_w = result.cache_write_input_tokens || 0
       parts << "cache r: #{format_tokens(cache_r)} w: #{format_tokens(cache_w)}" if cache_r > 0 || cache_w > 0
-      model = effective_model
-      pricing = Configuration.pricing_for(model, cache_ttl: RailsConsoleAi.configuration.resolved_cache_ttl)
-      if pricing
-        cost = usage_cost(pricing, input: result.input_tokens, output: result.output_tokens,
-                                   cache_read: cache_r, cache_write: cache_w)
-        parts << "~$#{'%.4f' % cost}"
+
+      if result.cost
+        parts << "$#{'%.4f' % result.cost}"
+      else
+        cost = Configuration.estimate_cost(effective_model,
+          input: result.input_tokens || 0, output: result.output_tokens || 0,
+          cache_read: cache_r, cache_write: cache_w,
+          cache_ttl: RailsConsoleAi.configuration.resolved_cache_ttl)
+        parts << "~$#{'%.4f' % cost}" if cost
       end
+
       parts.join(' | ')
     end
 
@@ -1597,11 +1690,18 @@ module RailsConsoleAi
       parts = ["in: #{format_tokens(input_t)}", "out: #{format_tokens(output_t)}"]
       parts << "cache r: #{format_tokens(cache_r)} w: #{format_tokens(cache_w)}" if cache_r > 0 || cache_w > 0
 
-      if pricing
-        cost = usage_cost(pricing, input: input_t, output: output_t,
-                                   cache_read: cache_r, cache_write: cache_w)
-        session_cost = (total_input * pricing[:input]) + (total_output * pricing[:output])
-        parts << "~$#{'%.4f' % cost}"
+      ttl = RailsConsoleAi.configuration.resolved_cache_ttl
+      if result.cost
+        parts << "$#{'%.4f' % result.cost}"
+        session_has_reported = @token_usage.any? { |_, u| u[:cost] && u[:cost] > 0 }
+        session_cost = session_has_reported ? @token_usage.sum { |_, u| u[:cost] || 0 } :
+          Configuration.estimate_cost(model, input: total_input, output: total_output, cache_ttl: ttl) || 0
+        $stderr.puts "\n#{d}[debug]   ← response: #{parts.join(' | ')}  (session: $#{'%.4f' % session_cost})#{r}"
+      elsif pricing
+        cost = Configuration.estimate_cost(model, input: input_t, output: output_t,
+          cache_read: cache_r, cache_write: cache_w, cache_ttl: ttl)
+        parts << "~$#{'%.4f' % cost}" if cost
+        session_cost = Configuration.estimate_cost(model, input: total_input, output: total_output, cache_ttl: ttl) || 0
         $stderr.puts "\n#{d}[debug]   ← response: #{parts.join(' | ')}  (session: ~$#{'%.4f' % session_cost})#{r}"
       else
         $stderr.puts "\n#{d}[debug]   ← response: #{parts.join(' | ')}#{r}"

data/lib/rails_console_ai/line_editor.rb

@@ -0,0 +1,142 @@
+module RailsConsoleAi
+  # Thin adapters over the two line editors we can drive, so the interactive loop
+  # doesn't care which one is underneath.
+  #
+  # Reline (bundled with Ruby >= 2.7) is preferred: it renders a live completion
+  # dropdown as you type, which is what makes "/" discoverable. Readline is the
+  # fallback and only offers Tab completion.
+  #
+  # The two differ in four ways that matter here, all absorbed by the adapters:
+  #   - prompt escaping: Readline needs \001..\002 around ANSI so it can compute
+  #     the prompt width; Reline parses ANSI itself and would print those literally.
+  #   - output: Reline writes through a Ruby IO, so it has to be pointed at the real
+  #     stdout — otherwise the dropdown's escape codes land in the captured session log.
+  #     Readline writes to its own C-level stream and bypasses $stdout entirely.
+  #   - key binding: Readline has parse_and_bind, Reline has add_default_key_binding.
+  #   - what a completion candidate may contain: see #matches in each adapter.
+  module LineEditor
+    # Shift-Tab: jump to line start, kill the line, type /auto, submit.
+    # Reline binds real bytes; Readline's inputrc parser wants the escapes
+    # un-interpreted, so it gets the backslash form verbatim.
+    SHIFT_TAB   = "\e[Z".freeze
+    AUTO_MACRO  = "\C-a\C-k/auto\C-m".freeze
+    INPUTRC_BIND = '"\e[Z": "\C-a\C-k/auto\C-m"'.freeze
+
+    def self.resolve(preference = nil, output: nil)
+      preference = (preference || :auto).to_sym
+      editor =
+        case preference
+        when :readline then readline_adapter
+        when :reline   then reline_adapter || readline_adapter
+        else reline_adapter || readline_adapter
+        end
+      editor.output = output if output && editor.respond_to?(:output=)
+      editor
+    end
+
+    def self.reline_adapter
+      require 'reline'
+      Reline.respond_to?(:autocompletion=) ? Reline_.new : nil
+    rescue LoadError
+      nil
+    end
+
+    def self.readline_adapter
+      require 'readline'
+      Readline_.new
+    end
+
+    class Base
+      def name; self.class.name.split('::').last.chomp('_').downcase; end
+
+      # Candidates come from a proc so the list stays live — skills and agents can
+      # be created mid-session. The proc returns [slug, label] pairs, where the
+      # label says what kind of thing the slug is ("command", "skill", "agent").
+      def complete_with(&candidates); @candidates = candidates; self; end
+
+      def matches(target)
+        matching(target).map(&:first)
+      end
+
+      private
+
+      def matching(target)
+        return [] unless target.to_s.start_with?('/')
+        entries = @candidates ? @candidates.call : []
+        entries.select { |slug, _| slug.start_with?(target) }
+      end
+    end
+
+    class Reline_ < Base
+      def initialize
+        Reline.autocompletion = true
+        Reline.completion_append_character = ' '
+        Reline.completion_proc = ->(target) { matches(target) }
+      end
+
+      def output=(io); Reline.output = io; end
+
+      def prompt(text, color)
+        "#{color}#{text}\e[0m"
+      end
+
+      def readline(prompt)
+        Reline.readline(prompt, false)
+      end
+
+      def push_history(line)
+        Reline::HISTORY.push(line) unless line == Reline::HISTORY.to_a.last
+      end
+
+      def bind_auto_toggle
+        Reline.core.config.add_default_key_binding(SHIFT_TAB.bytes, AUTO_MACRO.bytes)
+      rescue StandardError
+        nil
+      end
+
+      # Reline's menu inserts whichever row you arrow onto, verbatim, so a
+      # candidate has to be exactly the text that belongs in the buffer. No labels.
+    end
+
+    class Readline_ < Base
+      def initialize
+        Readline.completion_append_character = ' '
+        Readline.completion_proc = ->(target) { matches(target) }
+      end
+
+      def prompt(text, color)
+        "\001#{color}\002#{text}\001\e[0m\002"
+      end
+
+      def readline(prompt)
+        Readline.readline(prompt, false)
+      end
+
+      def push_history(line)
+        Readline::HISTORY.push(line) unless line == Readline::HISTORY.to_a.last
+      end
+
+      def bind_auto_toggle
+        return unless Readline.respond_to?(:parse_and_bind)
+        Readline.parse_and_bind(INPUTRC_BIND)
+      end
+
+      # Readline only ever inserts the common prefix of the candidates it is given,
+      # and displays the rest for the eye alone — so when there is more than one
+      # match we can append a kind label without it ever reaching the buffer. That
+      # is what makes a built-in command distinguishable from a skill or an agent
+      # in the Tab list. The labels sit past the point where the slugs diverge, so
+      # they can't lengthen the common prefix either.
+      #
+      # A lone match is different: there the common prefix IS the whole candidate,
+      # so it must be the bare slug, and Readline appends its trailing space.
+      def matches(target)
+        found = matching(target)
+        return found.map(&:first) if found.size <= 1
+
+        width = found.map { |slug, _| slug.length }.max + 2
+        found.map { |slug, label| "#{slug.ljust(width)}#{label}" }
+      end
+    end
+  end
+end

data/lib/rails_console_ai/providers/base.rb

@@ -5,6 +5,7 @@ module RailsConsoleAi
   module Providers
     class Base
       attr_reader :config
+      attr_accessor :routing_session_id
 
       def initialize(config = RailsConsoleAi.configuration)
         @config = config
@@ -150,7 +151,7 @@ module RailsConsoleAi
     class ProviderError < StandardError; end
 
     ChatResult = Struct.new(:text, :input_tokens, :output_tokens, :tool_calls, :stop_reason,
-                            :cache_read_input_tokens, :cache_write_input_tokens, keyword_init: true) do
+                            :cache_read_input_tokens, :cache_write_input_tokens, :cost, keyword_init: true) do
       def total_tokens
         (input_tokens || 0) + (output_tokens || 0)
       end
@@ -168,6 +169,10 @@ module RailsConsoleAi
       when :openai
         require 'rails_console_ai/providers/openai'
         OpenAI.new(config)
+      when :openrouter
+        require 'rails_console_ai/providers/openai'
+        require 'rails_console_ai/providers/openrouter'
+        OpenRouter.new(config)
       when :local
         require 'rails_console_ai/providers/openai'
         require 'rails_console_ai/providers/local'

data/lib/rails_console_ai/providers/local.rb

@@ -3,38 +3,19 @@ module RailsConsoleAi
     class Local < OpenAI
       private
 
-      def call_api(messages, system_prompt: nil, tools: nil)
-        base_url = config.local_url
-
-        headers = { 'Content-Type' => 'application/json' }
-        api_key = config.local_api_key
-        if api_key && api_key != 'no-key' && !api_key.empty?
-          headers['Authorization'] = "Bearer #{api_key}"
-        end
-
-        conn = build_connection(base_url, headers)
-
-        formatted = []
-        formatted << { role: 'system', content: system_prompt } if system_prompt
-        formatted.concat(format_messages(messages))
-
-        body = {
-          model: config.resolved_model,
-          max_tokens: config.resolved_max_tokens,
-          messages: formatted
-        }
-        temp = config.resolved_temperature
-        body[:temperature] = temp unless temp.nil?
-        body[:tools] = tools.to_openai_format if tools
+      def api_base
+        config.local_url
+      end
 
-        estimated_input_tokens = estimate_tokens(formatted, system_prompt, tools)
+      def request_headers
+        key = config.local_api_key
+        return {} if key.nil? || key.empty? || key == 'no-key'
+        { 'Authorization' => "Bearer #{key}" }
+      end
 
-        json_body = JSON.generate(body)
-        debug_request("#{base_url}/v1/chat/completions", body)
-        response = conn.post('/v1/chat/completions', json_body)
-        debug_response(response.body)
-        data = parse_response(response)
+      def build_result(data, body:, tools: nil)
         usage = data['usage'] || {}
+        estimated_input_tokens = estimate_tokens(body)
 
         prompt_tokens = usage['prompt_tokens']
         if prompt_tokens && estimated_input_tokens > 0 && prompt_tokens < estimated_input_tokens * 0.5
@@ -50,9 +31,6 @@ module RailsConsoleAi
 
         tool_calls = extract_tool_calls(message)
 
-        # Fallback: some local models (e.g. Ollama) emit tool calls as JSON
-        # in the content field instead of using the structured tool_calls format.
-        # Only match when the JSON "name" is a known tool name to avoid false positives.
         if tool_calls.empty? && tools
           tool_names = tools.to_openai_format.map { |t| t.dig('function', 'name') }.compact
           text_calls = extract_tool_calls_from_text(message['content'], tool_names)
@@ -74,10 +52,12 @@ module RailsConsoleAi
         )
       end
 
-      def estimate_tokens(messages, system_prompt, tools)
-        chars = system_prompt.to_s.length
-        messages.each { |m| chars += m[:content].to_s.length + (m[:tool_calls].to_s.length) }
-        chars += tools.to_openai_format.to_s.length if tools
+      def estimate_tokens(body)
+        chars = 0
+        (body[:messages] || []).each do |m|
+          chars += m[:content].to_s.length + (m[:tool_calls].to_s.length)
+        end
+        chars += body[:tools].to_s.length if body[:tools]
         chars / 4
       end
 

data/lib/rails_console_ai/providers/openai.rb

@@ -40,12 +40,35 @@ module RailsConsoleAi
       private
 
       def call_api(messages, system_prompt: nil, tools: nil)
-        conn = build_connection(API_URL, {
-          'Authorization' => "Bearer #{config.resolved_api_key}"
-        })
+        conn = build_connection(api_base, request_headers)
+        body = build_body(messages, system_prompt: system_prompt, tools: tools)
+        debug_request("#{api_base}#{endpoint_path}", body)
+        response = with_retries { conn.post(endpoint_path, JSON.generate(body)) }
+        debug_response(response.body)
+        build_result(parse_response(response), body: body, tools: tools)
+      end
+
+      def api_base
+        API_URL
+      end
+
+      def endpoint_path
+        '/v1/chat/completions'
+      end
 
+      def request_headers
+        { 'Authorization' => "Bearer #{config.resolved_api_key}" }
+      end
+
+      # Overridable: providers that support explicit cache breakpoints emit
+      # multipart content here instead of a bare string.
+      def system_message(system_prompt)
+        { role: 'system', content: system_prompt }
+      end
+
+      def build_body(messages, system_prompt:, tools:)
         formatted = []
-        formatted << { role: 'system', content: system_prompt } if system_prompt
+        formatted << system_message(system_prompt) if system_prompt
         formatted.concat(format_messages(messages))
 
         body = {
@@ -56,12 +79,10 @@ module RailsConsoleAi
         temp = config.resolved_temperature
         body[:temperature] = temp unless temp.nil?
         body[:tools] = tools.to_openai_format if tools
+        body
+      end
 
-        json_body = JSON.generate(body)
-        debug_request("#{API_URL}/v1/chat/completions", body)
-        response = with_retries { conn.post('/v1/chat/completions', json_body) }
-        debug_response(response.body)
-        data = parse_response(response)
+      def build_result(data, body:, tools: nil)
         usage = data['usage'] || {}
 
         choice = (data['choices'] || []).first || {}

data/lib/rails_console_ai/providers/openrouter.rb

@@ -0,0 +1,100 @@
+module RailsConsoleAi
+  module Providers
+    class OpenRouter < OpenAI
+      DEFAULT_URL = 'https://openrouter.ai'.freeze
+      ANTHROPIC_MODEL = /anthropic\/|claude/i
+
+      private
+
+      def api_base
+        config.openrouter_url || DEFAULT_URL
+      end
+
+      def endpoint_path
+        '/api/v1/chat/completions'
+      end
+
+      def request_headers
+        h = { 'Authorization' => "Bearer #{config.resolved_api_key}" }
+        h['HTTP-Referer'] = config.openrouter_site_url if config.openrouter_site_url
+        h['X-Title'] = config.openrouter_app_name if config.openrouter_app_name
+        h
+      end
+
+      def build_body(messages, system_prompt:, tools:)
+        body = super
+        # Root-level cache_control is OpenRouter's automatic mode: it places a
+        # breakpoint on the last cacheable block and moves it forward as the
+        # conversation grows, which is what a tool loop needs — otherwise every
+        # round re-bills the whole accumulated history at full input price.
+        body[:cache_control] = cache_control if cache_supported?
+        body[:session_id] = routing_session_id if routing_session_id
+        # OpenRouter only returns usage.cost — the real dollars every cost
+        # readout prefers over an estimate — when the request asks for it.
+        body[:usage] = { include: true }
+        body
+      end
+
+      # The static system prefix gets its own explicit breakpoint so it has a
+      # guaranteed read point no matter what happens later in `messages`; the
+      # automatic breakpoint above then covers the growing tail. OpenRouter
+      # expresses Anthropic breakpoints as OpenAI-style multipart content.
+      def system_message(system_prompt)
+        return super unless cache_supported?
+
+        { role: 'system',
+          content: [{ type: 'text', text: system_prompt, cache_control: cache_control }] }
+      end
+
+      # Same TTL on every breakpoint: entries with the longer TTL must precede
+      # shorter ones, and an explicit marker whose TTL differs from the root-level
+      # field's is rejected outright.
+      def cache_control
+        ttl = config.respond_to?(:resolved_cache_ttl) ? config.resolved_cache_ttl : nil
+        ttl ? { type: 'ephemeral', ttl: ttl } : { type: 'ephemeral' }
+      end
+
+      def build_result(data, body:, tools: nil)
+        raise_inline_error!(data)
+        result = super
+        usage = data['usage'] || {}
+        details = usage['prompt_tokens_details'] || {}
+
+        cache_read = details['cached_tokens'].to_i
+        cache_write = details['cache_write_tokens'].to_i
+        result.cache_read_input_tokens = cache_read
+        result.cache_write_input_tokens = cache_write
+        result.cost = usage['cost']
+
+        # OpenAI-shaped `prompt_tokens` is the WHOLE prompt, cached tokens
+        # included; Anthropic's `input_tokens` is the uncached remainder, and the
+        # engine is built on the Anthropic contract — it reconstructs total prompt
+        # volume as input + cache_read + cache_write for the runaway-loop budget
+        # breakers. Left as sent, a cached round counts twice and those breakers
+        # fire at half the volume they are set to.
+        if result.input_tokens
+          result.input_tokens = [result.input_tokens - cache_read - cache_write, 0].max
+        end
+
+        if result.tool_calls&.any?
+          result.stop_reason = :tool_use
+        end
+
+        result
+      end
+
+      def cache_supported?
+        config.resolved_model.to_s.match?(ANTHROPIC_MODEL)
+      end
+
+      def raise_inline_error!(data)
+        err = data['error'] || (data['choices'] || []).first&.dig('error')
+        return unless err
+
+        msg = err.is_a?(Hash) ? (err['message'] || err.to_s) : err.to_s
+        code = err.is_a?(Hash) ? err['code'] : 'unknown'
+        raise ProviderError, "OpenRouter error (#{code}): #{msg}"
+      end
+    end
+  end
+end