turnkit 0.1.0

data/lib/turnkit/stores/active_record_store.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+module TurnKit
+  class ActiveRecordStore < Store
+    def create_conversation(attributes)
+      record = conversation_class.create!(record_attributes(attributes, id_key: "uid"))
+      conversation_hash(record)
+    end
+
+    def load_conversation(id)
+      conversation_hash(conversation_class.find_by!(uid: id))
+    end
+
+    def next_message_sequence(conversation_id)
+      conversation_class.transaction do
+        conversation = conversation_class.lock.find_by!(uid: conversation_id)
+        message_class.where(conversation_uid: conversation.uid).maximum(:sequence).to_i + 1
+      end
+    end
+
+    def latest_message_sequence(conversation_id)
+      message_class.where(conversation_uid: conversation_id).maximum(:sequence).to_i
+    end
+
+    def append_message(attributes)
+      attrs = attributes.transform_keys(&:to_s)
+      sequence = nil
+      message = nil
+      record = conversation_class.transaction do
+        conversation_class.lock.find_by!(uid: attrs.fetch("conversation_id"))
+        sequence = message_class.where(conversation_uid: attrs.fetch("conversation_id")).maximum(:sequence).to_i + 1
+        message = Record.message(attrs.merge("sequence" => sequence))
+        message_class.create!(
+          uid: message.fetch("id"),
+          conversation_uid: message.fetch("conversation_id"),
+          turn_uid: message["turn_id"],
+          role: message.fetch("role"),
+          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")
+        )
+      end
+      message_hash(record)
+    end
+
+    def list_messages(conversation_id, through_sequence: nil, turn_id: nil)
+      scope = message_class.where(conversation_uid: conversation_id)
+      if through_sequence
+        scope = scope.where("sequence <= ? OR turn_uid = ?", through_sequence, turn_id)
+      end
+      scope.order(:sequence, :created_at, :uid).map { |record| message_hash(record) }
+    end
+
+    def create_turn(attributes)
+      attrs = Record.turn(attributes)
+      record = turn_class.create!(
+        uid: attrs.fetch("id"),
+        conversation_uid: attrs.fetch("conversation_id"),
+        agent_name: attrs["agent_name"],
+        parent_turn_uid: attrs["parent_turn_id"],
+        parent_tool_execution_uid: attrs["parent_tool_execution_id"],
+        root_turn_uid: attrs.fetch("root_turn_id"),
+        context_message_sequence: attrs["context_message_sequence"].to_i,
+        status: attrs.fetch("status"),
+        model: attrs["model"],
+        options: attrs["options"] || {},
+        usage: attrs["usage"] || {},
+        cost: attrs["cost"],
+        error: attrs["error"],
+        output_text: attrs["output_text"],
+        started_at: attrs["started_at"],
+        heartbeat_at: attrs["heartbeat_at"],
+        completed_at: attrs["completed_at"]
+      )
+      turn_hash(record)
+    end
+
+    def load_turn(id)
+      turn_hash(turn_class.find_by!(uid: id))
+    end
+
+    def update_turn(id, attributes)
+      record = turn_class.find_by!(uid: id)
+      record.update!(Record.turn_update(attributes))
+      turn_hash(record)
+    end
+
+    def list_turns(root_turn_id: nil, conversation_id: nil)
+      scope = turn_class.all
+      scope = scope.where(root_turn_uid: root_turn_id) if root_turn_id
+      scope = scope.where(conversation_uid: conversation_id) if conversation_id
+      scope.order(:created_at, :uid).map { |record| turn_hash(record) }
+    end
+
+    def create_tool_execution(attributes)
+      attrs = Record.tool_execution(attributes)
+      record = tool_execution_class.create!(
+        uid: attrs.fetch("id"),
+        turn_uid: attrs.fetch("turn_id"),
+        tool_call_id: attrs.fetch("tool_call_id"),
+        tool_name: attrs.fetch("tool_name"),
+        status: attrs.fetch("status"),
+        arguments: attrs["arguments"] || {},
+        result: attrs["result"],
+        error: attrs["error"],
+        started_at: attrs["started_at"],
+        completed_at: attrs["completed_at"]
+      )
+      tool_execution_hash(record)
+    end
+
+    def load_tool_execution(id)
+      tool_execution_hash(tool_execution_class.find_by!(uid: id))
+    end
+
+    def update_tool_execution(id, attributes)
+      record = tool_execution_class.find_by!(uid: id)
+      record.update!(Record.tool_execution_update(attributes))
+      tool_execution_hash(record)
+    end
+
+    def list_tool_executions(turn_id:)
+      tool_execution_class.where(turn_uid: turn_id).order(:created_at, :uid).map { |record| tool_execution_hash(record) }
+    end
+
+    def find_stale_turns(before:)
+      turn_class.where(status: %w[pending running]).where("COALESCE(heartbeat_at, started_at, created_at) < ?", before).map { |record| turn_hash(record) }
+    end
+
+    private
+      def conversation_class = constantize(TurnKit.conversation_record_class || "Turnkit::Conversation")
+      def turn_class = constantize(TurnKit.turn_record_class || "Turnkit::Turn")
+      def message_class = constantize(TurnKit.message_record_class || "Turnkit::Message")
+      def tool_execution_class = constantize(TurnKit.tool_execution_record_class || "Turnkit::ToolExecution")
+
+      def constantize(name)
+        name.to_s.split("::").inject(Object) { |mod, part| mod.const_get(part) }
+      end
+
+      def record_attributes(attributes, id_key:)
+        attrs = Record.conversation(attributes)
+        subject_type, subject_id = Record.subject_pair(attrs["subject"])
+        {
+          id_key => attrs.fetch("id"),
+          agent_name: attrs["agent_name"],
+          model: attrs["model"],
+          subject_type: subject_type,
+          subject_id: subject_id,
+          metadata: attrs["metadata"] || {}
+        }
+      end
+
+      def conversation_hash(record)
+        { "id" => record.uid, "agent_name" => record.agent_name, "model" => record.model, "metadata" => record.metadata || {}, "created_at" => record.created_at, "updated_at" => record.updated_at }
+      end
+
+      def turn_hash(record)
+        {
+          "id" => record.uid, "conversation_id" => record.conversation_uid, "agent_name" => record.agent_name,
+          "parent_turn_id" => record.parent_turn_uid, "parent_tool_execution_id" => record.parent_tool_execution_uid,
+          "root_turn_id" => record.root_turn_uid, "context_message_sequence" => record.context_message_sequence,
+          "status" => record.status, "model" => record.model, "options" => record.options || {}, "usage" => record.usage || {},
+          "cost" => record.cost, "error" => record.error, "output_text" => record.output_text,
+          "started_at" => record.started_at, "heartbeat_at" => record.heartbeat_at, "completed_at" => record.completed_at,
+          "created_at" => record.created_at, "updated_at" => record.updated_at
+        }
+      end
+
+      def message_hash(record)
+        {
+          "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,
+          "provider_message_id" => record.provider_message_id, "metadata" => record.metadata || {}, "created_at" => record.created_at
+        }
+      end
+
+      def tool_execution_hash(record)
+        {
+          "id" => record.uid, "turn_id" => record.turn_uid, "tool_call_id" => record.tool_call_id,
+          "tool_name" => record.tool_name, "status" => record.status, "arguments" => record.arguments || {},
+          "result" => record.result, "error" => record.error, "started_at" => record.started_at, "completed_at" => record.completed_at
+        }
+      end
+  end
+end

