turnkit 0.2.6 → 0.2.8

data/UPGRADE.md

@@ -0,0 +1,346 @@
+# Upgrade Guide
+
+This guide covers migrating to the newer task-runtime API. The changes are
+mostly additive: existing `Agent`, `Conversation`, `Tool`, and `Fleet` code
+should continue to work. The recommended migration is about improving developer
+experience and making autonomous workflows easier to read.
+
+## Quick summary
+
+You do **not** need to rewrite existing code immediately.
+
+Recommended new forms:
+
+```ruby
+TurnKit.configure do |config|
+  config.model = "gpt-5.2"
+  config.max_spend = 0.25
+end
+
+fleet = TurnKit.fleet("brief_writer", tools: [WebSearch, SaveBrief])
+run = fleet.run("Create a source-grounded brief.", input: { topic: "Rails 8" })
+
+puts run.output
+```
+
+Old forms still work:
+
+```ruby
+TurnKit.default_model = "gpt-5.2"
+
+fleet = TurnKit::Fleet.new(name: "brief_writer", tools: [WebSearch, SaveBrief])
+run = fleet.run(task: "Create a source-grounded brief.", input: { topic: "Rails 8" })
+
+puts run.output_text
+```
+
+## Configuration
+
+### Model name
+
+Before:
+
+```ruby
+TurnKit.default_model = "gpt-5.2"
+```
+
+After:
+
+```ruby
+TurnKit.model = "gpt-5.2"
+```
+
+`TurnKit.default_model` remains supported. `TurnKit.model` is the shorter public
+alias for app code and initializers.
+
+### Global setup
+
+Before:
+
+```ruby
+TurnKit.default_model = "gpt-5.2"
+TurnKit.cost_limit = 0.25
+TurnKit.max_iterations = 12
+```
+
+After:
+
+```ruby
+TurnKit.configure do |config|
+  config.model = "gpt-5.2"
+  config.max_spend = 0.25
+  config.max_iterations = 12
+end
+```
+
+`TurnKit.configure` simply yields the `TurnKit` module. There is no separate
+configuration object or DSL.
+
+### Spend limit naming
+
+Before:
+
+```ruby
+TurnKit.cost_limit = 0.25
+```
+
+After:
+
+```ruby
+TurnKit.max_spend = 0.25
+```
+
+`cost_limit` remains supported. Prefer `max_spend` in application-facing code
+because it matches how developers think about autonomous runs.
+
+## Running application tasks
+
+### Agent tasks
+
+Before:
+
+```ruby
+run = agent.run(task: "Classify this lead.", input: lead.attributes)
+puts run.output_text
+```
+
+After:
+
+```ruby
+run = agent.run("Classify this lead.", input: lead.attributes)
+puts run.output
+```
+
+The keyword form still works. The positional string is the recommended form for
+the common case.
+
+### Pending runs
+
+No behavior change.
+
+```ruby
+run = agent.run("Classify later.", async: true)
+request = run.preview
+run.run!
+```
+
+The existing keyword form remains valid:
+
+```ruby
+run = agent.run(task: "Classify later.", async: true)
+```
+
+## Fleets
+
+The fleet mental model changed from “many agents” to “one reusable autonomous
+task runtime.” A fleet packages:
+
+- one task-mode orchestrator
+- workflow skills
+- tools
+- guardrails
+- compaction
+- optional persistence/action tools
+
+### Construction
+
+Before:
+
+```ruby
+fleet = TurnKit::Fleet.new(
+  name: "sales_enrichment",
+  tools: [AccountLookup, WebSearch, SaveEnrichment],
+  skills: [sales_research_skill],
+  max_spend: 0.25
+)
+```
+
+After:
+
+```ruby
+fleet = TurnKit.fleet(
+  "sales_enrichment",
+  tools: [AccountLookup, WebSearch, SaveEnrichment],
+  skills: [sales_research_skill],
+  max_spend: 0.25
+)
+```
+
+`TurnKit::Fleet.new` remains supported.
+
+### Running
+
+Before:
+
+```ruby
+run = fleet.run(
+  task: "Enrich this account for responsible outreach.",
+  input: account.attributes
+)
+```
+
+After:
+
+```ruby
+run = fleet.run(
+  "Enrich this account for responsible outreach.",
+  input: account.attributes
+)
+```
+
+`task:` remains supported.
+
+### Auto-run alias
+
+No behavior change.
+
+```ruby
+run = fleet.auto_run("Enrich this account.", input: account.attributes)
+```
+
+Use `auto_run` when the name helps communicate that the fleet should navigate
+from input to output on its own. It is an alias for `run`.
+
+## Run inspection
+
+New convenience methods were added to `TurnKit::Run`.
+
+Before:
+
+```ruby
+run.output_text
+run.tool_executions
+run.turn_records.length
+TurnKit.store.load_turn(run.id)["error"]
+```
+
+After:
+
+```ruby
+run.output
+run.tool_calls
+run.steps
+run.error
+```
+
+Old methods remain available. Prefer the shorter methods in application code,
+examples, and docs.
+
+## Save/action tools
+
+Use `terminal!` for tools that complete the run by saving an artifact or taking
+the final action.
+
+Before:
+
+```ruby
+class SaveBrief < TurnKit::Tool
+  def self.ends_turn? = true
+  def self.completion_message(result) = "Saved #{result.fetch("id")}."
+
+  def call(title:, body:, context:)
+    { "id" => Brief.create!(title: title, body: body).id }
+  end
+end
+```
+
+After:
+
+```ruby
+class SaveBrief < TurnKit::Tool
+  terminal! { |result| "Saved #{result.fetch("id")}." }
+
+  def call(title:, body:, context:)
+    { "id" => Brief.create!(title: title, body: body).id }
+  end
+end
+```
+
+The old `ends_turn?` and `completion_message` methods remain supported. Prefer
+`terminal!` for readability.
+
+## Tool instances
+
+If a tool needs constructor arguments, register an instance instead of a class.
+
+Before, this may have failed at runtime:
+
+```ruby
+class WebSearch < TurnKit::Tool
+  def initialize(client:)
+    @client = client
+  end
+end
+
+agent = TurnKit::Agent.new(tools: [WebSearch])
+```
+
+After:
+
+```ruby
+client = SearchClient.new(api_key: ENV.fetch("SEARCH_API_KEY"))
+agent = TurnKit::Agent.new(tools: [WebSearch.new(client: client)])
+```
+
+This is the recommended pattern for API clients, test doubles, and per-tenant
+dependencies.
+
+## Multi-agent fleets
+
+If you previously modeled every role as a separate agent, consider migrating the
+default path to one fleet with a workflow skill.
+
+Before:
+
+```ruby
+researcher = TurnKit::Agent.new(name: "researcher", tools: [WebSearch])
+writer = TurnKit::Agent.new(name: "writer")
+verifier = TurnKit::Agent.new(name: "verifier")
+
+orchestrator = TurnKit::Agent.new(
+  name: "orchestrator",
+  sub_agents: [researcher, writer, verifier]
+)
+```
+
+After:
+
+```ruby
+workflow = TurnKit::Skill.new(
+  key: "source_grounded_brief",
+  name: "Source Grounded Brief",
+  content: <<~TEXT
+    Research first. Build an evidence pack. Draft only from evidence. Verify
+    important claims. Revise unsupported claims before final output.
+  TEXT
+)
+
+fleet = TurnKit.fleet(
+  "source_brief",
+  skills: [workflow],
+  tools: [WebSearch, ReadWebPage, SaveBrief],
+  max_spend: 0.25,
+  max_tool_executions: 20
+)
+```
+
+Keep separate agents when the isolation is worth the extra model calls:
+
+- different models
+- different tool permissions
+- adversarial review
+- parallel specialist research
+- separate durable child conversations
+
+## Suggested migration order
+
+1. Replace `TurnKit.default_model =` with `TurnKit.model =` in app-level config.
+2. Wrap global settings in `TurnKit.configure` if you have more than one.
+3. Replace `TurnKit::Fleet.new(name: ...)` with `TurnKit.fleet("...")` in new code.
+4. Replace `run(task: "...")` with `run("...")` where it improves readability.
+5. Replace `run.output_text` with `run.output` in application code.
+6. Replace save/action tool overrides with `terminal!` when convenient.
+7. Consider collapsing role-agent fleets into one fleet plus workflow skills if
+   cost or complexity is a concern.
+
+None of these steps are required for existing code to keep working.

