turnkit 0.4.2 → 0.6.0

data/lib/turnkit/active_record_store.rb

@@ -9,11 +9,34 @@ module TurnKit
   # persistence records. Turnkit::Conversation (a database row) is not
   # TurnKit::Conversation (the domain object).
   class ActiveRecordStore < Store
-    def initialize(conversation_class: "Turnkit::Conversation", turn_class: "Turnkit::Turn", message_class: "Turnkit::Message", tool_execution_class: "Turnkit::ToolExecution")
+    def initialize(conversation_class: "Turnkit::Conversation", turn_class: "Turnkit::Turn", message_class: "Turnkit::Message", tool_execution_class: "Turnkit::ToolExecution", delivery_class: "Turnkit::Delivery", wait_class: "Turnkit::Wait")
       @conversation_class_name = conversation_class
       @turn_class_name = turn_class
       @message_class_name = message_class
       @tool_execution_class_name = tool_execution_class
+      @delivery_class_name = delivery_class
+      @wait_class_name = wait_class
+    end
+
+    def atomic(conversation_id)
+      conversation_class.connection_pool.with_connection do
+        conversation_class.transaction do
+          conversation_class.lock.find_by!(uid: conversation_id)
+          yield
+        end
+      end
+    end
+
+    # Wait-graph mutations use one database-wide transaction lock. PostgreSQL
+    # advisory xact locks serialize opposite edges even when roots differ.
+    def atomic_graph
+      conversation_class.connection_pool.with_connection do |connection|
+        conversation_class.transaction do
+          raise ConfigError, "atomic wait graphs require PostgreSQL" unless connection.adapter_name.match?(/postg/i)
+          connection.execute("SELECT pg_advisory_xact_lock(1414876747)")
+          yield
+        end
+      end
     end
 
     def create_conversation(attributes)
@@ -85,6 +108,8 @@ module TurnKit
         cost: attrs["cost"],
         error: attrs["error"],
         output_text: attrs["output_text"],
+        submitted_at: attrs["submitted_at"],
+        claim_token: attrs["claim_token"],
         started_at: attrs["started_at"],
         heartbeat_at: attrs["heartbeat_at"],
         completed_at: attrs["completed_at"]
@@ -123,6 +148,85 @@ module TurnKit
       scope.order(:created_at, :uid).map { |record| turn_hash(record) }
     end
 
