turnkit 0.2.2 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be681d2deacaf1e3be9de2eb84eef412a686baf90a8b0c0a41280cf6a76ecc55
-  data.tar.gz: f0e6d232f50a67ce4a2cd5c46360549b7755a7b6ab100968bd9a2bf16f3cab0a
+  metadata.gz: 75121664c1e081304931fbf125db92a9abc8b9062f920c7e33f7759b52ce51ec
+  data.tar.gz: ccabe905d199d955d281c936a019995a3bd9bc29c0fc009160ea924de4605835
 SHA512:
-  metadata.gz: dc9fbeca56bbdc7e737a56dcbb0caa87eb17186c035f052285532749e1e27546884d020c216c72f008950ad38053fc67dbd71e5cfd8d572f169029d4a78ba116
-  data.tar.gz: ae8b955e099d1d81026ff34b3bae9e4a5009122e1e8cccaa64aed0675f888c0cb12fcae503781daa6ad710e8f9f56aec2387c1ce856cf66d6850430141b28dfe
+  metadata.gz: ff0fa50aabb4c4b4fd9ea6f3ae78b62a4b020522a083f96605028dca2f4ca50a4fb6a9b98b36070e070d38a36b205ebf343823b520f5b0e5b4fe7a06b643cdce
+  data.tar.gz: beec35d2fc1f51cc6fe674d12d72e0ec1b44722bdcfab28019e9ab2d2ae313c684125989647e6d5d389f80b2df5f98dd33aa3c154e0af7da0885d2b8bec0221c

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.2.4 - 2026-06-06
+
+- Add Anthropic prompt cache support for stable system prompt sections.
+- Track cache write tokens and expose model cost totals for turns, conversations, and agents.
+- Calculate costs from RubyLLM model registry pricing with custom rate and calculator overrides.
+- Refresh README usage examples for prompt caching and usage tracking.
+
 ## 0.2.0 - 2026-06-04
 
 - Add configurable system prompt sections and custom system prompt builders.

data/README.md

@@ -26,33 +26,9 @@ Set a provider key:
 
 ```sh
 export ANTHROPIC_API_KEY=...
-# or OPENAI_API_KEY=..., GEMINI_API_KEY=..., OPENROUTER_API_KEY=...
 ```
 
-TurnKit uses RubyLLM by default. Choose the provider by choosing a RubyLLM model name:
-
-```ruby
-TurnKit.default_model = "claude-sonnet-4-5" # Anthropic
-# TurnKit.default_model = "gpt-4.1-mini"    # OpenAI
-# TurnKit.default_model = "gemini-2.5-flash" # Gemini
-```
-
-You can also override the model per agent or per run.
-
-To use a different model SDK, provide a client object that responds to `chat`:
-
-```ruby
-class MyClient < TurnKit::Client
-  def chat(model:, messages:, tools:, instructions:, temperature: nil, metadata: nil)
-    # Call your provider here.
-    TurnKit::Result.new(text: "provider response", model: model)
-  end
-end
-
-TurnKit.client = MyClient.new
-```
-
-Ask an agent:
+Create an agent:
 
 ```ruby
 require "turnkit"
@@ -61,13 +37,39 @@ agent = TurnKit::Agent.new(
   name: "helper",
   instructions: "Answer briefly."
 )
+```
+
+Ask a question:
 
+```ruby
 turn = agent.conversation.ask("Explain Ruby blocks in one sentence.")
 puts turn.output_text
 ```
 
 ## Usage
 
+### Models
+
+Set the default model:
+
+```ruby
+TurnKit.default_model = "claude-sonnet-4-5"
+```
+
+Use OpenAI:
+
+```sh
+export OPENAI_API_KEY=...
+```
+
+Set an OpenAI model:
+
+```ruby
+TurnKit.default_model = "gpt-4.1-mini"
+```
+
+### Conversations
+
 Create a conversation:
 
 ```ruby
@@ -75,14 +77,24 @@ agent = TurnKit::Agent.new(
   name: "writer",
   instructions: "Write clear release notes."
 )
+```
 
