turnkit 0.2.6 → 0.2.7

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)
@@ -86,6 +90,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 +137,14 @@ module TurnKit
       parts << SystemPrompt.loaded_skills_text(skills)
       parts.reject(&:empty?).join("\n\n")
     end
+
+    private
+      def validate_tools!
+        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
   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,16 +26,17 @@ 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, 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, 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, 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,
@@ -47,7 +48,7 @@ module TurnKit
         "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

data/lib/turnkit/generators/turnkit/install/templates/create_turnkit_tables.rb

@@ -30,6 +30,7 @@ class CreateTurnkitTables < ActiveRecord::Migration[7.1]
       t.decimal :cost, precision: 14, scale: 6
       t.json :error
       t.text :output_text
+      t.json :output_data
       t.datetime :started_at
       t.datetime :heartbeat_at
       t.datetime :completed_at

data/lib/turnkit/generators/turnkit/install/templates/initializer.rb

@@ -12,8 +12,14 @@ TurnKit.tool_execution_record_class = "Turnkit::ToolExecution"
 # TurnKit.timeout = 300
 # TurnKit.max_depth = 3
 # TurnKit.max_tool_executions = 100
+# TurnKit.on_event = ->(event) { Rails.logger.info("turnkit.#{event.type} #{event.payload.inspect}") }
 
 # TurnKit builds each system prompt from these sections by default.
 # TurnKit.prompt_sections = %i[agent instructions behavior loaded_skills available_skills tools subject environment]
 # TurnKit.prompt_behavior = "Custom behavior instructions."
 # TurnKit.available_skills = TurnKit::Skill.from_directory(Rails.root.join("app/ai/skills"))
+
+# Suggested Rails convention:
+# - app/ai/agents/* builds TurnKit::Agent objects for your workflows.
+# - app/ai/tools/* defines TurnKit::Tool subclasses.
+# - app/ai/skills/* stores reusable Markdown skill files.

data/lib/turnkit/generators/turnkit/install_generator.rb

@@ -25,6 +25,12 @@ module TurnKit
         template "tool_execution.rb", "app/models/turnkit/tool_execution.rb"
       end
 
+      def create_ai_directories
+        empty_directory "app/ai/agents"
+        empty_directory "app/ai/tools"
+        empty_directory "app/ai/skills"
+      end
+
       def copy_migration
         migration_template "create_turnkit_tables.rb", "db/migrate/create_turnkit_tables.rb"
       end

data/lib/turnkit/model_request.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module TurnKit
+  class ModelRequest
+    attr_reader :model, :messages, :tools, :instructions, :thinking, :output_schema, :metadata, :report
+
+    def initialize(model:, messages:, tools:, instructions:, thinking: nil, output_schema: nil, metadata: {}, report: nil)
+      @model = model
+      @messages = Array(messages)
+      @tools = Array(tools)
+      @instructions = instructions.to_s
+      @thinking = thinking
+      @output_schema = output_schema
+      @metadata = metadata || {}
+      @report = report || {}
+    end
+
+    def tool_names
+      tools.map(&:tool_name)
+    end
+
+    def to_h
+      {
+        "model" => model,
+        "messages" => messages,
+        "tools" => tool_names,
+        "instructions" => instructions,
+        "thinking" => thinking,
+        "output_schema" => output_schema,
+        "metadata" => metadata,
+        "report" => report
+      }
+    end
+  end
+end

data/lib/turnkit/record.rb

@@ -5,7 +5,7 @@ module TurnKit
     TURN_STATUSES = %w[pending running completed failed cancelled stale].freeze
     TOOL_EXECUTION_STATUSES = %w[pending running completed failed cancelled].freeze
 
-    TURN_UPDATE_KEYS = %w[status options usage cost error output_text started_at heartbeat_at completed_at].freeze
+    TURN_UPDATE_KEYS = %w[status options usage cost error output_text output_data started_at heartbeat_at completed_at].freeze
     TOOL_EXECUTION_UPDATE_KEYS = %w[status result error started_at completed_at].freeze
 
     module_function
@@ -49,6 +49,7 @@ module TurnKit
         "cost" => attrs["cost"],
         "error" => attrs["error"],
         "output_text" => attrs["output_text"],
+        "output_data" => attrs["output_data"],
         "started_at" => attrs["started_at"],
         "heartbeat_at" => attrs["heartbeat_at"],
         "completed_at" => attrs["completed_at"],

