turnkit 0.2.10 → 0.3.0

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
@@ -248,9 +265,9 @@ 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) }
@@ -260,24 +277,23 @@ module TurnKit
         end
       end
 
-      def complete_from_terminal_tool(runner, execution)
+      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 +302,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 +362,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.3.0"
 end

data/lib/turnkit/workflow.rb

@@ -4,13 +4,7 @@ require_relative "agent"
 
 module TurnKit
   class Workflow
-    attr_reader :name, :description, :instructions, :tools, :skills, :available_skills
-    attr_reader :model, :client, :store, :prompt_mode, :thinking, :compaction, :output_schema
-    attr_reader :on_event
-    attr_reader :max_iterations, :timeout, :cost_limit, :max_depth, :max_tool_executions, :max_tool_executions_by_name
-    attr_reader :output_audit, :output_audit_mode, :output_policy, :output_policy_mode, :output_policy_model, :output_policy_thinking
-
-    DEFAULT_INSTRUCTIONS = <<~TEXT.strip
+    ORCHESTRATOR_PREAMBLE = <<~TEXT.strip
       You are an autonomous task orchestrator. Navigate from the application
       request to a final output without asking the user follow-up questions.
 
@@ -29,104 +23,36 @@ module TurnKit
       limits.
     TEXT
 
-    def initialize(name: "workflow", description: "", instructions: nil,
-      tools: [], skills: [], available_skills: [], model: nil, client: nil,
-      store: nil, prompt_mode: :task, thinking: nil, compaction: nil, on_event: nil,
-      output_schema: nil, max_iterations: nil, timeout: nil, max_spend: nil,
-      cost_limit: nil, max_depth: nil, max_tool_executions: nil, max_tool_executions_by_name: nil,
-      output_audit: nil, output_audit_mode: nil, output_policy: nil, output_policy_mode: nil, output_policy_model: nil, output_policy_thinking: nil)
+    DEFAULT_INSTRUCTIONS = ORCHESTRATOR_PREAMBLE
+
+    attr_reader :name, :options
 
+    def initialize(name: "workflow", instructions: nil, preamble: true, **options)
       @name = name.to_s
-      @description = description.to_s
-      @instructions = instructions || DEFAULT_INSTRUCTIONS
-      @tools = Array(tools)
-      @skills = Array(skills)
-      @available_skills = Array(available_skills)
-      @model = model
-      @client = client
-      @store = store
-      @prompt_mode = prompt_mode
-      @thinking = thinking
-      @compaction = compaction
-      @on_event = on_event
-      @output_schema = output_schema
-      @max_iterations = max_iterations
-      @timeout = timeout
-      @cost_limit = cost_limit || max_spend
-      @max_depth = max_depth
-      @max_tool_executions = max_tool_executions
-      @max_tool_executions_by_name = max_tool_executions_by_name
-      @output_audit = output_audit
-      @output_audit_mode = output_audit_mode
-      @output_policy = output_policy
-      @output_policy_mode = output_policy_mode
-      @output_policy_model = output_policy_model
-      @output_policy_thinking = output_policy_thinking
       raise ArgumentError, "name is required" if @name.empty?
-      @agent = build_agent
-    end
-
-    def run(prompt = nil, task: nil, input: nil, async: false, subject: nil, metadata: {},
-      max_spend: nil, cost_limit: nil, **options)
-
-      task = task || prompt
-      raise ArgumentError, "task is required" if task.to_s.empty?
-
-      runtime_agent = if options.empty? && cost_limit.nil? && max_spend.nil?
-        @agent
-      else
-        build_agent(cost_limit: cost_limit || max_spend, **options)
-      end
 
-      runtime_agent.run(
-        task,
-        input: input,
-        async: async,
-        subject: subject,
-        metadata: metadata
-      )
+      @options = options.merge(
+        name: @name,
+        prompt_mode: options.fetch(:prompt_mode, :task),
+        instructions: compose_instructions(instructions, preamble: preamble)
+      ).freeze
+      @agent = Agent.new(**@options)
     end
 
-    def agent(**options)
-      options.empty? ? @agent : build_agent(**options)
+    def run(prompt = nil, task: nil, input: nil, async: false, subject: nil, metadata: {}, **overrides)
+      agent(**overrides).run(task || prompt, input: input, async: async, subject: subject, metadata: metadata)
     end
 
-    def max_spend
-      cost_limit
+    def agent(**overrides)
+      overrides.empty? ? @agent : Agent.new(**@options.merge(overrides.compact))
     end
 
     private
