turnkit 0.4.1 → 0.4.2

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/turn.rb

@@ -43,7 +43,7 @@ module TurnKit
       @started_at = @record["started_at"]
       emit("turn.started", status: status, model: model)
       agent.effective_client.validate!(model: model)
-      @budget = Budget.resume(store: store, root_turn_id: root_turn_id, limits: budget_limits)
+      @budget = Budget.resume(store: store, root_turn_id: root_turn_id, limits: agent.budget_limits)
       revisions_used = 0
       loop do
         budget.check!(depth: depth)
@@ -113,7 +113,15 @@ module TurnKit
     end
 
     def policy_audit
-      (@record["options"] || {})["policy_audit"]
+      options = @record["options"] || {}
+      options.dig("state", "policy_audit") || options["policy_audit"]
+    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)
+      options = record["options"] || {}
+      (options.dig("state", "iterations") || options["iterations"]).to_i
     end
 
     def usage
@@ -168,23 +176,13 @@ module TurnKit
     end
 
     def paint(prompt, model:, provider: nil, size: nil, assume_model_exists: nil, input_images: nil, mask: nil, params: {}, metadata: {}, client: nil)
-      claimed_standalone = false
-      case status
-      when "pending"
-        claimed = store.claim_turn(id, from: "pending", to: "running", started_at: Clock.now, heartbeat_at: Clock.now)
-        raise Error, "turn is already running" unless claimed
-
+      claimed = claim_standalone!("paint")
+      if claimed
         @record = claimed
         @started_at = @record["started_at"]
-        @budget = Budget.resume(store: store, root_turn_id: root_turn_id, limits: budget_limits)
-        claimed_standalone = true
         emit("turn.started", status: status, model: model)
-      when "running"
-        # Image tools call this while their parent turn is running.
-      else
-        raise Error, "cannot paint for #{status} turn"
+        @budget = Budget.resume(store: store, root_turn_id: root_turn_id, limits: agent.budget_limits)
       end