+    def list_submitted_turns(limit: nil)
+      scope = turn_class.where.not(submitted_at: nil).order(:created_at, :uid)
+      scope = scope.limit(limit) if limit
+      scope.map { |record| turn_hash(record) }
+    end
+
+    def list_actionable_turns(limit:)
+      turn_class.where.not(submitted_at: nil).where(status: %w[pending waiting running]).order(:updated_at, :uid).limit(limit).map { |record| turn_hash(record) }
+    end
+
+    def list_stale_inline_turns(before:, limit:)
+      turn_class.where(submitted_at: nil, status: %w[pending running])
+        .where("COALESCE(heartbeat_at, started_at, created_at) < ?", before)
+        .order(:updated_at, :uid).limit(limit).map { |record| turn_hash(record) }
+    end
+
+    def busy_conversation?(id, include_pending: true)
+      turns = turn_class.where(conversation_uid: id)
+      active = turns.where(status: %w[running waiting])
+      active = active.or(turns.where(status: "pending").where.not(submitted_at: nil)) if include_pending
+      active.exists?
+    end
+
+    def next_delivery_trigger(id)
+      consumed = turn_class.where(conversation_uid: id).where.not(status: "pending", submitted_at: nil).maximum(:context_message_sequence).to_i
+      delivered_ids = delivery_class.where(destination_conversation_uid: id).where.not(message_uid: nil).select(:message_uid)
+      message = message_class.where(conversation_uid: id, uid: delivered_ids).where("sequence > ?", consumed).order(sequence: :desc).first
+      message_hash(message) if message
+    end
+
+    def create_delivery(attributes)
+      attrs = Record.delivery(attributes)
+      record = delivery_class.create_or_find_by!(key: attrs.fetch("key")) do |delivery|
+        delivery.uid = attrs.fetch("id")
+        delivery.source_conversation_uid = attrs.fetch("source_conversation_id")
+        delivery.destination_conversation_uid = attrs.fetch("destination_conversation_id")
+        delivery.source_turn_uid = attrs["source_turn_id"]
+        delivery.payload = attrs.fetch("payload")
+        delivery.message_uid = attrs["message_id"]
+        delivery.delivered_at = attrs["delivered_at"]
+        delivery.created_at = attrs.fetch("created_at")
+      end
+      existing = delivery_hash(record)
+      Record.assert_delivery_retry!(existing, attrs)
+      existing
+    end
+
+    def load_delivery(id)
+      delivery_hash(delivery_class.find_by!(uid: id))
+    end
+
+    def update_delivery(id, attributes)
+      record = delivery_class.find_by!(uid: id)
+      record.update!(Record.delivery_update(attributes).transform_keys { |key| key == "message_id" ? "message_uid" : key })
+      delivery_hash(record)
+    end
+
+    def list_deliveries(source_conversation_id: nil, destination_conversation_id: nil, pending: false, limit: nil)
+      scope = delivery_class.all
+      scope = scope.where(source_conversation_uid: source_conversation_id) if source_conversation_id
+      scope = scope.where(destination_conversation_uid: destination_conversation_id) if destination_conversation_id
+      scope = scope.where(delivered_at: nil) if pending
+      scope = scope.order(:created_at, :uid)
+      scope = scope.limit(limit) if limit
+      scope.map { |record| delivery_hash(record) }
+    end
+
+    def create_wait(turn_id:, target_turn_id:)
+      record = wait_class.create_or_find_by!(turn_uid: turn_id, target_turn_uid: target_turn_id)
+      wait_hash(record)
+    end
+
+    def list_waits(turn_id: nil, target_turn_id: nil)
+      scope = wait_class.all
+      scope = scope.where(turn_uid: turn_id) if turn_id
+      scope = scope.where(target_turn_uid: target_turn_id) if target_turn_id
+      scope.order(:id).map { |record| wait_hash(record) }
+    end
+
     def create_tool_execution(attributes)
       attrs = Record.tool_execution(attributes)
       record = tool_execution_class.create!(
@@ -144,25 +248,25 @@ module TurnKit
       tool_execution_hash(tool_execution_class.find_by!(uid: id))
     end
 
-    def update_tool_execution(id, attributes)
-      record = tool_execution_class.find_by!(uid: id)
-      record.update!(Record.tool_execution_update(attributes))
-      tool_execution_hash(record)
+    def claim_tool_execution(id, from: "running", to: "completed", **attributes)
+      attrs = Record.tool_execution_update(attributes.merge(status: to))
+      affected = tool_execution_class.where(uid: id, status: from).update_all(attrs.merge(updated_at: Clock.now))
+      return nil if affected.zero?
+
+      load_tool_execution(id)
     end
 
     def list_tool_executions(turn_id:)
       tool_execution_class.where(turn_uid: turn_id).order(:created_at, :uid).map { |record| tool_execution_hash(record) }
     end
 
-    def find_stale_turns(before:)
-      turn_class.where(status: %w[pending running]).where("COALESCE(heartbeat_at, started_at, created_at) < ?", before).map { |record| turn_hash(record) }
-    end
-
     private
       def conversation_class = constantize(@conversation_class_name)
       def turn_class = constantize(@turn_class_name)
       def message_class = constantize(@message_class_name)
       def tool_execution_class = constantize(@tool_execution_class_name)
+      def delivery_class = constantize(@delivery_class_name)
+      def wait_class = constantize(@wait_class_name)
 
       def constantize(name)
         name.to_s.split("::").inject(Object) { |mod, part| mod.const_get(part) }
@@ -182,7 +286,9 @@ module TurnKit
       end
 
       def conversation_hash(record)
-        { "id" => record.uid, "agent_name" => record.agent_name, "model" => record.model, "metadata" => record.metadata || {}, "created_at" => record.created_at, "updated_at" => record.updated_at }
+        { "id" => record.uid, "agent_name" => record.agent_name, "model" => record.model,
+          "subject" => record.subject_type && { "type" => record.subject_type, "id" => record.subject_id },
+          "metadata" => record.metadata || {}, "created_at" => record.created_at, "updated_at" => record.updated_at }
       end
 
       def turn_hash(record)
@@ -192,6 +298,7 @@ module TurnKit
           "root_turn_id" => record.root_turn_uid, "context_message_sequence" => record.context_message_sequence,
           "status" => record.status, "model" => record.model, "options" => record.options || {}, "usage" => record.usage || {},
           "cost" => record.cost, "error" => record.error, "output_text" => record.output_text,
+          "submitted_at" => record.submitted_at, "claim_token" => record.claim_token,
           "started_at" => record.started_at, "heartbeat_at" => record.heartbeat_at, "completed_at" => record.completed_at,
           "created_at" => record.created_at, "updated_at" => record.updated_at
         }
