turnkit 0.5.0 → 0.7.0

data/lib/turnkit/active_record_store.rb

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

data/lib/turnkit/adapters/ruby_llm.rb

@@ -10,9 +10,16 @@ module TurnKit
         openrouter: "OPENROUTER_API_KEY"
       }.freeze
 
+      def initialize(protocol: nil)
+        @protocol = protocol
+      end
+
       def validate!(model:)
         ensure_ruby_llm!
         raise ModelAccessError, "model is required" if model.to_s.empty?
+        if @protocol && !::RubyLLM::Chat.method_defined?(:generate)
+          raise ConfigError, "protocol selection requires RubyLLM 2.0 (currently 2.0.0.rc2)"
+        end
 
         configure_from_environment
         provider = provider_for(model)
@@ -27,16 +34,27 @@ module TurnKit
         ensure_ruby_llm!
         configure_from_environment
 
-        chat = ::RubyLLM.chat(model: model)
+        validate!(model: model) if @protocol
+        chat = ::RubyLLM.chat(**{ model: model, protocol: @protocol }.compact)
+        chat.with_provider_options(metadata: metadata.transform_values(&:to_s)) if @protocol == :responses && metadata
         add_instructions(chat, instructions, dynamic_instructions, model: model)
         chat.with_temperature(temperature) if temperature
         apply_thinking(chat, thinking)
         chat.with_schema(normalize_schema(output_schema)) if output_schema
-        Array(tools).each { |tool| chat.with_tool(ruby_llm_tool(tool)) }
-        Array(messages).each { |message| add_message(chat, message) }
+        Array(tools).each do |tool|
+          chat.respond_to?(:with_tool) ? chat.with_tool(ruby_llm_tool(tool)) : chat.with_tools(ruby_llm_tool(tool))
+        end
+        tool_names = {}
+        Array(messages).each { |message| add_message(chat, message, provider: chat.model.provider, tool_names: tool_names) }
 
         response = complete_without_tool_execution(chat)
         normalize_response(response, model: model)
+      rescue ConfigError
+        raise
+      rescue ::RubyLLM::Error, ::RubyLLM::ModelNotFoundError => error
+        # Provider failures (after RubyLLM's own retries) are task failures,
+        # not worker crashes to be replayed by durable reconciliation.
+        raise ModelError, "#{error.class}: #{error.message}"
       end
 
       def paint(prompt:, model:, provider: nil, size: nil, assume_model_exists: nil, input_images: nil, mask: nil, params: {}, metadata: nil, on_event: nil)
@@ -50,25 +68,44 @@ module TurnKit
           size: size || "1024x1024",
           with: input_images,
           mask: mask,
-          params: params || {}
+          **{ (::RubyLLM::Chat.method_defined?(:generate) ? :provider_options : :params) => params || {} }
         )
         normalize_image_response(image, model: model, provider: provider, params: { "size" => size || "1024x1024" }.merge(params || {}), metadata: metadata)
+      rescue ConfigError
+        raise
+      rescue ::RubyLLM::Error, ::RubyLLM::ModelNotFoundError => error
+        raise ModelError, "#{error.class}: #{error.message}"
       end
 
       def view_media(media:, objective:, model:, provider: nil, output_schema: nil, params: {}, metadata: nil, on_event: nil)
         ensure_ruby_llm!
         configure_from_environment
         media_input = MediaInput.wrap(media)
-        content = ::RubyLLM::Content.new(objective.to_s)
-        content.add_attachment(media_input.attachment_source, filename: media_input.filename)
 
         chat = ::RubyLLM.chat(model: model)
         chat.with_schema(normalize_schema(output_schema)) if output_schema
-        chat.with_params(**params) if params && !params.empty?
-        chat.add_message(role: :user, content: content)
+        if params && !params.empty?
+          if ::RubyLLM::Chat.method_defined?(:generate)
+            chat.with_provider_options(**params)
+          else
+            chat.with_params(**params)
+          end
+        end
+        if ::RubyLLM::Chat.method_defined?(:generate)
+          attachment = ::RubyLLM::Attachment.new(media_input.attachment_source, filename: media_input.filename)
+          chat.add_message(role: :user, content: objective.to_s, attachments: [attachment])
+        else
+          content = ::RubyLLM::Content.new(objective.to_s)
+          content.add_attachment(media_input.attachment_source, filename: media_input.filename)
+          chat.add_message(role: :user, content: content)
+        end
 
         response = complete_without_tool_execution(chat)
         normalize_media_analysis_response(response, media: media_input, model: model, provider: provider, params: params || {}, metadata: metadata)