+Add context:
+
+```ruby
 conversation = agent.conversation(subject: "v1 launch")
 conversation.say("Mention faster tool execution.")
+```
+
+Run the agent:
 
+```ruby
 turn = conversation.run!
 puts turn.output_text
 ```
 
+### Tools
+
 Create a tool:
 
 ```ruby
@@ -109,158 +121,183 @@ agent = TurnKit::Agent.new(
   instructions: "Save reports when asked.",
   tools: [SaveReport]
 )
+```
+
+Ask for tool use:
 
+```ruby
 turn = agent.conversation.ask("Save a short status report.")
 puts turn.output_text
 ```
 
-Add skills:
+### Skills
+
+Load a skill:
 
 ```ruby
 skill = TurnKit::Skill.from_file("skills/research.md")
+```
 
+Use the skill:
+
+```ruby
 agent = TurnKit::Agent.new(
   name: "researcher",
   skills: [skill]
 )
 ```
 
-List available skills:
+### Sub-agents
+
+Create a sub-agent:
 
 ```ruby
-research = TurnKit::Skill.from_file(
-  "skills/research.md",
-  description: "Use for source-backed research tasks."
+writer = TurnKit::Agent.new(
+  name: "writer",
+  description: "Draft concise copy."
 )
+```
 
-agent = TurnKit::Agent.new(
-  name: "researcher",
-  instructions: "Prefer primary sources.",
-  tools: [WebSearch, ReadWebPage],
-  available_skills: [research]
+Delegate to it:
+
+```ruby
+editor = TurnKit::Agent.new(
+  name: "editor",
+  sub_agents: [writer]
 )
 ```
 
-Add subject context:
+Ask the parent agent:
 
 ```ruby
-article = Article.find(1)
-conversation = agent.conversation(subject: article)
+turn = editor.conversation.ask("Ask the writer for three headlines.")
+puts turn.output_text
 ```
 
-Choose prompt sections:
+### Usage and costs
+
+Inspect token usage:
 
 ```ruby
-agent = TurnKit::Agent.new(
-  name: "writer",
-  instructions: "Write plainly.",
-  prompt_sections: %i[agent instructions tools environment]
-)
+turn.usage.total_tokens
+conversation.usage.total_tokens
+agent.usage.total_tokens
 ```
 
-Build a custom prompt:
+Inspect costs:
 
 ```ruby
-agent = TurnKit::Agent.new(
-  name: "custom",
-  instructions: "Answer in JSON.",
-  system_prompt: ->(prompt) {
-    [
-      prompt.agent_section,
-      prompt.instructions_section,
-      "Return only valid JSON."
-    ].compact.join("\n\n")
+turn.cost.total
+conversation.cost.total
+agent.cost.total
+```
+
+Use RubyLLM registry prices by default.
+
+Override model rates:
+
+```ruby
+TurnKit.cost_rates = {
+  "my-model" => {
+    input: 0.25,
+    output: 1.00,
+    cached_input: 0.05,
+    cache_creation: 0.25
   }
-)
+}
 ```
 
-Use safe prompt data blocks for pipeline-specific prompts:
+Override cost calculation:
 
 ```ruby
-agent = TurnKit::Agent.new(
-  name: "researcher",
-  system_prompt: ->(prompt) {
-    [
-      prompt.section(:agent),
-      prompt.section(:behavior),
-      prompt.untrusted_section(
-        :retrieval_context,
-        ExternalSearch.results_for("turnkit"),
-        label: "Retrieved external evidence."
-      ),
-      prompt.section(:tools),
-      prompt.section(:environment)
-    ].compact.join("\n\n")
+TurnKit.cost_calculator = ->(usage, model) do
+  {
+    input: usage.input_tokens * 0.25 / 1_000_000.0,
+    output: usage.output_tokens * 1.00 / 1_000_000.0
   }
-)
+end
 ```
 
-Choose a prompt mode:
+Limit turn cost:
 
 ```ruby
-TurnKit::Agent.new(name: "main", prompt_mode: :full)    # default sections
-TurnKit::Agent.new(name: "worker", prompt_mode: :minimal) # agent, instructions, behavior, tools, environment
-TurnKit::Agent.new(name: "raw", prompt_mode: :none)     # tiny TurnKit identity prompt
+agent = TurnKit::Agent.new(
+  name: "analyst",
+  cost_limit: 0.25
+)
 ```
 
-TurnKit automatically uses the minimal prompt mode for delegated sub-agent turns unless the child agent sets its own `prompt_mode`.
+### Prompt caching
 
-Inject live context on each turn:
+Enable prompt caching:
 
 ```ruby
-TurnKit.context_contributors << ->(context) {
-  TurnKit::LiveContextContribution.new(
-    name: "account",
-    content: AccountSummary.for(context.conversation.metadata["account_id"]),
-    trusted: false
-  )
-}
+TurnKit.prompt_cache = :auto
 ```
 
-Live context and subject context are rendered below `TurnKit::SystemPrompt::CACHE_BOUNDARY`, so provider adapters can reuse the stable prefix in the future.
+Disable prompt caching:
+
+```ruby
+TurnKit.prompt_cache = :off
+```
 
-Add model-specific prompt guidance:
+Split custom prompts:
 
 ```ruby
-TurnKit.model_prompt_contributors[/claude/] = ->(context) {
-  TurnKit::PromptContribution.new(
-    stable_prefix: "Provider guidance for #{context.model}.",
-    section_overrides: {
-      behavior: "Be concise, tool-aware, and explicit about uncertainty."
-    }
-  )
-}
+agent = TurnKit::Agent.new(
+  name: "cached",
+  system_prompt: [
+    "Stable instructions and tool guidance.",
+    TurnKit::SystemPrompt::CACHE_BOUNDARY,
+    "Dynamic subject and live context."
+  ].join("\n")
+)
 ```
 
-Inspect prompt shape without storing raw prompt text:
+### Custom clients
+
+Create a client:
 
 ```ruby
-prompt = TurnKit::SystemPrompt.new(agent: agent, turn: turn, conversation: conversation)
-prompt.report
-# => { "chars" => ..., "hash" => ..., "stable_chars" => ..., "dynamic_chars" => ... }
+class MyClient < TurnKit::Client
+  def chat(model:, messages:, tools:, instructions:, temperature: nil, metadata: nil)
+    TurnKit::Result.new(
+      text: "provider response",
+      model: model,
+      usage: TurnKit::Usage.new(
+        input_tokens: 100,
+        output_tokens: 20,
+        cached_tokens: 80,
+        cache_write_tokens: 100
+      )
+    )
+  end
+end
 ```
 
-Delegate to sub-agents:
+Use the client:
 
 ```ruby
-writer = TurnKit::Agent.new(
-  name: "writer",
-  description: "Draft concise copy."
-)
+TurnKit.client = MyClient.new
+```
 
-editor = TurnKit::Agent.new(
-  name: "editor",
-  sub_agents: [writer]
-)
+Split cache sections:
 
-turn = editor.conversation.ask("Ask the writer for three headlines.")
-puts turn.output_text
+```ruby
+stable, dynamic = TurnKit::SystemPrompt.split_cache_boundary(instructions)
 ```
 
+### Rails
+
 Install Rails persistence:
 
 ```sh
 bin/rails generate turnkit:install
+```
+
+Run migrations:
+
+```sh
 bin/rails db:migrate
 ```
 
@@ -268,8 +305,6 @@ Configure Rails:
 
 ```ruby
 TurnKit.store = TurnKit::ActiveRecordStore.new
-TurnKit.default_model = "claude-sonnet-4-5"
-TurnKit.timeout = 300
 ```
 
 Reconcile stale turns:
@@ -289,9 +324,12 @@ TurnKit.timeout = 300
 TurnKit.max_depth = 3
 TurnKit.max_tool_executions = 100
 TurnKit.cost_limit = nil
+TurnKit.cost_rates = {}
+TurnKit.cost_calculator = nil
+TurnKit.prompt_cache = :auto
 ```
 
-Override defaults per agent:
+Override an agent:
 
 ```ruby
 agent = TurnKit::Agent.new(
@@ -303,29 +341,18 @@ agent = TurnKit::Agent.new(
 )
 ```
 
-Override the model for a single conversation or turn:
-
-```ruby
-conversation = agent.conversation(model: "claude-opus-4-1")
-turn = conversation.run!(model: "gpt-4.1-mini")
-```
-
 | Option | Description |
 | --- | --- |
-| `default_model` | Set the default RubyLLM model. The model name determines the provider. |
-| `client` | Set the model client. Defaults to `TurnKit::Adapters::RubyLLM.new`. |
+| `default_model` | Set the default RubyLLM model. |
+| `client` | Set the model client. |
 | `store` | Set the conversation store. |
 | `max_iterations` | Limit model calls per turn. |
 | `timeout` | Limit seconds per root turn. |
-| `max_depth` | Limit sub-agent nesting. |
 | `max_tool_executions` | Limit tool calls per root turn. |
 | `cost_limit` | Limit cost per root turn. |
-| `prompt_sections` | Set default system prompt sections. |
-| `prompt_behavior` | Override the default behavior section text. |
-| `prompt_data_max_chars` | Limit data-block content rendered into prompts. |
-| `context_contributors` | Add live per-turn prompt context blocks. |
-| `system_prompt_contributors` | Add global prompt prefix/suffix/section overrides. |
-| `model_prompt_contributors` | Add model-matched prompt contributions. |
+| `cost_rates` | Override prices by model. |
+| `cost_calculator` | Override cost calculation. |
+| `prompt_cache` | Use provider prompt caching. |
 
 ## Contributing
 

data/lib/turnkit/adapters/ruby_llm.rb

@@ -9,7 +9,7 @@ module TurnKit
         configure_from_environment
 
         chat = ::RubyLLM.chat(model: model)
-        chat.with_instructions(instructions) if instructions && !instructions.empty?
+        add_instructions(chat, instructions, model: model)
         chat.with_temperature(temperature) if temperature
         Array(tools).each { |tool| chat.with_tool(ruby_llm_tool(tool)) }
         Array(messages).each { |message| add_message(chat, message) }
@@ -55,6 +55,37 @@ module TurnKit
           )
         end
 
+        def add_instructions(chat, instructions, model:)
+          return if instructions.nil? || instructions.empty?
+
+          if prompt_cache_enabled? && anthropic_model?(model) && instructions.include?(SystemPrompt::CACHE_BOUNDARY)
+            stable, dynamic = SystemPrompt.split_cache_boundary(instructions)
+            add_system_message(chat, stable, cache: true)
+            add_system_message(chat, dynamic, cache: false)
+          else
+            chat.with_instructions(instructions)
+          end
+        end
+
+        def add_system_message(chat, content, cache: false)
+          content = content.to_s.strip
+          return if content.empty?
+
+          if cache
+            content = ::RubyLLM::Providers::Anthropic::Content.new(content, cache: true)
+          end
+
+          chat.add_message(role: :system, content: content)
+        end
+
+        def prompt_cache_enabled?
+          TurnKit.prompt_cache != :off
+        end
+
+        def anthropic_model?(model)
+          model.to_s.start_with?("claude")
+        end
+
         def ruby_llm_tool_calls(tool_calls)
           return nil if tool_calls.nil? || tool_calls.empty?
 
@@ -88,9 +119,11 @@ module TurnKit
             ToolCall.new(id: call.id, name: call.name, arguments: call.arguments)
           end
           usage = Usage.new(
-            input_tokens: response.respond_to?(:input_tokens) ? response.input_tokens : 0,
-            output_tokens: response.respond_to?(:output_tokens) ? response.output_tokens : 0,
-            cached_tokens: response.respond_to?(:cached_tokens) ? response.cached_tokens : 0
+            input_tokens: token_value(response, :input_tokens),
+            output_tokens: token_value(response, :output_tokens),
+            cached_tokens: token_value(response, :cached_tokens),
+            cache_write_tokens: token_value(response, :cache_creation_tokens),
+            cost: response_cost(response)
           )
           Result.new(
             text: response.respond_to?(:content) ? response.content.to_s : response.to_s,
@@ -99,6 +132,16 @@ module TurnKit
             model: response.respond_to?(:model_id) ? response.model_id : model
           )
         end
+
+        def token_value(response, method)
+          response.respond_to?(method) ? response.public_send(method).to_i : 0
+        end
+
+        def response_cost(response)
+          return unless response.respond_to?(:cost)
+
+          response.cost&.total
+        end
     end
   end
 end

data/lib/turnkit/agent.rb

@@ -41,6 +41,14 @@ module TurnKit
       Conversation.new(agent: self, record: record, store: store, model: model || effective_model, subject: subject, metadata: metadata)
     end
 
+    def cost
+      Cost.from_records(effective_store.list_turns(agent_name: name))
+    end
+
+    def usage
+      Usage.from_records(effective_store.list_turns(agent_name: name))
+    end
+
     def effective_model
       model || TurnKit.default_model
     end

data/lib/turnkit/budget.rb

@@ -32,10 +32,14 @@ module TurnKit
     end
 
     def add_usage!(usage)
-      return unless usage&.cost && cost_limit
+      add_cost!(usage&.cost)
+    end
+
+    def add_cost!(cost)
+      return unless cost && cost_limit
 
       @mutex.synchronize do
-        @cost += usage.cost.to_f
+        @cost += cost.to_f
         raise Error, "cost limit reached" if @cost > cost_limit
       end
     end

data/lib/turnkit/conversation.rb

@@ -48,6 +48,14 @@ module TurnKit
       store.list_messages(id).map { |attrs| Message.new(attrs) }
     end
 
+    def usage
+      Usage.from_records(store.list_turns(conversation_id: id))
+    end
+
+    def cost
+      Cost.from_records(store.list_turns(conversation_id: id))
+    end
+
     def messages_for_turn(turn)
       store.list_messages(id, through_sequence: turn.context_message_sequence, turn_id: turn.id).map { |attrs| Message.new(attrs) }
     end

data/lib/turnkit/cost.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module TurnKit
+  class Cost
+    COMPONENTS = %i[input output cache_read cache_write].freeze
+    PER_MILLION = 1_000_000.0
+
+    attr_reader :input, :output, :cache_read, :cache_write
+
+    def self.aggregate(costs)
+      costs = costs.compact
+      return new unless costs.any?
+
+      if costs.any? { |cost| COMPONENTS.any? { |component| !cost.public_send(component).nil? } }
+        values = COMPONENTS.to_h do |component|
+          amounts = costs.filter_map { |cost| cost.public_send(component) }
+          [ component, amounts.any? ? amounts.sum : nil ]
+        end
+        return new(**values)
+      end
+
+      totals = costs.map(&:total)
+      return new(total: totals.sum) if totals.none?(&:nil?)
+
+      new
+    end
+
+    def self.from_usage(usage, model: nil)
+      return new(total: usage.cost) if usage.cost
+
+      custom = custom_cost(usage, model)
+      return custom if custom
+
+      rates = TurnKit.cost_rates[model.to_s] || TurnKit.cost_rates[model&.to_sym]
+      rates ? from_rates(usage, rates) : from_ruby_llm(usage, model)
+    end
+
+    def self.from_records(records)
+      aggregate(records.map { |record| from_record(record) })
+    end
+
+    def self.from_record(record)
+      attrs = record.transform_keys(&:to_s)
+      usage = attrs["usage"] || {}
+      return from_hash(usage["cost_details"] || usage[:cost_details]) if usage["cost_details"] || usage[:cost_details]
+      return new(total: attrs["cost"]) if attrs["cost"]
+
+      from_usage(Usage.from_h(usage), model: attrs["model"])
+    end
+
+    def self.from_rates(usage, rates)
+      rates = rates.transform_keys(&:to_sym)
+      new(
+        input: amount(usage.input_tokens, rates[:input] || rates[:input_per_million]),
+        output: amount(usage.output_tokens, rates[:output] || rates[:output_per_million]),
+        cache_read: amount(usage.cached_tokens, rates[:cache_read] || rates[:cached_input] || rates[:cache_read_input_per_million] || rates[:cached_input_per_million]),
+        cache_write: amount(usage.cache_write_tokens, rates[:cache_write] || rates[:cache_creation] || rates[:cache_write_input_per_million] || rates[:cache_creation_input_per_million]),
+        strict: true
+      )
+    end
+
+    def self.from_ruby_llm(usage, model)
+      require "ruby_llm"
+
+      model_info = ::RubyLLM.models.find(model) if model
+      return new unless model_info
+
+      if defined?(::RubyLLM::Cost)
+        tokens = ::RubyLLM::Tokens.new(
+          input: usage.input_tokens,
+          output: usage.output_tokens,
+          cached: usage.cached_tokens,
+          cache_creation: usage.cache_write_tokens
+        )
+        from_hash(::RubyLLM::Cost.new(tokens: tokens, model: model_info).to_h)
+      else
+        from_rates(
+          usage,
+          input: model_info.input_price_per_million,
+          output: model_info.output_price_per_million,
+          cached_input: model_info.pricing&.text_tokens&.cached_input
+        )
+      end
+    rescue LoadError, StandardError
+      new
+    end
+
+    def self.from_hash(hash)
+      hash = hash.transform_keys(&:to_sym)
+      new(
+        input: hash[:input],
+        output: hash[:output],
+        cache_read: hash[:cache_read] || hash[:cached_input],
+        cache_write: hash[:cache_write] || hash[:cache_creation],
+        total: hash[:total]
+      )
+    end
+
+    def self.custom_cost(usage, model)
+      return unless TurnKit.cost_calculator
+
+      value = TurnKit.cost_calculator.call(usage, model)
+      case value
+      when nil
+        nil
+      when Cost
+        value
+      when Hash
+        from_hash(value)
+      else
+        new(total: value)
+      end
+    end
+
+    def self.amount(tokens, price)
+      return nil if tokens.to_i.positive? && price.nil?
+      return 0.0 if tokens.to_i.zero?
+
+      tokens.to_i * price.to_f / PER_MILLION
+    end
+
+    def initialize(input: nil, output: nil, cache_read: nil, cache_write: nil, total: nil, strict: false)
+      @input = number(input)
+      @output = number(output)
+      @cache_read = number(cache_read)
+      @cache_write = number(cache_write)
+      @total = number(total)
+      @strict = strict
+    end
+
+    def total
+      return @total if @total
+      return nil if @strict && COMPONENTS.any? { |component| public_send(component).nil? }
+
+      values = COMPONENTS.filter_map { |component| public_send(component) }
+      values.empty? ? nil : values.sum
+    end
+
+    def to_h
+      {
+        "input" => input,
+        "output" => output,
+        "cache_read" => cache_read,
+        "cache_write" => cache_write,
+        "total" => total
+      }.compact
+    end
+
+    private
+      def number(value)
+        value.nil? ? nil : value.to_f
+      end
+  end
+end

data/lib/turnkit/memory_store.rb

@@ -68,11 +68,12 @@ module TurnKit
       end
     end
 
-    def list_turns(root_turn_id: nil, conversation_id: nil)
+    def list_turns(root_turn_id: nil, conversation_id: nil, agent_name: nil)
       @mutex.synchronize do
         rows = @turns.values
         rows = rows.select { |turn| turn["root_turn_id"] == root_turn_id } if root_turn_id
         rows = rows.select { |turn| turn["conversation_id"] == conversation_id } if conversation_id
+        rows = rows.select { |turn| turn["agent_name"] == agent_name } if agent_name
         rows.sort_by { |turn| [ turn["created_at"].to_f, turn["id"] ] }.map { |turn| duplicate(turn) }
       end
     end

data/lib/turnkit/store.rb

@@ -12,7 +12,7 @@ module TurnKit
     def create_turn(_attributes) = raise(NotImplementedError)
     def load_turn(_id) = raise(NotImplementedError)
     def update_turn(_id, _attributes) = raise(NotImplementedError)
-    def list_turns(root_turn_id: nil, conversation_id: nil) = raise(NotImplementedError)
+    def list_turns(root_turn_id: nil, conversation_id: nil, agent_name: nil) = raise(NotImplementedError)
 
     def create_tool_execution(_attributes) = raise(NotImplementedError)
     def load_tool_execution(_id) = raise(NotImplementedError)

data/lib/turnkit/stores/active_record_store.rb

@@ -89,10 +89,11 @@ module TurnKit
       turn_hash(record)
     end
 
-    def list_turns(root_turn_id: nil, conversation_id: nil)
+    def list_turns(root_turn_id: nil, conversation_id: nil, agent_name: nil)
       scope = turn_class.all
       scope = scope.where(root_turn_uid: root_turn_id) if root_turn_id
       scope = scope.where(conversation_uid: conversation_id) if conversation_id
+      scope = scope.where(agent_name: agent_name) if agent_name
       scope.order(:created_at, :uid).map { |record| turn_hash(record) }
     end
 

data/lib/turnkit/turn.rb

@@ -42,9 +42,10 @@ module TurnKit
           instructions: agent.system_prompt_for(turn: self, conversation: conversation),
           metadata: { turn_id: id, conversation_id: conversation.id }
         )
+        result_cost = Cost.from_usage(result.usage, model: result.model || model)
 
-        budget.add_usage!(result.usage)
-        add_usage!(result.usage)
+        budget.add_cost!(result_cost.total)
+        add_usage!(result.usage, cost: result_cost)
         persist_assistant_message(result)
 
         if result.tool_calls?
@@ -79,6 +80,14 @@ module TurnKit
       @record["output_text"].to_s
     end
 
+    def usage
+      Usage.from_h(@record["usage"] || {})
+    end
+
+    def cost
+      Cost.from_record(@record)
+    end
+
     def tool_executions
       store.list_tool_executions(turn_id: id).map { |attrs| ToolExecution.new(attrs) }
     end
@@ -117,15 +126,25 @@ module TurnKit
         update!(status: "completed", output_text: message, completed_at: Clock.now)
       end
 
-      def add_usage!(usage)
+      def add_usage!(usage, cost: nil)
         current = @record["usage"] || {}
         totals = {
           "input_tokens" => current["input_tokens"].to_i + usage.input_tokens,
           "output_tokens" => current["output_tokens"].to_i + usage.output_tokens,
           "cached_tokens" => current["cached_tokens"].to_i + usage.cached_tokens,
+          "cache_write_tokens" => current["cache_write_tokens"].to_i + usage.cache_write_tokens,
           "total_tokens" => current["total_tokens"].to_i + usage.total_tokens
         }
-        update!(usage: totals, heartbeat_at: Clock.now)
+        totals["cost_details"] = aggregate_cost(current["cost_details"], cost).to_h if cost&.total
+        attributes = { usage: totals, heartbeat_at: Clock.now }
+        attributes[:cost] = @record["cost"].to_f + cost.total if cost&.total
+        update!(attributes)
+      end
+
+      def aggregate_cost(current, cost)
+        return cost unless current
+
+        Cost.aggregate([ Cost.from_hash(current), cost ])
       end
 
       def update!(attributes)

data/lib/turnkit/usage.rb

@@ -2,17 +2,47 @@
 
 module TurnKit
   class Usage
-    attr_reader :input_tokens, :output_tokens, :cached_tokens, :cost
+    attr_reader :input_tokens, :output_tokens, :cached_tokens, :cache_write_tokens, :cost
 
-    def initialize(input_tokens: 0, output_tokens: 0, cached_tokens: 0, cost: nil)
+    def self.aggregate(usages)
+      usages = usages.compact
+      costs = usages.map(&:cost).compact
+      cost = costs.sum if costs.any?
+      new(
+        input_tokens: usages.sum(&:input_tokens),
+        output_tokens: usages.sum(&:output_tokens),
+        cached_tokens: usages.sum(&:cached_tokens),
+        cache_write_tokens: usages.sum(&:cache_write_tokens),
+        cost: cost
+      )
+    end
+
+    def self.from_records(records)
+      aggregate(records.map { |record| from_h(record.fetch("usage", {})) })
+    end
+
+    def self.from_h(hash)
+      attrs = hash.transform_keys(&:to_s)
+      cost = attrs["cost"] unless attrs["cost"].is_a?(Hash)
+      new(
+        input_tokens: attrs["input_tokens"],
+        output_tokens: attrs["output_tokens"],
+        cached_tokens: attrs["cached_tokens"],
+        cache_write_tokens: attrs["cache_write_tokens"],
+        cost: cost
+      )
+    end
+
+    def initialize(input_tokens: 0, output_tokens: 0, cached_tokens: 0, cache_write_tokens: 0, cost: nil)
       @input_tokens = input_tokens.to_i
       @output_tokens = output_tokens.to_i
       @cached_tokens = cached_tokens.to_i
+      @cache_write_tokens = cache_write_tokens.to_i
       @cost = cost
     end
 
     def total_tokens
-      input_tokens + output_tokens + cached_tokens
+      input_tokens + output_tokens + cached_tokens + cache_write_tokens
     end
 
     def to_h
@@ -20,6 +50,7 @@ module TurnKit
         "input_tokens" => input_tokens,
         "output_tokens" => output_tokens,
         "cached_tokens" => cached_tokens,
+        "cache_write_tokens" => cache_write_tokens,
         "total_tokens" => total_tokens,
         "cost" => cost
       }.compact

data/lib/turnkit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TurnKit
-  VERSION = "0.2.2"
+  VERSION = "0.2.4"
 end

data/lib/turnkit.rb

@@ -10,6 +10,7 @@ require_relative "turnkit/version"
 require_relative "turnkit/error"
 require_relative "turnkit/id"
 require_relative "turnkit/clock"
+require_relative "turnkit/cost"
 require_relative "turnkit/budget"
 require_relative "turnkit/agent"
 require_relative "turnkit/client"
@@ -41,7 +42,8 @@ module TurnKit
   class << self
     attr_accessor :default_model, :client, :store, :logger
     attr_accessor :max_iterations, :timeout, :max_depth, :max_tool_executions
-    attr_accessor :cost_limit
+    attr_accessor :cost_limit, :prompt_cache
+    attr_accessor :cost_rates, :cost_calculator
     attr_accessor :prompt_sections, :prompt_behavior, :available_skills
     attr_accessor :prompt_data_max_chars, :context_contributors
     attr_accessor :system_prompt_contributors, :model_prompt_contributors
@@ -56,6 +58,8 @@ module TurnKit
   self.timeout = 300
   self.max_depth = 3
   self.max_tool_executions = 100
+  self.prompt_cache = :auto
+  self.cost_rates = {}
   self.prompt_sections = SystemPrompt::DEFAULT_SECTIONS.dup
   self.prompt_data_max_chars = 20_000
   self.available_skills = []

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: turnkit
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.4
 platform: ruby
 authors:
 - Sam Couch
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-05 00:00:00.000000000 Z
+date: 2026-06-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -43,6 +43,7 @@ files:
 - lib/turnkit/client.rb
 - lib/turnkit/clock.rb
 - lib/turnkit/conversation.rb
+- lib/turnkit/cost.rb
 - lib/turnkit/error.rb
 - lib/turnkit/generators/turnkit/install/templates/conversation.rb
 - lib/turnkit/generators/turnkit/install/templates/create_turnkit_tables.rb