data/lib/turnkit/adapters/ruby_llm.rb

@@ -3,7 +3,28 @@
 module TurnKit
   module Adapters
     class RubyLLM < Client
-      def chat(model:, messages:, tools:, instructions:, temperature: nil, thinking: nil, metadata: nil)
+      KEY_BY_PROVIDER = {
+        openai: "OPENAI_API_KEY",
+        gemini: "GEMINI_API_KEY",
+        anthropic: "ANTHROPIC_API_KEY",
+        openrouter: "OPENROUTER_API_KEY"
+      }.freeze
+
+      def validate!(model:)
+        require "ruby_llm"
+
+        raise ModelAccessError, "model is required" if model.to_s.empty?
+
+        configure_from_environment
+        provider = provider_for(model)
+        key_name = KEY_BY_PROVIDER[provider]
+        return true unless key_name
+        return true if ENV[key_name].to_s != "" || config_key_present?(provider)
+
+        raise ModelAccessError, "#{key_name} is required for #{model}. Set ENV[#{key_name.inspect}] or configure RubyLLM before running TurnKit."
+      end
+
+      def chat(model:, messages:, tools:, instructions:, temperature: nil, thinking: nil, output_schema: nil, metadata: nil, on_event: nil)
         require "ruby_llm"
 
         configure_from_environment
