turnkit 0.2.6 → 0.2.7

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, :compact
+    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
@@ -24,28 +24,29 @@ module TurnKit
       @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)
@@ -60,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
@@ -68,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
@@ -84,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
@@ -100,6 +111,7 @@ module TurnKit
       @record = store.load_turn(id)
       @thinking = thinking_from_options
       @compact = compact_from_options
+      @output_schema = output_schema_from_options
       self
     end
 
@@ -107,7 +119,57 @@ 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(TurnKit::Compaction.project(conversation.messages_for_turn(self)))
       end
@@ -124,24 +186,34 @@ module TurnKit
         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)
@@ -172,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

data/lib/turnkit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TurnKit
-  VERSION = "0.2.6"
+  VERSION = "0.2.7"
 end

data/lib/turnkit.rb

@@ -12,6 +12,8 @@ require_relative "turnkit/id"
 require_relative "turnkit/clock"
 require_relative "turnkit/cost"
 require_relative "turnkit/budget"
+require_relative "turnkit/event"
+require_relative "turnkit/model_request"
 require_relative "turnkit/agent"
 require_relative "turnkit/client"
 require_relative "turnkit/conversation"
@@ -49,6 +51,7 @@ module TurnKit
     attr_accessor :prompt_sections, :prompt_behavior, :available_skills
     attr_accessor :prompt_data_max_chars, :context_contributors
     attr_accessor :system_prompt_contributors, :model_prompt_contributors
+    attr_accessor :on_event
     attr_accessor :conversation_record_class, :turn_record_class
     attr_accessor :message_record_class, :tool_execution_record_class
   end
@@ -69,6 +72,7 @@ module TurnKit
   self.context_contributors = []
   self.system_prompt_contributors = []
   self.model_prompt_contributors = {}
+  self.on_event = nil
 
   def self.reconcile_stale!(before: Clock.now - (timeout || 300))
     store.find_stale_turns(before: before).each do |turn|

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: turnkit
 version: !ruby/object:Gem::Version
-  version: 0.2.6
+  version: 0.2.7
 platform: ruby
 authors:
 - Sam Couch
@@ -24,9 +24,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.14'
-description: TurnKit provides a small Ruby runtime for AI agents with conversations,
-  turns, tool calls, terminal tools, file-based skills, sub-agents, and optional Rails
-  persistence.
+description: TurnKit is a Ruby/Rails agent runtime for durable AI conversations, tool
+  calling, skills, sub-agents, context compaction, and persistence.
 email:
 - sam@samcouch.com
 executables: []
@@ -46,6 +45,7 @@ files:
 - lib/turnkit/conversation.rb
 - lib/turnkit/cost.rb
 - lib/turnkit/error.rb
+- lib/turnkit/event.rb
 - lib/turnkit/generators/turnkit/install/templates/conversation.rb
 - lib/turnkit/generators/turnkit/install/templates/create_turnkit_tables.rb
 - lib/turnkit/generators/turnkit/install/templates/initializer.rb
@@ -57,6 +57,7 @@ files:
 - lib/turnkit/memory_store.rb
 - lib/turnkit/message.rb
 - lib/turnkit/message_projection.rb
+- lib/turnkit/model_request.rb
 - lib/turnkit/prompt_context.rb
 - lib/turnkit/prompt_contribution.rb
 - lib/turnkit/prompt_data.rb
@@ -102,5 +103,5 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Durable Ruby AI agent turns, tools, skills, and conversations.
+summary: Ruby/Rails agent runtime for durable AI conversations.
 test_files: []