data/lib/turnkit/result.rb

@@ -2,14 +2,15 @@
 
 module TurnKit
   class Result
-    attr_reader :text, :tool_calls, :usage, :model, :finish_reason
+    attr_reader :text, :tool_calls, :usage, :model, :finish_reason, :output_data
 
-    def initialize(text: "", tool_calls: [], usage: Usage.new, model: nil, finish_reason: nil)
+    def initialize(text: "", tool_calls: [], usage: Usage.new, model: nil, finish_reason: nil, output_data: nil)
       @text = text.to_s
       @tool_calls = Array(tool_calls)
       @usage = usage || Usage.new
       @model = model
       @finish_reason = finish_reason
+      @output_data = output_data
     end
 
     def tool_calls?

data/lib/turnkit/stores/active_record_store.rb

@@ -57,7 +57,7 @@ module TurnKit
 
     def create_turn(attributes)
       attrs = Record.turn(attributes)
-      record = turn_class.create!(
+      record_attrs = {
         uid: attrs.fetch("id"),
         conversation_uid: attrs.fetch("conversation_id"),
         agent_name: attrs["agent_name"],
@@ -75,7 +75,9 @@ module TurnKit
         started_at: attrs["started_at"],
         heartbeat_at: attrs["heartbeat_at"],
         completed_at: attrs["completed_at"]
-      )
+      }
+      record_attrs[:output_data] = attrs["output_data"] if turn_has_attribute?("output_data")
+      record = turn_class.create!(record_attrs)
       turn_hash(record)
     end
 
@@ -85,7 +87,9 @@ module TurnKit
 
     def update_turn(id, attributes)
       record = turn_class.find_by!(uid: id)
-      record.update!(Record.turn_update(attributes))
+      attrs = Record.turn_update(attributes)
+      attrs.delete("output_data") unless turn_has_attribute?("output_data")
+      record.update!(attrs)
       turn_hash(record)
     end
 
@@ -160,7 +164,7 @@ module TurnKit
       end
 
       def turn_hash(record)
