turnkit 0.5.0 → 0.7.0

data/lib/turnkit/turn.rb

@@ -2,6 +2,7 @@
 
 module TurnKit
   class Turn
+    include TurnControls
     STATUSES = Record::TURN_STATUSES
 
     attr_reader :agent, :conversation, :store, :budget, :depth
@@ -13,6 +14,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 +38,92 @@ 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!
+      store.atomic do
+        reload
+        update!(status: @record.dig("options", "controls", "pause_requested") ? "paused" : "waiting", claim_token: nil)
+      end
+    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 +144,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 +214,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 +253,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 +288,98 @@ 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
+          control = control_boundary!
+          break if control == :paused
+          if control == :waiting
+            suspend!
+            break
+          end
+          @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)
+            control = control_boundary!
+            break if control == :paused
+            next if control
+            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)
+            break if terminal == :paused
+            next if terminal == :steered
+            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 unless status == "running"
+            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,12 +393,12 @@ 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,
           output_schema: output_schema,
-          metadata: { turn_id: id, conversation_id: conversation.id },
+          metadata: { turn_id: id, conversation_id: conversation.id, request_id: @record.dig("options", "state", "request_id") },
           report: prompt.report
         )
       end
@@ -291,15 +419,30 @@ 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
-        MessageProjection.for(TurnKit::Compaction.project(conversation.messages_for_turn(self)))
+        messages = TurnKit::Compaction.project(conversation.messages_for_turn(self))
+        # Delivery time is not application time. A next-turn message can arrive
+        # between an earlier turn's tool call/result or before its steering.
+        # Keep UI sequence order intact, but place each delivery at the frozen
+        # context boundary of its first receiving turn in the provider input.
+        turns = store.list_turns(conversation_id: conversation.id)
+        messages = messages.sort_by do |message|
+          delivery_id = message.metadata["delivery_id"]
+          receiver = if delivery_id
+            turns.find { |row| row.dig("options", "state", "delivery_requests", delivery_id) } ||
+              turns.find { |row| row["context_message_sequence"] >= message.sequence &&
+                (row["submitted_at"] || row["started_at"] || row["id"] == id) }
+          end
+          receiver ? [receiver.fetch("context_message_sequence"), 1, message.sequence] : [message.sequence, 0, 0]
+        end
+        MessageProjection.for(messages)
       end
 
       def emit_model_requested(type, request)
@@ -362,7 +505,7 @@ module TurnKit
           message = conversation.append_message(role: "assistant", kind: "media_analysis", content: result.media_analyses.map { |analysis| analysis.to_h.merge("type" => "media_analysis") }, turn_id: id, metadata: { "output_data" => result.output_data }.compact)
           emit("message.created", message_id: message.id, role: message.role, kind: message.kind)
         else
-          message = conversation.append_message(role: "assistant", kind: "text", text: result.text, turn_id: id, metadata: { "output_data" => result.output_data }.compact)
+          message = conversation.append_message(role: "assistant", kind: "text", content: result.parts, turn_id: id, metadata: { "output_data" => result.output_data }.compact)
           emit("message.created", message_id: message.id, role: message.role, kind: message.kind)
         end
       end
@@ -392,8 +535,15 @@ module TurnKit
         else
           attrs[:status] = "completed"
         end
-        update!(attrs)
-        persist_policy_audit(audit) if audit
+        controlled = store.atomic(Background.root_conversation(store, @record)) do
+          control = control_boundary!
+          next control if control
+          update_state!("policy_audit" => audit.to_h) if audit
+          update!(attrs)
+          nil
+        end
+        return if controlled
+        emit("output_policy.completed", clean: audit.clean?, violation_count: audit.violations.length) if audit
 
         if failed?
           emit("turn.failed", error: @record["error"])