data/lib/turnkit/sub_agent_tool.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module TurnKit
+  class SubAgentTool < Tool
+    parameter :task, :string, required: true, description: "The task for the sub-agent to complete."
+    parameter :context, :string, required: false, description: "Relevant context for the sub-agent."
+
+    def self.for(agent)
+      Class.new(self) do
+        @agent = agent
+        tool_name agent.name
+        description agent.description.empty? ? "Delegate work to #{agent.name}." : agent.description
+
+        class << self
+          attr_reader :agent
+        end
+      end
+    end
+
+    def call(task:, context: nil, turnkit_context:)
+      sub_agent = self.class.agent
+      parent_turn = turnkit_context.turn
+      conversation = parent_turn.conversation
+      prompt = [ task, context ].compact.join("\n\n")
+      trigger = conversation.append_message(role: "user", kind: "text", text: prompt, turn_id: parent_turn.id)
+      child = conversation.run!(
+        trigger_message_id: trigger.id,
+        budget: parent_turn.budget,
+        parent_turn: parent_turn,
+        parent_tool_execution: turnkit_context.execution,
+        depth: parent_turn.depth + 1,
+        model: sub_agent.effective_model,
+        agent: sub_agent
+      )
+      { "turn_id" => child.id, "status" => child.status, "result" => child.output_text }
+    end
+  end
+end