-        {
+        attrs = {
           "id" => record.uid, "conversation_id" => record.conversation_uid, "agent_name" => record.agent_name,
           "parent_turn_id" => record.parent_turn_uid, "parent_tool_execution_id" => record.parent_tool_execution_uid,
           "root_turn_id" => record.root_turn_uid, "context_message_sequence" => record.context_message_sequence,
@@ -169,6 +173,12 @@ module TurnKit
           "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
         }
+        attrs["output_data"] = record.output_data if record.respond_to?(:output_data)
+        attrs
+      end
+
+      def turn_has_attribute?(name)
+        turn_class.respond_to?(:attribute_names) && turn_class.attribute_names.include?(name)
       end
 
       def message_hash(record)

data/lib/turnkit/sub_agent_tool.rb

@@ -21,9 +21,17 @@ module TurnKit
     def call(task:, context: nil, turnkit_context:)
       sub_agent = self.class.agent
       parent_turn = turnkit_context.turn
-      conversation = parent_turn.conversation
       prompt = [ task, context ].compact.join("\n\n")
-      trigger = conversation.append_message(role: "user", kind: "text", text: prompt, turn_id: parent_turn.id)
+      conversation = sub_agent.conversation(metadata: {
+        "parent_conversation_id" => parent_turn.conversation.id,
+        "parent_turn_id" => parent_turn.id,
+        "parent_tool_execution_id" => turnkit_context.execution.id
+      })
+      trigger = conversation.say(prompt, metadata: {
+        "parent_conversation_id" => parent_turn.conversation.id,
+        "parent_turn_id" => parent_turn.id,
+        "parent_tool_execution_id" => turnkit_context.execution.id
+      })
       child = conversation.run!(
         trigger_message_id: trigger.id,
         budget: parent_turn.budget,
@@ -31,9 +39,10 @@ module TurnKit
         parent_tool_execution: turnkit_context.execution,
         depth: parent_turn.depth + 1,
         model: sub_agent.effective_model,
-        agent: sub_agent
+        agent: sub_agent,
+        on_event: parent_turn.agent.effective_on_event
       )
-      { "turn_id" => child.id, "status" => child.status, "result" => child.output_text }
+      { "conversation_id" => conversation.id, "turn_id" => child.id, "status" => child.status, "result" => child.output_text, "output_data" => child.output_data }.compact
     end
   end
 end

data/lib/turnkit/tool.rb

@@ -3,6 +3,7 @@
 module TurnKit
   class Tool
     TYPES = %i[string integer number boolean array object enum].freeze
+    NAME_PATTERN = /\A[a-zA-Z_][a-zA-Z0-9_]*\z/
 
     class << self
       def tool_name(value = nil)
@@ -20,16 +21,22 @@ module TurnKit
         @usage_hint.to_s
       end
 
-      def parameter(name, type = :string, required: false, description: "", default: nil, enum: nil)
+      def parameter(name, type = :string, required: false, description: "", default: nil, enum: nil, items: nil, properties: nil)
+        name = name.to_s
         raise ArgumentError, "unknown parameter type: #{type}" unless TYPES.include?(type)
+        raise ArgumentError, "invalid parameter name: #{name}" unless NAME_PATTERN.match?(name)
+        raise ArgumentError, "duplicate parameter: #{name}" if parameters.any? { |param| param.fetch(:name) == name }
+        raise ArgumentError, "enum values are required for enum parameter: #{name}" if type == :enum && Array(enum).empty?
 
         parameters << {
-          name: name.to_s,
+          name: name,
           type: type,
           required: required ? true : false,
           description: description.to_s,
           default: default,
-          enum: enum
+          enum: enum,
+          items: items,
+          properties: properties
         }.compact
       end
 
@@ -45,8 +52,56 @@ module TurnKit
         nil
       end
 
+      def validate_definition!
+        raise ArgumentError, "tool name is required" if tool_name.empty?
+        raise ArgumentError, "invalid tool name: #{tool_name}" unless NAME_PATTERN.match?(tool_name)
+
+        parameters.each do |param|
+          type = param.fetch(:type)
+          raise ArgumentError, "unknown parameter type: #{type}" unless TYPES.include?(type)
+          raise ArgumentError, "enum values are required for enum parameter: #{param.fetch(:name)}" if type == :enum && Array(param[:enum]).empty?
+          validate_value!(param[:default], param) if param.key?(:default)
+        end
+        true
+      end
+
+      def input_schema
+        properties = parameters.to_h { |param| [ param.fetch(:name), schema_for(param) ] }
+        required = parameters.select { |param| param.fetch(:required) }.map { |param| param.fetch(:name) }
+        {
+          "type" => "object",
+          "properties" => properties,
+          "required" => required
+        }
+      end
+
+      def validate_arguments(arguments)
+        attrs = arguments.respond_to?(:to_h) ? arguments.to_h.transform_keys(&:to_s) : {}
+        allowed = parameters.map { |param| param.fetch(:name) }
+        unknown = attrs.keys - allowed
+        raise ToolValidationError, "unknown argument#{unknown.length == 1 ? "" : "s"}: #{unknown.join(", ")}" if unknown.any?
+
+        normalized = {}
+        parameters.each do |param|
+          name = param.fetch(:name)
+          if attrs.key?(name)
+            value = attrs[name]
+          elsif param.key?(:default)
+            value = param[:default]
+          elsif param.fetch(:required)
+            raise ToolValidationError, "missing required argument: #{name}"
+          else
+            next
+          end
+
+          validate_value!(value, param)
+          normalized[name] = value
+        end
+        normalized
+      end
+
       def call(arguments = {}, context:)
-        keyword_arguments = symbolize(arguments)
+        keyword_arguments = symbolize(validate_arguments(arguments))
         instance = new
         if accepts_turnkit_context?(instance)
           instance.call(**keyword_arguments, turnkit_context: context)
@@ -56,6 +111,64 @@ module TurnKit
       end
 
       private
+        def schema_for(param)
+          schema = {
+            "type" => schema_type(param.fetch(:type)),
+            "description" => param[:description].to_s
+          }.reject { |_key, value| value.nil? || value == "" }
+          schema["enum"] = Array(param[:enum]) if param[:enum]
+          schema["default"] = param[:default] if param.key?(:default)
+          schema["items"] = normalize_items(param[:items]) if param[:items]
+          schema["properties"] = normalize_properties(param[:properties]) if param[:properties]
+          schema
+        end
+
+        def schema_type(type)
+          type == :enum ? "string" : type.to_s
+        end
+
+        def normalize_items(value)
+          return { "type" => value.to_s } if value.is_a?(Symbol)
+
+          stringify_schema(value)
+        end
+
+        def normalize_properties(value)
+          value.to_h.transform_keys(&:to_s).transform_values { |schema| stringify_schema(schema) }
+        end
+
+        def stringify_schema(value)
+          case value
+          when Hash
+            value.transform_keys(&:to_s).transform_values { |nested| nested.is_a?(Hash) ? stringify_schema(nested) : nested }
+          else
+            { "type" => value.to_s }
+          end
+        end
+
+        def validate_value!(value, param)
+          return if value.nil? && !param.fetch(:required)
+
+          case param.fetch(:type)
+          when :string, :enum
+            raise ToolValidationError, "#{param.fetch(:name)} must be a string" unless value.is_a?(String)
+          when :integer
+            raise ToolValidationError, "#{param.fetch(:name)} must be an integer" unless value.is_a?(Integer)
+          when :number
+            raise ToolValidationError, "#{param.fetch(:name)} must be a number" unless value.is_a?(Numeric)
+          when :boolean
+            raise ToolValidationError, "#{param.fetch(:name)} must be a boolean" unless value == true || value == false
+          when :array
+            raise ToolValidationError, "#{param.fetch(:name)} must be an array" unless value.is_a?(Array)
+          when :object
+            raise ToolValidationError, "#{param.fetch(:name)} must be an object" unless value.is_a?(Hash)
+          end
+
+          if param[:enum] && !Array(param[:enum]).include?(value)
+            raise ToolValidationError, "#{param.fetch(:name)} must be one of: #{Array(param[:enum]).join(", ")}"
+          end
+        end
+
         def accepts_turnkit_context?(instance)
           instance.method(:call).parameters.any? { |kind, name| %i[key keyreq].include?(kind) && name == :turnkit_context }
         end

data/lib/turnkit/tool_call.rb

@@ -2,11 +2,12 @@
 
 module TurnKit
   class ToolCall
-    attr_reader :id, :name, :arguments
+    attr_reader :id, :name, :arguments, :arguments_error
 
     def initialize(id:, name:, arguments: {})
       @id = id.to_s
       @name = name.to_s
+      @arguments_error = nil
       @arguments = normalize_arguments(arguments)
     end
 
@@ -22,6 +23,7 @@ module TurnKit
           {}
         end
       rescue JSON::ParserError
+        @arguments_error = "invalid JSON arguments"
         {}
       end
   end

data/lib/turnkit/tool_runner.rb

@@ -31,6 +31,10 @@ module TurnKit
           return finish_error(execution, tool_call, "unknown tool: #{tool_call.name}")
         end
 
+        if tool_call.arguments_error
+          return finish_error(execution, tool_call, tool_call.arguments_error)
+        end
+
         context = ToolContext.new(turn: turn, execution: execution)
         payload = begin
           normalize_payload(tool.call(tool_call.arguments, context: context))
@@ -54,6 +58,7 @@ module TurnKit
       def finish_success(execution, tool_call, payload)
         attrs = turn.store.update_tool_execution(execution.id, "status" => "completed", "result" => payload, "completed_at" => Clock.now)
         append_result(execution, tool_call, payload)
+        turn.emit("tool_call.completed", id: tool_call.id, name: tool_call.name)
         ToolExecution.new(attrs)
       end
 
@@ -61,11 +66,12 @@ module TurnKit
         error = { "message" => message.to_s, "details" => details }.compact
         attrs = turn.store.update_tool_execution(execution.id, "status" => "failed", "error" => error, "completed_at" => Clock.now)
         append_result(execution, tool_call, error)
+        turn.emit("tool_call.failed", id: tool_call.id, name: tool_call.name, error: error)
         ToolExecution.new(attrs)
       end
 
       def append_result(execution, tool_call, payload)
-        turn.conversation.append_message(
+        message = turn.conversation.append_message(
           role: "tool",
           kind: "tool_result",
           text: payload.to_json,
@@ -73,6 +79,7 @@ module TurnKit
           tool_execution_id: execution.id,
           metadata: { "tool_call_id" => tool_call.id, "tool_name" => tool_call.name }
         )
+        turn.emit("message.created", message_id: message.id, role: message.role, kind: message.kind)
       end
 
       def tool_class(name)