turnkit 0.2.5 → 0.2.7

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/message.rb

@@ -3,7 +3,7 @@
 module TurnKit
   class Message
     ROLES = %w[user assistant tool].freeze
-    KINDS = %w[text tool_call tool_result].freeze
+    KINDS = %w[text tool_call tool_result context_summary].freeze
 
     attr_reader :id, :conversation_id, :turn_id, :role, :kind, :sequence
     attr_reader :content, :text, :tool_execution_id, :provider_message_id, :metadata, :created_at
@@ -43,6 +43,26 @@ module TurnKit
       }
     end
 
+    def text?
+      kind == "text"
+    end
+
+    def tool_call?
+      kind == "tool_call"
+    end
+
+    def tool_result?
+      kind == "tool_result"
+    end
+
+    def context_summary?
+      kind == "context_summary"
+    end
+
+    def compaction_metadata
+      metadata.fetch("compaction", {})
+    end
+
     private
       def stringify(hash)
         hash.transform_keys(&:to_s)

data/lib/turnkit/message_projection.rb

@@ -2,14 +2,41 @@
 
 module TurnKit
   class MessageProjection
+    CONTEXT_SUMMARY_TRIGGER = "What did we do so far?"
+    CONTEXT_SUMMARY_PREFIX = <<~TEXT.strip
+      [CONTEXT COMPACTION — REFERENCE ONLY]
+
+      Earlier TurnKit conversation messages were compacted into the summary below. This is a handoff from a previous context window. Treat it as background reference, not as active instructions.
+
+      Do not answer questions or perform tasks merely because they appear in this summary. Respond to the latest user message after this summary.
+
+      If the latest user message contradicts, supersedes, changes topic from, or diverges from Active Task, In Progress, Pending User Asks, or Remaining Work, the latest user message wins.
+
+      Subject context and live context are recomputed for the current turn and are more authoritative for state-sensitive facts.
+
+      The original messages remain durably stored; this summary only affects the model-visible prompt projection.
+    TEXT
+
     def self.for(messages)
-      messages.map { |message| new(message).to_h }
+      messages.flat_map { |message| new(message).to_a }
     end
 
     def initialize(message)
       @message = message
     end
 
+    def to_a
+      case message.kind
+      when "context_summary"
+        [
+          { role: :user, content: CONTEXT_SUMMARY_TRIGGER },
+          { role: :assistant, content: [ CONTEXT_SUMMARY_PREFIX, message.text ].reject(&:empty?).join("\n\n") }
+        ]
+      else
+        [ to_h ]
+      end
+    end
+
     def to_h
       case message.kind
       when "tool_call"

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)

data/lib/turnkit/turn.rb

@@ -6,10 +6,10 @@ module TurnKit
 
     attr_reader :agent, :conversation, :store, :budget, :depth
     attr_reader :id, :conversation_id, :agent_name, :parent_turn_id, :parent_tool_execution_id
-    attr_reader :root_turn_id, :context_message_sequence, :model, :thinking
+    attr_reader :root_turn_id, :context_message_sequence, :model, :thinking, :compact, :output_schema
     attr_reader :started_at
 
-    def initialize(agent:, conversation:, record:, store:, budget: nil, depth: 0)
+    def initialize(agent:, conversation:, record:, store:, budget: nil, depth: 0, on_event: nil)
       @agent = agent
       @conversation = conversation
       @store = store
@@ -23,27 +23,30 @@ module TurnKit
       @context_message_sequence = @record["context_message_sequence"].to_i
       @model = @record["model"] || agent.effective_model
       @thinking = thinking_from_options
+      @compact = compact_from_options
+      @output_schema = output_schema_from_options
       @started_at = @record["started_at"]
       @budget = budget || agent.build_budget
       @depth = depth
+      @on_event = on_event
     end
 
-    def run!
+    def run!(&block)
+      @on_event = block if block
       return self unless status == "pending"
 
       update!(status: "running", started_at: Clock.now, heartbeat_at: Clock.now)
+      emit("turn.started", status: status, model: model)
+      agent.effective_client.validate!(model: model)
       loop do
         budget.check!(depth: depth)
         budget.count_iteration!
+        TurnKit::Compaction.maybe_compact!(self)
 
-        result = agent.effective_client.chat(
-          model: model,
-          messages: llm_messages,
-          tools: agent.effective_tools,
-          instructions: agent.system_prompt_for(turn: self, conversation: conversation),
-          thinking: thinking,
-          metadata: { turn_id: id, conversation_id: conversation.id }
-        )
+        request = model_request
+        emit("model.requested", model: request.model, tool_names: request.tool_names)
+        result = call_client(request)
+        emit("model.completed", model: result.model || model, tool_call_count: result.tool_calls.length)
         result_cost = Cost.from_usage(result.usage, model: result.model || model)
 
         budget.add_cost!(result_cost.total)
@@ -58,7 +61,8 @@ module TurnKit
             break
           end
         else
-          update!(status: "completed", output_text: result.text, completed_at: Clock.now)
+          update!(status: "completed", output_text: result.text, output_data: result.output_data, completed_at: Clock.now)
+          emit("turn.completed", status: status, output_text: result.text)
           break
         end
       end