+      rescue ConfigError
+        raise
+      rescue ::RubyLLM::Error, ::RubyLLM::ModelNotFoundError => error
+        raise ModelError, "#{error.class}: #{error.message}"
       end
 
       private
@@ -119,12 +156,10 @@ module TurnKit
           end
         end
 
-        # RubyLLM has no public API to request a completion without executing
-        # tool calls, so this depends on the private RubyLLM::Chat#provider_completion
-        # (added in ruby_llm 1.16). TurnKit must run tools itself (to persist
-        # executions and enforce budgets). Guarded by a canary test in the
-        # suite; revisit when RubyLLM exposes a public equivalent.
+        # 2.0's public generate requests one completion without executing tools.
+        # 1.16 needs its private provider_completion, guarded by a canary test.
         def complete_without_tool_execution(chat)
+          return chat.generate if chat.respond_to?(:generate)
           unless chat.respond_to?(:provider_completion, true)
             raise ConfigError, "TurnKit::Adapters::RubyLLM requires ruby_llm >= 1.16 (RubyLLM::Chat#provider_completion not found)"
           end
@@ -132,15 +167,31 @@ module TurnKit
           chat.send(:provider_completion)
         end
 
-        def add_message(chat, message)
+        def add_message(chat, message, provider: nil, tool_names: {})
           role = (message[:role] || message["role"]).to_sym
           content = message[:content] || message["content"] || ""
+          kind = { "openai" => "openai_responses", "anthropic" => "anthropic", "gemini" => "gemini" }[provider.to_s]
+          replay = Array(message[:provider_parts] || message["provider_parts"]).find { |part| part["kind"] == kind } if kind
+          calls = ruby_llm_tool_calls(message[:tool_calls] || message["tool_calls"])
+          raw_content = replay&.fetch("data")
+          if raw_content && %w[anthropic gemini].include?(kind) && !::RubyLLM::Chat.method_defined?(:generate)
+            content = ::RubyLLM::Content::Raw.new(raw_content)
+            raw_content = nil
+            if kind == "gemini"
+              # 1.16 appends normalized calls after Raw content. Omit those
+              # duplicates and supply names for its positional function results.
+              calls&.each { |id, call| tool_names[id] = call.name }
+              calls = nil
+            end
+          end
+          call_id = message[:tool_call_id] || message["tool_call_id"]
           chat.add_message(
             {
               role: role,
               content: content,
-              tool_calls: ruby_llm_tool_calls(message[:tool_calls] || message["tool_calls"]),
-              tool_call_id: message[:tool_call_id] || message["tool_call_id"]
+              raw_content: raw_content,
+              tool_calls: calls,
+              tool_call_id: tool_names.fetch(call_id, call_id)
             }.compact
           )
         end
@@ -162,6 +213,10 @@ module TurnKit
           content = content.to_s.strip
           return if content.empty?
 
+          if ::RubyLLM::Chat.method_defined?(:generate)
+            chat.add_message(role: :system, content: content, cache_until_here: cache)
+            return
+          end
           if cache
             content = ::RubyLLM::Providers::Anthropic::Content.new(content, cache: true)
           end
@@ -193,7 +248,7 @@ module TurnKit
           Class.new(::RubyLLM::Tool) do
             define_singleton_method(:name) { tool.tool_name }
             description tool.description
-            params tool.input_schema
+            respond_to?(:params) ? params(tool.input_schema) : parameters(tool.input_schema)
 
             define_method(:execute) do |**arguments|
               raise ToolError, "tools must be executed by TurnKit turns, not the RubyLLM adapter"
@@ -202,6 +257,10 @@ module TurnKit
         end
 
         def normalize_response(response, model:)
