turnkit 0.2.10 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 268561a36c656098e1d23ea6de4c17616358ff931e05e1389e707a9e28fe458b
-  data.tar.gz: 8f6731d78fed5b3e3cc94d781c4f4e26accc4f8d05842b5c56eb58a6e7448907
+  metadata.gz: b5694bc97b2f735e5076574e2863ee5addc41926bd85edf02e1835263ffb3516
+  data.tar.gz: 65286330a1d0b4bbd0e3e6c11ba73abd836fb22a44ae4b3ab48a58ecf9d19425
 SHA512:
-  metadata.gz: ae0a246b5937e586c808a25d28f051bafc54c2a922a52d89160eb3f5ef3bf7360b1d637cbb0c170d41eb74cd536638b6f9a1880275bd0ccd2fc8dcb4ac44db5c
-  data.tar.gz: 7ffebcfeadf51f193c7f2277a0842c2f56e00d9ff95d502915924f2a6d7e10744a0a710d1d2f5b1865182a9de21b2cce30edc3e94c16f49626912b93b1fc7063
+  metadata.gz: 2b3674abf0cae37286a04431f0ceb02a30e282c715e4d6d96e51c0a08d600c94a9fee6c82bf178c0b97ff080ee221b00a18b5409e72003d92c7a5430b34d5733
+  data.tar.gz: 7141f5cc00df42bfaf0e9b035d75f54e0b7c9b14ff71a8c95805242b32835fb410358f7f42ff2161f89896425b62fd840c05dcc2504f555430450517dc61bf9b

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.3.0 - 2026-06-10
+
+- Make the task-runtime API skills-first and intentionally breaking: `max_spend` is the only spend-limit name and output validation is exposed as `output_policy` / `policy_audit`.
+- Store message content as ordered typed parts, with text derived from content and tool calls/results persisted in the transcript instead of metadata.
+- Add `load_skill` for progressively disclosed available skills.
+- Add output-policy revision loops with `output_retries`, including skill/policy rehydration in revision prompts.
+- Add deterministic `input_schema` validation before turns are created.
+- Ensure terminal tools never orphan sibling tool calls; skipped siblings receive cancelled executions and tool-result messages.
+- Add turn claiming, tool-runner heartbeats, persisted budget resume, and sub-agent failure details.
+
 ## 0.2.10 - 2026-06-10
 
 - Add output audits and file-backed output policies for validating final run output.

data/README.md

@@ -331,8 +331,8 @@ end
 
 workflow = TurnKit::Workflow.new(
   name: "memo_writer",
-  output_audit: [no_em_dash, numbered_lists_only],
-  output_audit_mode: :fail
+  output_policy: [no_em_dash, numbered_lists_only],
+  output_policy_mode: :fail
 )
 ```
 
@@ -340,7 +340,7 @@ Run checks directly when you want to test a renderer or policy without calling a
 model:
 
 ```ruby