-      def build_agent(**overrides)
-        attrs = {
-          name: name,
-          description: description,
-          instructions: instructions,
-          tools: tools,
-          skills: skills,
-          available_skills: available_skills,
-          model: model,
-          client: client,
-          store: store,
-          prompt_mode: prompt_mode,
-          thinking: thinking,
-          compaction: compaction,
-          on_event: on_event,
-          output_schema: output_schema,
-          max_iterations: max_iterations,
-          timeout: timeout,
-          cost_limit: cost_limit,
-          max_depth: max_depth,
-          max_tool_executions: max_tool_executions,
-          max_tool_executions_by_name: max_tool_executions_by_name,
-          output_audit: output_audit,
-          output_audit_mode: output_audit_mode,
-          output_policy: output_policy,
-          output_policy_mode: output_policy_mode,
-          output_policy_model: output_policy_model,
-          output_policy_thinking: output_policy_thinking
-        }
-        attrs.merge!(overrides.compact)
-        Agent.new(**attrs)
+      def compose_instructions(instructions, preamble:)
+        parts = []
+        parts << ORCHESTRATOR_PREAMBLE if preamble
+        parts << instructions.to_s.strip unless instructions.to_s.strip.empty?
+        parts.join("\n\n")
       end
   end
 end

data/lib/turnkit.rb

@@ -15,6 +15,7 @@ require_relative "turnkit/cost"
 require_relative "turnkit/budget"
 require_relative "turnkit/event"
 require_relative "turnkit/model_request"
+require_relative "turnkit/schema_check"
 require_relative "turnkit/agent"
 require_relative "turnkit/workflow"
 require_relative "turnkit/client"
@@ -36,6 +37,7 @@ require_relative "turnkit/tool"
 require_relative "turnkit/tool_call"
 require_relative "turnkit/tool_execution"
 require_relative "turnkit/sub_agent_tool"
+require_relative "turnkit/load_skill_tool"
 require_relative "turnkit/message_projection"
 require_relative "turnkit/tool_runner"
 require_relative "turnkit/turn"
@@ -52,7 +54,7 @@ module TurnKit
     attr_accessor :default_model, :client, :store, :logger
     attr_accessor :max_iterations, :timeout, :max_depth, :max_tool_executions
     attr_accessor :max_tool_executions_by_name
-    attr_accessor :cost_limit, :prompt_cache
+    attr_accessor :max_spend, :prompt_cache
     attr_accessor :compaction
     attr_accessor :output_policy_model, :output_policy_thinking
     attr_accessor :cost_rates, :cost_calculator
@@ -72,6 +74,7 @@ module TurnKit
   self.max_depth = 3
   self.max_tool_executions = 100
   self.max_tool_executions_by_name = {}
+  self.max_spend = nil
   self.prompt_cache = :auto
   self.compaction = true
   self.cost_rates = {}
@@ -97,21 +100,13 @@ module TurnKit
     self.default_model = value
   end
 
-  def self.max_spend
-    cost_limit
-  end
-
-  def self.max_spend=(value)
-    self.cost_limit = value
-  end
-
   def self.reconcile_stale!(before: Clock.now - (timeout || 300))
     store.find_stale_turns(before: before).each do |turn|
       store.update_turn(turn.fetch("id"), "status" => "stale", "completed_at" => Clock.now)
     end
   end
 
-  def self.audit_output(output, constraints: [], context: {})
+  def self.check_output_policy(output, constraints: [], context: {})
     OutputAudit.check(output, constraints: constraints, context: context)
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: turnkit
 version: !ruby/object:Gem::Version
-  version: 0.2.10
+  version: 0.3.0
 platform: ruby
 authors:
 - Sam Couch
@@ -57,6 +57,7 @@ files:
 - lib/turnkit/generators/turnkit/install/templates/turn.rb
 - lib/turnkit/generators/turnkit/install_generator.rb
 - lib/turnkit/id.rb
+- lib/turnkit/load_skill_tool.rb
 - lib/turnkit/memory_store.rb
 - lib/turnkit/message.rb
 - lib/turnkit/message_projection.rb
@@ -70,6 +71,7 @@ files:
 - lib/turnkit/record.rb
 - lib/turnkit/result.rb
 - lib/turnkit/run.rb
+- lib/turnkit/schema_check.rb
 - lib/turnkit/skill.rb
 - lib/turnkit/store.rb
 - lib/turnkit/stores/active_record_store.rb