turnkit 0.2.10 → 0.4.0

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,9 +39,19 @@ 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))
+        rescue BudgetError => error
+          finish_error(execution, tool_call, error.message, details: { "class" => error.class.name, "budget_denied" => true })
+          raise
         rescue StandardError => error
           return finish_error(execution, tool_call, error.message, details: { "class" => error.class.name })
         end
@@ -63,32 +70,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

data/lib/turnkit/turn.rb

@@ -36,12 +36,18 @@ module TurnKit
       @on_event = block if block
       return self unless status == "pending"
 
-      update!(status: "running", started_at: Clock.now, heartbeat_at: Clock.now)
+      claimed = store.claim_turn(id, from: "pending", to: "running", started_at: Clock.now, heartbeat_at: Clock.now)
+      return self unless claimed
+
+      @record = claimed
+      @started_at = @record["started_at"]
       emit("turn.started", status: status, model: model)
       agent.effective_client.validate!(model: model)
+      @budget = Budget.resume(store: store, root_turn_id: root_turn_id, limits: budget_limits)
+      revisions_used = 0
       loop do
         budget.check!(depth: depth)
-        budget.count_iteration!
+        count_iteration!
         TurnKit::Compaction.maybe_compact!(self)
 
         request = model_request
@@ -58,13 +64,24 @@ module TurnKit
           runner = ToolRunner.new(self)
           terminal = runner.dispatch(result.tool_calls)
           if terminal
-            complete_from_terminal_tool(runner, terminal)
-            break
+            candidate = append_terminal_completion(runner, terminal)
+          else
+            next
           end
         else
-          complete_with_output(result.text, output_data: result.output_data)
-          break
+          candidate = result.text
         end
+
+        audit = check_policy(candidate, output_data: result.output_data)
+        if should_revise?(audit, revisions_used)
+          revisions_used += 1
+          append_revision_message(audit, attempt: revisions_used, terminal_tool_name: terminal&.tool_name)
+          emit("output_policy.revision", violation_count: audit.violations.length, attempt: revisions_used)
+          next
+        end
+
+        complete_with_output(candidate, output_data: result.output_data, audit: audit)
+        break
       end
       reload
       self
@@ -95,8 +112,8 @@ module TurnKit
       @record["output_data"]
     end
 
-    def output_audit
-      (@record["options"] || {})["output_audit"]
+    def policy_audit
+      (@record["options"] || {})["policy_audit"]
     end
 
     def usage
@@ -150,6 +167,59 @@ module TurnKit
       result
     end
 
+    def paint(prompt, model:, provider: nil, size: nil, assume_model_exists: nil, input_images: nil, mask: nil, params: {}, metadata: {}, client: nil)
+      claimed_standalone = false
+      case status
+      when "pending"
+        claimed = store.claim_turn(id, from: "pending", to: "running", started_at: Clock.now, heartbeat_at: Clock.now)
+        raise Error, "turn is already running" unless claimed
+
+        @record = claimed
+        @started_at = @record["started_at"]
+        @budget = Budget.resume(store: store, root_turn_id: root_turn_id, limits: budget_limits)
+        claimed_standalone = true
+        emit("turn.started", status: status, model: model)
+      when "running"
+        # Image tools call this while their parent turn is running.
+      else
+        raise Error, "cannot paint for #{status} turn"
+      end
+
+      image_client = client || agent.effective_client
+      request = {
+        prompt: prompt,
+        model: model,
+        provider: provider,
+        size: size,
+        assume_model_exists: assume_model_exists,
+        input_images: input_images,
+        mask: mask,
+        params: params || {},
+        metadata: { turn_id: id, conversation_id: conversation.id }.merge(metadata || {})
+      }
+
+      image_client.validate!(model: model)
+      emit("image.requested", request.except(:input_images, :mask))
+      result = call_image_client(image_client, request)
+      result_cost = Cost.from_usage(result.usage, model: result.model || model)
+      add_usage!(result.usage, cost: result_cost)
+      budget.add_cost!(result_cost.total)
+      image = result.images.first
+      raise Error, "image client returned no image" unless image
+      raise Error, "image client returned image without url or data" if image.url.to_s.empty? && image.data.to_s.empty?
+
+      persist_image_message(image)
+      emit("image.completed", image: image.to_h, model: image.model || model, provider: image.provider || provider&.to_s, mime_type: image.mime_type, usage: result.usage.to_h, cost: result_cost.to_h, metadata: metadata || {})
+      complete_with_output(image.url.to_s, output_data: { "type" => "image", "images" => [ image.to_h ] }, audit: check_policy(image.url.to_s, output_data: { "type" => "image", "images" => [ image.to_h ] })) if claimed_standalone
+      image
+    rescue StandardError => error
+      if claimed_standalone
+        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 })
+      end
+      raise
+    end
+
     private
       def model_request
         prompt = SystemPrompt.new(agent: agent, turn: self, conversation: conversation, mode: prompt_mode || agent.effective_prompt_mode(turn: self))
@@ -197,6 +267,16 @@ module TurnKit
         end
       end
 
+      def call_image_client(client, request)
+        kwargs = request.merge(on_event: ->(event) { emit_event(event) })
+        accepted = client.method(:paint).parameters.filter_map do |kind, name|
+          return client.paint(**kwargs) if kind == :keyrest
+
+          name if %i[key keyreq].include?(kind)
+        end
+        client.paint(**kwargs.slice(*accepted))
+      end
+
       def llm_messages
         MessageProjection.for(TurnKit::Compaction.project(conversation.messages_for_turn(self)))
       end