-audit = TurnKit.audit_output(
+audit = TurnKit.check_output_policy(
   "1. Recommendation\n- unordered item — fix this\n",
   constraints: [no_em_dash, numbered_lists_only]
 )
@@ -350,8 +350,8 @@ puts audit.messages
 ```
 
 Use `output_policy` when a semantic judge is worth the extra model call. The
-policy can be a `.md`, `.markdown`, or `.txt` file path, a `TurnKit::OutputPolicy`,
-or any object that responds to `#call` or `#check`.
+policy can be a `.md`, `.markdown`, or `.txt` file path, a `TurnKit::Skill`, a
+`TurnKit::OutputPolicy`, or any object that responds to `#call` or `#check`.
 
 ```ruby
 workflow = TurnKit::Workflow.new(
@@ -364,8 +364,34 @@ workflow = TurnKit::Workflow.new(
 ```
 
 `output_policy_mode: :report` records violations while allowing the run to
-complete. `:fail` marks the run failed after recording the output and audit.
-Policy model usage and cost are counted on the parent run.
+complete. `:fail` marks the run failed after recording the output and audit;
+`:fail` is the default for contract-driven workflows. Policy model usage and
+cost are counted on the parent run.
+
+Add `output_retries:` to turn policy failures into bounded revision loops instead
+of dead ends:
+
+```ruby
+voice = TurnKit::Skill.from_file("app/ai/skills/memo_voice.md")
+
+workflow = TurnKit::Workflow.new(
+  name: "memo_writer",
+  skills: [voice],
+  output_policy: [voice, no_em_dash],
+  output_retries: 2,
+  input_schema: {
+    "type" => "object",
+    "required" => ["project_id"],
+    "properties" => { "project_id" => { "type" => "string" } }
+  }
+)
+```
+
+`skills:` are always loaded into the prompt. `available_skills:` are listed in
+`<skills_available>` and exposed through the `load_skill` tool, so the model can
+load full instructions on demand. Every advertised tool call receives exactly one
+tool result, including validation errors, budget denials, and calls skipped after
+a terminal tool ends the turn.
 
 ### Prompt Preview
 
@@ -639,8 +665,7 @@ TurnKit.output_policy_model = "gpt-4.1-mini"
 TurnKit.timeout = 300
 ```
 
-`TurnKit.cost_limit` remains supported as the internal/legacy name for
-`max_spend`.
+`max_spend` is the only spend-limit name in the public API.
 
 Set options per agent:
 

data/UPGRADE.md

@@ -1,313 +1,51 @@
 # Upgrade Guide
 
-This guide covers migrating to the workflow-based task-runtime API. The
-recommended migration is about making the three work shapes easier to read:
+## 0.3.0 is a clean break
 
-- conversations for durable multi-turn threads;
-- runs for one non-interactive application task;
-- workflows for reusable task runners with tools, skills, limits, and policy.
+TurnKit 0.3.0 intentionally removes the short-lived legacy names from the 0.2
+series. The gem is pre-1.0 and the durable transcript schema changed, so migrate
+by updating call sites and reinstalling the generated tables for new projects.
 
-## Quick summary
+### Renames
 
-Before changing call sites, bump TurnKit to the latest version and run your
-test suite against the new release.
+- `TurnKit.cost_limit` → `TurnKit.max_spend`
+- `Agent.new(cost_limit:)` → `Agent.new(max_spend:)`
+- `Workflow.new(cost_limit:)` / `workflow.run(cost_limit:)` → `max_spend:`
+- `output_audit:` → `output_policy:`
+- `output_audit_mode:` → `output_policy_mode:`
+- `run.output_audit` → `run.policy_audit`
+- `run.output_audit_clean?` → `run.policy_clean?`
+- `TurnKit.audit_output(...)` → `TurnKit.check_output_policy(...)`
 
-```ruby
-# Gemfile
-gem "turnkit", "~> 0.2.9"
-```
+The audit result class remains `TurnKit::OutputAudit`; only the public option and
+run-accessor names changed.
 
-```sh
-bundle update turnkit
-```
+### Message schema
 
-Use workflows for reusable autonomous task runners.
+`turnkit_messages.text` was removed. Message `content` is now the canonical
+ordered array of parts:
 
-Recommended new forms:
+- `text`
+- `thinking`
+- `tool_call`
+- `tool_result`
+- opaque provider parts
 
-```ruby
-TurnKit.configure do |config|
-  config.model = "gpt-5.2"
-  config.max_spend = 0.25
-end
+`Message#text` is derived from text parts. New Rails installs should regenerate
+the install migration; there is no compatibility shim for older schemas.
 
-workflow = TurnKit::Workflow.new(name: "brief_writer", tools: [WebSearch, SaveBrief])
-run = workflow.run("Create a source-grounded brief.", input: { topic: "Rails 8" })
+### Workflows
 
-puts run.output
-```
+`TurnKit::Workflow` now forwards options directly to `Agent`. Use
+`workflow.options[:name]` or `workflow.agent` for inspection instead of per-option
+workflow attr readers. Workflow `instructions:` compose with the orchestrator
+preamble by default; pass `preamble: false` to opt out.
 
-## Configuration
+### Skills and policy loops
 
-### Model name
-
-Before:
-
-```ruby
-TurnKit.default_model = "gpt-5.2"
-```
-
-After:
-
-```ruby
-TurnKit.model = "gpt-5.2"
-```
-
-`TurnKit.default_model` remains supported. `TurnKit.model` is the shorter public
-alias for app code and initializers.
-
-### Global setup
-
-Before:
-
-```ruby
-TurnKit.default_model = "gpt-5.2"
-TurnKit.cost_limit = 0.25
-TurnKit.max_iterations = 12
-```
-
-After:
-
-```ruby
-TurnKit.configure do |config|
-  config.model = "gpt-5.2"
-  config.max_spend = 0.25
-  config.max_iterations = 12
-end
-```
-
-`TurnKit.configure` simply yields the `TurnKit` module. There is no separate
-configuration object or DSL.
-
-### Spend limit naming
-
-Before:
-
-```ruby
-TurnKit.cost_limit = 0.25
-```
-
-After:
-
-```ruby
-TurnKit.max_spend = 0.25
-```
-
-`cost_limit` remains supported. Prefer `max_spend` in application-facing code
-because it matches how developers think about autonomous runs.
-
-## Running application tasks
-
-### Agent tasks
-
-Before:
-
-```ruby
-run = agent.run(task: "Classify this lead.", input: lead.attributes)
-puts run.output_text
-```
-
-After:
-
-```ruby
-run = agent.run("Classify this lead.", input: lead.attributes)
-puts run.output
-```
-
-The keyword form still works. The positional string is the recommended form for
-the common case. `Agent#run` uses task prompt behavior by default; pass
-`prompt_mode: :full` if you need conversation-style prompt behavior for a run.
-
-### Pending runs
-
-No behavior change.
-
-```ruby
-run = agent.run("Classify later.", async: true)
-request = run.preview
-run.run!
-```
-
-The existing keyword form remains valid:
-
-```ruby
-run = agent.run(task: "Classify later.", async: true)
-```
-
-## Workflows
-
-The preferred name for reusable autonomous task runtimes is now workflow. A
-workflow packages:
-
-- one task-mode orchestrator
-- workflow skills
-- tools
-- guardrails
-- compaction
-- optional persistence/action tools
-
-### Construction
-
-```ruby
-workflow = TurnKit::Workflow.new(
-  name: "sales_enrichment",
-  tools: [AccountLookup, WebSearch, SaveEnrichment],
-  skills: [sales_research_skill],
-  max_spend: 0.25
-)
-```
-
-### Running
-
-```ruby
-run = workflow.run(
-  "Enrich this account for responsible outreach.",
-  input: account.attributes
-)
-```
-
-`task:` remains supported.
-
-## Run inspection
-
-New convenience methods were added to `TurnKit::Run`.
-
-Before:
-
-```ruby
-run.output_text
-run.tool_executions
-run.turn_records.length
-TurnKit.store.load_turn(run.id)["error"]
-```
-
-After:
-
-```ruby
-run.output
-run.tool_calls
-run.steps
-run.error
-```
-
-Old methods remain available. Prefer the shorter methods in application code,
-examples, and docs.
-
-## Save/action tools
-
-Use `terminal!` for tools that complete the run by saving an artifact or taking
-the final action.
-
-Before:
-
-```ruby
-class SaveBrief < TurnKit::Tool
-  def self.ends_turn? = true
-  def self.completion_message(result) = "Saved #{result.fetch("id")}."
-
-  def call(title:, body:, context:)
-    { "id" => Brief.create!(title: title, body: body).id }
-  end
-end
-```
-
-After:
-
-```ruby
-class SaveBrief < TurnKit::Tool
-  terminal! { |result| "Saved #{result.fetch("id")}." }
-
-  def call(title:, body:, context:)
-    { "id" => Brief.create!(title: title, body: body).id }
-  end
-end
-```
-
-The old `ends_turn?` and `completion_message` methods remain supported. Prefer
-`terminal!` for readability.
-
-## Tool instances
-
-If a tool needs constructor arguments, register an instance instead of a class.
-
-Before, this may have failed at runtime:
-
-```ruby
-class WebSearch < TurnKit::Tool
-  def initialize(client:)
-    @client = client
-  end
-end
-
-agent = TurnKit::Agent.new(tools: [WebSearch])
-```
-
-After:
-
-```ruby
-client = SearchClient.new(api_key: ENV.fetch("SEARCH_API_KEY"))
-agent = TurnKit::Agent.new(tools: [WebSearch.new(client: client)])
-```
-
-This is the recommended pattern for API clients, test doubles, and per-tenant
-dependencies.
-
-## Multi-agent workflows
-
-If you previously modeled every role as a separate agent, consider migrating the
-default path to one workflow with a workflow skill.
-
-Before:
-
-```ruby
-researcher = TurnKit::Agent.new(name: "researcher", tools: [WebSearch])
-writer = TurnKit::Agent.new(name: "writer")
-verifier = TurnKit::Agent.new(name: "verifier")
-
-orchestrator = TurnKit::Agent.new(
-  name: "orchestrator",
-  sub_agents: [researcher, writer, verifier]
-)
-```
-
-After:
-
-```ruby
-workflow = TurnKit::Skill.new(
-  key: "source_grounded_brief",
-  name: "Source Grounded Brief",
-  content: <<~TEXT
-    Research first. Build an evidence pack. Draft only from evidence. Verify
-    important claims. Revise unsupported claims before final output.
-  TEXT
-)
-
-source_brief = TurnKit::Workflow.new(
-  name: "source_brief",
-  skills: [workflow],
-  tools: [WebSearch, ReadWebPage, SaveBrief],
-  max_spend: 0.25,
-  max_tool_executions: 20
-)
-```
-
-Keep separate agents when the isolation is worth the extra model calls:
-
-- different models
-- different tool permissions
-- adversarial review
-- parallel specialist research
-- separate durable child conversations
-
-## Suggested migration order
-
-1. Replace `TurnKit.default_model =` with `TurnKit.model =` in app-level config.
-2. Wrap global settings in `TurnKit.configure` if you have more than one.
-3. Use `TurnKit::Workflow.new(name: "...")` for reusable autonomous task runners.
-4. Replace `run(task: "...")` with `run("...")` where it improves readability.
-5. Replace `run.output_text` with `run.output` in application code.
-6. Replace save/action tool overrides with `terminal!` when convenient.
-7. Consider collapsing role-agent workflows into one workflow plus workflow skills if
-   cost or complexity is a concern.
-
-Run your test suite after migrating call sites.
+- `available_skills:` now exposes a real `load_skill` tool.
+- `output_policy:` accepts `TurnKit::Skill` instances.
+- `output_retries:` controls bounded revision loops. The default policy mode is
+  now `:fail`; use `output_policy_mode: :report` if dirty output should complete.
+- `input_schema:` validates application input before any conversation or turn is
+  created.

data/lib/turnkit/adapters/ruby_llm.rb

@@ -182,6 +182,7 @@ module TurnKit
           )
           Result.new(
             text: response_text(response),
+            parts: response_parts(response, tool_calls: tool_calls),
             output_data: response_data(response),
             tool_calls: tool_calls,
             usage: usage,
@@ -189,6 +190,34 @@ module TurnKit
           )
         end
 
