turnkit 0.5.0 → 0.7.0

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 or paused turns can be submitted" unless %w[pending paused].include?(record["status"])
+        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: record["status"] == "paused" ? "paused" : 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 paused].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"), "principal" => delivery.dig("payload", "principal"), "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.map { |row| store.load_turn(row.fetch("id")) }.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

data/lib/turnkit/budget.rb

@@ -30,9 +30,9 @@ module TurnKit
     def seed!(turns:, tool_executions:)
       @mutex.synchronize do
         @iterations = Array(turns).sum { |turn| Turn.iterations_for(turn) }
-        completed = Array(tool_executions).select { |execution| %w[completed failed].include?(execution["status"]) && !execution.dig("error", "details", "budget_denied") }
-        @tool_executions = completed.length
-        completed.each { |execution| @tool_executions_by_name[execution.fetch("tool_name").to_s] += 1 }
+        reserved = Array(tool_executions).reject { |execution| execution["status"] == "cancelled" || execution.dig("error", "details", "budget_denied") }
+        @tool_executions = reserved.length
+        reserved.each { |execution| @tool_executions_by_name[execution.fetch("tool_name").to_s] += 1 }
         @cost = Array(turns).sum { |turn| turn["cost"].to_f }
       end
       self
@@ -74,6 +74,7 @@ module TurnKit
     def check!(depth:)
       raise BudgetError, "maximum sub-agent depth reached" if max_depth && depth > max_depth
       raise BudgetError, "turn timed out" if timeout && Clock.now >= root_started_at + timeout
+      raise BudgetError, "cost limit reached" if max_spend && @cost > max_spend
     end
 
     private

data/lib/turnkit/client.rb

@@ -4,7 +4,9 @@ module TurnKit
   # The adapter contract. TurnKit calls clients with the full keyword
   # signatures below. Custom adapters should subclass TurnKit::Client (or
   # accept the same keywords) and must not execute tools themselves; TurnKit
-  # runs tools and persists their results.
+  # runs tools and persists their results. Messages may include :provider_parts
+  # for opaque continuation state from Result parts with type "provider".
+  # Adapters should consume only their own provider kind, never display it.
   class Client
     def validate!(model:)
       true

data/lib/turnkit/conversation.rb

@@ -20,6 +20,55 @@ module TurnKit
       append_message(role: "user", kind: "text", text: text, metadata: metadata)
     end
 
+    # Destination-oriented, durable next-turn input. The destination is also
+    # the delivery's source; the application need not create a sender agent.
+    def post(text, key:, principal: nil)
+      Authorization.authorize!(:send_message, principal: principal, source_conversation: id, destination_conversation: id)
+      delivery = store.create_delivery("source_conversation_id" => id, "destination_conversation_id" => id,
+        "key" => key, "payload" => { "text" => text, "principal" => principal })
+      Background.enqueue
+      delivery
+    end
+
+    def messages_after(sequence, principal: nil)
+      Authorization.authorize!(:read_messages, principal: principal, destination_conversation: id)
+      messages.select { |message| message.sequence > sequence }.map do |message|
+        # Provider thinking/signature parts are not application progress.
+        attrs = message.to_h
+        attrs["content"] = Array(attrs["content"]).reject { |part| %w[thinking provider].include?(part["type"]) }
+        Message.new(attrs)
+      end
+    end
+
+    def input_status(delivery_id, principal: nil)
+      Authorization.authorize!(:read_control, principal: principal, destination_conversation: id)
+      delivery = store.load_delivery(delivery_id)
+      raise ArgumentError, "delivery belongs to another conversation" unless delivery["destination_conversation_id"] == id
+      applied = store.list_turns(conversation_id: id).filter_map do |row|
+        request = row.dig("options", "state", "delivery_requests", delivery_id)
+        { "turn_id" => row.fetch("id"), "request_id" => request } if request
+      end.first
+      delivery.merge("application" => applied, "status" => applied ? "applied" : "pending")
+    end
+
+    def subject_prompt
+      subject.respond_to?(:to_prompt) ? subject.to_prompt.to_s : metadata["turnkit_subject_prompt"].to_s
+    end
+
+    def send_message(destination, text, key:, principal: nil)
+      Authorization.authorize!(:send_message, principal: principal, source_conversation: id, destination_conversation: destination.respond_to?(:id) ? destination.id : destination)
+      Background.send_message(source: id, destination: destination.respond_to?(:id) ? destination.id : destination,
+        text: text, key: key, store: store, principal: principal)
+    end
+
+    def inbox
+      store.list_deliveries(destination_conversation_id: id)
+    end
+
+    def outbox
+      store.list_deliveries(source_conversation_id: id)
+    end
+
     def ask(text, async: false, **options)
       trigger = say(text)
       turn = build_turn(trigger_message_id: trigger.id, **options)