@@ -199,6 +306,19 @@ module TurnKit
         attrs
       end
 
+      def delivery_hash(record)
+        {
+          "id" => record.uid, "source_conversation_id" => record.source_conversation_uid,
+          "destination_conversation_id" => record.destination_conversation_uid, "source_turn_id" => record.source_turn_uid,
+          "key" => record.key, "payload" => record.payload || {}, "message_id" => record.message_uid,
+          "delivered_at" => record.delivered_at, "created_at" => record.created_at
+        }
+      end
+
+      def wait_hash(record)
+        { "turn_id" => record.turn_uid, "target_turn_id" => record.target_turn_uid }
+      end
+
       def turn_has_attribute?(name)
         turn_class.respond_to?(:attribute_names) && turn_class.attribute_names.include?(name)
       end

data/lib/turnkit/adapters/ruby_llm.rb

@@ -37,6 +37,12 @@ module TurnKit
 
         response = complete_without_tool_execution(chat)
         normalize_response(response, model: model)
+      rescue ConfigError
+        raise
+      rescue ::RubyLLM::Error, ::RubyLLM::ModelNotFoundError => error
+        # Provider failures (after RubyLLM's own retries) are task failures,
+        # not worker crashes to be replayed by durable reconciliation.
+        raise ModelError, "#{error.class}: #{error.message}"
       end
 
       def paint(prompt:, model:, provider: nil, size: nil, assume_model_exists: nil, input_images: nil, mask: nil, params: {}, metadata: nil, on_event: nil)
@@ -53,6 +59,10 @@ module TurnKit
           params: params || {}
         )
         normalize_image_response(image, model: model, provider: provider, params: { "size" => size || "1024x1024" }.merge(params || {}), metadata: metadata)
+      rescue ConfigError
+        raise
+      rescue ::RubyLLM::Error, ::RubyLLM::ModelNotFoundError => error
+        raise ModelError, "#{error.class}: #{error.message}"
       end
 
       def view_media(media:, objective:, model:, provider: nil, output_schema: nil, params: {}, metadata: nil, on_event: nil)
@@ -69,6 +79,10 @@ module TurnKit
 
         response = complete_without_tool_execution(chat)
         normalize_media_analysis_response(response, media: media_input, model: model, provider: provider, params: params || {}, metadata: metadata)
+      rescue ConfigError
+        raise
+      rescue ::RubyLLM::Error, ::RubyLLM::ModelNotFoundError => error
+        raise ModelError, "#{error.class}: #{error.message}"
       end
 
       private

data/lib/turnkit/agent.rb

@@ -24,21 +24,21 @@ module TurnKit
     attr_reader :name, :description, :model, :instructions, :tools, :skills, :available_skills, :sub_agents
     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