+        def response_parts(response, tool_calls:)
+          content = response.respond_to?(:content) ? response.content : response
+          parts = case content
+          when Array
+            content.map { |part| normalize_provider_part(part) }
+          when Hash
+            [ { "type" => "text", "text" => content.to_json } ]
+          else
+            text = content.to_s
+            text.empty? ? [] : [ { "type" => "text", "text" => text } ]
+          end.compact
+          parts + Array(tool_calls).map { |call| { "type" => "tool_call", "id" => call.id, "name" => call.name, "arguments" => call.arguments } }
+        end
+
+        def normalize_provider_part(part)
+          attrs = part.respond_to?(:to_h) ? part.to_h.transform_keys(&:to_s) : nil
+          return { "type" => "text", "text" => part.to_s } unless attrs
+
+          case attrs["type"].to_s
+          when "text", "output_text"
+            { "type" => "text", "text" => attrs["text"] || attrs["content"].to_s }
+          when "thinking", "reasoning"
+            { "type" => "thinking", "text" => attrs["text"] || attrs["content"].to_s, "signature" => attrs["signature"], "redacted" => attrs["redacted"] || false }.compact
+          else
+            { "type" => "provider", "kind" => attrs["type"].to_s, "data" => attrs }
+          end
+        end
+
         def response_text(response)
           content = response.respond_to?(:content) ? response.content : response
           content.is_a?(Hash) || content.is_a?(Array) ? content.to_json : content.to_s