@@ -30,14 +79,18 @@ module TurnKit
       build_turn(trigger_message_id: trigger_message_id, model: model, budget: budget, parent_turn: parent_turn, parent_tool_execution: parent_tool_execution, root_turn_id: root_turn_id, depth: depth, agent: agent, thinking: thinking, compact: compact, output_schema: output_schema, prompt_mode: prompt_mode, on_event: on_event).run!
     end
 
-    def build_turn(trigger_message_id: nil, model: nil, budget: nil, parent_turn: nil, parent_tool_execution: nil, root_turn_id: nil, depth: 0, agent: self.agent, thinking: THINKING_UNSET, compact: nil, output_schema: nil, prompt_mode: nil, on_event: nil)
+    def build_turn(trigger_message_id: nil, model: nil, budget: nil, parent_turn: nil, parent_tool_execution: nil, root_turn_id: nil, depth: 0, agent: self.agent, thinking: THINKING_UNSET, compact: nil, output_schema: nil, prompt_mode: nil, on_event: nil, context: nil, principal: nil)
       snapshot = latest_message_sequence
       effective_thinking = thinking.equal?(THINKING_UNSET) ? agent.effective_thinking : Agent.normalize_thinking(thinking)
       options = { "trigger_message_id" => trigger_message_id }.compact
+      options["budget_limits"] = agent.budget_limits.transform_keys(&:to_s)
       options["thinking"] = effective_thinking
       options["compact"] = compact unless compact.nil?
       options["output_schema"] = output_schema || agent.output_schema if output_schema || agent.output_schema
       options["prompt_mode"] = prompt_mode.to_sym if prompt_mode
