turnkit 0.4.1 → 0.5.0

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.5.0"
 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,10 +30,10 @@ 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"
+require_relative "turnkit/reconciliation"
 require_relative "turnkit/compaction"
 require_relative "turnkit/tool"
 require_relative "turnkit/image_tool"
@@ -50,9 +49,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 +62,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 +81,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,18 +89,8 @@ 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)
-    end
+    Reconciliation.reconcile!(before: before)
   end
 
   def self.check_output_policy(output, constraints: [], context: {})

metadata

@@ -1,31 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: turnkit
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Sam Couch
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-19 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: ruby_llm
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.14'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.14'
+date: 2026-07-22 00:00:00.000000000 Z
+dependencies: []
 description: TurnKit is a Ruby/Rails agent runtime for durable AI conversations, application
-  runs, reusable workflows, tool calling, skills, sub-agents, context compaction,
+  runs, orchestrator agents, tool calling, skills, sub-agents, context compaction,
   and persistence.
 email:
 - sam@samcouch.com
@@ -37,7 +23,16 @@ files:
 - LICENSE.md
 - README.md
 - UPGRADE.md
+- UPGRADE_TO_0_4_2.md
+- lib/generators/turnkit/install/templates/conversation.rb
+- lib/generators/turnkit/install/templates/create_turnkit_tables.rb
+- lib/generators/turnkit/install/templates/initializer.rb
+- lib/generators/turnkit/install/templates/message.rb
+- lib/generators/turnkit/install/templates/tool_execution.rb
+- lib/generators/turnkit/install/templates/turn.rb
+- lib/generators/turnkit/install_generator.rb
 - lib/turnkit.rb
+- lib/turnkit/active_record_store.rb
 - lib/turnkit/adapters/codex.rb
 - lib/turnkit/adapters/ruby_llm.rb
 - lib/turnkit/agent.rb
@@ -49,13 +44,6 @@ files:
 - lib/turnkit/cost.rb
 - lib/turnkit/error.rb
 - lib/turnkit/event.rb
-- lib/turnkit/generators/turnkit/install/templates/conversation.rb
-- lib/turnkit/generators/turnkit/install/templates/create_turnkit_tables.rb
-- lib/turnkit/generators/turnkit/install/templates/initializer.rb
-- lib/turnkit/generators/turnkit/install/templates/message.rb
-- lib/turnkit/generators/turnkit/install/templates/tool_execution.rb
-- lib/turnkit/generators/turnkit/install/templates/turn.rb
-- lib/turnkit/generators/turnkit/install_generator.rb
 - lib/turnkit/id.rb
 - lib/turnkit/image_result.rb
 - lib/turnkit/image_tool.rb
@@ -69,16 +57,14 @@ files:
 - lib/turnkit/output_audit.rb
 - lib/turnkit/output_policy.rb
 - lib/turnkit/prompt_context.rb
-- lib/turnkit/prompt_contribution.rb
 - lib/turnkit/prompt_data.rb
-- lib/turnkit/rails/railtie.rb
+- lib/turnkit/reconciliation.rb
 - lib/turnkit/record.rb
 - lib/turnkit/result.rb
 - lib/turnkit/run.rb
 - lib/turnkit/schema_check.rb
 - lib/turnkit/skill.rb
 - lib/turnkit/store.rb
-- lib/turnkit/stores/active_record_store.rb
 - lib/turnkit/sub_agent_tool.rb
 - lib/turnkit/system_prompt.rb
 - lib/turnkit/tool.rb
@@ -89,7 +75,6 @@ files:
 - lib/turnkit/usage.rb
 - lib/turnkit/version.rb
 - lib/turnkit/view_media_tool.rb
-- lib/turnkit/workflow.rb
 homepage: https://github.com/samuelcouch/turnkit
 licenses:
 - MIT
@@ -117,5 +102,6 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Ruby/Rails agent runtime for durable AI conversations, runs, and workflows.
+summary: Ruby/Rails agent runtime for durable AI conversations, runs, and orchestrator
+  agents.
 test_files: []

data/lib/turnkit/prompt_contribution.rb

@@ -1,13 +0,0 @@
-# frozen_string_literal: true
-
-module TurnKit
-  class PromptContribution
-    attr_accessor :stable_prefix, :dynamic_suffix, :section_overrides
-
-    def initialize(stable_prefix: nil, dynamic_suffix: nil, section_overrides: nil)
-      @stable_prefix = stable_prefix.to_s
-      @dynamic_suffix = dynamic_suffix.to_s
-      @section_overrides = (section_overrides || {}).transform_keys(&:to_sym)
-    end
-  end
-end

data/lib/turnkit/rails/railtie.rb

@@ -1,9 +0,0 @@
-# frozen_string_literal: true
-
-module TurnKit
-  class Railtie < Rails::Railtie
-    generators do
-      require_relative "../generators/turnkit/install_generator"
-    end
-  end
-end

data/lib/turnkit/workflow.rb

@@ -1,58 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "agent"
-
-module TurnKit
-  class Workflow
-    ORCHESTRATOR_PREAMBLE = <<~TEXT.strip
-      You are an autonomous task orchestrator. Navigate from the application
-      request to a final output without asking the user follow-up questions.
-
-      Use the available tools to gather context, inspect sources, take actions,
-      persist outputs, and verify work. Use loaded skills as reusable workflow
-      patterns. Iterate when work needs missing context, critique, revision, or
-      verification.
-
-      When multiple independent items need the same kind of fetch or read, and
-      an available batch tool can handle them in one call, prefer the batch tool
-      over repeated one-item tool calls.
-
-      Stop when the task is complete, when the available context and tools are
-      sufficient for the best possible answer, or when further iteration would
-      not materially improve the result. Respect runtime, cost, and iteration
-      limits.
-    TEXT
-
-    DEFAULT_INSTRUCTIONS = ORCHESTRATOR_PREAMBLE
-
-    attr_reader :name, :options
-
-    def initialize(name: "workflow", instructions: nil, preamble: true, **options)
-      @name = name.to_s
-      raise ArgumentError, "name is required" if @name.empty?
-
-      @options = options.merge(
-        name: @name,
-        prompt_mode: options.fetch(:prompt_mode, :task),
-        instructions: compose_instructions(instructions, preamble: preamble)
-      ).freeze
-      @agent = Agent.new(**@options)
-    end
-
-    def run(prompt = nil, task: nil, input: nil, async: false, subject: nil, metadata: {}, **overrides)
-      agent(**overrides).run(task || prompt, input: input, async: async, subject: subject, metadata: metadata)
-    end
-
-    def agent(**overrides)
-      overrides.empty? ? @agent : Agent.new(**@options.merge(overrides.compact))
-    end
-
-    private
-      def compose_instructions(instructions, preamble:)
-        parts = []
-        parts << ORCHESTRATOR_PREAMBLE if preamble
-        parts << instructions.to_s.strip unless instructions.to_s.strip.empty?
-        parts.join("\n\n")
-      end
-  end
-end