@@ -12,6 +33,7 @@ module TurnKit
         add_instructions(chat, 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) }
 
@@ -28,11 +50,39 @@ module TurnKit
           config.openrouter_api_key ||= ENV["OPENROUTER_API_KEY"]
         end
 
+        def provider_for(model)
+          value = model.to_s.downcase
+          return :openrouter if value.start_with?("openrouter/")
+          return :anthropic if value.start_with?("anthropic/", "claude")
+          return :gemini if value.start_with?("gemini/", "gemini")
+          return :openai if value.start_with?("openai/", "gpt", "o1", "o3", "o4")
+
+          nil
+        end
+
+        def config_key_present?(provider)
+          value = ::RubyLLM.config.public_send("#{provider}_api_key") if ::RubyLLM.config.respond_to?("#{provider}_api_key")
+          value.to_s != ""
+        end
+
         def apply_thinking(chat, thinking)
           thinking = Agent.normalize_thinking(thinking)
           chat.with_thinking(**thinking) if thinking
         end
 
+        def normalize_schema(schema)
+          case schema
+          when Hash
+            normalized = schema.transform_keys(&:to_s).transform_values { |value| normalize_schema(value) }
+            normalized["additionalProperties"] = false if normalized["type"] == "object" && !normalized.key?("additionalProperties")
+            normalized
+          when Array
+            schema.map { |value| normalize_schema(value) }
+          else
+            schema
+          end
+        end
+
         def complete_without_tool_execution(chat)
           provider = chat.instance_variable_get(:@provider)
           provider.complete(
@@ -110,9 +160,7 @@ module TurnKit
           Class.new(::RubyLLM::Tool) do
             define_singleton_method(:name) { tool.tool_name }
             description tool.description
-            tool.parameters.each do |param|
-              param(param.fetch(:name).to_sym, type: param.fetch(:type), required: param.fetch(:required), desc: param.fetch(:description))
-            end
+            params tool.input_schema
 
             define_method(:execute) do |**arguments|
               raise ToolError, "tools must be executed by TurnKit turns, not the RubyLLM adapter"
@@ -133,13 +181,29 @@ module TurnKit
             cost: response_cost(response)
           )
           Result.new(
-            text: response.respond_to?(:content) ? response.content.to_s : response.to_s,
+            text: response_text(response),
+            output_data: response_data(response),
             tool_calls: tool_calls,
             usage: usage,
             model: response.respond_to?(:model_id) ? response.model_id : model
           )
         end
 
