turnkit 0.4.2 → 0.6.0

data/lib/turnkit/turn.rb

@@ -13,6 +13,7 @@ module TurnKit
       @agent = agent
       @conversation = conversation
       @store = store
+      @base_store = store
       @record = record.transform_keys(&:to_s)
       @id = @record.fetch("id")
       @conversation_id = @record.fetch("conversation_id")
@@ -36,62 +37,89 @@ module TurnKit
       @on_event = block if block
       return self unless status == "pending"
 
-      claimed = store.claim_turn(id, from: "pending", to: "running", started_at: Clock.now, heartbeat_at: Clock.now)
+      @store = @base_store
+      claimed = Background.claim(store, @record)
       return self unless claimed
 
       @record = claimed
       @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: agent.budget_limits)
-      revisions_used = 0
-      loop do
-        budget.check!(depth: depth)
-        count_iteration!
-        TurnKit::Compaction.maybe_compact!(self)
-
-        request = model_request
-        emit_model_requested("model.requested", request)
-        result = call_client(request)
-        result_cost = Cost.from_usage(result.usage, model: result.model || model)
-
-        add_usage!(result.usage, cost: result_cost)
-        emit_model_completed("model.completed", result, result_cost, model: model)
-        budget.add_cost!(result_cost.total)
-        persist_assistant_message(result)
-
-        if result.tool_calls?
-          runner = ToolRunner.new(self)
-          terminal = runner.dispatch(result.tool_calls)
-          if terminal
-            candidate = append_terminal_completion(runner, terminal)
-          else
-            next
-          end
-        else
-          candidate = result.text
-        end
-
-        audit = check_policy(candidate, output_data: result.output_data)
-        if should_revise?(audit, revisions_used)
-          revisions_used += 1
-          append_revision_message(audit, attempt: revisions_used, terminal_tool_name: terminal&.tool_name)
-          emit("output_policy.revision", violation_count: audit.violations.length, attempt: revisions_used)
-          next
-        end
-
-        complete_with_output(candidate, output_data: result.output_data, audit: audit)
-        break
+      fence!
+      with_heartbeat do
+        emit("turn.started", status: status, model: model)
+        agent.effective_client.validate!(model: model)
+        execute
       end
       reload
       self
+    rescue LostClaim
+      reload
     rescue StandardError => error
+      # Background infrastructure failures must reach the job backend. The
+      # reconciler recovers the persisted phase rather than guessing here.
+      raise if background? && !error.is_a?(TurnKit::Error)
+      raise unless claimed
+
       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 })
       reload
       self
     end
 
+    def background? = !!@record["submitted_at"]
+
+    def perform_later(callback: nil)
+      Background.submit(self, callback: callback.respond_to?(:id) ? callback.id : callback)
+    end
+
+    def wait_for(*targets)
+      Background.wait(self, targets.flatten, transition: true)
+      reload
+    end
+
+    def suspend!
+      update!(status: "waiting", claim_token: nil)
+    end
+
+    # Revokes the local claim. An already-sent remote request cannot be
+    # recalled, but ExecutionStore fences every later write from that worker.
+    def cancel!(descendants: :retain, principal: nil)
+      raise ArgumentError, "descendants must be :retain or :cascade" unless %i[retain cascade].include?(descendants)
+      Authorization.authorize!(:cancel, principal: principal, turn: self, descendants: descendants)
+      @base_store.atomic(Background.root_conversation(@base_store, @record)) do
+        all = @base_store.list_turns(root_turn_id: root_turn_id)
+        rows = [@base_store.load_turn(id)]
+        if descendants == :cascade
+          descendant_ids = { id => true }
+          loop do
+            added = all.select { |row| row["parent_turn_id"] && descendant_ids[row["parent_turn_id"]] && !descendant_ids[row["id"]] }
+            break if added.empty?
+            added.each { |row| descendant_ids[row["id"]] = true }
+          end
+          rows.concat(all.select { |row| row["id"] != id && descendant_ids[row["id"]] })
+        end
+        rows.each do |row|
+          next if Background::TERMINAL.include?(row["status"])
+          executions = Reconciliation.interrupt_tool_executions(row, store: @base_store)
+          Reconciliation.repair_transcript(row, executions, store: @base_store)
+          attrs = { status: "cancelled", claim_token: nil, completed_at: Clock.now,
+            error: { "class" => "TurnKit::Cancelled", "message" => "cancelled by application" } }
+          terminal_row = @base_store.update_turn(row.fetch("id"), attrs)
+          Background.callback_after_terminal(@base_store, terminal_row) if row["submitted_at"]
+        end
+        rows.map { |row| row.fetch("conversation_id") }.uniq.each { |conversation_id| Background.wake(conversation_id, store: @base_store) } if background?
+      end
+      Background.enqueue if background?
+      reload
+    end
+
+    def execution_budget(excluding: nil)
+      root = store.load_turn(root_turn_id)
+      limits = root.dig("options", "budget_limits") || agent.budget_limits
+      turns = store.list_turns(root_turn_id: root_turn_id)
+      executions = turns.flat_map { |row| store.list_tool_executions(turn_id: row.fetch("id")) }.reject { |row| row["id"] == excluding }
+      Budget.new(**limits.transform_keys(&:to_sym), root_started_at: root["submitted_at"] || root["started_at"] || Clock.now).seed!(turns: turns, tool_executions: executions)
+    end
+
     def preview
       model_request
     end
