turnkit 0.2.8 → 0.2.10

data/lib/turnkit/turn.rb

@@ -6,7 +6,7 @@ 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, :output_schema
+    attr_reader :root_turn_id, :context_message_sequence, :model, :thinking, :compact, :output_schema, :prompt_mode
     attr_reader :started_at
 
     def initialize(agent:, conversation:, record:, store:, budget: nil, depth: 0, on_event: nil)
@@ -25,6 +25,7 @@ module TurnKit
       @thinking = thinking_from_options
       @compact = compact_from_options
       @output_schema = output_schema_from_options
+      @prompt_mode = prompt_mode_from_options
       @started_at = @record["started_at"]
       @budget = budget || agent.build_budget
       @depth = depth
@@ -44,13 +45,13 @@ module TurnKit
         TurnKit::Compaction.maybe_compact!(self)
 
         request = model_request
-        emit("model.requested", model: request.model, tool_names: request.tool_names)
+        emit_model_requested("model.requested", request)
         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)
         add_usage!(result.usage, cost: result_cost)
+        emit_model_completed("model.completed", result, result_cost, model: model)
+        budget.add_cost!(result_cost.total)
         persist_assistant_message(result)
 
         if result.tool_calls?
@@ -61,8 +62,7 @@ module TurnKit
             break
           end
         else
-          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)
+          complete_with_output(result.text, output_data: result.output_data)
           break
         end
       end
@@ -95,6 +95,10 @@ module TurnKit
       @record["output_data"]
     end
 
+    def output_audit
+      (@record["options"] || {})["output_audit"]
+    end
+
     def usage
       Usage.from_h(@record["usage"] || {})
     end
@@ -112,6 +116,7 @@ module TurnKit
       @thinking = thinking_from_options
       @compact = compact_from_options
       @output_schema = output_schema_from_options
+      @prompt_mode = prompt_mode_from_options
       self
     end
 
@@ -123,9 +128,31 @@ module TurnKit
       emit_event(Event.new(type: type, turn_id: id, conversation_id: conversation.id, payload: payload))
     end
 
+    def internal_model_call(model:, messages:, instructions:, tools: [], thinking: nil, output_schema: nil, metadata: {}, purpose:, client: nil)
+      request = ModelRequest.new(
+        model: model,
+        messages: messages,
+        tools: tools,
+        instructions: instructions,
+        thinking: thinking,
+        output_schema: output_schema,
+        metadata: { purpose: purpose.to_s, turn_id: id, conversation_id: conversation.id }.merge(metadata || {})
+      )
+      model_client = client || agent.effective_client
+      model_client.validate!(model: request.model)
+
+      emit_model_requested("#{purpose}.model.requested", request)
+      result = call_client(request, client: model_client)
+      result_cost = Cost.from_usage(result.usage, model: result.model || request.model)
+      add_usage!(result.usage, cost: result_cost)
+      emit_model_completed("#{purpose}.model.completed", result, result_cost, model: request.model)
+      budget.add_cost!(result_cost.total)
+      result
+    end
+
     private
       def model_request
-        prompt = SystemPrompt.new(agent: agent, turn: self, conversation: conversation, mode: agent.effective_prompt_mode(turn: self))
+        prompt = SystemPrompt.new(agent: agent, turn: self, conversation: conversation, mode: prompt_mode || agent.effective_prompt_mode(turn: self))
         instructions = case agent.system_prompt
         when nil
           prompt.to_s
@@ -146,7 +173,7 @@ module TurnKit
         )
       end
 
-      def call_client(request)
+      def call_client(request, client: agent.effective_client)
         kwargs = {
           model: request.model,
           messages: request.messages,
@@ -157,9 +184,9 @@ module TurnKit
           metadata: request.metadata,
           on_event: ->(event) { emit_event(event) }
         }
-        accepted = chat_keyword_names(agent.effective_client)
+        accepted = chat_keyword_names(client)
         kwargs = kwargs.slice(*accepted) unless accepted.include?(:keyrest)
-        agent.effective_client.chat(**kwargs)
+        client.chat(**kwargs)
       end
 
       def chat_keyword_names(client)
@@ -174,6 +201,26 @@ module TurnKit
         MessageProjection.for(TurnKit::Compaction.project(conversation.messages_for_turn(self)))
       end
 