+      options["context"] = JSON.parse(JSON.generate(context || metadata["turnkit_context"] || {}))
+      principal ||= metadata["principal"]
+      options["principal"] = JSON.parse(JSON.generate(principal)) unless principal.nil?
       record = store.create_turn(
         "conversation_id" => id,
         "agent_name" => agent.name,

data/lib/turnkit/coordination_tools.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module TurnKit
+  # Opt-in tools: the application chooses which agents can address conversations.
+  class SendMessageTool < Tool
+    tool_name "send_message"
+    description "Send a durable message to a conversation and wake it when idle."
+    parameter :conversation_id, :string, required: true
+    parameter :text, :string, required: true
+
+    def call(conversation_id:, text:, context:)
+      Background.send_message(source: context.turn.conversation.id, destination: conversation_id,
+        text: text, key: "message:#{context.execution.id}", store: context.turn.store, source_turn_id: context.turn.id, principal: context.principal)
+    end
+  end
+
+  class LaunchAgentTool < Tool
+    tool_name "launch_agent"
+    description "Launch a configured sub-agent independently. Returns IDs immediately; optionally receive a completion message."
+    parameter :agent_name, :string, required: true
+    parameter :task, :string, required: true
+    parameter :callback, :boolean, required: false
+
+    def call(agent_name:, task:, callback: false, context:)
+      parent = context.turn
+      agent = parent.agent.sub_agents.find { |candidate| candidate.name == agent_name }
+      raise ToolError, "unknown sub-agent: #{agent_name}" unless agent
+      Authorization.authorize!(:launch_agent, principal: context.principal, turn: parent, agent: agent, arguments: { "task" => task, "callback" => callback })
+      Authorization.authorize!(:callback, principal: context.principal, turn: parent.id, destination_conversation: parent.conversation.id) if callback
+      TurnKit.resolve_agent(agent.name)
+      child = nil
+      parent.store.atomic do
+        control = parent.control_boundary!
+        if control
+          child = control
+          next
+        end
+        existing = parent.store.list_turns(root_turn_id: parent.root_turn_id).find { |row| row["parent_tool_execution_id"] == context.execution.id }
+        if existing
+          child = existing
+        else
+          built = SubAgentTool.for(agent).build_child(task: task, context: context)
+          options = parent.store.load_turn(built.id).fetch("options")
+          options = options.merge("callback_conversation_id" => parent.conversation.id) if callback
+          child = parent.store.update_turn(built.id, submitted_at: Clock.now, options: options)
+        end
+      end
+      return child if child.is_a?(Symbol)
+      Background.enqueue(child.fetch("id"))
+      SubAgentTool.result(child)
+    end
+  end
+
+  class WaitTool < Tool
+    tool_name "wait_for"
+    description "Suspend this background turn until all listed turns finish. Releases the worker while waiting."
+    parameter :turn_ids, :array, required: true
+
+    def call(turn_ids:, context:)
+      raise ToolError, "wait_for requires a background turn" unless context.turn.background?
+      ids = Background.wait(context.turn, turn_ids)
+      return :waiting unless Background.ready?(context.turn.store, context.turn.id)
+
+      { "results" => ids.map { |id| SubAgentTool.result(context.turn.store.load_turn(id)) } }
+    end
+  end
+end

data/lib/turnkit/cost.rb

@@ -73,13 +73,13 @@ module TurnKit
       return new unless defined?(::RubyLLM) && model
 
       model_info = ::RubyLLM.models.find(model)
-      tokens = ::RubyLLM::Tokens.new(
-        input: usage.input_tokens,
-        output: usage.output_tokens,
-        cached: usage.cached_tokens,
-        cache_creation: usage.cache_write_tokens,
-        thinking: usage.thinking_tokens
-      )
+      tokens = if ::RubyLLM::Chat.method_defined?(:generate)
+        ::RubyLLM::Tokens.new(input: usage.input_tokens, output: usage.output_tokens + usage.thinking_tokens,
+          cache_read: usage.cached_tokens, cache_write: usage.cache_write_tokens, thinking: usage.thinking_tokens)
+      else
+        ::RubyLLM::Tokens.new(input: usage.input_tokens, output: usage.output_tokens,
+          cached: usage.cached_tokens, cache_creation: usage.cache_write_tokens, thinking: usage.thinking_tokens)
+      end
       from_hash(::RubyLLM::Cost.new(tokens: tokens, model: model_info).to_h)
     rescue ::RubyLLM::ModelNotFoundError
       new

data/lib/turnkit/error.rb

@@ -2,12 +2,15 @@
 
 module TurnKit
   class Error < StandardError; end
+  class AuthorizationError < Error; end
   class BudgetError < Error; end
   class ConfigError < Error; end
   class CompactionError < Error; end
   class InputError < Error; end
   class ModelAccessError < ConfigError; end
+  class ModelError < Error; end
   class StoreError < Error; end
+  class LostClaim < Error; end
   class ToolError < Error; end
   class ToolValidationError < ToolError; end
 end

data/lib/turnkit/execution_store.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module TurnKit
+  # All writes made by an execution, including writes by tools and compaction,
+  # are fenced by the same root lock used to revoke its claim.
+  class ExecutionStore < SimpleDelegator
+    def initialize(store, turn_id:, token:, conversation_id:)
+      super(store)
+      @turn_id, @token, @conversation_id = turn_id, token, conversation_id
+    end
+
+    def atomic(_conversation_id = nil)
+      __getobj__.atomic(@conversation_id) do
+        raise LostClaim, "turn ownership was revoked" unless load_turn(@turn_id)["claim_token"] == @token
+
+        yield
+      end
+    end
+
+    %i[create_conversation append_message next_message_sequence create_turn update_turn
+       claim_turn create_tool_execution claim_tool_execution create_delivery update_delivery
+       create_wait].each do |method|
+      define_method(method) do |*args, **kwargs|
+        atomic { __getobj__.public_send(method, *args, **kwargs) }
+      end
+    end
+  end
+end

data/lib/turnkit/id.rb

@@ -6,6 +6,7 @@ module TurnKit
       conversation: "conv",
       message: "msg",
       turn: "turn",
+      delivery: "delivery",
       tool_execution: "tool"
     }.freeze
 

data/lib/turnkit/image_tool.rb

@@ -18,11 +18,21 @@ module TurnKit
         provider: self.class.provider,
         size: self.class.size,
         assume_model_exists: self.class.assume_model_exists,
+        input_images: input_images(**arguments),
+        mask: mask(**arguments),
         params: self.class.params || {},
         metadata: metadata(**arguments)
       ).to_h
     end
 
+    def input_images(**)
+      nil
+    end
+
+    def mask(**)
+      nil
+    end
+
     def metadata(**)
       {}
     end

data/lib/turnkit/job.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+gem "activejob", ">= 7.2"
+gem "activerecord", ">= 7.2"
+require "active_job"
+require "active_record"
+
+module TurnKit
+  class Job < ActiveJob::Base
+    def perform(turn_id = nil)
+      Background.perform(turn_id)
+    end
+  end
+
+  # Schedule with the application's existing recurring-job facility.
+  class ReconcileJob < ActiveJob::Base
+    def perform
+      Background.reconcile
+    end
+  end
+end