@@ -112,6 +140,8 @@ module TurnKit
       @record["output_data"]
     end
 
+    def context = JSON.parse(JSON.generate(@record.dig("options", "context") || {}))
+
     def policy_audit
       options = @record["options"] || {}
       options.dig("state", "policy_audit") || options["policy_audit"]
@@ -180,6 +210,7 @@ module TurnKit
       if claimed
         @record = claimed
         @started_at = @record["started_at"]
+        fence!
         emit("turn.started", status: status, model: model)
         @budget = Budget.resume(store: store, root_turn_id: root_turn_id, limits: agent.budget_limits)
       end
@@ -218,6 +249,7 @@ module TurnKit
       if claimed
         @record = claimed
         @started_at = @record["started_at"]
+        fence!
         emit("turn.started", status: status, model: model)
         @budget = Budget.resume(store: store, root_turn_id: root_turn_id, limits: agent.budget_limits)
       end
@@ -252,6 +284,87 @@ module TurnKit
     end
 
     private
+      def fence!
+        @store = ExecutionStore.new(store, turn_id: id, token: @record.fetch("claim_token"), conversation_id: Background.root_conversation(store, @record))
+        @conversation = Conversation.new(agent: agent, record: store.load_conversation(conversation.id), store: store,
+          model: conversation.model, subject: conversation.subject, metadata: conversation.metadata)
+      end
+
+      def execute
+        loop do
+          @budget = execution_budget
+          budget.check!(depth: depth)
+          state = @record.dig("options", "state") || {}
+          case state["phase"] || "model"
+          when "model"
+            count_iteration!
+            TurnKit::Compaction.maybe_compact!(self)
+            request = model_request
+            emit_model_requested("model.requested", request)
+            result = call_client(request)
+            cost = Cost.from_usage(result.usage, model: result.model || model)
+            store.atomic do
+              add_usage!(result.usage, cost: cost)
+              persist_assistant_message(result)
+              update_state!("phase" => result.tool_calls? ? "tools" : "output", "parts" => result.parts,
+                "candidate" => result.text, "output_data" => result.output_data, "terminal_tool_name" => nil)
+            end
+            emit_model_completed("model.completed", result, cost, model: model)
+            budget.add_cost!(cost.total)
+          when "tools"
+            runner = ToolRunner.new(self)
+            terminal = runner.dispatch(Result.new(parts: state.fetch("parts")).tool_calls)
+            if terminal == :waiting
+              suspend!
+              break
+            end
+            store.atomic do
+              if terminal
+                candidate = append_terminal_completion(runner, terminal)
+                update_state!("phase" => "output", "candidate" => candidate, "terminal_tool_name" => terminal.tool_name)
+              else
+                update_state!("phase" => "model", "parts" => nil)
+              end
+            end
+          when "output"
+            candidate = state.fetch("candidate")
+            audit = check_policy(candidate, output_data: state["output_data"])
+            revisions_used = state["revisions_used"].to_i
+            if should_revise?(audit, revisions_used)
+              store.atomic do
+                append_revision_message(audit, attempt: revisions_used + 1, terminal_tool_name: state["terminal_tool_name"])
+                update_state!("phase" => "model", "parts" => nil, "revisions_used" => revisions_used + 1)
+              end
+              emit("output_policy.revision", violation_count: audit.violations.length, attempt: revisions_used + 1)
+            else
+              complete_with_output(candidate, output_data: state["output_data"], audit: audit)
+              break
+            end
+          end
+        end
+      end
+
+      def with_heartbeat
+        mutex, wake = Mutex.new, ConditionVariable.new
+        stopped = false
+        heartbeat = Thread.new do
+          loop do
+            break if mutex.synchronize {
+              wake.wait(mutex, (TurnKit.timeout || 300) / 3.0) unless stopped
+              stopped
+            }
+            heartbeat!
+          end
+        rescue LostClaim
+          # The executing thread observes the same revocation on its next write.
+        end
+        yield
+      ensure
+        # Never interrupt a database write/connection initialization mid-flight.
+        mutex.synchronize { stopped = true; wake.signal }
+        heartbeat&.value
+      end
+
       def model_request
         prompt = SystemPrompt.new(agent: agent, turn: self, conversation: conversation, mode: prompt_mode || agent.effective_prompt_mode(turn: self))
         instructions, dynamic_instructions = case agent.system_prompt