@@ -410,11 +560,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,20 +607,35 @@ 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!
+          request_id = SecureRandom.uuid
+          options = store.load_turn(id).fetch("options")
+          controls = options["controls"] || {}
+          inputs = controls.fetch("inputs", []).map do |input|
+            input["message_id"] && !input["request_id"] ? input.merge("request_id" => request_id) : input
+          end
+          update!(options: options.merge("controls" => controls.merge("inputs" => inputs)))
+          deliveries = options.dig("state", "delivery_requests") || {}
+          conversation.messages_for_turn(self).each do |message|
+            delivery_id = message.metadata["delivery_id"]
+            deliveries[delivery_id] ||= request_id if delivery_id
+          end
+          update_state!("iterations" => Turn.iterations_for(@record) + 1, "request_id" => request_id, "delivery_requests" => deliveries)
+        end
       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"] || {}
+        options = store.load_turn(id)["options"] || {}
         update!(options: options.merge("state" => (options["state"] || {}).merge(changes)))
       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 +646,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 +676,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 +709,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/turn_controls.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module TurnKit
+  # Human controls share the execution root lock. Options are the durable
+  # source of truth; no callbacks or job payloads are needed for recovery.
+  module TurnControls
+    def pause!(descendants: :retain, principal: nil)
+      control_tree(:pause, descendants, principal) do |row|
+        controls = row.dig("options", "controls") || {}
+        attrs = { options: row.fetch("options").merge("controls" => controls.merge("pause_requested" => true)) }
+        attrs[:status] = "paused" unless row["status"] == "running"
+        @base_store.update_turn(row.fetch("id"), attrs)
+      end
+      reload
+    end
+
+    def resume!(descendants: :retain, principal: nil)
+      control_tree(:resume, descendants, principal) do |row|
+        controls = row.dig("options", "controls") || {}
+        attrs = { options: row.fetch("options").merge("controls" => controls.merge("pause_requested" => false)) }
+        if row["status"] == "paused"
+          attrs[:status] = Background.ready?(@base_store, row.fetch("id")) ? "pending" : "waiting"
+        end
+        @base_store.update_turn(row.fetch("id"), attrs)
+      end
+      Background.enqueue if background?
+      reload
+    end
+
+    def steer!(text, key:, principal: nil, descendants: :retain)
+      raise ArgumentError, "key must be a nonempty string" unless key.is_a?(String) && !key.empty?
+      text = text.to_s
+      principal = JSON.parse(JSON.generate(principal))
+      receipts = []
+      control_tree(:steer, descendants, principal) do |row|
+        controls = row.dig("options", "controls") || {}
+        inputs = controls.fetch("inputs", [])
+        existing = inputs.find { |input| input["key"] == key }
+        if existing
+          unless existing["text"] == text && existing["principal"] == principal
+            raise ToolError, "steering key is already used for a different input"
+          end
+          receipts << existing
+          next
+        end
+        if Background::TERMINAL.include?(row["status"]) || row["status"] == "stale"
+          raise Error, "cannot steer a #{row['status']} turn; post next-turn input instead" if row["id"] == id
+          next
+        end
+        input = { "id" => SecureRandom.uuid, "key" => key, "text" => text,
+          "principal" => principal, "turn_id" => row.fetch("id"), "sequence" => inputs.length + 1 }
+        @base_store.update_turn(row.fetch("id"), options: row.fetch("options").merge(
+          "controls" => controls.merge("inputs" => inputs + [input])))
+        receipts << input
+      end
+      receipts
+    end
+
+    def control_state(principal: nil)
+      Authorization.authorize!(:read_control, principal: principal, turn: self)
+      row = @base_store.load_turn(id)
+      { "status" => row.fetch("status"), "controls" => row.dig("options", "controls") || {} }
+    end
+
+    # Called before dispatching another unit of work, never during a remote
+    # call. The lock acquisition is the dispatch/control linearization point.
+    def control_boundary!
+      store.atomic do
+        reload
+        if @record.dig("options", "controls", "pause_requested")
+          update!(status: "paused", claim_token: nil)
+          next :paused
+        end
+        inputs = @record.dig("options", "controls", "inputs") || []
+        pending = inputs.reject { |input| input["message_id"] }
+        next unless pending.any?
+        unless Background.ready?(store, id)
+          next Background.deadline_exceeded?(store, @record) ? nil : :waiting
+        end
+
+        executions = store.list_tool_executions(turn_id: id)
+        parts = @record.dig("options", "state", "parts") || []
+        parts.select { |part| part["type"] == "tool_call" }.each do |part|
+          execution = executions.find { |row| row["tool_call_id"] == part["id"] }
+          child = store.list_turns(root_turn_id: root_turn_id).find { |row| execution && row["parent_tool_execution_id"] == execution["id"] }
+          if child && Background::TERMINAL.include?(child["status"]) && %w[pending running].include?(execution["status"])
+            store.claim_tool_execution(execution.fetch("id"), from: execution.fetch("status"), to: "completed",
+              result: SubAgentTool.result(child), completed_at: Clock.now)
+          elsif !execution
+            store.create_tool_execution("turn_id" => id, "tool_call_id" => part.fetch("id"), "tool_name" => part.fetch("name"),
+              "arguments" => part["arguments"], "status" => "cancelled", "completed_at" => Clock.now,
+              "result" => { "skipped" => true, "message" => "not executed: superseded by human steering" })
+          end
+        end
+        executions = Reconciliation.interrupt_tool_executions(@record, store: store)
+        # Complete known results and close unexecuted proposals before adding
+        # human input: providers require a result for every assistant tool ID.
+        Reconciliation.repair_transcript(@record, executions, store: store)
+        pending.each do |input|
+          message = conversation.append_message(role: "user", kind: "text", text: input.fetch("text"), turn_id: id,
+            metadata: { "steering_id" => input.fetch("id"), "principal" => input["principal"] })
+          input["message_id"] = message.id
+        end
+        options = @record.fetch("options")
+        update!(options: options.merge("controls" => options.fetch("controls").merge("inputs" => inputs)))
+        update_state!("phase" => "model", "parts" => nil, "candidate" => nil, "output_data" => nil, "terminal_tool_name" => nil)
+        :steered
+      end
+    end
+
+    private
+      def control_tree(action, descendants, principal)
+        raise ArgumentError, "descendants must be :retain or :cascade" unless %i[retain cascade].include?(descendants)
+        @base_store.atomic(Background.root_conversation(@base_store, @record)) do
+          rows = [@base_store.load_turn(id)]
+          if descendants == :cascade
+            all = @base_store.list_turns(root_turn_id: root_turn_id)
+            loop do
+              ids = rows.map { |row| row.fetch("id") }
+              added = all.select { |row| ids.include?(row["parent_turn_id"]) && !ids.include?(row["id"]) }
+              break if added.empty?
+              rows.concat(added)
+            end
+          end
+          rows.each do |row|
+            Authorization.authorize!(action, principal: principal,
+              turn: row["id"] == id ? self : Background.load_turn(row.fetch("id"), store: @base_store), descendants: descendants)
+          end
+          rows.each do |row|
+            next if action != :steer && (Background::TERMINAL.include?(row["status"]) || row["status"] == "stale")
+            yield row
+          end
+        end
+      end
+  end
+end

data/lib/turnkit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TurnKit
-  VERSION = "0.5.0"
+  VERSION = "0.7.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"
@@ -44,12 +45,17 @@ require_relative "turnkit/sub_agent_tool"
 require_relative "turnkit/load_skill_tool"
 require_relative "turnkit/message_projection"
 require_relative "turnkit/tool_runner"
+require_relative "turnkit/turn_controls"
 require_relative "turnkit/turn"
 require_relative "turnkit/usage"
 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
@@ -63,6 +69,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"
@@ -84,6 +113,8 @@ 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