turnkit 0.7.1 → 0.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 170286a1c5a1975fe34234a667c946c465cb6512509be4bf06d397f48b2f9f2e
-  data.tar.gz: 8798216dcaece0679c5f8365ee5a2af900b9660694cb3a640c1924f99b814c5d
+  metadata.gz: fb1f58cfea02169c68e433d8a8b84dc5eb2a8a54f18ea9e89853e4ad85445ccd
+  data.tar.gz: '085c56655a5e11670528b157926a6003a04a074944adaf7cf61730cc18c5d6a3'
 SHA512:
-  metadata.gz: 2e0286f571241210786433490a66cbf54d7b2453e1202d60ada2a45ae7fa6c1c370857cf6ad96348ab1cb1e4d16bdbdf0b8a26ccc59cb7a712718f0e9e309ba8
-  data.tar.gz: 85dcbfe855bc6937f495eddbc7a20bd32ba994035b024b8958b08cf9ce69c1ac5f98171722373462c034a8426f658788fd13c8ee49cb9d6b7954369c38a749f5
+  metadata.gz: 38ef2c605e8ee0d5a15417db75a6efce91b045103f68f86a241f7db788806b63ab6dbdd16cc40b1bee24b54ed93f6b83fb9331e13dbf6d06900bc79f4e7305d8
+  data.tar.gz: a9a752449f11422b599b9eaba4598441a295366fc4ab1dddccb136689d9279c2e8b426de9d1f2f8b45fe74011209bd22942e388033892547b5f8355a65d8e56c

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.7.2 - 2026-09-10
+
+- Add explicit `Tool.budget_completion!` for replay-safe local terminal saves
+  from an already-billed response that reaches the spend limit. Persist the
+  exact eligible call ID with the response; skip other batch calls and preserve
+  ordinary authorization, validation, receipts, fencing and recovery. Ambiguous
+  or failed saves fail without another model request.
+- Treat exact spend exhaustion as a bound and recheck persisted spend before
+  model, media and ordinary tool dispatch. Terminal status alone does not permit
+  over-budget execution; the opt-in does not waive other runtime limits.
+
 ## 0.7.1 - 2026-09-10
 
 - Preserve OpenAI prompt prefixes with durable, append-only dynamic context

data/README.md

@@ -323,6 +323,50 @@ class SaveBrief < TurnKit::Tool
 end
 ```
 
+### Saving an already-billed final response at the spend limit
+
+By default, reaching `max_spend` stops the turn before further work. A model
+response can itself reach or exceed that limit: its usage and proposed tool
+calls are persisted, but an ordinary terminal tool is not allowed to run.
+
+For a **local, idempotent final save only**, explicitly opt in on the tool:
+
+```ruby
+class SavePacket < TurnKit::Tool
+  terminal! { |result| "Saved #{result.fetch('id')}." }
+  recovery :replay_safe
+  budget_completion!
+
+  # Define parameters and call normally. Validate the complete packet before
+  # saving; persist context.idempotency_key with the save in one transaction.
+end
+```
+
+`budget_completion!` requires both terminal behavior and `recovery :replay_safe`.
+It is an application promise that the tool only validates/saves already acquired
+output locally: no model calls, acquisition, or child launches. Terminal status
+alone never grants this exception, and the marker is not inherited implicitly.
+
+When the billed response reaches the spend limit, TurnKit atomically records the
+sole eligible call ID with that response. The normal tool runner executes only
+that call; other calls in the batch get skipped receipts and paired tool results,
+even if they precede the save. Zero or multiple eligible calls fail without tool
+dispatch. No new model request is allowed in the exhausted turn, including
+compaction, model-backed output audits, image generation, or media analysis.
+
+Authorization, argument validation, claim fencing, cancellation, timeout/depth,
+and global/per-tool execution limits still apply. Invalid saves must raise
+`ToolValidationError`/`ToolError`; an ordinary error-shaped hash is still tool
+result data. Failed receipts are never replayed or repaired with another model
+call. Failed local output audits also terminate rather than request revision;
+model-backed audits cannot run at exhaustion. Use local validation for this path.
+
+Worker recovery reuses the persisted call/execution and its idempotency key;
+completed receipts are not re-executed. The application must make the save and
+its receipt atomic. An already-started external effect cannot be recalled by
+cancellation, so this marker must not be applied to acquisition tools. No schema
+migration is needed; upgrade workers together before enabling the opt-in.
+
 ### Output audits and policies
 
 Use output audits for deterministic checks that should not depend on another
@@ -1058,7 +1102,9 @@ TurnKit.timeout = 300
 ```
 
 `max_spend` is the only spend-limit name in the public API.