data/lib/turnkit/tool.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module TurnKit
+  class Tool
+    TYPES = %i[string integer number boolean array object enum].freeze
+
+    class << self
+      def tool_name(value = nil)
+        @tool_name = value.to_s if value
+        @tool_name ||= name.to_s.split("::").last.gsub(/([a-z\d])([A-Z])/, "\\1_\\2").downcase
+      end
+
+      def description(value = nil)
+        @description = value.to_s if value
+        @description.to_s
+      end
+
+      def parameter(name, type = :string, required: false, description: "", default: nil, enum: nil)
+        raise ArgumentError, "unknown parameter type: #{type}" unless TYPES.include?(type)
+
+        parameters << {
+          name: name.to_s,
+          type: type,
+          required: required ? true : false,
+          description: description.to_s,
+          default: default,
+          enum: enum
+        }.compact
+      end
+
+      def parameters
+        @parameters ||= superclass.respond_to?(:parameters) ? superclass.parameters.dup : []
+      end
+
+      def ends_turn?
+        false
+      end
+
+      def completion_message(_result)
+        nil
+      end
+
+      def call(arguments = {}, context:)
+        keyword_arguments = symbolize(arguments)
+        instance = new
+        if accepts_turnkit_context?(instance)
+          instance.call(**keyword_arguments, turnkit_context: context)
+        else
+          instance.call(**keyword_arguments, context: context)
+        end
+      end
+
+      private
+        def accepts_turnkit_context?(instance)
+          instance.method(:call).parameters.any? { |kind, name| %i[key keyreq].include?(kind) && name == :turnkit_context }
+        end
+
+        def symbolize(hash)
+          hash.transform_keys(&:to_sym)
+        end
+    end
+  end
+end

data/lib/turnkit/tool_call.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module TurnKit
+  class ToolCall
+    attr_reader :id, :name, :arguments
+
+    def initialize(id:, name:, arguments: {})
+      @id = id.to_s
+      @name = name.to_s
+      @arguments = normalize_arguments(arguments)
+    end
+
+    private
+      def normalize_arguments(value)
+        case value
+        when Hash
+          value.transform_keys(&:to_s)
+        when String
+          parsed = JSON.parse(value)
+          parsed.is_a?(Hash) ? parsed.transform_keys(&:to_s) : {}
+        else
+          {}
+        end
+      rescue JSON::ParserError
+        {}
+      end
+  end
+end

data/lib/turnkit/tool_execution.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module TurnKit
+  class ToolExecution
+    STATUSES = Record::TOOL_EXECUTION_STATUSES
+
+    attr_reader :id, :turn_id, :tool_call_id, :tool_name, :status
+    attr_reader :arguments, :result, :error, :started_at, :completed_at
+
+    def initialize(attributes = {})
+      attrs = attributes.transform_keys(&:to_s)
+      @id = attrs.fetch("id")
+      @turn_id = attrs.fetch("turn_id")
+      @tool_call_id = attrs.fetch("tool_call_id")
+      @tool_name = attrs.fetch("tool_name")
+      @status = attrs.fetch("status")
+      @arguments = attrs["arguments"] || {}
+      @result = attrs["result"]
+      @error = attrs["error"]
+      @started_at = attrs["started_at"]
+      @completed_at = attrs["completed_at"]
+    end
+
+    STATUSES.each do |state|
+      define_method("#{state}?") { status == state }
+    end
+  end
+end