@@ -265,7 +378,7 @@ module TurnKit
         ModelRequest.new(
           model: model,
           messages: llm_messages,
-          tools: agent.effective_tools,
+          tools: agent.effective_tools(turn: self),
           instructions: instructions,
           dynamic_instructions: dynamic_instructions,
           thinking: thinking,
@@ -291,11 +404,11 @@ module TurnKit
       end
 
       def call_image_client(client, request)
-        client.paint(**request, on_event: ->(event) { emit_event(event) })
+        with_heartbeat { client.paint(**request, on_event: ->(event) { emit_event(event) }) }
       end
 
       def call_media_client(client, request)
-        client.view_media(**request, on_event: ->(event) { emit_event(event) })
+        with_heartbeat { client.view_media(**request, on_event: ->(event) { emit_event(event) }) }
       end
 
       def llm_messages
@@ -392,8 +505,11 @@ module TurnKit
         else
           attrs[:status] = "completed"
         end
-        update!(attrs)
-        persist_policy_audit(audit) if audit
+        store.atomic(Background.root_conversation(store, @record)) do
+          update_state!("policy_audit" => audit.to_h) if audit
+          update!(attrs)
+        end
+        emit("output_policy.completed", clean: audit.clean?, violation_count: audit.violations.length) if audit
 
         if failed?
           emit("turn.failed", error: @record["error"])
@@ -410,11 +526,6 @@ module TurnKit
         TurnKit.check_output_policy(output, constraints: constraints, context: { turn: self, output_text: text, output_data: output_data })
       end
 
-      def persist_policy_audit(audit)
-        update_state!("policy_audit" => audit.to_h)
-        emit("output_policy.completed", clean: audit.clean?, violation_count: audit.violations.length)
-      end
-
       def should_revise?(audit, revisions_used)
         audit && !audit.clean? && revisions_used < agent.output_retries
       end
@@ -462,8 +573,11 @@ module TurnKit
       end
 
       def count_iteration!
-        budget.count_iteration!
-        update_state!("iterations" => Turn.iterations_for(@record) + 1)
+        store.atomic do
+          @budget = execution_budget
+          budget.count_iteration!
+          update_state!("iterations" => Turn.iterations_for(@record) + 1)
+        end
       end
 
       # Runtime state lives under options["state"]; the rest of options is
@@ -475,7 +589,7 @@ module TurnKit
       end
 
       def heartbeat!
-        update!(heartbeat_at: Clock.now)
+        store.update_turn(id, heartbeat_at: Clock.now)
       end
 
       # Claims a pending turn for a standalone media call. Returns the claimed
@@ -486,7 +600,7 @@ module TurnKit
       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)
+          claimed = Background.claim(store, @record)
           raise Error, "turn is already running" unless claimed
 
           claimed
@@ -516,7 +630,21 @@ module TurnKit
       end
 
       def update!(attributes)
-        @record = store.update_turn(id, attributes)
+        terminal = Background::TERMINAL.include?(attributes[:status])
+        store.atomic(Background.root_conversation(store, @record)) do
+          if terminal
+            if attributes[:status] == "failed" && background?
+              executions = Reconciliation.interrupt_tool_executions(@record, store: store)
+              Reconciliation.repair_transcript(@record, executions, store: store)
+            end
+            attributes = attributes.merge(claim_token: nil)
+          end
+          @record = store.update_turn(id, attributes)
+          # The terminal write clears this execution's claim token, so durable
+          # callback work must use the unfenced store after that write.
+          Background.callback_after_terminal(@base_store, @record) if terminal && background?
+          Background.wake(conversation.id, store: @base_store) if terminal && background?
+        end
         @started_at = @record["started_at"]
         @model = @record["model"] || agent.effective_model
         @record
@@ -535,5 +663,8 @@ module TurnKit
       @turn = turn
       @execution = execution
     end