+      def emit_model_requested(type, request)
+        emit(
+          type,
+          model: request.model,
+          tool_names: request.tool_names,
+          message_count: request.messages.length,
+          prompt: request.report
+        )
+      end
+
+      def emit_model_completed(type, result, cost, model: self.model)
+        emit(
+          type,
+          model: result.model || model,
+          tool_call_count: result.tool_calls.length,
+          usage: result.usage.to_h,
+          cost: cost.to_h
+        )
+      end
+
       def thinking_from_options
         options = (@record["options"] || {}).transform_keys(&:to_s)
         return Agent.normalize_thinking(options["thinking"]) if options.key?("thinking")
@@ -191,6 +238,11 @@ module TurnKit
         options["output_schema"] if options.key?("output_schema")
       end
 
+      def prompt_mode_from_options
+        options = (@record["options"] || {}).transform_keys(&:to_s)
+        options["prompt_mode"]&.to_sym if options.key?("prompt_mode")
+      end
+
       def persist_assistant_message(result)
         if result.tool_calls?
           message = conversation.append_message(
@@ -212,8 +264,40 @@ module TurnKit
         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)
-        update!(status: "completed", output_text: message, completed_at: Clock.now)
-        emit("turn.completed", status: status, output_text: message)
+        complete_with_output(message)
+      end
+
+      def complete_with_output(text, output_data: nil)
+        audit = audit_output(text, output_data: output_data)
+        attrs = { output_text: text, output_data: output_data, completed_at: Clock.now }
+        if audit && !audit.clean? && agent.output_audit_mode == :fail
+          attrs[:status] = "failed"
+          attrs[:error] = { "class" => "TurnKit::OutputAudit", "message" => audit.messages.join("; "), "output_audit" => audit.to_h }
+        else
+          attrs[:status] = "completed"
+        end
+        update!(attrs)
+        persist_output_audit(audit) if audit
+
+        if failed?
+          emit("turn.failed", error: @record["error"])
+        else
+          emit("turn.completed", status: status, output_text: text)
+        end
+      end
+
+      def audit_output(text, output_data: nil)
+        constraints = agent.effective_output_audit
+        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 })
+      end
+
+      def persist_output_audit(audit)
+        options = (@record["options"] || {}).merge("output_audit" => audit.to_h)
+        update!(options: options)
+        emit("output_audit.completed", clean: audit.clean?, violation_count: audit.violations.length)
       end
 
       def add_usage!(usage, cost: nil)

data/lib/turnkit/version.rb

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

data/lib/turnkit/{fleet.rb → workflow.rb}

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
+require_relative "agent"
+
 module TurnKit
-  class Fleet
+  class Workflow
     attr_reader :name, :description, :instructions, :tools, :skills, :available_skills
     attr_reader :model, :client, :store, :prompt_mode, :thinking, :compaction, :output_schema
-    attr_reader :max_iterations, :timeout, :cost_limit, :max_depth, :max_tool_executions
+    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
       You are an autonomous task orchestrator. Navigate from the application
@@ -15,17 +19,22 @@ module TurnKit
       patterns. Iterate when work needs missing context, critique, revision, or
       verification.
 
+      When multiple independent items need the same kind of fetch or read, and
+      an available batch tool can handle them in one call, prefer the batch tool
+      over repeated one-item tool calls.
+
       Stop when the task is complete, when the available context and tools are
       sufficient for the best possible answer, or when further iteration would
       not materially improve the result. Respect runtime, cost, and iteration
       limits.
     TEXT
 
-    def initialize(name: "orchestrator", description: "", instructions: nil,
+    def initialize(name: "workflow", description: "", instructions: nil,
       tools: [], skills: [], available_skills: [], model: nil, client: nil,
-      store: nil, prompt_mode: :task, thinking: nil, compaction: 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)
+      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)
 
       @name = name.to_s
       @description = description.to_s
@@ -39,14 +48,22 @@ module TurnKit
       @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?
-      build_agent
+      @agent = build_agent
     end
 
     def run(prompt = nil, task: nil, input: nil, async: false, subject: nil, metadata: {},
@@ -55,7 +72,13 @@ module TurnKit
       task = task || prompt
       raise ArgumentError, "task is required" if task.to_s.empty?
 
-      build_agent(cost_limit: cost_limit || max_spend, **options).run(
+      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,
@@ -64,11 +87,8 @@ module TurnKit
       )
     end
 
-    alias_method :auto_run, :run
-    alias_method :autorun, :run
-
     def agent(**options)
-      build_agent(**options)
+      options.empty? ? @agent : build_agent(**options)
     end
 
     def max_spend
@@ -90,16 +110,23 @@ module TurnKit
           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: 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)
       end
   end
-
 end

data/lib/turnkit.rb

