turnkit 0.4.1 → 0.5.0

data/lib/turnkit/output_policy.rb

@@ -75,7 +75,7 @@ module TurnKit
       else
         audit_client = client || TurnKit.client
         audit_client.validate!(model: model_name)
-        chat(audit_client, model: model_name, messages: audit_messages(output), tools: [], instructions: audit_instructions, thinking: thinking, output_schema: DEFAULT_SCHEMA, metadata: { output_policy: name })
+        audit_client.chat(model: model_name, messages: audit_messages(output), tools: [], instructions: audit_instructions, thinking: thinking, output_schema: DEFAULT_SCHEMA, metadata: { output_policy: name })
       end
       data = result.output_data || parse_json(result.text)
       return if data.fetch("approved", false)
@@ -111,20 +111,6 @@ module TurnKit
         [ { role: :user, content: JSON.generate(output: output) } ]
       end
 
-      def chat(client, **kwargs)
-        accepted = chat_keyword_names(client)
-        kwargs = kwargs.slice(*accepted) unless accepted.include?(:keyrest)
-        client.chat(**kwargs)
-      end
-
-      def chat_keyword_names(client)
-        client.method(:chat).parameters.filter_map do |kind, name|
-          return [ :keyrest ] if kind == :keyrest
-
-          name if %i[key keyreq].include?(kind)
-        end
-      end
-
       def parse_json(value)
         JSON.parse(extract_json(value.to_s))
       rescue JSON::ParserError

data/lib/turnkit/reconciliation.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module TurnKit
+  # Reconciles turns abandoned by a dead worker: atomically marks them stale,
+  # marks their unfinished tool executions interrupted, and appends synthetic
+  # error tool results so the persisted transcript stays structurally complete
+  # for continuation. TurnKit never reruns an interrupted tool; the synthetic
+  # result tells the continued model the outcome is unknown.
+  module Reconciliation
+    INTERRUPTED_MESSAGE = "Tool execution was interrupted before a result was recorded. " \
+      "It is unknown whether the operation ran; do not assume it did or did not."
+
+    module_function
+
+    def reconcile!(before:)
+      TurnKit.store.reconcile_stale_turns(before: before).each do |turn|
+        emit("turn.stale", turn)
+        executions = interrupt_tool_executions(turn)
+        repair_transcript(turn, executions)
+      end
+    end
+
+    def interrupt_tool_executions(turn)
+      store = TurnKit.store
+      store.list_tool_executions(turn_id: turn.fetch("id")).map do |execution|
+        next execution unless %w[pending running].include?(execution.fetch("status"))
+
+        interrupted = store.claim_tool_execution(
+          execution.fetch("id"),
+          from: execution.fetch("status"),
+          to: "interrupted",
+          error: { "message" => "interrupted: worker terminated while the tool was executing" },
+          completed_at: Clock.now
+        )
+        next execution unless interrupted
+
+        emit("tool_call.interrupted", turn, id: interrupted.fetch("tool_call_id"), name: interrupted.fetch("tool_name"), tool_execution_id: interrupted.fetch("id"))
+        interrupted
+      end
+    end
+
+    def repair_transcript(turn, executions)
+      store = TurnKit.store
+      messages = store.list_messages(turn.fetch("conversation_id"))
+      resolved = messages
+        .select { |message| message["kind"] == "tool_result" }
+        .flat_map { |message| message["content"].map { |part| part["tool_call_id"] } }
+
+      messages
+        .select { |message| message["turn_id"] == turn.fetch("id") && message["kind"] == "tool_call" }
+        .flat_map { |message| message["content"].select { |part| part["type"] == "tool_call" } }
+        .reject { |part| resolved.include?(part["id"]) }
+        .each do |part|
+          execution = executions.find { |candidate| candidate["tool_call_id"] == part["id"] }
+          message = store.append_message(
+            "conversation_id" => turn.fetch("conversation_id"),
+            "turn_id" => turn.fetch("id"),
+            "role" => "tool",
+            "kind" => "tool_result",
+            "content" => [ { "type" => "tool_result", "tool_call_id" => part["id"], "text" => { "error" => true, "message" => INTERRUPTED_MESSAGE }.to_json, "error" => true } ],
+            "tool_execution_id" => execution&.fetch("id"),
+            "metadata" => { "tool_name" => part["name"], "interrupted" => true }
+          )
+          emit("message.created", turn, message_id: message.fetch("id"), role: "tool", kind: "tool_result")
+        end
+    end
+
+    def emit(type, turn, payload = {})
+      TurnKit.on_event&.call(Event.new(type: type, turn_id: turn.fetch("id"), conversation_id: turn.fetch("conversation_id"), payload: payload))
+    end
+  end
+end