data/lib/turnkit/agent.rb

@@ -3,14 +3,14 @@
 module TurnKit
   class Agent
     attr_reader :name, :description, :model, :instructions, :tools, :skills, :available_skills, :sub_agents
-    attr_reader :client, :store, :max_iterations, :timeout, :cost_limit, :max_depth, :max_tool_executions, :max_tool_executions_by_name
-    attr_reader :prompt_sections, :system_prompt, :prompt_mode, :thinking, :compaction, :output_schema, :on_event
-    attr_reader :output_audit, :output_audit_mode, :output_policy_model
+    attr_reader :client, :store, :max_iterations, :timeout, :max_spend, :max_depth, :max_tool_executions, :max_tool_executions_by_name
+    attr_reader :prompt_sections, :system_prompt, :prompt_mode, :thinking, :compaction, :output_schema, :input_schema, :on_event
+    attr_reader :output_policy, :output_policy_mode, :output_policy_model, :output_retries
 
     def initialize(name:, description: "", model: nil, instructions: "", tools: [], skills: [], available_skills: [], sub_agents: [],
       system_prompt: nil, prompt_sections: nil, prompt_mode: nil, client: nil, store: nil,
-      max_iterations: nil, timeout: nil, cost_limit: nil, max_depth: nil, max_tool_executions: nil, max_tool_executions_by_name: nil, thinking: nil, compaction: nil,
-      output_schema: nil, output_audit: nil, output_audit_mode: nil, output_policy: nil, output_policy_mode: nil, output_policy_model: nil, output_policy_thinking: nil, on_event: nil)
+      max_iterations: nil, timeout: nil, max_spend: nil, max_depth: nil, max_tool_executions: nil, max_tool_executions_by_name: nil, thinking: nil, compaction: nil,
+      output_schema: nil, input_schema: nil, output_policy: nil, output_policy_mode: nil, output_policy_model: nil, output_policy_thinking: nil, output_retries: 0, on_event: nil)
       @name = name.to_s
       @description = description.to_s
       @model = model