+        def response_text(response)
+          content = response.respond_to?(:content) ? response.content : response
+          content.is_a?(Hash) || content.is_a?(Array) ? content.to_json : content.to_s
+        end
+
+        def response_data(response)
+          content = response.respond_to?(:content) ? response.content : nil
+          return content if content.is_a?(Hash) || content.is_a?(Array)
+          return nil unless content.is_a?(String)
+
+          JSON.parse(content)
+        rescue JSON::ParserError
+          nil
+        end
+
         def token_value(response, method)
           response.respond_to?(method) ? response.public_send(method).to_i : 0
         end

data/lib/turnkit/agent.rb

@@ -4,11 +4,12 @@ module TurnKit
   class Agent
     attr_reader :name, :description, :model, :instructions, :tools, :skills, :available_skills, :sub_agents
     attr_reader :client, :store, :max_iterations, :timeout, :cost_limit, :max_depth, :max_tool_executions
-    attr_reader :prompt_sections, :system_prompt, :prompt_mode, :thinking, :compaction
+    attr_reader :prompt_sections, :system_prompt, :prompt_mode, :thinking, :compaction, :output_schema, :on_event
 
     def initialize(name:, description: "", model: nil, instructions: "", tools: [], skills: [], available_skills: [], sub_agents: [],
       system_prompt: nil, prompt_sections: nil, prompt_mode: nil, client: nil, store: nil,
-      max_iterations: nil, timeout: nil, cost_limit: nil, max_depth: nil, max_tool_executions: nil, thinking: nil, compaction: nil)
+      max_iterations: nil, timeout: nil, cost_limit: nil, max_depth: nil, max_tool_executions: nil, thinking: nil, compaction: nil,
+      output_schema: nil, on_event: nil)
       @name = name.to_s
       @description = description.to_s
       @model = model
@@ -29,7 +30,10 @@ module TurnKit
       @max_tool_executions = max_tool_executions
       @thinking = self.class.normalize_thinking(thinking)
       @compaction = compaction
+      @output_schema = output_schema
+      @on_event = on_event
       raise ArgumentError, "name is required" if @name.empty?
+      validate_tools!
     end
 
     def self.normalize_thinking(value)
@@ -58,6 +62,21 @@ module TurnKit
       Conversation.new(agent: self, record: record, store: store, model: model || effective_model, subject: subject, metadata: metadata)
     end
 
+    def run(prompt = nil, task: nil, input: nil, async: false, subject: nil, metadata: {}, parent_run: nil, root_turn_id: nil, **options)
+      task = task || prompt
+      raise ArgumentError, "task is required" if task.to_s.empty?
+
+      conversation = self.conversation(subject: subject, metadata: metadata)
+      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),
+        **options
+      )
+      run = Run.new(turn)
+      async ? run : run.run!
+    end
+
     def cost
       Cost.from_records(effective_store.list_turns(agent_name: name))
     end
@@ -86,6 +105,10 @@ module TurnKit
       tools + sub_agents.map { |agent| SubAgentTool.for(agent) }
     end
 
+    def effective_on_event
+      on_event || TurnKit.on_event
+    end
+
     def effective_available_skills
       (Array(TurnKit.available_skills) + available_skills).uniq { |skill| skill.key }
     end
@@ -129,5 +152,47 @@ module TurnKit
       parts << SystemPrompt.loaded_skills_text(skills)
       parts.reject(&:empty?).join("\n\n")
     end
