turnkit 0.2.10 → 0.3.0

data/lib/turnkit/compaction.rb

@@ -83,6 +83,7 @@ module TurnKit
       - Keep every section.
       - Use terse bullets.
       - Preserve exact file paths, commands, error strings, IDs, and important values.
+      - In Tool Results To Remember, record which skill keys were loaded.
       - Do not invent facts.
       - Do not include secrets.
       - Do not include a greeting or preamble.

data/lib/turnkit/error.rb

@@ -5,6 +5,7 @@ module TurnKit
   class BudgetError < Error; end
   class ConfigError < Error; end
   class CompactionError < Error; end
+  class InputError < Error; end
   class ModelAccessError < ConfigError; end
   class StoreError < Error; end
   class ToolError < Error; end

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

@@ -50,7 +50,6 @@ class CreateTurnkitTables < ActiveRecord::Migration[7.1]
       t.string :kind, null: false
       t.integer :sequence, null: false
       t.json :content, null: false, default: []
-      t.text :text
       t.string :tool_execution_uid
       t.string :provider_message_id
       t.json :metadata, null: false, default: {}

data/lib/turnkit/load_skill_tool.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module TurnKit
+  class LoadSkillTool < Tool
+    tool_name "load_skill"
+    description "Load the full instructions for an available skill by key."
+    parameter :key, :string, required: true, description: "Skill key from <skills_available>."
+
+    def self.for(skills)
+      Class.new(self) do
+        tool_name "load_skill"
+        @skills = Array(skills).to_h { |skill| [ skill.key, skill ] }
+        class << self
+          attr_reader :skills
+        end
+      end
+    end
+
+    def call(key:, context:)
+      skill = self.class.skills[key]
+      unless skill
+        available = self.class.skills.keys.join(", ")
+        raise ToolError, "unknown skill: #{key}. Available: #{available}"
+      end
+
+      { "key" => skill.key, "name" => skill.name, "content" => skill.content }
+    end
+  end
+end

data/lib/turnkit/memory_store.rb

@@ -68,6 +68,17 @@ module TurnKit
       end
     end
 
+    def claim_turn(id, from: "pending", to: "running", **attributes)
+      attrs = Record.turn_update(attributes.merge(status: to))
+      @mutex.synchronize do
+        record = @turns.fetch(id)
+        return nil unless record["status"] == from
+
+        record.merge!(attrs.merge("updated_at" => Clock.now))
+        duplicate(record)
+      end
+    end
+
     def list_turns(root_turn_id: nil, conversation_id: nil, agent_name: nil)
       @mutex.synchronize do
         rows = @turns.values

data/lib/turnkit/message.rb

@@ -6,7 +6,7 @@ module TurnKit
     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
+    attr_reader :content, :tool_execution_id, :provider_message_id, :metadata, :created_at
 
     def initialize(attributes = {})
       attrs = stringify(attributes)
@@ -16,8 +16,7 @@ module TurnKit
       @role = attrs.fetch("role").to_s
       @kind = attrs.fetch("kind", "text").to_s
       @sequence = attrs.fetch("sequence").to_i
-      @content = normalize_content(attrs["content"] || attrs["text"])
-      @text = attrs["text"] || extract_text(@content)
+      @content = normalize_content(attrs["content"].nil? ? attrs["text"] : attrs["content"])
       @tool_execution_id = attrs["tool_execution_id"]
       @provider_message_id = attrs["provider_message_id"]
       @metadata = attrs["metadata"] || {}
@@ -35,7 +34,6 @@ module TurnKit
         "kind" => kind,
         "sequence" => sequence,
         "content" => content,
-        "text" => text,
         "tool_execution_id" => tool_execution_id,
         "provider_message_id" => provider_message_id,
         "metadata" => metadata,
@@ -59,6 +57,13 @@ module TurnKit
       kind == "context_summary"
     end
 
+    def text
+      content.filter_map do |part|
+        attrs = stringify(part)
+        attrs["text"] if attrs["type"] == "text"
+      end.join("\n")
+    end
+
     def compaction_metadata
       metadata.fetch("compaction", {})
     end
@@ -69,13 +74,15 @@ module TurnKit
       end
 
       def normalize_content(value)
-        return value if value.is_a?(Array)
+        return Array(value).map { |part| normalize_part(part) } if value.is_a?(Array)
 
         [ { "type" => "text", "text" => value.to_s } ]
       end
 