+    attr_reader :output_policy, :output_policy_mode, :output_policy_model, :output_retries, :context_contributors
 
     def initialize(name:, description: "", model: nil, instructions: "", orchestrator: false, tools: [], skills: [], available_skills: [], sub_agents: [],
       system_prompt: nil, prompt_sections: nil, prompt_mode: nil, client: nil, store: 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)
+      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, context_contributors: [], inherit_globals: true)
       @name = name.to_s
       @description = description.to_s
       @model = model
       @orchestrator = orchestrator ? true : false
       @instructions = compose_instructions(instructions)
-      @tools = Array(tools)
-      @skills = Array(skills)
-      @available_skills = Array(available_skills)
-      @sub_agents = Array(sub_agents)
+      @tools = Array(tools).dup.freeze
+      @skills = Array(skills).dup.freeze
+      @available_skills = ((inherit_globals ? Array(TurnKit.available_skills) : []) + Array(available_skills)).uniq { |skill| skill.key }.freeze
+      @sub_agents = Array(sub_agents).dup.freeze
       @system_prompt = system_prompt
       @prompt_sections = prompt_sections
       @prompt_mode = prompt_mode&.to_sym || (:task if @orchestrator)
@@ -59,6 +59,7 @@ module TurnKit
       @output_policy_mode = normalize_output_policy_mode(output_policy_mode)
       @output_retries = Integer(output_retries || 0)
       @on_event = on_event
+      @context_contributors = ((inherit_globals ? Array(TurnKit.context_contributors) : []) + Array(context_contributors)).freeze
       raise ArgumentError, "name is required" if @name.empty?
       validate_tools!
     end
@@ -78,32 +79,35 @@ module TurnKit
       attrs.slice(:effort, :budget).compact
     end
 
-    def conversation(model: nil, subject: nil, metadata: {})
+    def conversation(model: nil, subject: nil, metadata: {}, context: {}, principal: nil)
       store = effective_store
+      context = JSON.parse(JSON.generate(context))
+      metadata = metadata.merge("principal" => principal) unless principal.nil?
+      metadata = metadata.merge("turnkit_subject_prompt" => subject.to_prompt.to_s) if subject.respond_to?(:to_prompt)
       record = store.create_conversation(
         "agent_name" => name,
         "model" => model || effective_model,
         "subject" => subject,
-        "metadata" => metadata
+        "metadata" => metadata.merge("turnkit_context" => context)
       )
-      Conversation.new(agent: self, record: record, store: store, model: model || effective_model, subject: subject, metadata: metadata)
+      Conversation.new(agent: self, record: record, store: store, model: model || effective_model, subject: subject, metadata: metadata.merge("turnkit_context" => context))
     end
 
     def orchestrator?
       @orchestrator
     end
 
-    def run(task, input: nil, async: false, subject: nil, metadata: {}, parent_run: nil, root_turn_id: nil, prompt_mode: :task, **options)
+    def run(task, input: nil, async: false, subject: nil, metadata: {}, context: {}, principal: nil, parent_run: nil, root_turn_id: nil, prompt_mode: :task, **options)
       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)
+      conversation = self.conversation(subject: subject, metadata: metadata, context: context, principal: principal)
       message = conversation.say(task_message(task, input), metadata: { "source" => "application", "task" => true })
       turn = conversation.build_turn(
         trigger_message_id: message.id,
         root_turn_id: root_turn_id || parent_run_root_turn_id(parent_run),
         prompt_mode: prompt_mode,
-        **options
+        principal: principal, context: context, **options
       )
       run = Run.new(turn)
       async ? run : run.run!
@@ -137,10 +141,11 @@ module TurnKit
       store || TurnKit.store
     end
 
-    def effective_tools
-      configured = tools + sub_agents.map { |agent| SubAgentTool.for(agent) }
-      skills = effective_available_skills
-      skills.empty? ? configured : configured + [ LoadSkillTool.for(skills) ]
+    def effective_tools(turn: nil)
+      loaded = turn ? turn.tool_executions.select { |execution| execution.tool_name == "load_skill" && execution.completed? }.map { |execution| execution.result.fetch("key") } : []
+      active_skills = skills + available_skills.select { |skill| loaded.include?(skill.key) }
+      configured = tools + active_skills.flat_map(&:tools) + sub_agents.map { |agent| SubAgentTool.for(agent) }
+      available_skills.empty? ? configured : configured + [ LoadSkillTool.for(available_skills) ]
     end
 
     def effective_on_event