data/lib/turnkit/record.rb

@@ -3,7 +3,7 @@
 module TurnKit
   module Record
     TURN_STATUSES = %w[pending running completed failed cancelled stale].freeze
-    TOOL_EXECUTION_STATUSES = %w[pending running completed failed cancelled].freeze
+    TOOL_EXECUTION_STATUSES = %w[pending running completed failed cancelled interrupted].freeze
 
     TURN_UPDATE_KEYS = %w[status options usage cost error output_text output_data started_at heartbeat_at completed_at].freeze
     TOOL_EXECUTION_UPDATE_KEYS = %w[status result error started_at completed_at].freeze

data/lib/turnkit/run.rb

@@ -11,16 +11,12 @@ module TurnKit
     def id = turn.id
     def root_turn_id = turn.root_turn_id
     def status = turn.status
-    def output = output_text
     def output_text = turn.output_text
     def output_data = turn.output_data
     def policy_audit = turn.policy_audit
     def policy_clean? = policy_audit.nil? || policy_audit.fetch("clean", false)
     def usage = Usage.from_records(turn_records)
     def cost = Cost.from_records(turn_records)
-    def steps = turn_records.length
-    def tool_calls = tool_executions
-    def persisted? = true
 
     def error
       turn.store.load_turn(id)["error"]

data/lib/turnkit/store.rb

@@ -12,19 +12,28 @@ module TurnKit
     def create_turn(_attributes) = raise(NotImplementedError)
     def load_turn(_id) = raise(NotImplementedError)
     def update_turn(_id, _attributes) = raise(NotImplementedError)
-    def claim_turn(id, from: "pending", to: "running", **attributes)
-      turn = load_turn(id)
-      return nil unless turn["status"] == from
-
-      update_turn(id, attributes.merge(status: to))
-    end
+    # claim_turn is the concurrency-safety point: it must atomically
+    # compare-and-set status from `from` to `to` (returning nil when the turn
+    # is not in `from`), so concurrent workers cannot both claim a turn.
+    def claim_turn(_id, from: "pending", to: "running", **_attributes) = 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)
-    def update_tool_execution(_id, _attributes) = raise(NotImplementedError)
+    # claim_tool_execution mirrors claim_turn: an atomic compare-and-set on
+    # status, so a tool result recorded by a live worker and a reconciler
+    # marking the execution interrupted cannot overwrite each other.
+    def claim_tool_execution(_id, from: "running", to: "completed", **_attributes) = raise(NotImplementedError)
     def list_tool_executions(turn_id:) = raise(NotImplementedError)
 
-    def find_stale_turns(before:) = []
+    # reconcile_stale_turns is the other concurrency-safety point: it must
+    # atomically transition each pending/running turn whose stale anchor
+    # (heartbeat_at, else started_at, else created_at) is older than `before`
+    # to `stale`, rechecking both predicates at write time so a concurrently
+    # claimed, heartbeated, or completed turn is never overwritten. Returns
+    # the reconciled turn records. Descendant turns of a dead process stop
+    # heartbeating too and are reconciled by the same predicate, so no
+    # explicit subtree cascade is needed.
+    def reconcile_stale_turns(before:) = []
   end
 end

data/lib/turnkit/sub_agent_tool.rb

@@ -2,8 +2,7 @@
 
 module TurnKit
   class SubAgentTool < Tool
-    parameter :task, :string, required: true, description: "The task for the sub-agent to complete."
-    parameter :context, :string, required: false, description: "Relevant context for the sub-agent."
+    parameter :task, :string, required: true, description: "The complete task for the sub-agent, including all relevant context."
 
     def self.for(agent)
       Class.new(self) do
@@ -18,25 +17,21 @@ module TurnKit
       end
     end
 
-    def call(task:, context: nil, turnkit_context:)
+    def call(task:, context:)
       sub_agent = self.class.agent