-      def extract_text(blocks)
-        Array(blocks).filter_map { |block| block.is_a?(Hash) ? block["text"] || block[:text] : nil }.join("\n")
+      def normalize_part(part)
+        attrs = part.respond_to?(:to_h) ? part.to_h.transform_keys(&:to_s) : { "type" => "text", "text" => part.to_s }
+        attrs["type"] ||= "text"
+        attrs
       end
 
       def validate!

data/lib/turnkit/message_projection.rb

@@ -40,9 +40,10 @@ module TurnKit
     def to_h
       case message.kind
       when "tool_call"
-        { role: :assistant, content: message.text, tool_calls: message.metadata.fetch("tool_calls", []) }
+        { role: :assistant, content: projected_content, tool_calls: tool_call_parts }
       when "tool_result"
-        { role: :tool, content: message.text, tool_call_id: message.metadata["tool_call_id"] }
+        part = message.content.find { |candidate| candidate.fetch("type") == "tool_result" }
+        { role: :tool, content: part&.fetch("text", message.text) || message.text, tool_call_id: part&.fetch("tool_call_id", nil) }
       else
         { role: message.role.to_sym, content: message.text }
       end
@@ -50,5 +51,19 @@ module TurnKit
 
     private
       attr_reader :message
+
+      def projected_content
+        parts = message.content.reject { |part| %w[tool_call provider].include?(part.fetch("type")) }
+        ordered = parts.select { |part| part.fetch("type") == "thinking" } + parts.select { |part| part.fetch("type") == "text" }
+        ordered.filter_map { |part| part.fetch("text", nil) }.join("\n")
+      end
+
+      def tool_call_parts
+        message.content.filter_map do |part|
+          next unless part.fetch("type") == "tool_call"
+
+          { "id" => part.fetch("id"), "name" => part.fetch("name"), "arguments" => part["arguments"] || {} }
+        end
+      end
   end
 end

data/lib/turnkit/output_policy.rb

@@ -27,6 +27,10 @@ module TurnKit
       new(name: name || File.basename(path, File.extname(path)), content: File.read(path), **options)
     end
 
+    def self.from_skill(skill, **options)
+      new(name: skill.key, content: skill.content, **options)
+    end
+
     def initialize(content:, name: "output_policy", model: nil, thinking: nil, client: nil)
       @name = name.to_s
       @content = content.to_s
@@ -78,6 +82,8 @@ module TurnKit
 
           Set approved to true only when the output satisfies the policy. For each violation, include a concise rule and message. Do not repair the output. Do not wrap the JSON in Markdown. Do not include commentary before or after the JSON.
 
+          The policy may be a skill; treat its output-facing rules as normative and ignore process steps that are not observable in the output.
+
           Policy:
           #{content}
         TEXT

data/lib/turnkit/result.rb

@@ -2,19 +2,44 @@
 
 module TurnKit
   class Result
-    attr_reader :text, :tool_calls, :usage, :model, :finish_reason, :output_data
+    attr_reader :parts, :usage, :model, :finish_reason, :output_data
 
-    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)
+    def initialize(text: "", tool_calls: [], parts: nil, usage: Usage.new, model: nil, finish_reason: nil, output_data: nil)
+      @parts = parts ? normalize_parts(parts) : synthesize_parts(text: text, tool_calls: tool_calls)
       @usage = usage || Usage.new
       @model = model
       @finish_reason = finish_reason
       @output_data = output_data
     end
 
+    def text
+      parts.filter_map { |part| part["text"] if part["type"] == "text" }.join("\n")
+    end
+
+    def tool_calls
+      parts.filter_map do |part|
+        next unless part["type"] == "tool_call"
+
+        ToolCall.new(id: part.fetch("id"), name: part.fetch("name"), arguments: part["arguments"] || {}, arguments_error: part["arguments_error"])
+      end
+    end
+
     def tool_calls?
       tool_calls.any?
     end
+
+    private
+      def synthesize_parts(text:, tool_calls:)
+        parts = []
+        parts << { "type" => "text", "text" => text.to_s } unless text.to_s.empty?
+        Array(tool_calls).each do |call|
+          parts << { "type" => "tool_call", "id" => call.id, "name" => call.name, "arguments" => call.arguments, "arguments_error" => call.arguments_error }.compact
+        end
+        parts
+      end
+
+      def normalize_parts(value)
+        Array(value).map { |part| part.to_h.transform_keys(&:to_s) }
+      end
   end
 end