data/lib/turnkit/tool_runner.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module TurnKit
+  class ToolRunner
+    def initialize(turn)
+      @turn = turn
+    end
+
+    def dispatch(tool_calls)
+      tool_calls.each do |tool_call|
+        execution = run(tool_call)
+        return execution if execution.completed? && tool_class(tool_call.name)&.ends_turn?
+      end
+      nil
+    end
+
+    def completion_message(execution)
+      tool = tool_class(execution.tool_name)
+      tool.completion_message(execution.result) || execution.result&.fetch("result", nil) || "Completed via #{execution.tool_name}."
+    end
+
+    private
+      attr_reader :turn
+
+      def run(tool_call)
+        turn.budget.count_tool_execution!
+        tool = tool_class(tool_call.name)
+        execution = ToolExecution.new(create_execution(tool_call))
+
+        unless tool
+          return finish_error(execution, tool_call, "unknown tool: #{tool_call.name}")
+        end
+
+        context = ToolContext.new(turn: turn, execution: execution)
+        payload = begin
+          normalize_payload(tool.call(tool_call.arguments, context: context))
+        rescue StandardError => error
+          return finish_error(execution, tool_call, error.message, details: { "class" => error.class.name })
+        end
+        finish_success(execution, tool_call, payload)
+      end
+
+      def create_execution(tool_call)
+        turn.store.create_tool_execution(
+          "turn_id" => turn.id,
+          "tool_call_id" => tool_call.id,
+          "tool_name" => tool_call.name,
+          "status" => "running",
+          "arguments" => tool_call.arguments,
+          "started_at" => Clock.now
+        )
+      end
+
+      def finish_success(execution, tool_call, payload)
+        attrs = turn.store.update_tool_execution(execution.id, "status" => "completed", "result" => payload, "completed_at" => Clock.now)
+        append_result(execution, tool_call, payload)
+        ToolExecution.new(attrs)
+      end
+
+      def finish_error(execution, tool_call, message, details: nil)
+        error = { "message" => message.to_s, "details" => details }.compact
+        attrs = turn.store.update_tool_execution(execution.id, "status" => "failed", "error" => error, "completed_at" => Clock.now)
+        append_result(execution, tool_call, error)
+        ToolExecution.new(attrs)
+      end
+
+      def append_result(execution, tool_call, payload)
+        turn.conversation.append_message(
+          role: "tool",
+          kind: "tool_result",
+          text: payload.to_json,
+          turn_id: turn.id,
+          tool_execution_id: execution.id,
+          metadata: { "tool_call_id" => tool_call.id, "tool_name" => tool_call.name }
+        )
+      end
+
+      def tool_class(name)
+        turn.agent.effective_tools.find { |tool| tool.tool_name == name.to_s }
+      end
+
+      def normalize_payload(value)
+        case value
+        when Hash then value.transform_keys(&:to_s)
+        when Array then { "items" => value }
+        else { "result" => value.to_s }
+        end
+      end
+  end
+end