@@ -148,7 +153,7 @@ module TurnKit
     end
 
     def effective_available_skills
-      (Array(TurnKit.available_skills) + available_skills).uniq { |skill| skill.key }
+      available_skills
     end
 
     def effective_prompt_sections
@@ -204,18 +209,19 @@ module TurnKit
       end
 
       def validate_tools!
-        effective_tools.each do |tool|
+        all_tools = effective_tools + available_skills.flat_map(&:tools)
+        all_tools.each do |tool|
           next if tool.is_a?(Class) && tool < Tool
           next if tool.is_a?(Tool)
 
           raise ArgumentError, "tools must be TurnKit::Tool classes or instances"
         end
 
-        names = effective_tools.map(&:tool_name)
+        names = all_tools.map(&:tool_name)
         duplicate = names.find { |name| names.count(name) > 1 }
         raise ArgumentError, "duplicate tool name: #{duplicate}" if duplicate
 
-        effective_tools.each(&:validate_definition!)
+        all_tools.each(&:validate_definition!)
       end
 
       def normalize_output_policy(value, model: nil, thinking: nil)

data/lib/turnkit/authorization.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module TurnKit
+  # Application-owned authorization boundary. A configured policy must return
+  # true explicitly; the model never supplies the principal.
+  module Authorization
+    module_function
+
+    def authorize!(action, principal:, **resource)
+      policy = TurnKit.authorization_policy
+      return true unless policy
+      allowed = policy.respond_to?(:authorize?) ? policy.authorize?(action, principal: principal, **resource) : policy.call(action, principal: principal, **resource)
+      raise AuthorizationError, "not authorized to #{action}" unless allowed == true
+      true
+    end
+  end
+end