data/lib/turnkit/run.rb

@@ -14,8 +14,8 @@ module TurnKit
     def output = output_text
     def output_text = turn.output_text
     def output_data = turn.output_data
-    def output_audit = turn.output_audit
-    def output_audit_clean? = output_audit.nil? || output_audit.fetch("clean", false)
+    def policy_audit = turn.policy_audit
+    def policy_clean? = policy_audit.nil? || policy_audit.fetch("clean", false)
     def usage = Usage.from_records(turn_records)
     def cost = Cost.from_records(turn_records)
     def steps = turn_records.length
@@ -27,9 +27,8 @@ module TurnKit
     end
 
     def messages
-      turn_records.flat_map do |record|
-        conversation = turn.store.load_conversation(record.fetch("conversation_id"))
-        turn.store.list_messages(conversation.fetch("id"))
+      turn_records.map { |record| record.fetch("conversation_id") }.uniq.flat_map do |conversation_id|
+        turn.store.list_messages(conversation_id).map { |attrs| Message.new(attrs) }
       end
     end
 

data/lib/turnkit/schema_check.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module TurnKit
+  module SchemaCheck
+    module_function
+
+    def validate!(value, schema, error_class: ToolValidationError, label: "input")
+      schema = stringify_schema(schema || {})
+      type = schema["type"] || "object"
+      validate_type!(value, type, schema, error_class: error_class, label: label)
+      validate_enum!(value, schema, error_class: error_class, label: label)
+
+      if type == "object" && schema["properties"]
+        attrs = value.respond_to?(:to_h) ? value.to_h.transform_keys(&:to_s) : {}
+        required = Array(schema["required"]).map(&:to_s)
+        missing = required.reject { |name| attrs.key?(name) }
+        raise error_class, "#{label} missing required field#{missing.length == 1 ? "" : "s"}: #{missing.join(", ")}" if missing.any?
+
+        schema.fetch("properties", {}).each do |name, child_schema|
+          next unless attrs.key?(name)
+
+          validate!(attrs[name], child_schema, error_class: error_class, label: "#{label}.#{name}")
+        end
+      elsif type == "array" && schema["items"] && value.is_a?(Array)
+        value.each_with_index do |item, index|
+          validate!(item, schema["items"], error_class: error_class, label: "#{label}[#{index}]")
+        end
+      end
+
+      true
+    end
+
+    def stringify_schema(value)
+      case value
+      when Hash
+        value.transform_keys(&:to_s).transform_values { |nested| stringify_schema(nested) }
+      when Array
+        value.map { |nested| stringify_schema(nested) }
+      when Symbol
+        value.to_s
+      else
+        value
+      end
+    end
+
+    def validate_type!(value, type, schema, error_class:, label:)
+      return if value.nil? && !Array(schema["required"]).include?(label.to_s)
+
+      valid = case type.to_s
+      when "string" then value.is_a?(String)
+      when "integer" then value.is_a?(Integer)
+      when "number" then value.is_a?(Numeric)
+      when "boolean" then value == true || value == false
+      when "array" then value.is_a?(Array)
+      when "object" then value.is_a?(Hash)
+      else true
+      end
+      raise error_class, "#{label} must be a #{type}" unless valid
+    end
+
+    def validate_enum!(value, schema, error_class:, label:)
+      enum = schema["enum"]
+      return unless enum && !Array(enum).include?(value)
+
+      raise error_class, "#{label} must be one of: #{Array(enum).join(", ")}"
+    end
+  end
+end

data/lib/turnkit/skill.rb

@@ -1,13 +1,15 @@
 # frozen_string_literal: true
 
+require "yaml"
+
 module TurnKit
   class Skill
     attr_reader :key, :name, :description, :content
 
     def self.from_file(path, key: nil, name: nil, description: "")
-      content = File.read(path)
+      content, metadata = parse_file(File.read(path))
       base = File.basename(path, File.extname(path))
-      new(key: key || base, name: name || base.tr("_-", " ").split.map(&:capitalize).join(" "), description: description, content: content)
+      new(key: key || base, name: name || metadata["name"] || base.tr("_-", " ").split.map(&:capitalize).join(" "), description: description.to_s.empty? ? metadata["description"].to_s : description, content: content)
     end
 
     def self.from_directory(path, pattern: "*.md")