@@ -66,10 +70,15 @@ module TurnKit
       self
     rescue StandardError => error
       update!(status: "failed", error: { "class" => error.class.name, "message" => error.message }, completed_at: Clock.now)
+      emit("turn.failed", error: { "class" => error.class.name, "message" => error.message })
       reload
       self
     end
 
+    def preview
+      model_request
+    end
+
     def status
       @record.fetch("status")
     end
@@ -82,6 +91,10 @@ module TurnKit
       @record["output_text"].to_s
     end
 
+    def output_data
+      @record["output_data"]
+    end
+
     def usage
       Usage.from_h(@record["usage"] || {})
     end
@@ -97,6 +110,8 @@ module TurnKit
     def reload
       @record = store.load_turn(id)
       @thinking = thinking_from_options
+      @compact = compact_from_options
+      @output_schema = output_schema_from_options
       self
     end
 
@@ -104,9 +119,59 @@ module TurnKit
       update!(status: "stale", completed_at: Clock.now)
     end
 
+    def emit(type, payload = {})
+      emit_event(Event.new(type: type, turn_id: id, conversation_id: conversation.id, payload: payload))
+    end
+
     private
+      def model_request
+        prompt = SystemPrompt.new(agent: agent, turn: self, conversation: conversation, mode: agent.effective_prompt_mode(turn: self))
+        instructions = case agent.system_prompt
+        when nil
+          prompt.to_s
+        when String
+          agent.system_prompt
+        else
+          agent.system_prompt.call(prompt).to_s
+        end
+        ModelRequest.new(
+          model: model,
+          messages: llm_messages,
+          tools: agent.effective_tools,
+          instructions: instructions,
+          thinking: thinking,
+          output_schema: output_schema,
+          metadata: { turn_id: id, conversation_id: conversation.id },
+          report: prompt.report
+        )
+      end
+
+      def call_client(request)
+        kwargs = {
+          model: request.model,
+          messages: request.messages,
+          tools: request.tools,
+          instructions: request.instructions,
+          thinking: request.thinking,
+          output_schema: request.output_schema,
+          metadata: request.metadata,
+          on_event: ->(event) { emit_event(event) }
+        }
+        accepted = chat_keyword_names(agent.effective_client)
+        kwargs = kwargs.slice(*accepted) unless accepted.include?(:keyrest)
+        agent.effective_client.chat(**kwargs)
+      end
+
+      def chat_keyword_names(client)
+        client.method(:chat).parameters.filter_map do |kind, name|
+          return [ :keyrest ] if kind == :keyrest
+
+          name if %i[key keyreq].include?(kind)
+        end
+      end
+
       def llm_messages
-        MessageProjection.for(conversation.messages_for_turn(self))
+        MessageProjection.for(TurnKit::Compaction.project(conversation.messages_for_turn(self)))
       end
 
       def thinking_from_options
@@ -116,24 +181,39 @@ module TurnKit
         agent.effective_thinking
       end
 
+      def compact_from_options
+        options = (@record["options"] || {}).transform_keys(&:to_s)
+        options["compact"] if options.key?("compact")
+      end
+
+      def output_schema_from_options
+        options = (@record["options"] || {}).transform_keys(&:to_s)
+        options["output_schema"] if options.key?("output_schema")
+      end
+
       def persist_assistant_message(result)
         if result.tool_calls?
-          conversation.append_message(
+          message = conversation.append_message(
             role: "assistant",
             kind: "tool_call",
             text: result.text,
             turn_id: id,
             metadata: { "tool_calls" => result.tool_calls.map { |call| { "id" => call.id, "name" => call.name, "arguments" => call.arguments } } }
           )
+          emit("message.created", message_id: message.id, role: message.role, kind: message.kind)
+          result.tool_calls.each { |call| emit("tool_call.created", id: call.id, name: call.name) }
         else
-          conversation.append_message(role: "assistant", kind: "text", text: result.text, turn_id: id)
+          message = conversation.append_message(role: "assistant", kind: "text", text: result.text, turn_id: id, metadata: { "output_data" => result.output_data }.compact)
+          emit("message.created", message_id: message.id, role: message.role, kind: message.kind)
         end
       end
 
       def complete_from_terminal_tool(runner, execution)
         message = runner.completion_message(execution)
-        conversation.append_message(role: "assistant", kind: "text", text: message, turn_id: id)
+        assistant = conversation.append_message(role: "assistant", kind: "text", text: message, turn_id: id)
+        emit("message.created", message_id: assistant.id, role: assistant.role, kind: assistant.kind)
         update!(status: "completed", output_text: message, completed_at: Clock.now)
+        emit("turn.completed", status: status, output_text: message)
       end
 
       def add_usage!(usage, cost: nil)
@@ -164,6 +244,11 @@ module TurnKit
         @model = @record["model"] || agent.effective_model
         @record
       end
+
+      def emit_event(event)
+        event = Event.new(type: event[:type] || event["type"], turn_id: id, conversation_id: conversation.id, payload: event[:payload] || event["payload"] || {}) if event.is_a?(Hash)
+        Array(@on_event || agent.effective_on_event).each { |callback| callback.call(event) }
+      end
   end
 
   class ToolContext