data/lib/turnkit/turn.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module TurnKit
+  class Turn
+    STATUSES = Record::TURN_STATUSES
+
+    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
+
+    def initialize(agent:, conversation:, record:, store:, budget: nil, depth: 0)
+      @agent = agent
+      @conversation = conversation
+      @store = store
+      @record = record.transform_keys(&:to_s)
+      @id = @record.fetch("id")
+      @conversation_id = @record.fetch("conversation_id")
+      @agent_name = @record["agent_name"]
+      @parent_turn_id = @record["parent_turn_id"]
+      @parent_tool_execution_id = @record["parent_tool_execution_id"]
+      @root_turn_id = @record["root_turn_id"] || id
+      @context_message_sequence = @record["context_message_sequence"].to_i
+      @model = @record["model"] || agent.effective_model
+      @budget = budget || agent.build_budget
+      @depth = depth
+    end
+
+    def run!
+      return self unless status == "pending"
+
+      update!(status: "running", started_at: Clock.now, heartbeat_at: Clock.now)
+      loop do
+        budget.check!(depth: depth)
+        budget.count_iteration!
+
+        result = agent.effective_client.chat(
+          model: model,
+          messages: llm_messages,
+          tools: agent.effective_tools,
+          instructions: agent.instructions_with_skills,
+          metadata: { turn_id: id, conversation_id: conversation.id }
+        )
+
+        budget.add_usage!(result.usage)
+        add_usage!(result.usage)
+        persist_assistant_message(result)
+
+        if result.tool_calls?
+          runner = ToolRunner.new(self)
+          terminal = runner.dispatch(result.tool_calls)
+          if terminal
+            complete_from_terminal_tool(runner, terminal)
+            break
+          end
+        else
+          update!(status: "completed", output_text: result.text, completed_at: Clock.now)
+          break
+        end
+      end
+      reload
+      self
+    rescue StandardError => error
+      update!(status: "failed", error: { "class" => error.class.name, "message" => error.message }, completed_at: Clock.now)
+      reload
+      self
+    end
+
+    def status
+      @record.fetch("status")
+    end
+
+    STATUSES.each do |state|
+      define_method("#{state}?") { status == state }
+    end
+
+    def output_text
+      @record["output_text"].to_s
+    end
+
+    def tool_executions
+      store.list_tool_executions(turn_id: id).map { |attrs| ToolExecution.new(attrs) }
+    end
+
+    def reload
+      @record = store.load_turn(id)
+      self
+    end
+
+    def stale!
+      update!(status: "stale", completed_at: Clock.now)
+    end
+
+    private
+      def llm_messages
+        MessageProjection.for(conversation.messages_for_turn(self))
+      end
+
+      def persist_assistant_message(result)
+        if result.tool_calls?
+          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 } } }
+          )
+        else
+          conversation.append_message(role: "assistant", kind: "text", text: result.text, turn_id: id)
+        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)
+        update!(status: "completed", output_text: message, completed_at: Clock.now)
+      end
+
+      def add_usage!(usage)
+        current = @record["usage"] || {}
+        totals = {
+          "input_tokens" => current["input_tokens"].to_i + usage.input_tokens,
+          "output_tokens" => current["output_tokens"].to_i + usage.output_tokens,
+          "cached_tokens" => current["cached_tokens"].to_i + usage.cached_tokens,
+          "total_tokens" => current["total_tokens"].to_i + usage.total_tokens
+        }
+        update!(usage: totals, heartbeat_at: Clock.now)
+      end
+
+      def update!(attributes)
+        @record = store.update_turn(id, attributes)
+      end
+  end
+
+  class ToolContext
+    attr_reader :turn, :execution
+
+    def initialize(turn:, execution:)
+      @turn = turn
+      @execution = execution
+    end
+  end
+end

data/lib/turnkit/usage.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module TurnKit
+  class Usage
+    attr_reader :input_tokens, :output_tokens, :cached_tokens, :cost
+
+    def initialize(input_tokens: 0, output_tokens: 0, cached_tokens: 0, cost: nil)
+      @input_tokens = input_tokens.to_i
+      @output_tokens = output_tokens.to_i
+      @cached_tokens = cached_tokens.to_i
+      @cost = cost
+    end
+
+    def total_tokens
+      input_tokens + output_tokens + cached_tokens
+    end
+
+    def to_h
+      {
+        "input_tokens" => input_tokens,
+        "output_tokens" => output_tokens,
+        "cached_tokens" => cached_tokens,
+        "total_tokens" => total_tokens,
+        "cost" => cost
+      }.compact
+    end
+  end
+end

data/lib/turnkit/version.rb

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

data/lib/turnkit.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "time"
+
+require_relative "turnkit/version"
+require_relative "turnkit/error"
+require_relative "turnkit/id"
+require_relative "turnkit/clock"
+require_relative "turnkit/budget"
+require_relative "turnkit/agent"
+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/store"
+require_relative "turnkit/memory_store"
+require_relative "turnkit/tool"
+require_relative "turnkit/tool_call"
+require_relative "turnkit/tool_execution"
+require_relative "turnkit/sub_agent_tool"
+require_relative "turnkit/message_projection"
+require_relative "turnkit/tool_runner"
+require_relative "turnkit/turn"
+require_relative "turnkit/usage"
+require_relative "turnkit/adapters/ruby_llm"
+require_relative "turnkit/stores/active_record_store"
+
+require_relative "turnkit/rails/railtie" if defined?(Rails)
+
+module TurnKit
+  class << self
+    attr_accessor :default_model, :client, :store, :logger
+    attr_accessor :max_iterations, :timeout, :max_depth, :max_tool_executions
+    attr_accessor :cost_limit
+    attr_accessor :conversation_record_class, :turn_record_class
+    attr_accessor :message_record_class, :tool_execution_record_class
+  end
+
+  self.default_model = "claude-sonnet-4-5"
+  self.store = MemoryStore.new
+  self.client = Adapters::RubyLLM.new
+  self.max_iterations = 25
+  self.timeout = 300
+  self.max_depth = 3
+  self.max_tool_executions = 100
+
+  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
+end