@@ -23,5 +25,17 @@ module TurnKit
       raise ArgumentError, "name is required" if @name.empty?
       raise ArgumentError, "content is required" if @content.empty?
     end
+
+    def self.parse_file(content)
+      text = content.to_s
+      return [ text, {} ] unless text.start_with?("---\n")
+
+      _, frontmatter, body = text.split(/^---\s*$/, 3)
+      return [ text, {} ] unless body
+
+      [ body.sub(/\A\n/, ""), YAML.safe_load(frontmatter, permitted_classes: [ Symbol ], aliases: false) || {} ]
+    rescue Psych::SyntaxError
+      [ text, {} ]
+    end
   end
 end

data/lib/turnkit/store.rb

@@ -12,6 +12,12 @@ module TurnKit
     def create_turn(_attributes) = raise(NotImplementedError)
     def load_turn(_id) = raise(NotImplementedError)
     def update_turn(_id, _attributes) = raise(NotImplementedError)
+    def claim_turn(id, from: "pending", to: "running", **attributes)
+      turn = load_turn(id)
+      return nil unless turn["status"] == from
+
+      update_turn(id, attributes.merge(status: to))
+    end
     def list_turns(root_turn_id: nil, conversation_id: nil, agent_name: nil) = raise(NotImplementedError)
 
     def create_tool_execution(_attributes) = raise(NotImplementedError)

data/lib/turnkit/stores/active_record_store.rb

@@ -38,7 +38,6 @@ module TurnKit
           kind: message.fetch("kind"),
           sequence: message.fetch("sequence"),
           content: message.fetch("content"),
-          text: message.fetch("text"),
           tool_execution_uid: message["tool_execution_id"],
           provider_message_id: message["provider_message_id"],
           metadata: message.fetch("metadata")
@@ -93,6 +92,15 @@ module TurnKit
       turn_hash(record)
     end
 
+    def claim_turn(id, from: "pending", to: "running", **attributes)
+      attrs = Record.turn_update(attributes.merge(status: to))
+      attrs.delete("output_data") unless turn_has_attribute?("output_data")
+      affected = turn_class.where(uid: id, status: from).update_all(attrs.merge(updated_at: Clock.now))
+      return nil if affected.zero?
+
+      load_turn(id)
+    end
+
     def list_turns(root_turn_id: nil, conversation_id: nil, agent_name: nil)
       scope = turn_class.all
       scope = scope.where(root_turn_uid: root_turn_id) if root_turn_id
@@ -185,7 +193,7 @@ module TurnKit
         {
           "id" => record.uid, "conversation_id" => record.conversation_uid, "turn_id" => record.turn_uid,
           "role" => record.role, "kind" => record.kind, "sequence" => record.sequence, "content" => record.content,
-          "text" => record.text, "tool_execution_id" => record.tool_execution_uid,
+          "tool_execution_id" => record.tool_execution_uid,
           "provider_message_id" => record.provider_message_id, "metadata" => record.metadata || {}, "created_at" => record.created_at
         }
       end

data/lib/turnkit/sub_agent_tool.rb

@@ -42,7 +42,8 @@ module TurnKit
         agent: sub_agent,
         on_event: parent_turn.agent.effective_on_event
       )
-      { "conversation_id" => conversation.id, "turn_id" => child.id, "status" => child.status, "result" => child.output_text, "output_data" => child.output_data }.compact
+      error = child.store.load_turn(child.id)["error"] if child.failed?
+      { "conversation_id" => conversation.id, "turn_id" => child.id, "status" => child.status, "result" => child.output_text, "output_data" => child.output_data, "error" => error }.compact
     end
   end
 end

data/lib/turnkit/system_prompt.rb

@@ -194,7 +194,7 @@ module TurnKit
 
       tagged(
         "skills_available",
-        "Load or follow a skill when the task matches its description.\n\n#{entries.join("\n")}"
+        "These skills are listed but not loaded. When a task matches a skill description, call load_skill with the skill key before relying on it.\n\n#{entries.join("\n")}"
       )
     end
 

data/lib/turnkit/tool.rb

@@ -106,7 +106,7 @@ module TurnKit
             next
           end
 
