turnkit 0.5.0 → 0.6.0

data/lib/turnkit/tool_runner.rb

@@ -7,14 +7,22 @@ module TurnKit
     end
 
     def dispatch(tool_calls)
+      waiting = false
       tool_calls.each_with_index do |tool_call, index|
-        execution = run(tool_call)
+        # Fan out a contiguous group of subagents, but never reorder ordinary
+        # tools across it or execute past a terminal tool.
+        return :waiting if waiting && !subagent?(tool_for(tool_call.name))
+        execution = run(tool_call, defer_result: waiting)
+        if execution == :waiting
+          waiting = true
+          next
+        end
         if execution.completed? && tool_for(tool_call.name)&.ends_turn?
           skip_remaining(tool_calls.drop(index + 1), terminal: tool_call)
           return execution
         end
       end
-      nil
+      waiting ? :waiting : nil
     end
 
     def completion_message(execution)
@@ -25,11 +33,30 @@ module TurnKit
     private
       attr_reader :turn
 
-      def run(tool_call)
-        execution = ToolExecution.new(create_execution(tool_call))
-        heartbeat!
-
+      def run(tool_call, defer_result: false)
+        @defer_result = defer_result
         tool = tool_for(tool_call.name)
+        existing = turn.store.list_tool_executions(turn_id: turn.id).find { |row| row["tool_call_id"] == tool_call.id }
+        if existing && !%w[pending running].include?(existing["status"])
+          execution = ToolExecution.new(existing)
+          append_result_once(execution, tool_call, execution.result || execution.error, error: !execution.completed? && !execution.cancelled?)
+          return execution
+        end
+
+        denied = nil
+        execution = turn.store.atomic do
+          execution = ToolExecution.new(existing || create_execution(tool_call))
+          unless existing
+            begin
+              turn.execution_budget(excluding: execution.id).count_tool_execution!(tool_call.name)
+            rescue BudgetError => error
+              denied = error
+              finish_error(execution, tool_call, error.message, details: { "class" => error.class.name, "budget_denied" => true })
+            end
+          end
+          execution
+        end
+        raise denied if denied
 
         unless tool
           return finish_error(execution, tool_call, "unknown tool: #{tool_call.name}")
@@ -39,20 +66,33 @@ module TurnKit
           return finish_error(execution, tool_call, tool_call.arguments_error)
         end
 
-        begin
-          turn.budget.count_tool_execution!(tool_call.name)
-        rescue BudgetError => error
-          finish_error(execution, tool_call, error.message, details: { "class" => error.class.name, "budget_denied" => true })
-          raise
+        if execution.status == "pending" && !subagent?(tool) && ![WaitTool, LaunchAgentTool, SendMessageTool].include?(tool)
+          claimed = turn.store.claim_tool_execution(execution.id, from: "pending", to: "running", started_at: Clock.now)
+          raise LostClaim, "tool execution claim was revoked" unless claimed
+          execution = ToolExecution.new(claimed)
         end
 
         context = ToolContext.new(turn: turn, execution: execution)
         payload = begin
-          normalize_payload(call_tool(tool, tool_call.arguments, context: context))
+          Authorization.authorize!(:tool, principal: context.principal, turn: turn, tool: tool, arguments: tool_call.arguments)
+          # Observe cancellation/reconciliation immediately before crossing the
+          # external-effect boundary. Calls already sent cannot be recalled.
+          turn.store.atomic { true }
+          if turn.background? && subagent?(tool)
+            return delegate(tool, tool_call, context)
+          end
+          value = call_tool(tool, tool_call.arguments, context: context)
+          return :waiting if value == :waiting && tool == WaitTool
+          normalize_payload(value)
+        rescue LostClaim
+          raise
         rescue BudgetError => error
           finish_error(execution, tool_call, error.message, details: { "class" => error.class.name, "budget_denied" => true })
           raise
+        rescue AuthorizationError => error
+          return finish_error(execution, tool_call, error.message, details: { "class" => error.class.name, "authorization_denied" => true })
         rescue StandardError => error
+          raise if turn.background? && !error.is_a?(ToolError)
           return finish_error(execution, tool_call, error.message, details: { "class" => error.class.name })
         end
         finish_success(execution, tool_call, payload)
@@ -63,7 +103,7 @@ module TurnKit
           "turn_id" => turn.id,
           "tool_call_id" => tool_call.id,
           "tool_name" => tool_call.name,
-          "status" => "running",
+          "status" => turn.background? && (subagent?(tool_for(tool_call.name)) || [WaitTool, LaunchAgentTool, SendMessageTool].include?(tool_for(tool_call.name))) ? "pending" : "running",
           "arguments" => tool_call.arguments,
           "started_at" => Clock.now
         )
@@ -71,11 +111,12 @@ module TurnKit
 
       def finish_success(execution, tool_call, payload)
         json = payload.to_json
-        attrs = turn.store.claim_tool_execution(execution.id, from: "running", to: "completed", result: payload, completed_at: Clock.now)
+        attrs = turn.store.atomic do
+          row = turn.store.claim_tool_execution(execution.id, from: execution.status, to: "completed", result: payload, completed_at: Clock.now)
+          append_result_once(execution, tool_call, payload) if row
+          row
+        end
         return superseded_execution(execution) unless attrs