+
+    def idempotency_key = "turnkit:tool:#{execution.id}"
+    def principal = turn.store.load_turn(turn.id).dig("options", "principal")
   end
 end

data/lib/turnkit/version.rb

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

data/lib/turnkit.rb

@@ -16,6 +16,7 @@ require_relative "turnkit/budget"
 require_relative "turnkit/event"
 require_relative "turnkit/model_request"
 require_relative "turnkit/schema_check"
+require_relative "turnkit/authorization"
 require_relative "turnkit/agent"
 require_relative "turnkit/client"
 require_relative "turnkit/conversation"
@@ -33,6 +34,7 @@ require_relative "turnkit/prompt_context"
 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"
@@ -49,6 +51,10 @@ require_relative "turnkit/run"
 require_relative "turnkit/adapters/codex"
 require_relative "turnkit/adapters/ruby_llm"
 require_relative "turnkit/active_record_store"
+require_relative "turnkit/execution_store"
+require_relative "turnkit/background"
+require_relative "turnkit/coordination_tools"
+require_relative "turnkit/specialists"
 
 module TurnKit
   class << self
@@ -62,6 +68,29 @@ module TurnKit
     attr_accessor :prompt_sections, :prompt_behavior, :available_skills
     attr_accessor :prompt_data_max_chars, :context_contributors
     attr_accessor :on_event
+    attr_accessor :job_dispatcher
+    attr_accessor :authorization_policy, :maintenance_batch_size
+    attr_reader :agents
+  end
+
+  @agents = {}
+
+  def self.register(agent)
+    @agents[agent.name] = agent
+    agent.sub_agents.each { |child| register(child) }
+    agent
+  end
+
+  def self.resolve_agent(name)
+    @agents.fetch(name.to_s) { raise ConfigError, "register agent #{name.inspect} in every worker at boot" }
+  end
+
+  def self.load_turn(id)
+    Background.load_turn(id)
+  end
+
+  def self.load_conversation(id)
+    Background.load_conversation(id)
   end
 
   self.default_model = "claude-sonnet-4-5"
@@ -83,15 +112,15 @@ module TurnKit
   self.on_event = nil
   self.output_policy_model = nil
   self.output_policy_thinking = { effort: :low }
+  self.authorization_policy = nil
+  self.maintenance_batch_size = 100
 
   def self.configure
     yield self
   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,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: turnkit
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.6.0
 platform: ruby
 authors:
 - Sam Couch
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-07-02 00:00:00.000000000 Z
+date: 2026-09-06 00:00:00.000000000 Z
 dependencies: []
 description: TurnKit is a Ruby/Rails agent runtime for durable AI conversations, application
   runs, orchestrator agents, tool calling, skills, sub-agents, context compaction,
@@ -26,27 +26,36 @@ files:
 - 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/delivery.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/templates/wait.rb
 - lib/generators/turnkit/install_generator.rb
+- lib/generators/turnkit/upgrade/templates/add_turnkit_durable_orchestration.rb
+- lib/generators/turnkit/upgrade_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
+- lib/turnkit/authorization.rb
+- lib/turnkit/background.rb
 - lib/turnkit/budget.rb
 - lib/turnkit/client.rb
 - lib/turnkit/clock.rb
 - lib/turnkit/compaction.rb
 - lib/turnkit/conversation.rb
+- lib/turnkit/coordination_tools.rb
 - lib/turnkit/cost.rb
 - lib/turnkit/error.rb
 - lib/turnkit/event.rb
+- lib/turnkit/execution_store.rb
 - lib/turnkit/id.rb
 - lib/turnkit/image_result.rb
 - lib/turnkit/image_tool.rb
+- lib/turnkit/job.rb
 - lib/turnkit/load_skill_tool.rb
 - lib/turnkit/media_analysis_result.rb
 - lib/turnkit/media_input.rb
@@ -58,11 +67,13 @@ files:
 - lib/turnkit/output_policy.rb
 - lib/turnkit/prompt_context.rb
 - lib/turnkit/prompt_data.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/specialists.rb
 - lib/turnkit/store.rb
 - lib/turnkit/sub_agent_tool.rb
 - lib/turnkit/system_prompt.rb
@@ -83,7 +94,7 @@ metadata:
   changelog_uri: https://github.com/samuelcouch/turnkit/blob/master/CHANGELOG.md
   allowed_push_host: https://rubygems.org
   rubygems_mfa_required: 'true'
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -99,7 +110,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.5.22
-signing_key:
+signing_key: 
 specification_version: 4
 summary: Ruby/Rails agent runtime for durable AI conversations, runs, and orchestrator
   agents.