-          validate_value!(value, param)
+          SchemaCheck.validate!(value, schema_for(param), error_class: ToolValidationError, label: name)
           normalized[name] = value
         end
         normalized
@@ -169,26 +169,7 @@ module TurnKit
         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
+          SchemaCheck.validate!(value, schema_for(param), error_class: ToolValidationError, label: param.fetch(:name))
         end
 
         def accepts_turnkit_context?(instance)

data/lib/turnkit/tool_call.rb

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

data/lib/turnkit/tool_runner.rb

@@ -7,9 +7,12 @@ module TurnKit
     end
 
     def dispatch(tool_calls)
-      tool_calls.each do |tool_call|
+      tool_calls.each_with_index do |tool_call, index|
         execution = run(tool_call)
-        return execution if execution.completed? && tool_for(tool_call.name)&.ends_turn?
+        if execution.completed? && tool_for(tool_call.name)&.ends_turn?
+          skip_remaining(tool_calls.drop(index + 1), terminal: tool_call)
+          return execution
+        end
       end
       nil
     end
@@ -24,13 +27,7 @@ module TurnKit
 
       def run(tool_call)
         execution = ToolExecution.new(create_execution(tool_call))
-
-        begin
-          turn.budget.count_tool_execution!(tool_call.name)
-        rescue BudgetError => error
-          finish_error(execution, tool_call, error.message, details: { "class" => error.class.name, "budget_denied" => true })
-          raise
-        end
+        heartbeat!
 
         tool = tool_for(tool_call.name)
 
@@ -42,6 +39,13 @@ module TurnKit
           return finish_error(execution, tool_call, tool_call.arguments_error)
         end
 
+        begin
+          turn.budget.count_tool_execution!(tool_call.name)
+        rescue BudgetError => error
+          finish_error(execution, tool_call, error.message, details: { "class" => error.class.name, "budget_denied" => true })
+          raise
+        end
+
         context = ToolContext.new(turn: turn, execution: execution)
         payload = begin
           normalize_payload(call_tool(tool, tool_call.arguments, context: context))
@@ -63,32 +67,50 @@ module TurnKit
       end
 
       def finish_success(execution, tool_call, payload)
+        json = payload.to_json
         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, result_chars: payload.to_json.length)
+        append_result(execution, tool_call, payload, json: json, error: false)
+        heartbeat!
+        turn.emit("tool_call.completed", id: tool_call.id, name: tool_call.name, result_chars: json.length)
         ToolExecution.new(attrs)
       end
 
       def finish_error(execution, tool_call, message, details: nil)
         error = { "message" => message.to_s, "details" => details }.compact
+        json = error.to_json
         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, result_chars: error.to_json.length)
+        append_result(execution, tool_call, error, json: json, error: true)
+        heartbeat!
+        turn.emit("tool_call.failed", id: tool_call.id, name: tool_call.name, error: error, result_chars: json.length)
         ToolExecution.new(attrs)
       end
 
-      def append_result(execution, tool_call, payload)
+      def append_result(execution, tool_call, payload, json: payload.to_json, error: false)
         message = turn.conversation.append_message(
           role: "tool",
           kind: "tool_result",
-          text: payload.to_json,
+          content: [ { "type" => "tool_result", "tool_call_id" => tool_call.id, "text" => json, "error" => error } ],
           turn_id: turn.id,
           tool_execution_id: execution.id,
-          metadata: { "tool_call_id" => tool_call.id, "tool_name" => tool_call.name }
+          metadata: { "tool_name" => tool_call.name }
         )
         turn.emit("message.created", message_id: message.id, role: message.role, kind: message.kind)
       end
 
+      def skip_remaining(calls, terminal:)
+        calls.each do |call|
+          payload = { "skipped" => true, "message" => "not executed: turn ended by #{terminal.name}" }
+          execution = ToolExecution.new(create_execution(call))
+          attrs = turn.store.update_tool_execution(execution.id, "status" => "cancelled", "result" => payload, "completed_at" => Clock.now)
+          append_result(ToolExecution.new(attrs), call, payload)
+          turn.emit("tool_call.skipped", id: call.id, name: call.name)
+        end
+      end
+
+      def heartbeat!
+        turn.send(:heartbeat!)
+      end
+
       def tool_for(name)
         turn.agent.effective_tools.find { |tool| tool.tool_name == name.to_s }
       end