-
       image_client = client || agent.effective_client
       request = {
         prompt: prompt,
@@ -201,43 +199,28 @@ module TurnKit
       image_client.validate!(model: model)
       emit("image.requested", request.except(:input_images, :mask))
       result = call_image_client(image_client, request)
-      result_cost = Cost.from_usage(result.usage, model: result.model || model)
-      add_usage!(result.usage, cost: result_cost)
-      budget.add_cost!(result_cost.total)
+      result_cost = apply_result_cost(result, model: model)
       image = result.images.first
       raise Error, "image client returned no image" unless image
       raise Error, "image client returned image without url or data" if image.url.to_s.empty? && image.data.to_s.empty?
 
       persist_image_message(image)
       emit("image.completed", image: image.to_h, model: image.model || model, provider: image.provider || provider&.to_s, mime_type: image.mime_type, usage: result.usage.to_h, cost: result_cost.to_h, metadata: metadata || {})
-      complete_with_output(image.url.to_s, output_data: { "type" => "image", "images" => [ image.to_h ] }, audit: check_policy(image.url.to_s, output_data: { "type" => "image", "images" => [ image.to_h ] })) if claimed_standalone
+      complete_with_output(image.url.to_s, output_data: { "type" => "image", "images" => [ image.to_h ] }, audit: check_policy(image.url.to_s, output_data: { "type" => "image", "images" => [ image.to_h ] })) if claimed
       image
     rescue StandardError => error
-      if claimed_standalone
-        update!(status: "failed", error: { "class" => error.class.name, "message" => error.message }, completed_at: Clock.now)
-        emit("turn.failed", error: { "class" => error.class.name, "message" => error.message })
-      end
+      fail_standalone!(error) if claimed
       raise
     end
 
     def view_media(media, objective:, model:, provider: nil, output_schema: nil, params: {}, metadata: {}, client: nil)
-      claimed_standalone = false
-      case status
-      when "pending"
-        claimed = store.claim_turn(id, from: "pending", to: "running", started_at: Clock.now, heartbeat_at: Clock.now)
-        raise Error, "turn is already running" unless claimed
-
+      claimed = claim_standalone!("view media")
+      if claimed
         @record = claimed
         @started_at = @record["started_at"]
-        @budget = Budget.resume(store: store, root_turn_id: root_turn_id, limits: budget_limits)
-        claimed_standalone = true
         emit("turn.started", status: status, model: model)
-      when "running"
-        # Media tools call this while their parent turn is running.
-      else
-        raise Error, "cannot view media for #{status} turn"
+        @budget = Budget.resume(store: store, root_turn_id: root_turn_id, limits: agent.budget_limits)
       end
-
       media_input = MediaInput.wrap(media)
       media_client = client || agent.effective_client
       request = {
@@ -253,42 +236,38 @@ module TurnKit
       media_client.validate!(model: model)
       emit("media.requested", request.except(:media).merge(media: media_input.to_h))
       result = call_media_client(media_client, request)
-      result_cost = Cost.from_usage(result.usage, model: result.model || model)
-      add_usage!(result.usage, cost: result_cost)
-      budget.add_cost!(result_cost.total)
+      result_cost = apply_result_cost(result, model: model)
       analysis = result.media_analyses.first
       raise Error, "media client returned no media analysis" unless analysis
 
       persist_media_analysis_message(analysis)
       output_data = { "type" => "media_analysis", "media_analyses" => [ analysis.to_h ] }
       emit("media.completed", analysis: analysis.to_h, model: analysis.model || model, provider: analysis.provider || provider&.to_s, media: media_input.to_h, usage: result.usage.to_h, cost: result_cost.to_h, metadata: metadata || {})
-      complete_with_output(analysis.text, output_data: output_data, audit: check_policy(analysis.text, output_data: output_data)) if claimed_standalone
+      complete_with_output(analysis.text, output_data: output_data, audit: check_policy(analysis.text, output_data: output_data)) if claimed
       analysis
     rescue StandardError => error
-      emit("media.failed", error: { "class" => error.class.name, "message" => error.message }, metadata: metadata || {}) if status == "running" || claimed_standalone
-      if claimed_standalone
-        update!(status: "failed", error: { "class" => error.class.name, "message" => error.message }, completed_at: Clock.now)
-        emit("turn.failed", error: { "class" => error.class.name, "message" => error.message })
-      end
+      emit("media.failed", error: { "class" => error.class.name, "message" => error.message }, metadata: metadata || {}) if status == "running" || claimed
+      fail_standalone!(error) if claimed
       raise
     end
 
     private
       def model_request
         prompt = SystemPrompt.new(agent: agent, turn: self, conversation: conversation, mode: prompt_mode || agent.effective_prompt_mode(turn: self))
-        instructions = case agent.system_prompt
+        instructions, dynamic_instructions = case agent.system_prompt
         when nil
-          prompt.to_s
+          [ prompt.stable, prompt.dynamic ]
         when String
-          agent.system_prompt
+          [ agent.system_prompt, nil ]
         else
-          agent.system_prompt.call(prompt).to_s
+          [ agent.system_prompt.call(prompt).to_s, nil ]
         end
         ModelRequest.new(
           model: model,
           messages: llm_messages,
           tools: agent.effective_tools,
           instructions: instructions,
+          dynamic_instructions: dynamic_instructions,
           thinking: thinking,
           output_schema: output_schema,
           metadata: { turn_id: id, conversation_id: conversation.id },
@@ -296,48 +275,27 @@ module TurnKit
         )
       end
 
+      # Clients implement the TurnKit::Client keyword contract. See client.rb.
       def call_client(request, client: agent.effective_client)
-        kwargs = {
+        client.chat(
           model: request.model,
           messages: request.messages,
           tools: request.tools,
           instructions: request.instructions,
+          dynamic_instructions: request.dynamic_instructions,
           thinking: request.thinking,
           output_schema: request.output_schema,
           metadata: request.metadata,
           on_event: ->(event) { emit_event(event) }
-        }
-        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 call_image_client(client, request)
-        kwargs = request.merge(on_event: ->(event) { emit_event(event) })
-        accepted = client.method(:paint).parameters.filter_map do |kind, name|
-          return client.paint(**kwargs) if kind == :keyrest
-
-          name if %i[key keyreq].include?(kind)
-        end
-        client.paint(**kwargs.slice(*accepted))
+        client.paint(**request, on_event: ->(event) { emit_event(event) })
       end
 
       def call_media_client(client, request)
-        kwargs = request.merge(on_event: ->(event) { emit_event(event) })
-        accepted = client.method(:view_media).parameters.filter_map do |kind, name|
-          return client.view_media(**kwargs) if kind == :keyrest
-
-          name if %i[key keyreq].include?(kind)
-        end
-        client.view_media(**kwargs.slice(*accepted))
+        client.view_media(**request, on_event: ->(event) { emit_event(event) })
       end
 
       def llm_messages
@@ -453,8 +411,7 @@ module TurnKit
       end
 
       def persist_policy_audit(audit)
-        options = (@record["options"] || {}).merge("policy_audit" => audit.to_h)
-        update!(options: options)
+        update_state!("policy_audit" => audit.to_h)
         emit("output_policy.completed", clean: audit.clean?, violation_count: audit.violations.length)
       end
 
@@ -506,23 +463,50 @@ module TurnKit
 
       def count_iteration!
         budget.count_iteration!
-        options = (@record["options"] || {}).merge("iterations" => (@record.dig("options", "iterations").to_i + 1))
-        update!(options: options)
+        update_state!("iterations" => Turn.iterations_for(@record) + 1)
+      end
+
+      # Runtime state lives under options["state"]; the rest of options is
+      # write-once turn configuration. Reads fall back to the legacy top-level
+      # keys for turns persisted before the split.
+      def update_state!(changes)
+        options = @record["options"] || {}
+        update!(options: options.merge("state" => (options["state"] || {}).merge(changes)))
       end
 
       def heartbeat!
         update!(heartbeat_at: Clock.now)
       end
 
-      def budget_limits
-        {
-          max_iterations: agent.max_iterations || TurnKit.max_iterations,
-          timeout: agent.timeout || TurnKit.timeout,
-          max_depth: agent.max_depth || TurnKit.max_depth,
-          max_tool_executions: agent.max_tool_executions || TurnKit.max_tool_executions,
-          max_tool_executions_by_name: agent.max_tool_executions_by_name || TurnKit.max_tool_executions_by_name,
-          max_spend: agent.max_spend || TurnKit.max_spend
-        }
+      # Claims a pending turn for a standalone media call. Returns the claimed
+      # record when this call owns turn completion, nil when running inside a parent
+      # turn (media tools call paint/view_media while their turn is running).
+      # Callers perform any post-claim setup after assignment, so later errors
+      # still fail the claimed turn.
+      def claim_standalone!(action)
+        case status
+        when "pending"
+          claimed = store.claim_turn(id, from: "pending", to: "running", started_at: Clock.now, heartbeat_at: Clock.now)
+          raise Error, "turn is already running" unless claimed
+
+          claimed
+        when "running"
+          nil
+        else
+          raise Error, "cannot #{action} for #{status} turn"
+        end
+      end
+
+      def fail_standalone!(error)
+        update!(status: "failed", error: { "class" => error.class.name, "message" => error.message }, completed_at: Clock.now)
+        emit("turn.failed", error: { "class" => error.class.name, "message" => error.message })
+      end
+
+      def apply_result_cost(result, model:)
+        cost = Cost.from_usage(result.usage, model: result.model || model)
+        add_usage!(result.usage, cost: cost)
+        budget.add_cost!(cost.total)
+        cost
       end
 
       def aggregate_cost(current, cost)

data/lib/turnkit/version.rb

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

data/lib/turnkit/view_media_tool.rb

@@ -11,8 +11,8 @@ module TurnKit
       end
     end
 
-    def call(turnkit_context:, **arguments)
-      turnkit_context.turn.view_media(
+    def call(context:, **arguments)
+      context.turn.view_media(
         media(**arguments),
         objective: objective(**arguments),
         model: self.class.model,

data/lib/turnkit.rb

@@ -17,7 +17,6 @@ require_relative "turnkit/event"
 require_relative "turnkit/model_request"
 require_relative "turnkit/schema_check"
 require_relative "turnkit/agent"
-require_relative "turnkit/workflow"
 require_relative "turnkit/client"
 require_relative "turnkit/conversation"
 require_relative "turnkit/message"
@@ -31,7 +30,6 @@ require_relative "turnkit/output_audit"
 require_relative "turnkit/output_policy"
 require_relative "turnkit/prompt_data"
 require_relative "turnkit/prompt_context"
-require_relative "turnkit/prompt_contribution"
 require_relative "turnkit/system_prompt"
 require_relative "turnkit/store"
 require_relative "turnkit/memory_store"
@@ -50,9 +48,7 @@ require_relative "turnkit/usage"
 require_relative "turnkit/run"
 require_relative "turnkit/adapters/codex"
 require_relative "turnkit/adapters/ruby_llm"
-require_relative "turnkit/stores/active_record_store"
-
-require_relative "turnkit/rails/railtie" if defined?(Rails)
+require_relative "turnkit/active_record_store"
 
 module TurnKit
   class << self
@@ -65,10 +61,7 @@ module TurnKit
     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
     attr_accessor :on_event
-    attr_accessor :conversation_record_class, :turn_record_class
-    attr_accessor :message_record_class, :tool_execution_record_class
   end
 
   self.default_model = "claude-sonnet-4-5"
@@ -87,8 +80,6 @@ module TurnKit
   self.prompt_data_max_chars = 20_000
   self.available_skills = []
   self.context_contributors = []
-  self.system_prompt_contributors = []
-  self.model_prompt_contributors = {}
   self.on_event = nil
   self.output_policy_model = nil
   self.output_policy_thinking = { effort: :low }
@@ -97,14 +88,6 @@ module TurnKit
     yield self
   end
 
-  def self.model
-    default_model
-  end
-
-  def self.model=(value)
-    self.default_model = value
-  end
-
   def self.reconcile_stale!(before: Clock.now - (timeout || 300))
     store.find_stale_turns(before: before).each do |turn|
       store.update_turn(turn.fetch("id"), "status" => "stale", "completed_at" => Clock.now)