@@ -26,16 +26,18 @@ module TurnKit
       @store = store
       @max_iterations = max_iterations
       @timeout = timeout
-      @cost_limit = cost_limit
+      @max_spend = max_spend
       @max_depth = max_depth
       @max_tool_executions = max_tool_executions
       @max_tool_executions_by_name = max_tool_executions_by_name
       @thinking = self.class.normalize_thinking(thinking)
       @compaction = compaction
       @output_schema = output_schema
+      @input_schema = input_schema
       @output_policy_model = output_policy_model
-      @output_audit = normalize_output_policy_options(output_audit: output_audit, output_policy: output_policy, output_policy_model: output_policy_model, output_policy_thinking: output_policy_thinking)
-      @output_audit_mode = normalize_output_policy_mode(output_audit_mode: output_audit_mode, output_policy_mode: output_policy_mode)
+      @output_policy = normalize_output_policy(output_policy, model: output_policy_model, thinking: output_policy_thinking)
+      @output_policy_mode = normalize_output_policy_mode(output_policy_mode)
+      @output_retries = Integer(output_retries || 0)
       @on_event = on_event
       raise ArgumentError, "name is required" if @name.empty?
       validate_tools!
@@ -70,6 +72,7 @@ module TurnKit
     def run(prompt = nil, task: nil, input: nil, async: false, subject: nil, metadata: {}, parent_run: nil, root_turn_id: nil, prompt_mode: :task, **options)
       task = task || prompt
       raise ArgumentError, "task is required" if task.to_s.empty?
+      SchemaCheck.validate!(input, input_schema, error_class: InputError, label: "input") if input_schema
 
       conversation = self.conversation(subject: subject, metadata: metadata)
       message = conversation.say(task_message(task, input), metadata: { "source" => "application", "task" => true })
@@ -99,16 +102,8 @@ module TurnKit
       thinking
     end
 
-    def effective_output_audit
-      Array(output_audit).compact
-    end
-
-    def output_policy
-      output_audit
-    end
-
-    def output_policy_mode
-      output_audit_mode
+    def effective_output_policy
+      Array(output_policy).compact
     end
 
     def effective_client
@@ -120,7 +115,9 @@ module TurnKit
     end
 
     def effective_tools
-      tools + sub_agents.map { |agent| SubAgentTool.for(agent) }
+      configured = tools + sub_agents.map { |agent| SubAgentTool.for(agent) }
+      skills = effective_available_skills
+      skills.empty? ? configured : configured + [ LoadSkillTool.for(skills) ]
     end
 
     def effective_on_event
@@ -161,7 +158,7 @@ module TurnKit
         max_depth: max_depth || TurnKit.max_depth,
         max_tool_executions: max_tool_executions || TurnKit.max_tool_executions,
         max_tool_executions_by_name: max_tool_executions_by_name || TurnKit.max_tool_executions_by_name,
-        cost_limit: cost_limit || TurnKit.cost_limit,
+        max_spend: max_spend || TurnKit.max_spend,
         root_started_at: root_started_at
       )
     end
@@ -188,12 +185,6 @@ module TurnKit
         effective_tools.each(&:validate_definition!)
       end
 
-      def normalize_output_policy_options(output_audit:, output_policy:, output_policy_model:, output_policy_thinking:)
-        raise ArgumentError, "use output_policy: or output_audit:, not both" if output_audit && output_policy
-
-        output_policy.nil? ? output_audit : normalize_output_policy(output_policy, model: output_policy_model, thinking: output_policy_thinking)
-      end
-
       def normalize_output_policy(value, model: nil, thinking: nil)
         case value
         when nil