-
+Spend equal to the limit is exhausted, not just spend above it. Dispatch checks
+use persisted aggregate spend, including after recovery and before internal
+model/media calls. Committed response cost is retained even when the turn fails.
 
 Customize cost rates with USD-per-million-token component keys:
 

data/lib/turnkit/budget.rb

@@ -67,14 +67,18 @@ module TurnKit
 
       @mutex.synchronize do
         @cost += cost.to_f
-        raise BudgetError, "cost limit reached" if @cost > max_spend
+        raise BudgetError, "cost limit reached" if spend_exhausted?
       end
     end
 
-    def check!(depth:)
+    def spend_exhausted?
+      max_spend && @cost >= max_spend
+    end
+
+    def check!(depth:, allow_exhausted_spend: false)
       raise BudgetError, "maximum sub-agent depth reached" if max_depth && depth > max_depth
       raise BudgetError, "turn timed out" if timeout && Clock.now >= root_started_at + timeout
-      raise BudgetError, "cost limit reached" if max_spend && @cost > max_spend
+      raise BudgetError, "cost limit reached" if spend_exhausted? && !allow_exhausted_spend
     end
 
     private

data/lib/turnkit/tool.rb

@@ -54,6 +54,16 @@ module TurnKit
         @ends_turn || false
       end
 
+      # Explicit application promise: this terminal tool only validates/saves
+      # already acquired output locally, without model calls or acquisition.
+      def budget_completion!
+        @budget_completion = true
+      end
+
+      def budget_completion?
+        @budget_completion || false
+      end
+
       # :unknown is the safe default for external effects. :replay_safe means
       # the application/tool honors ToolContext#idempotency_key on retries.
       def recovery(value = nil)
@@ -79,6 +89,9 @@ module TurnKit
       def validate_definition!
         raise ArgumentError, "tool name is required" if tool_name.empty?
         raise ArgumentError, "invalid tool name: #{tool_name}" unless NAME_PATTERN.match?(tool_name)
+        if budget_completion? && (!ends_turn? || recovery != :replay_safe)
+          raise ArgumentError, "budget_completion! requires a terminal tool with recovery :replay_safe"
+        end
 
         parameters.each do |param|
           type = param.fetch(:type)
@@ -188,6 +201,7 @@ module TurnKit
     def input_schema = self.class.input_schema
     def validate_definition! = self.class.validate_definition!
     def ends_turn? = self.class.ends_turn?
+    def budget_completion? = self.class.budget_completion?
     def completion_message(result) = self.class.completion_message(result)
   end
 end

data/lib/turnkit/tool_runner.rb

@@ -7,6 +7,20 @@ module TurnKit
     end
 
     def dispatch(tool_calls)
+      completion_id = turn.budget_completion_call_id
+      if completion_id
+        control = turn.control_boundary!
+        return control if control
+        selected = tool_calls.select { |call| call.id == completion_id }
+        tool = tool_for(selected.first&.name)
+        unless selected.length == 1 && tool&.budget_completion? && tool.ends_turn?
+          raise BudgetError, "budget completion is no longer available"
+        end
+        # Preserve pairing and receipts, regardless of where acquisition calls
+        # appear in the response. Only the durably selected call may execute.
+        skip_remaining(tool_calls - selected, terminal: selected.first)
+        tool_calls = selected
+      end
       waiting = false
       tool_calls.each_with_index do |tool_call, index|
         control = turn.control_boundary!
@@ -24,6 +38,7 @@ module TurnKit
           skip_remaining(tool_calls.drop(index + 1), terminal: tool_call)
           return execution
         end
+        raise BudgetError, "budget completion failed" if completion_id
       end
       waiting ? :waiting : nil
     end
@@ -82,6 +97,7 @@ module TurnKit
           # external-effect boundary. Calls already sent cannot be recalled.
           control = turn.control_boundary!
           return control if control
+          turn.execution_budget.check!(depth: turn.depth, allow_exhausted_spend: turn.budget_completion_call_id == tool_call.id)
           if turn.background? && subagent?(tool)
             return delegate(tool, tool_call, context)
           end
@@ -164,7 +180,8 @@ module TurnKit
         calls.each do |call|
           turn.store.atomic do
             next if turn.store.list_tool_executions(turn_id: turn.id).any? { |row| row["tool_call_id"] == call.id }