-      parent_turn = turnkit_context.turn
-      prompt = [ task, context ].compact.join("\n\n")
-      conversation = sub_agent.conversation(metadata: {
+      parent_turn = context.turn
+      lineage = {
         "parent_conversation_id" => parent_turn.conversation.id,
         "parent_turn_id" => parent_turn.id,
-        "parent_tool_execution_id" => turnkit_context.execution.id
-      })
-      trigger = conversation.say(prompt, metadata: {
-        "parent_conversation_id" => parent_turn.conversation.id,
-        "parent_turn_id" => parent_turn.id,
-        "parent_tool_execution_id" => turnkit_context.execution.id
-      })
+        "parent_tool_execution_id" => context.execution.id
+      }
+      conversation = sub_agent.conversation(metadata: lineage)
+      trigger = conversation.say(task, metadata: lineage)
       child = conversation.run!(
         trigger_message_id: trigger.id,
         budget: parent_turn.budget,
         parent_turn: parent_turn,
-        parent_tool_execution: turnkit_context.execution,
+        parent_tool_execution: context.execution,
         depth: parent_turn.depth + 1,
         model: sub_agent.effective_model,
         agent: sub_agent,

data/lib/turnkit/system_prompt.rb

@@ -3,7 +3,6 @@
 module TurnKit
   class SystemPrompt
     DEFAULT_SECTIONS = %i[agent instructions behavior loaded_skills available_skills tools subject live_context environment].freeze
-    CACHE_BOUNDARY = "<!-- TURNKIT_DYNAMIC_PROMPT_BOUNDARY -->"
     NONE_PROMPT = "You are an assistant running inside TurnKit."
     PROMPT_MODES = %i[full minimal task none].freeze
     MODE_SECTIONS = {
@@ -13,7 +12,6 @@ module TurnKit
       none: []
     }.freeze
     DYNAMIC_SECTIONS = %i[subject live_context environment].freeze
-    OVERRIDABLE_SECTIONS = %i[behavior tools].freeze
 
     SECTION_METHODS = {
       agent: :agent_section,
@@ -92,44 +90,28 @@ module TurnKit
       raise ArgumentError, "unknown prompt mode: #{@mode}" unless PROMPT_MODES.include?(@mode)
 
       @sections = Array(sections || prompt_sections_for_mode)
-      @prompt_contribution = nil
     end
 
-    def to_s
-      return NONE_PROMPT if mode == :none
-
-      values = []
-      contribution = prompt_contribution
-      values << contribution.stable_prefix unless contribution.stable_prefix.empty?
-
-      boundary_inserted = false
-      sections.each do |section|
-        rendered = render(section)
-        next if rendered.nil? || rendered.strip.empty?
-
-        if dynamic_section?(section) && !boundary_inserted
-          values << CACHE_BOUNDARY
-          boundary_inserted = true
-        end
-
-        values << rendered
-      end
+    # The prompt splits into a stable part (identical across turns of the same
+    # agent, safe to cache) and a dynamic part (subject, live context,
+    # environment) recomputed each turn. Adapters that support prompt caching
+    # receive both via ModelRequest#instructions and #dynamic_instructions.
+    def stable
+      parts.fetch(0).join("\n\n")
+    end
 
-      unless contribution.dynamic_suffix.empty?
-        values << CACHE_BOUNDARY unless boundary_inserted
-        values << contribution.dynamic_suffix
-      end
+    def dynamic
+      parts.fetch(1).join("\n\n")
+    end
 
-      values.compact.reject { |value| value.strip.empty? }.join("\n\n")
+    def to_s
+      [ stable, dynamic ].reject(&:empty?).join("\n\n")
     end
 
     def render(section)
       method = SECTION_METHODS[section.to_sym]
       raise ArgumentError, "unknown prompt section: #{section}" unless method
 
-      override = section_override(section)
-      return tagged(section, override) if override
-
       public_send(method)
     end
 
@@ -292,11 +274,9 @@ module TurnKit
 
     def report
       text = to_s
-      stable, dynamic = self.class.split_cache_boundary(text)
       {
         "chars" => text.length,
         "hash" => Digest::SHA256.hexdigest(text),
-        "has_cache_boundary" => text.include?(CACHE_BOUNDARY),
         "stable_chars" => stable.length,
         "dynamic_chars" => dynamic.length,
         "sections" => sections.map(&:to_s),
@@ -304,12 +284,27 @@ module TurnKit
       }
     end
 
-    def self.split_cache_boundary(text)
-      stable, dynamic = text.to_s.split(CACHE_BOUNDARY, 2)
-      [ stable.to_s, dynamic.to_s ]
-    end
-
     private
+      def parts
+        @parts ||= build_parts
+      end
+
+      def build_parts
+        return [ [ NONE_PROMPT ], [] ] if mode == :none
+
+        stable_parts = []
+        dynamic_parts = []
+        target = stable_parts
+        sections.each do |section|
+          rendered = render(section)
+          next if rendered.nil? || rendered.strip.empty?
+
+          target = dynamic_parts if dynamic_section?(section)
+          target << rendered
+        end
+        [ stable_parts, dynamic_parts ]
+      end
+
       def tagged(name, content)
         "<#{name}>\n#{content}\n</#{name}>"
       end
@@ -383,64 +378,5 @@ module TurnKit
         end
       end
 
-      def prompt_contribution
-        @prompt_contribution ||= merge_prompt_contributions(resolve_prompt_contributions)
-      end
-
-      def resolve_prompt_contributions
-        contributors = Array(TurnKit.system_prompt_contributors)
-        contributors += matching_model_prompt_contributors
-        contributors.filter_map do |contributor|
-          value = contributor.respond_to?(:call) ? contributor.call(prompt_build_context) : contributor
-          normalize_prompt_contribution(value)
-        end
-      end
-
-      def matching_model_prompt_contributors
-        model_name = (turn.model || agent.effective_model).to_s
-        TurnKit.model_prompt_contributors.flat_map do |matcher, contributor|
-          matches = case matcher
-          when Regexp
-            matcher.match?(model_name)
-          else
-            matcher.to_s == model_name
-          end
-          matches ? Array(contributor) : []
-        end
-      end
-
-      def normalize_prompt_contribution(value)
-        case value
-        when nil, false
-          nil
-        when PromptContribution
-          value
-        when Hash
-          PromptContribution.new(
-            stable_prefix: value[:stable_prefix] || value["stable_prefix"],
-            dynamic_suffix: value[:dynamic_suffix] || value["dynamic_suffix"],
-            section_overrides: value[:section_overrides] || value["section_overrides"]
-          )
-        else
-          PromptContribution.new(stable_prefix: value.to_s)
-        end
-      end
-
-      def merge_prompt_contributions(contributions)
-        stable_prefix = contributions.map(&:stable_prefix).reject(&:empty?).join("\n\n")
-        dynamic_suffix = contributions.map(&:dynamic_suffix).reject(&:empty?).join("\n\n")
-        section_overrides = contributions.each_with_object({}) do |contribution, overrides|
-          overrides.merge!(contribution.section_overrides)
-        end
-        PromptContribution.new(stable_prefix: stable_prefix, dynamic_suffix: dynamic_suffix, section_overrides: section_overrides)
-      end
-
-      def section_override(section)
-        key = section.to_sym
-        return nil unless OVERRIDABLE_SECTIONS.include?(key)
-
-        value = prompt_contribution.section_overrides[key]
-        value.to_s unless value.nil?
-      end
   end
 end

data/lib/turnkit/tool.rb

@@ -25,6 +25,7 @@ module TurnKit
         name = name.to_s
         raise ArgumentError, "unknown parameter type: #{type}" unless TYPES.include?(type)
         raise ArgumentError, "invalid parameter name: #{name}" unless NAME_PATTERN.match?(name)
+        raise ArgumentError, "context is a reserved parameter name" if name == "context"
         raise ArgumentError, "duplicate parameter: #{name}" if parameters.any? { |param| param.fetch(:name) == name }
         raise ArgumentError, "enum values are required for enum parameter: #{name}" if type == :enum && Array(enum).empty?
 
@@ -113,23 +114,15 @@ module TurnKit
       end
 
       def call(arguments = {}, context:)
-        instance = begin
-          new
-        rescue ArgumentError => error
-          raise if error.message !~ /wrong number of arguments|missing keyword/
+        required = instance_method(:initialize).parameters.any? { |kind, _| %i[req keyreq].include?(kind) }
+        raise ToolError, "#{tool_name} requires constructor arguments; register an instance instead" if required
 
-          raise ToolError, "#{tool_name} requires constructor arguments; register an instance instead"
-        end
-        invoke(instance, arguments, context: context)
+        invoke(new, arguments, context: context)
       end
 
       def invoke(instance, arguments = {}, context:)
         keyword_arguments = symbolize(validate_arguments(arguments))
-        if accepts_turnkit_context?(instance)
-          instance.call(**keyword_arguments, turnkit_context: context)
-        else
-          instance.call(**keyword_arguments, context: context)
-        end
+        instance.call(**keyword_arguments, context: context)
       end
 
       private
@@ -172,10 +165,6 @@ module TurnKit
           SchemaCheck.validate!(value, schema_for(param), error_class: ToolValidationError, label: param.fetch(:name))
         end
 
-        def accepts_turnkit_context?(instance)
-          instance.method(:call).parameters.any? { |kind, name| %i[key keyreq].include?(kind) && name == :turnkit_context }
-        end
-
         def symbolize(hash)
           hash.transform_keys(&:to_sym)
         end

data/lib/turnkit/tool_runner.rb

@@ -71,7 +71,9 @@ module TurnKit
 
       def finish_success(execution, tool_call, payload)
         json = payload.to_json
-        attrs = turn.store.update_tool_execution(execution.id, "status" => "completed", "result" => payload, "completed_at" => Clock.now)
+        attrs = turn.store.claim_tool_execution(execution.id, from: "running", to: "completed", result: payload, completed_at: Clock.now)
+        return superseded_execution(execution) unless attrs
+
         append_result(execution, tool_call, payload, json: json, error: false)
         heartbeat!
         turn.emit("tool_call.completed", id: tool_call.id, name: tool_call.name, result_chars: json.length)
@@ -81,13 +83,21 @@ module TurnKit
       def finish_error(execution, tool_call, message, details: nil)
         error = { "message" => message.to_s, "details" => details }.compact
         json = error.to_json
-        attrs = turn.store.update_tool_execution(execution.id, "status" => "failed", "error" => error, "completed_at" => Clock.now)
+        attrs = turn.store.claim_tool_execution(execution.id, from: "running", to: "failed", error: error, completed_at: Clock.now)
+        return superseded_execution(execution) unless attrs
+
         append_result(execution, tool_call, error, json: json, error: true)
         heartbeat!
         turn.emit("tool_call.failed", id: tool_call.id, name: tool_call.name, error: error, result_chars: json.length)
         ToolExecution.new(attrs)
       end
 
+      # The execution was reconciled (interrupted) while the tool ran; a
+      # synthetic result message already exists, so the late result is dropped.
+      def superseded_execution(execution)
+        ToolExecution.new(turn.store.load_tool_execution(execution.id))
+      end
+
       def append_result(execution, tool_call, payload, json: payload.to_json, error: false)
         message = turn.conversation.append_message(
           role: "tool",
@@ -104,7 +114,9 @@ module TurnKit
         calls.each do |call|
           payload = { "skipped" => true, "message" => "not executed: turn ended by #{terminal.name}" }
           execution = ToolExecution.new(create_execution(call))
-          attrs = turn.store.update_tool_execution(execution.id, "status" => "cancelled", "result" => payload, "completed_at" => Clock.now)
+          attrs = turn.store.claim_tool_execution(execution.id, from: "running", to: "cancelled", result: payload, completed_at: Clock.now)
+          next unless attrs
+
           append_result(ToolExecution.new(attrs), call, payload)
           turn.emit("tool_call.skipped", id: call.id, name: call.name)
         end
@@ -118,12 +130,24 @@ module TurnKit
         turn.agent.effective_tools.find { |tool| tool.tool_name == name.to_s }
       end
 
+      # Heartbeats while the tool runs so a tool slower than TurnKit.timeout
+      # keeps its turn's stale anchor fresh and is not falsely reconciled.
       def call_tool(tool, arguments, context:)
+        interval = (TurnKit.timeout || 300) / 3.0
+        heartbeat = Thread.new do
+          loop do
+            sleep interval
+            heartbeat!
+          end
+        end
+
         if tool.is_a?(Class)
           tool.call(arguments, context: context)
         else
           tool.class.invoke(tool, arguments, context: context)
         end
+      ensure
+        heartbeat.kill
       end
 
       def normalize_payload(value)