@@ -5,6 +5,7 @@ require "digest"
 require "securerandom"
 require "time"
 require "date"
+require "pathname"
 
 require_relative "turnkit/version"
 require_relative "turnkit/error"
@@ -15,13 +16,15 @@ require_relative "turnkit/budget"
 require_relative "turnkit/event"
 require_relative "turnkit/model_request"
 require_relative "turnkit/agent"
-require_relative "turnkit/fleet"
+require_relative "turnkit/workflow"
 require_relative "turnkit/client"
 require_relative "turnkit/conversation"
 require_relative "turnkit/message"
 require_relative "turnkit/record"
 require_relative "turnkit/result"
 require_relative "turnkit/skill"
+require_relative "turnkit/output_audit"
+require_relative "turnkit/output_policy"
 require_relative "turnkit/prompt_data"
 require_relative "turnkit/prompt_context"
 require_relative "turnkit/prompt_contribution"
@@ -38,6 +41,7 @@ require_relative "turnkit/tool_runner"
 require_relative "turnkit/turn"
 require_relative "turnkit/usage"
 require_relative "turnkit/run"
+require_relative "turnkit/adapters/codex"
 require_relative "turnkit/adapters/ruby_llm"
 require_relative "turnkit/stores/active_record_store"
 
@@ -47,8 +51,10 @@ module TurnKit
   class << self
     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 :compaction
+    attr_accessor :output_policy_model, :output_policy_thinking
     attr_accessor :cost_rates, :cost_calculator
     attr_accessor :prompt_sections, :prompt_behavior, :available_skills
     attr_accessor :prompt_data_max_chars, :context_contributors
@@ -65,6 +71,7 @@ module TurnKit
   self.timeout = 300
   self.max_depth = 3
   self.max_tool_executions = 100
+  self.max_tool_executions_by_name = {}
   self.prompt_cache = :auto
   self.compaction = true
   self.cost_rates = {}
@@ -75,6 +82,8 @@ module TurnKit
   self.system_prompt_contributors = []
   self.model_prompt_contributors = {}
   self.on_event = nil
+  self.output_policy_model = nil
+  self.output_policy_thinking = { effort: :low }
 
   def self.configure
     yield self
@@ -96,13 +105,13 @@ module TurnKit
     self.cost_limit = value
   end
 
-  def self.fleet(name = "orchestrator", **options)
-    Fleet.new(name: name, **options)
-  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: {})
+    OutputAudit.check(output, constraints: constraints, context: context)
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: turnkit
 version: !ruby/object:Gem::Version
-  version: 0.2.8
+  version: 0.2.10
 platform: ruby
 authors:
 - Sam Couch
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-08 00:00:00.000000000 Z
+date: 2026-06-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -24,8 +24,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.14'
-description: TurnKit is a Ruby/Rails agent runtime for durable AI conversations, tool
-  calling, skills, sub-agents, context compaction, and persistence.
+description: TurnKit is a Ruby/Rails agent runtime for durable AI conversations, application
+  runs, reusable workflows, tool calling, skills, sub-agents, context compaction,
+  and persistence.
 email:
 - sam@samcouch.com
 executables: []
@@ -37,6 +38,7 @@ files:
 - README.md
 - UPGRADE.md
 - lib/turnkit.rb
+- lib/turnkit/adapters/codex.rb
 - lib/turnkit/adapters/ruby_llm.rb
 - lib/turnkit/agent.rb
 - lib/turnkit/budget.rb
@@ -47,7 +49,6 @@ files:
 - lib/turnkit/cost.rb
 - lib/turnkit/error.rb
 - lib/turnkit/event.rb
-- lib/turnkit/fleet.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
@@ -60,6 +61,8 @@ files:
 - lib/turnkit/message.rb
 - lib/turnkit/message_projection.rb
 - lib/turnkit/model_request.rb
+- lib/turnkit/output_audit.rb
+- lib/turnkit/output_policy.rb
 - lib/turnkit/prompt_context.rb
 - lib/turnkit/prompt_contribution.rb
 - lib/turnkit/prompt_data.rb
@@ -79,6 +82,7 @@ files:
 - lib/turnkit/turn.rb
 - lib/turnkit/usage.rb
 - lib/turnkit/version.rb
+- lib/turnkit/workflow.rb
 homepage: https://github.com/samuelcouch/turnkit
 licenses:
 - MIT
@@ -106,5 +110,5 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Ruby/Rails agent runtime for durable AI conversations.
+summary: Ruby/Rails agent runtime for durable AI conversations, runs, and workflows.
 test_files: []