+
+    private
+      def validate_tools!
+        effective_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)
+        duplicate = names.find { |name| names.count(name) > 1 }
+        raise ArgumentError, "duplicate tool name: #{duplicate}" if duplicate
+
+        effective_tools.each(&:validate_definition!)
+      end
+
+      def task_message(task, input)
+        text = task.to_s
+        return text if input.nil?
+
+        "Task:\n#{text}\n\nInput:\n#{format_task_input(input)}"
+      end
+
+      def format_task_input(input)
+        case input
+        when String
+          input
+        else
+          JSON.pretty_generate(input)
+        end
+      rescue JSON::GeneratorError
+        input.inspect
+      end
+
+      def parent_run_root_turn_id(parent_run)
+        return nil unless parent_run
+        return parent_run.root_turn_id if parent_run.respond_to?(:root_turn_id)
+        return parent_run.fetch("root_turn_id") if parent_run.respond_to?(:fetch)
+
+        nil
+      end
   end
 end

data/lib/turnkit/client.rb

@@ -2,7 +2,11 @@
 
 module TurnKit
   class Client
-    def chat(model:, messages:, tools:, instructions:, temperature: nil, thinking: nil, metadata: nil)
+    def validate!(model:)
+      true
+    end
+
+    def chat(model:, messages:, tools:, instructions:, temperature: nil, thinking: nil, output_schema: nil, metadata: nil, on_event: nil)
       raise NotImplementedError
     end
   end

data/lib/turnkit/conversation.rb

@@ -26,28 +26,29 @@ module TurnKit
       async ? turn : turn.run!
     end
 
-    def run!(trigger_message_id: nil, model: nil, budget: nil, parent_turn: nil, parent_tool_execution: nil, depth: 0, agent: self.agent, thinking: THINKING_UNSET, compact: nil)
-      build_turn(trigger_message_id: trigger_message_id, model: model, budget: budget, parent_turn: parent_turn, parent_tool_execution: parent_tool_execution, depth: depth, agent: agent, thinking: thinking, compact: compact).run!
+    def run!(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, on_event: nil)
+      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, on_event: on_event).run!
     end
 
-    def build_turn(trigger_message_id: nil, model: nil, budget: nil, parent_turn: nil, parent_tool_execution: nil, depth: 0, agent: self.agent, thinking: THINKING_UNSET, compact: 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, on_event: 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["thinking"] = effective_thinking
       options["compact"] = compact unless compact.nil?
+      options["output_schema"] = output_schema || agent.output_schema if output_schema || agent.output_schema
       record = store.create_turn(
         "conversation_id" => id,
         "agent_name" => agent.name,
         "parent_turn_id" => parent_turn&.id,
         "parent_tool_execution_id" => parent_tool_execution&.id,
-        "root_turn_id" => parent_turn&.root_turn_id,
+        "root_turn_id" => parent_turn&.root_turn_id || root_turn_id,
         "context_message_sequence" => snapshot,
         "status" => "pending",
         "model" => model || self.model || agent.effective_model,
         "options" => options
       )
-      Turn.new(agent: agent, conversation: self, record: record, store: store, budget: budget, depth: depth)
+      Turn.new(agent: agent, conversation: self, record: record, store: store, budget: budget, depth: depth, on_event: on_event)
     end
 
     def compact!(focus: nil, model: nil)

data/lib/turnkit/error.rb

@@ -4,6 +4,8 @@ module TurnKit
   class Error < StandardError; end
   class ConfigError < Error; end
   class CompactionError < Error; end
+  class ModelAccessError < ConfigError; end
   class StoreError < Error; end
   class ToolError < Error; end
+  class ToolValidationError < ToolError; end
 end

data/lib/turnkit/event.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module TurnKit
+  class Event
+    attr_reader :type, :turn_id, :conversation_id, :payload, :created_at
+
+    def initialize(type:, turn_id:, conversation_id:, payload: {}, created_at: Clock.now)
+      @type = type.to_s
+      @turn_id = turn_id
+      @conversation_id = conversation_id
+      @payload = payload || {}
+      @created_at = created_at
+    end
+
+    def to_h
+      {
+        "type" => type,
+        "turn_id" => turn_id,
+        "conversation_id" => conversation_id,
+        "payload" => payload,
+        "created_at" => created_at
+      }
+    end
+  end
+end