+          raw = response.raw.body if response.respond_to?(:raw) && response.raw.respond_to?(:body)
+          if raw.is_a?(Hash) && raw["object"] == "response" && raw["status"] != "completed"
+            raise ModelError, "OpenAI Responses #{raw['status']}: #{raw.dig('incomplete_details', 'reason')}"
+          end
           tool_calls = Array(response.respond_to?(:tool_calls) ? response.tool_calls&.values : []).map do |call|
             ToolCall.new(id: call.id, name: call.name, arguments: call.arguments)
           end
@@ -219,7 +278,7 @@ module TurnKit
             output_data: response_data(response),
             tool_calls: tool_calls,
             usage: usage,
-            model: response.respond_to?(:model_id) ? response.model_id : model
+            model: response_model(response, model)
           )
         end
 
@@ -234,6 +293,14 @@ module TurnKit
             text = content.to_s
             text.empty? ? [] : [ { "type" => "text", "text" => text } ]
           end.compact
+          raw = response.raw.body if response.respond_to?(:raw) && response.raw.respond_to?(:body)
+          if raw.is_a?(Hash) && raw["object"] == "response"
+            parts << { "type" => "provider", "kind" => "openai_responses", "data" => raw.fetch("output") }
+          elsif raw.is_a?(Hash) && raw["type"] == "message" && raw["role"] == "assistant"
+            parts << { "type" => "provider", "kind" => "anthropic", "data" => raw.fetch("content") }
+          elsif raw.is_a?(Hash) && raw.dig("candidates", 0, "content", "parts")
+            parts << { "type" => "provider", "kind" => "gemini", "data" => raw.dig("candidates", 0, "content", "parts") }
+          end
           parts + Array(tool_calls).map { |call| { "type" => "tool_call", "id" => call.id, "name" => call.name, "arguments" => call.arguments } }
         end
 
@@ -267,7 +334,25 @@ module TurnKit
         end
 
         def token_value(response, method)
-          response.respond_to?(method) ? response.public_send(method).to_i : 0
+          if response.respond_to?(method)
+            value = response.public_send(method).to_i
+            raw = response.raw.body if response.respond_to?(:raw) && response.raw.respond_to?(:body)
+            native = raw.is_a?(Hash) && (raw["candidates"] || raw["type"] == "message")
+            # Native 1.16 providers also include thinking in their output count.
+            return native && method == :output_tokens ? value - thinking_token_value(response) : value
+          end
+          return 0 unless response.respond_to?(:tokens)
+
+          key = { input_tokens: :input, output_tokens: :output, cached_tokens: :cache_read,
+            cache_creation_tokens: :cache_write, thinking_tokens: :thinking, reasoning_tokens: :thinking }.fetch(method)
+          value = response.tokens.public_send(key).to_i
+          # RubyLLM 2.0 includes thinking in output; TurnKit buckets are additive.
+          method == :output_tokens ? value - response.tokens.thinking.to_i : value
+        end
+
+        def response_model(response, fallback)
+          return response.model if response.respond_to?(:model)
+          response.respond_to?(:model_id) ? response.model_id : fallback
         end
 
         def thinking_token_value(response)
@@ -291,7 +376,7 @@ module TurnKit
             data: image.respond_to?(:data) ? image.data : nil,
             mime_type: image.respond_to?(:mime_type) ? image.mime_type : nil,
             revised_prompt: image.respond_to?(:revised_prompt) ? image.revised_prompt : nil,
-            model: image.respond_to?(:model_id) ? image.model_id : model,
+            model: response_model(image, model),
             provider: provider&.to_s,
             usage: usage,
             params: params,
@@ -313,7 +398,7 @@ module TurnKit
           part = MediaAnalysisResult.new(
             text: response_text(response),
             data: response_data(response),
-            model: response.respond_to?(:model_id) ? response.model_id : model,
+            model: response_model(response, model),
             provider: provider&.to_s,
             usage: usage,
             params: params,
@@ -325,6 +410,7 @@ module TurnKit
         end
 
         def image_usage_value(image, key)
+          return image.tokens.public_send(key == "input_tokens" ? :input : :output).to_i if image.respond_to?(:tokens)
           usage = image.respond_to?(:usage) ? image.usage || {} : {}
           (usage[key] || usage[key.to_sym]).to_i
         end

data/lib/turnkit/agent.rb

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

data/lib/turnkit/authorization.rb

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