@@ -248,36 +328,43 @@ module TurnKit
           message = conversation.append_message(
             role: "assistant",
             kind: "tool_call",
-            text: result.text,
+            content: result.parts,
             turn_id: id,
-            metadata: { "tool_calls" => result.tool_calls.map { |call| { "id" => call.id, "name" => call.name, "arguments" => call.arguments } } }
+            metadata: {}
           )
           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) }
+        elsif result.image?
+          message = conversation.append_message(role: "assistant", kind: "image", content: result.images.map { |image| image.to_h.merge("type" => "image") }, turn_id: id, metadata: { "output_data" => result.output_data }.compact)
+          emit("message.created", message_id: message.id, role: message.role, kind: message.kind)
         else
           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)
+      def persist_image_message(image)
+        message = conversation.append_message(role: "assistant", kind: "image", content: [ image.to_h.merge("type" => "image") ], turn_id: id, metadata: { "output_data" => { "type" => "image", "images" => [ image.to_h ] } })
+        emit("message.created", message_id: message.id, role: message.role, kind: message.kind)
+      end
+
+      def append_terminal_completion(runner, execution)
         message = runner.completion_message(execution)
         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)
-        complete_with_output(message)
+        message
       end
 
-      def complete_with_output(text, output_data: nil)
-        audit = audit_output(text, output_data: output_data)
+      def complete_with_output(text, output_data: nil, audit: nil)
         attrs = { output_text: text, output_data: output_data, completed_at: Clock.now }
-        if audit && !audit.clean? && agent.output_audit_mode == :fail
+        if audit && !audit.clean? && agent.output_policy_mode == :fail
           attrs[:status] = "failed"
-          attrs[:error] = { "class" => "TurnKit::OutputAudit", "message" => audit.messages.join("; "), "output_audit" => audit.to_h }
+          attrs[:error] = { "class" => "TurnKit::OutputAudit", "message" => audit.messages.join("; "), "policy_audit" => audit.to_h }
         else
           attrs[:status] = "completed"
         end
         update!(attrs)
-        persist_output_audit(audit) if audit
+        persist_policy_audit(audit) if audit
 
         if failed?
           emit("turn.failed", error: @record["error"])
@@ -286,18 +373,48 @@ module TurnKit
         end
       end
 
-      def audit_output(text, output_data: nil)
-        constraints = agent.effective_output_audit
+      def check_policy(text, output_data: nil)
+        constraints = agent.effective_output_policy
         return nil if constraints.empty?
 
         output = output_data.nil? ? text : output_data
-        TurnKit.audit_output(output, constraints: constraints, context: { turn: self, output_text: text, output_data: output_data })
+        TurnKit.check_output_policy(output, constraints: constraints, context: { turn: self, output_text: text, output_data: output_data })
       end
 
-      def persist_output_audit(audit)
-        options = (@record["options"] || {}).merge("output_audit" => audit.to_h)
+      def persist_policy_audit(audit)
+        options = (@record["options"] || {}).merge("policy_audit" => audit.to_h)
         update!(options: options)
-        emit("output_audit.completed", clean: audit.clean?, violation_count: audit.violations.length)
+        emit("output_policy.completed", clean: audit.clean?, violation_count: audit.violations.length)
+      end
+
+      def should_revise?(audit, revisions_used)
+        audit && !audit.clean? && revisions_used < agent.output_retries
+      end
+
+      def append_revision_message(audit, attempt:, terminal_tool_name: nil)
+        text = <<~TEXT.strip
+          The previous output failed policy checks.
+
+          Revise the previous output. Do not introduce new claims.
+          Do not deviate from the skill or policy below.
+
+          #{revision_policy_blocks}
+
+          Violations:
+          #{audit.violations.each_with_index.map { |violation, index| "#{index + 1}. #{violation.rule}: #{violation.message}" }.join("\n")}
+          #{terminal_tool_name ? "\nResubmit via #{terminal_tool_name}." : ""}
+        TEXT
+        message = conversation.append_message(role: "user", kind: "text", text: text, turn_id: id, metadata: { "source" => "output_policy", "attempt" => attempt })
+        emit("message.created", message_id: message.id, role: message.role, kind: message.kind)
+      end
+
+      def revision_policy_blocks
+        agent.effective_output_policy.filter_map do |policy|
+          next unless policy.respond_to?(:content)
+
+          key = policy.respond_to?(:name) ? policy.name : "output_policy"
+          "<skill key=\"#{key}\">\n#{policy.content}\n</skill>"
+        end.join("\n\n")
       end
 
       def add_usage!(usage, cost: nil)
@@ -316,6 +433,27 @@ module TurnKit
         update!(attributes)
       end
 
+      def count_iteration!
+        budget.count_iteration!
+        options = (@record["options"] || {}).merge("iterations" => (@record.dig("options", "iterations").to_i + 1))
+        update!(options: options)
+      end
+
+      def heartbeat!
+        update!(heartbeat_at: Clock.now)
+      end
+
+      def budget_limits
+        {
+          max_iterations: agent.max_iterations || TurnKit.max_iterations,
+          timeout: agent.timeout || TurnKit.timeout,
+          max_depth: agent.max_depth || TurnKit.max_depth,
+          max_tool_executions: agent.max_tool_executions || TurnKit.max_tool_executions,
+          max_tool_executions_by_name: agent.max_tool_executions_by_name || TurnKit.max_tool_executions_by_name,
+          max_spend: agent.max_spend || TurnKit.max_spend
+        }
+      end
+
       def aggregate_cost(current, cost)
         return cost unless current
 

data/lib/turnkit/version.rb

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