data/lib/turnkit/background.rb

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+
+module TurnKit
+  # Jobs are wake-up signals. Submitted turns, deliveries, and waits in the
+  # store are authoritative and can be rediscovered after a lost enqueue.
+  module Background
+    TERMINAL = %w[completed failed cancelled].freeze
+    module_function
+
+    def root_conversation(store, record)
+      store.load_turn(record.fetch("root_turn_id")).fetch("conversation_id")
+    end
+
+    def load_turn(id, store: TurnKit.store)
+      record = store.load_turn(id)
+      agent = TurnKit.resolve_agent(record.fetch("agent_name"))
+      conversation = load_conversation(record.fetch("conversation_id"), store: store, agent: agent)
+      depth = 0
+      ancestor = record
+      while ancestor["parent_turn_id"]
+        depth += 1
+        ancestor = store.load_turn(ancestor.fetch("parent_turn_id"))
+      end
+      Turn.new(agent: agent, conversation: conversation, record: record, store: store, depth: depth)
+    end
+
+    def load_conversation(id, store: TurnKit.store, agent: nil)
+      record = store.load_conversation(id)
+      agent ||= TurnKit.resolve_agent(record.fetch("agent_name"))
+      Conversation.new(agent: agent, record: record, store: store, model: record["model"], subject: record["subject"], metadata: record["metadata"])
+    end
+
+    def submit(turn, callback: nil)
+      store = turn.store
+      raw = store
+      raw = raw.__getobj__ while raw.is_a?(ExecutionStore)
+      raise ConfigError, "background turns must use TurnKit.store" unless raw.equal?(TurnKit.store)
+      TurnKit.resolve_agent(turn.agent_name)
+      principal = store.load_turn(turn.id).dig("options", "principal")
+      Authorization.authorize!(:callback, principal: principal, turn: turn.id, destination_conversation: callback) if callback
+      store.load_conversation(callback) if callback
+      store.atomic(root_conversation(store, store.load_turn(turn.id))) do
+        record = store.load_turn(turn.id)
+        raise Error, "only pending turns can be submitted" unless record["status"] == "pending"
+        options = record.fetch("options")
+        options = options.merge("callback_conversation_id" => callback) if callback
+        store.update_turn(turn.id, submitted_at: record["submitted_at"] || Clock.now, options: options,
+          status: ready?(store, turn.id) ? "pending" : "waiting")
+      end
+      enqueue(turn.id)
+      turn.reload
+    end
+
+    def enqueue(id = nil)
+      if TurnKit.store.is_a?(ActiveRecordStore)
+        require_relative "job"
+        ActiveRecord.after_all_transactions_commit { dispatch_job(id) }
+      else
+        dispatch_job(id)
+      end
+    end
+
+    def dispatch_job(id)
+      if TurnKit.job_dispatcher
+        TurnKit.job_dispatcher.call(id)
+      else
+        raise ConfigError, "background jobs require ActiveRecordStore" unless TurnKit.store.is_a?(ActiveRecordStore)
+        require_relative "job"
+        if [ActiveJob::QueueAdapters::InlineAdapter, ActiveJob::QueueAdapters::AsyncAdapter].any? { |type| Job.queue_adapter.is_a?(type) }
+          raise ConfigError, "configure a persistent Active Job backend (not inline or async)"
+        end
+        Job.perform_later(id)
+      end
+    end
+
+    def perform(id = nil)
+      if id
+        turn = load_turn(id)
+        turn.run! if turn.background?
+      end
+      drain
+    end
+
+    def claim(store, record)
+      store.atomic(root_conversation(store, record)) do
+        store.atomic(record.fetch("conversation_id")) do
+          current = store.load_turn(record.fetch("id"))
+          next unless current["status"] == "pending"
+          state = current.dig("options", "state") || {}
+          next if !state["phase"] && !ready?(store, current.fetch("id")) && !deadline_exceeded?(store, current)
+          if current["submitted_at"]
+            others = store.list_turns(conversation_id: current.fetch("conversation_id")).reject { |row| row["id"] == current["id"] }
+            next if others.any? { |row| %w[running waiting].include?(row["status"]) }
+            first = ([current] + others.select { |row| row["submitted_at"] && row["status"] == "pending" }).min_by { |row| [row["created_at"], row["id"]] }
+            next unless first["id"] == current["id"]
+          end
+          # An application-level join supplies its results as turn-local input.
+          # Tool-level joins already have a persisted tools phase/result channel.
+          waits = store.list_waits(turn_id: current.fetch("id"))
+          if waits.any? && !state["phase"] && !state["wait_input"] && ready?(store, current.fetch("id"))
+            results = waits.map { |wait| SubAgentTool.result(store.load_turn(wait.fetch("target_turn_id"))) }
+            store.append_message("conversation_id" => current.fetch("conversation_id"), "turn_id" => current.fetch("id"),
+              "role" => "user", "kind" => "text", "text" => { "wait_results" => results }.to_json)
+            current = store.update_turn(current.fetch("id"), options: current.fetch("options").merge("state" => state.merge("wait_input" => true)))
+          end
+          store.claim_turn(current.fetch("id"), started_at: current["started_at"] || Clock.now, heartbeat_at: Clock.now, claim_token: SecureRandom.hex(16))
+        end
+      end
+    end
+
+    def send_message(source:, destination:, text:, key:, store: TurnKit.store, source_turn_id: nil, principal: nil)
+      Authorization.authorize!(:send_message, principal: principal, source_conversation: source, destination_conversation: destination)
+      store.load_conversation(destination)
+      delivery = store.create_delivery(
+        "source_conversation_id" => source, "destination_conversation_id" => destination,
+        "source_turn_id" => source_turn_id, "key" => key, "payload" => { "text" => text }
+      )
+      enqueue
+      delivery
+    end
+
+    def callback(store, record)
+      destination = record.dig("options", "callback_conversation_id")
+      return unless destination && TERMINAL.include?(record["status"])
+
+      Authorization.authorize!(:callback, principal: record.dig("options", "principal"), turn: record.fetch("id"), destination_conversation: destination)
+
+      store.create_delivery(
+        "source_conversation_id" => record.fetch("conversation_id"), "destination_conversation_id" => destination,
+        "source_turn_id" => record.fetch("id"), "key" => "completion:#{record.fetch('id')}",
+        "payload" => { "text" => SubAgentTool.result(record).to_json }
+      )
+    end
+
+    def callback_after_terminal(store, record)
+      callback(store, record)
+    rescue AuthorizationError => error
+      options = record.fetch("options").merge("callback_denied" => {
+        "class" => error.class.name, "message" => error.message, "at" => Clock.now.iso8601
+      })
+      store.update_turn(record.fetch("id"), options: options)
+    end
+
+    def deliver(delivery, store: TurnKit.store)
+      destination = delivery.fetch("destination_conversation_id")
+      store.atomic(destination) do
+        delivery = store.load_delivery(delivery.fetch("id"))
+        next if delivery["delivered_at"]
+
+        message = store.append_message(
+          "conversation_id" => destination, "role" => "user", "kind" => "text",
+          "text" => delivery.fetch("payload").fetch("text"),
+          "metadata" => { "delivery_id" => delivery.fetch("id"), "source_conversation_id" => delivery["source_conversation_id"], "source_turn_id" => delivery["source_turn_id"] }
+        )
+        store.update_delivery(delivery.fetch("id"), message_id: message.fetch("id"), delivered_at: Clock.now)
+        wake(destination, store: store)
+      end
+    end
+
+    def wake(conversation_id, store: TurnKit.store)
+      store.atomic(conversation_id) do
+        next if store.busy_conversation?(conversation_id)
+        incoming = store.next_delivery_trigger(conversation_id)
+        next unless incoming
+
+        conversation = load_conversation(conversation_id, store: store)
+        turn = conversation.build_turn(trigger_message_id: incoming.fetch("id"), principal: conversation.metadata["principal"])
+        store.update_turn(turn.id, submitted_at: Clock.now)
+      end
+    end
+
+    def wait(turn, targets, transition: false)
+      ids = Array(targets).map { |target| target.respond_to?(:id) ? target.id : target.to_s }.uniq
+      principal = turn.store.load_turn(turn.id).dig("options", "principal")
+      Authorization.authorize!(:wait, principal: principal, turn: turn.id, targets: ids)
+      turn.store.atomic_graph do
+        turn.store.atomic(root_conversation(turn.store, turn.store.load_turn(turn.id))) do
+          current = turn.store.load_turn(turn.id)
+          raise Error, "only pending turns can wait" if transition && current["status"] != "pending"
+          ids.each do |id|
+            raise ToolError, "a turn cannot wait for itself" if id == turn.id
+            target = turn.store.load_turn(id)
+            raise ToolError, "wait targets must be submitted" unless target["submitted_at"] || TERMINAL.include?(target["status"])
+            if target["conversation_id"] == turn.conversation.id && !TERMINAL.include?(target["status"])
+              raise ToolError, "cannot wait for unfinished work in the same conversation"
+            end
+            raise ToolError, "wait would create a cycle" if wait_reachable?(turn.store, id, turn.id)
+            turn.store.create_wait(turn_id: turn.id, target_turn_id: id)
+          end
+          turn.store.update_turn(turn.id, status: "waiting") if transition && current["submitted_at"] && !ready?(turn.store, turn.id)
+        end
+      end
+      ids
+    end
+
+    def wait_reachable?(store, from, sought, seen = {})
+      target = store.load_turn(from)
+      return false if TERMINAL.include?(target["status"])
+      conversation = target.fetch("conversation_id")
+      return true if conversation == store.load_turn(sought).fetch("conversation_id")
+      return false if seen[conversation]
+      seen[conversation] = true
+      # A conversation is a serial execution lane. Conservatively include waits
+      # of every unfinished peer, not just explicit edges on the requested turn.
+      store.list_turns(conversation_id: conversation).reject { |row| TERMINAL.include?(row["status"]) }.any? do |row|
+        store.list_waits(turn_id: row.fetch("id")).any? { |edge| wait_reachable?(store, edge.fetch("target_turn_id"), sought, seen) }
+      end
+    end
+
+    def ready?(store, id)
+      store.list_waits(turn_id: id).all? { |wait| TERMINAL.include?(store.load_turn(wait.fetch("target_turn_id"))["status"]) }
+    end
+
+    def deadline_exceeded?(store, record)
+      root = store.load_turn(record.fetch("root_turn_id"))
+      limits = root.dig("options", "budget_limits") || {}
+      timeout = limits.fetch("timeout", TurnKit.timeout)
+      start = root["submitted_at"] || root["started_at"]
+      timeout && start && Clock.now >= start + timeout
+    end
+
+    def drain(store: TurnKit.store)
+      limit = TurnKit.maintenance_batch_size
+      store.list_deliveries(pending: true, limit: limit).each { |delivery| deliver(delivery, store: store) }
+      turns = store.list_actionable_turns(limit: limit)
+      turns.each do |record|
+        if record["status"] == "waiting"
+          store.atomic(root_conversation(store, record)) do
+            current = store.load_turn(record.fetch("id"))
+            next unless current["status"] == "waiting"
+            if ready?(store, current.fetch("id")) || deadline_exceeded?(store, current)
+              store.claim_turn(current.fetch("id"), from: "waiting", to: "pending")
+            else
+              store.claim_turn(current.fetch("id"), from: "waiting", to: "waiting") # rotate safely
+            end
+          end
+        elsif record["status"] == "running"
+          store.claim_turn(record.fetch("id"), from: "running", to: "running") # rotate without changing heartbeat
+        elsif record["status"] == "pending"
+          store.claim_turn(record.fetch("id"), from: "pending", to: "pending") # blocked conversations must rotate too
+        end
+      end
+      turns.group_by { |record| record.fetch("conversation_id") }.each do |conversation_id, records|
+        next if store.busy_conversation?(conversation_id, include_pending: false)
+        record = records.find { |row| row["status"] == "pending" }
+        if record
+          rotated = store.claim_turn(record.fetch("id"), from: "pending", to: "pending")
+          enqueue(record.fetch("id")) if rotated
+        end
+      end
+    end
+
+    def reconcile(before: Clock.now - (TurnKit.timeout || 300), store: TurnKit.store)
+      store.list_actionable_turns(limit: TurnKit.maintenance_batch_size).each do |record|
+        store.atomic(root_conversation(store, record)) do
+          record = store.load_turn(record.fetch("id"))
+          next unless record["status"] == "running" && record.fetch("heartbeat_at") < before
+
+          store.update_turn(record.fetch("id"), claim_token: nil)
+          # A pending child is known work, not an interrupted external effect.
+          executions = store.list_tool_executions(turn_id: record.fetch("id"))
+          executions.each do |execution|
+            next unless execution["status"] == "running"
+            loaded = Background.load_turn(record.fetch("id"), store: store)
+            tool = loaded.agent.effective_tools(turn: loaded).find { |candidate| candidate.tool_name == execution["tool_name"] }
+            recovery = tool.is_a?(Class) ? tool.recovery : tool&.class&.recovery
+            ordinary = tool && !(tool.is_a?(Class) && tool < SubAgentTool) &&
+              ![WaitTool, LaunchAgentTool, SendMessageTool].include?(tool)
+            if ordinary && recovery == :replay_safe
+              store.claim_tool_execution(execution.fetch("id"), to: "pending", started_at: nil)
+              next
+            end
+            store.claim_tool_execution(execution.fetch("id"), to: "interrupted", error: { "message" => Reconciliation::INTERRUPTED_MESSAGE }, completed_at: Clock.now)
+          end
+          store.update_turn(record.fetch("id"), status: "pending", heartbeat_at: nil)
+        end
+      end
+      drain(store: store)
+    end
+  end
+end