-
-        append_result(execution, tool_call, payload, json: json, error: false)
-        heartbeat!
         turn.emit("tool_call.completed", id: tool_call.id, name: tool_call.name, result_chars: json.length)
         ToolExecution.new(attrs)
       end
@@ -83,11 +124,12 @@ module TurnKit
       def finish_error(execution, tool_call, message, details: nil)
         error = { "message" => message.to_s, "details" => details }.compact
         json = error.to_json
-        attrs = turn.store.claim_tool_execution(execution.id, from: "running", to: "failed", error: error, completed_at: Clock.now)
+        attrs = turn.store.atomic do
+          row = turn.store.claim_tool_execution(execution.id, from: execution.status, to: "failed", error: error, completed_at: Clock.now)
+          append_result_once(execution, tool_call, error, error: true) if row
+          row
+        end
         return superseded_execution(execution) unless attrs
-
-        append_result(execution, tool_call, error, json: json, error: true)
-        heartbeat!
         turn.emit("tool_call.failed", id: tool_call.id, name: tool_call.name, error: error, result_chars: json.length)
         ToolExecution.new(attrs)
       end
@@ -98,11 +140,14 @@ module TurnKit
         ToolExecution.new(turn.store.load_tool_execution(execution.id))
       end
 
-      def append_result(execution, tool_call, payload, json: payload.to_json, error: false)
+      def append_result_once(execution, tool_call, payload, error: false)
+        return if @defer_result
+        return if turn.store.list_messages(turn.conversation.id).any? { |row| row["tool_execution_id"] == execution.id }
+
         message = turn.conversation.append_message(
           role: "tool",
           kind: "tool_result",
-          content: [ { "type" => "tool_result", "tool_call_id" => tool_call.id, "text" => json, "error" => error } ],
+          content: [ { "type" => "tool_result", "tool_call_id" => tool_call.id, "text" => payload.to_json, "error" => error } ],
           turn_id: turn.id,
           tool_execution_id: execution.id,
           metadata: { "tool_name" => tool_call.name }
@@ -112,42 +157,53 @@ module TurnKit
 
       def skip_remaining(calls, terminal:)
         calls.each do |call|
-          payload = { "skipped" => true, "message" => "not executed: turn ended by #{terminal.name}" }
-          execution = ToolExecution.new(create_execution(call))
-          attrs = turn.store.claim_tool_execution(execution.id, from: "running", to: "cancelled", result: payload, completed_at: Clock.now)
-          next unless attrs
-
-          append_result(ToolExecution.new(attrs), call, payload)
-          turn.emit("tool_call.skipped", id: call.id, name: call.name)
+          turn.store.atomic do
+            next if turn.store.list_tool_executions(turn_id: turn.id).any? { |row| row["tool_call_id"] == call.id }
+            payload = { "skipped" => true, "message" => "not executed: turn ended by #{terminal.name}" }
+            execution = ToolExecution.new(create_execution(call))
+            attrs = turn.store.claim_tool_execution(execution.id, from: execution.status, to: "cancelled", result: payload, completed_at: Clock.now)
+            append_result_once(ToolExecution.new(attrs), call, payload)
+            turn.emit("tool_call.skipped", id: call.id, name: call.name)
+          end
         end
       end
 
-      def heartbeat!
-        turn.send(:heartbeat!)
+      def subagent?(tool)
+        tool.is_a?(Class) && tool < SubAgentTool
+      end
+
+      def delegate(tool, call, context)
+        arguments = tool.validate_arguments(call.arguments)
+        Authorization.authorize!(:launch_agent, principal: context.principal, turn: turn, agent: tool.agent, arguments: arguments)
+        TurnKit.resolve_agent(tool.agent.name)
+        child = turn.store.atomic_graph do
+          turn.store.atomic(Background.root_conversation(turn.store, turn.store.load_turn(turn.id))) do
+            row = turn.store.list_turns(root_turn_id: turn.root_turn_id).find { |candidate| candidate["parent_tool_execution_id"] == context.execution.id }
+            unless row
+              built = tool.build_child(task: arguments.fetch("task"), context: context)
+              row = turn.store.update_turn(built.id, submitted_at: Clock.now)
+            end
+            Background.wait(turn, [row.fetch("id")])
+            row
+          end
+        end
+        unless Background::TERMINAL.include?(child["status"])
+          Background.enqueue(child.fetch("id")) if child["status"] == "pending"
+          return :waiting
+        end
+        finish_success(context.execution, call, SubAgentTool.result(child))
       end
 
       def tool_for(name)
-        turn.agent.effective_tools.find { |tool| tool.tool_name == name.to_s }
+        turn.agent.effective_tools(turn: turn).find { |tool| tool.tool_name == name.to_s }
       end
 
-      # Heartbeats while the tool runs so a tool slower than TurnKit.timeout
-      # keeps its turn's stale anchor fresh and is not falsely reconciled.
       def call_tool(tool, arguments, context:)
-        interval = (TurnKit.timeout || 300) / 3.0
-        heartbeat = Thread.new do
-          loop do
-            sleep interval
-            heartbeat!
-          end
-        end
-
         if tool.is_a?(Class)
           tool.call(arguments, context: context)
         else
           tool.class.invoke(tool, arguments, context: context)
         end
-      ensure
-        heartbeat.kill
       end
 
       def normalize_payload(value)

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.5.0"
+  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"
@@ -50,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
@@ -63,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"
@@ -84,6 +112,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