-            payload = { "skipped" => true, "message" => "not executed: turn ended by #{terminal.name}" }
+            reason = turn.budget_completion_call_id ? "spend limit reached" : "turn ended by #{terminal.name}"
+            payload = { "skipped" => true, "message" => "not executed: #{reason}" }
             execution = ToolExecution.new(create_execution(call))
             attrs = turn.store.claim_tool_execution(execution.id, from: execution.status, to: "cancelled", result: payload, completed_at: Clock.now)
             append_result_once(ToolExecution.new(attrs), call, payload)

data/lib/turnkit/turn.rb

@@ -151,6 +151,10 @@ module TurnKit
       options.dig("state", "policy_audit") || options["policy_audit"]
     end
 
+    def budget_completion_call_id
+      @record.dig("options", "state", "budget_completion_call_id")
+    end
+
     # Reads iterations from options["state"], falling back to the legacy
     # top-level key for turns persisted before the state split.
     def self.iterations_for(record)
@@ -188,6 +192,7 @@ module TurnKit
     end
 
     def internal_model_call(model:, messages:, instructions:, tools: [], thinking: nil, output_schema: nil, metadata: {}, purpose:, client: nil)
+      execution_budget.check!(depth: depth)
       request = ModelRequest.new(
         model: model,
         messages: messages,
@@ -303,8 +308,8 @@ module TurnKit
             break
           end
           @budget = execution_budget
-          budget.check!(depth: depth)
           state = @record.dig("options", "state") || {}
+          budget.check!(depth: depth, allow_exhausted_spend: budget_completion_call_id && %w[tools output].include?(state["phase"]))
           case state["phase"] || "model"
           when "model"
             count_iteration!
@@ -320,10 +325,11 @@ module TurnKit
               add_usage!(result.usage, cost: cost)
               persist_assistant_message(result)
               update_state!("phase" => result.tool_calls? ? "tools" : "output", "parts" => result.parts,
-                "candidate" => result.text, "output_data" => result.output_data, "terminal_tool_name" => nil)
+                "candidate" => result.text, "output_data" => result.output_data, "terminal_tool_name" => nil,
+                "budget_completion_call_id" => select_budget_completion(result))
             end
             emit_model_completed("model.completed", result, cost, model: model)
-            budget.add_cost!(cost.total)
+            budget.add_cost!(cost.total) unless budget_completion_call_id
           when "tools"
             runner = ToolRunner.new(self)
             terminal = runner.dispatch(Result.new(parts: state.fetch("parts")).tool_calls)
@@ -344,6 +350,9 @@ module TurnKit
           when "output"
             candidate = state.fetch("candidate")
             audit = check_policy(candidate, output_data: state["output_data"])
+            if budget_completion_call_id && audit && !audit.clean?
+              raise BudgetError, "budget completion rejected: #{audit.messages.join('; ')}"
+            end
             revisions_used = state["revisions_used"].to_i
             if should_revise?(audit, revisions_used)
               store.atomic do
@@ -418,6 +427,7 @@ module TurnKit
 
       # Clients implement the TurnKit::Client keyword contract. See client.rb.
       def call_client(request, client: agent.effective_client)
+        execution_budget.check!(depth: depth)
         client.chat(
           model: request.model,
           messages: request.messages,
@@ -432,13 +442,26 @@ module TurnKit
       end
 
       def call_image_client(client, request)
+        execution_budget.check!(depth: depth)
         with_heartbeat { client.paint(**request, on_event: ->(event) { emit_event(event) }) }
       end
 
       def call_media_client(client, request)
+        execution_budget.check!(depth: depth)
         with_heartbeat { client.view_media(**request, on_event: ->(event) { emit_event(event) }) }
       end
 
+      def select_budget_completion(result)
+        return unless execution_budget.spend_exhausted?
+
+        tools = agent.effective_tools(turn: self)
+        candidates = result.tool_calls.select do |call|
+          tool = tools.find { |candidate| candidate.tool_name == call.name }
+          tool&.budget_completion? && tool.ends_turn?
+        end
+        candidates.first.id if candidates.length == 1
+      end
+
       def llm_messages(include_dynamic_context: false)
         messages = TurnKit::Compaction.project(conversation.messages_for_turn(self))
         # Delivery time is not application time. A next-turn message can arrive

data/lib/turnkit/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: turnkit
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.7.2
 platform: ruby
 authors:
 - Sam Couch