@@ -204,10 +195,12 @@ module TurnKit
           output_policy_from_path(value, model: model, thinking: thinking)
         when Pathname
           output_policy_from_path(value.to_s, model: model, thinking: thinking)
+        when Skill
+          OutputPolicy.from_skill(value, model: model || TurnKit.output_policy_model, thinking: thinking || TurnKit.output_policy_thinking)
         else
           return value if value.respond_to?(:call) || value.respond_to?(:check)
 
-          raise ArgumentError, "output_policy must be a policy file path, a #call/#check object, or an array of those"
+          raise ArgumentError, "output_policy must be a policy file path, a skill, a #call/#check object, or an array of those"
         end
       end
 
@@ -223,12 +216,8 @@ module TurnKit
         )
       end
 
-      def normalize_output_policy_mode(output_audit_mode:, output_policy_mode:)
-        if output_audit_mode && output_policy_mode && output_audit_mode.to_sym != output_policy_mode.to_sym
-          raise ArgumentError, "use output_policy_mode: or output_audit_mode:, not both"
-        end
-
-        value = output_policy_mode || output_audit_mode || :report
+      def normalize_output_policy_mode(value)
+        value ||= :fail
         mode = value.to_sym
         raise ArgumentError, "unknown output_policy_mode: #{value}" unless %i[report fail].include?(mode)
 

data/lib/turnkit/budget.rb

@@ -2,16 +2,24 @@
 
 module TurnKit
   class Budget
-    attr_reader :root_started_at, :max_iterations, :timeout, :max_depth, :max_tool_executions, :max_tool_executions_by_name, :cost_limit
+    attr_reader :root_started_at, :max_iterations, :timeout, :max_depth, :max_tool_executions, :max_tool_executions_by_name, :max_spend
 
-    def initialize(max_iterations:, timeout:, max_depth:, max_tool_executions:, max_tool_executions_by_name: {}, cost_limit: nil, root_started_at: Clock.now)
+    def self.resume(store:, root_turn_id:, limits: {})
+      turns = store.list_turns(root_turn_id: root_turn_id)
+      root = turns.find { |turn| turn.fetch("id") == root_turn_id } || turns.first || {}
+      budget = new(**limits.merge(root_started_at: root["started_at"] || Clock.now))
+      budget.seed!(turns: turns, tool_executions: turns.flat_map { |turn| store.list_tool_executions(turn_id: turn.fetch("id")) })
+      budget
+    end
+
+    def initialize(max_iterations:, timeout:, max_depth:, max_tool_executions:, max_tool_executions_by_name: {}, max_spend: nil, root_started_at: Clock.now)
       @root_started_at = root_started_at
       @max_iterations = max_iterations
       @timeout = timeout
       @max_depth = max_depth
       @max_tool_executions = max_tool_executions
       @max_tool_executions_by_name = normalize_tool_limits(max_tool_executions_by_name)
-      @cost_limit = cost_limit
+      @max_spend = max_spend
       @iterations = 0
       @tool_executions = 0
       @tool_executions_by_name = Hash.new(0)
@@ -19,6 +27,17 @@ module TurnKit
       @mutex = Mutex.new
     end
 
+    def seed!(turns:, tool_executions:)
+      @mutex.synchronize do
+        @iterations = Array(turns).sum { |turn| (turn["options"] || {})["iterations"].to_i }
+        completed = Array(tool_executions).select { |execution| %w[completed failed].include?(execution["status"]) && !execution.dig("error", "details", "budget_denied") }
+        @tool_executions = completed.length
+        completed.each { |execution| @tool_executions_by_name[execution.fetch("tool_name").to_s] += 1 }
+        @cost = Array(turns).sum { |turn| turn["cost"].to_f }
+      end
+      self
+    end
+
     def count_iteration!
       @mutex.synchronize do
         raise BudgetError, "maximum iterations reached" if max_iterations && @iterations >= max_iterations
@@ -44,11 +63,11 @@ module TurnKit
     end
 
     def add_cost!(cost)
-      return unless cost && cost_limit
+      return unless cost && max_spend
 
       @mutex.synchronize do
         @cost += cost.to_f
-        raise BudgetError, "cost limit reached" if @cost > cost_limit
+        raise BudgetError, "cost limit reached" if @cost > max_spend
       end
     end