turnkit 0.5.0 → 0.7.0

data/lib/turnkit/store.rb

@@ -2,6 +2,9 @@
 
 module TurnKit
   class Store
+    def atomic(_conversation_id, &) = raise(NotImplementedError)
+    def atomic_graph(&) = atomic(nil, &)
+
     def create_conversation(_attributes) = raise(NotImplementedError)
     def load_conversation(_id) = raise(NotImplementedError)
 
@@ -17,6 +20,28 @@ module TurnKit
     # is not in `from`), so concurrent workers cannot both claim a turn.
     def claim_turn(_id, from: "pending", to: "running", **_attributes) = raise(NotImplementedError)
     def list_turns(root_turn_id: nil, conversation_id: nil, agent_name: nil) = raise(NotImplementedError)
+    # Public inventory. Maintenance uses the explicitly bounded active scope.
+    def list_submitted_turns(limit: nil) = raise(NotImplementedError)
+    def list_actionable_turns(limit:) = raise(NotImplementedError)
+    def list_stale_inline_turns(before:, limit:) = raise(NotImplementedError)
+
+    # Stores may optimize these continuation queries without loading history.
+    def busy_conversation?(id, include_pending: true)
+      list_turns(conversation_id: id).any? { |row| %w[running waiting paused].include?(row["status"]) || (include_pending && row["submitted_at"] && row["status"] == "pending") }
+    end
+
+    def next_delivery_trigger(id)
+      consumed = list_turns(conversation_id: id).reject { |row| row["status"] == "pending" && !row["submitted_at"] }.map { |row| row["context_message_sequence"] }.max.to_i
+      list_messages(id).select { |row| row.dig("metadata", "delivery_id") && row["sequence"] > consumed }.last
+    end
+
+    def create_delivery(_attributes) = raise(NotImplementedError)
+    def load_delivery(_id) = raise(NotImplementedError)
+    def update_delivery(_id, _attributes) = raise(NotImplementedError)
+    def list_deliveries(source_conversation_id: nil, destination_conversation_id: nil, pending: false, limit: nil) = raise(NotImplementedError)
+
+    def create_wait(turn_id:, target_turn_id:) = raise(NotImplementedError)
+    def list_waits(turn_id: nil, target_turn_id: nil) = raise(NotImplementedError)
 
     def create_tool_execution(_attributes) = raise(NotImplementedError)
     def load_tool_execution(_id) = raise(NotImplementedError)
@@ -26,14 +51,18 @@ module TurnKit
     def claim_tool_execution(_id, from: "running", to: "completed", **_attributes) = raise(NotImplementedError)
     def list_tool_executions(turn_id:) = raise(NotImplementedError)
 
-    # reconcile_stale_turns is the other concurrency-safety point: it must
-    # atomically transition each pending/running turn whose stale anchor
-    # (heartbeat_at, else started_at, else created_at) is older than `before`
-    # to `stale`, rechecking both predicates at write time so a concurrently
-    # claimed, heartbeated, or completed turn is never overwritten. Returns
-    # the reconciled turn records. Descendant turns of a dead process stop
-    # heartbeating too and are reconciled by the same predicate, so no
-    # explicit subtree cascade is needed.
-    def reconcile_stale_turns(before:) = []
+    # Inline abandoned work is fenced and left stale for application-directed
+    # continuation. Submitted work is resumed by Background.reconcile instead.
+    def reconcile_stale_turns(before:)
+      list_stale_inline_turns(before: before, limit: TurnKit.maintenance_batch_size).filter_map do |record|
+        atomic(Background.root_conversation(self, record)) do
+          current = load_turn(record.fetch("id"))
+          anchor = current["heartbeat_at"] || current["started_at"] || current["created_at"]
+          next if current["submitted_at"] || !%w[pending running].include?(current["status"]) || anchor >= before
+
+          update_turn(current.fetch("id"), status: "stale", claim_token: nil, completed_at: Clock.now)
+        end
+      end
+    end
   end
 end

data/lib/turnkit/sub_agent_tool.rb

@@ -17,17 +17,20 @@ module TurnKit
       end
     end
 
-    def call(task:, context:)
-      sub_agent = self.class.agent
+    def self.build_child(task:, context:)
+      sub_agent = agent
       parent_turn = context.turn
       lineage = {
         "parent_conversation_id" => parent_turn.conversation.id,
         "parent_turn_id" => parent_turn.id,
-        "parent_tool_execution_id" => context.execution.id
+        "parent_tool_execution_id" => context.execution.id,
+        "principal" => context.principal
       }
-      conversation = sub_agent.conversation(metadata: lineage)
+      store = parent_turn.store
+      record = store.create_conversation("agent_name" => sub_agent.name, "model" => sub_agent.effective_model, "metadata" => lineage)
+      conversation = Conversation.new(agent: sub_agent, record: record, store: store, model: sub_agent.effective_model, metadata: lineage)
       trigger = conversation.say(task, metadata: lineage)
-      child = conversation.run!(
+      conversation.build_turn(
         trigger_message_id: trigger.id,
         budget: parent_turn.budget,
         parent_turn: parent_turn,
@@ -35,10 +38,23 @@ module TurnKit
         depth: parent_turn.depth + 1,
         model: sub_agent.effective_model,
         agent: sub_agent,
+        principal: context.principal,
         on_event: parent_turn.agent.effective_on_event
       )
-      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
+
+    def self.result(record)
+      { "conversation_id" => record.fetch("conversation_id"), "turn_id" => record.fetch("id"),
+        "status" => record.fetch("status"), "result" => record["output_text"].to_s,
+        "output_data" => record["output_data"], "error" => record["error"] }.compact
+    end
+
+    def call(task:, context:)
+      Authorization.authorize!(:launch_agent, principal: context.principal, turn: context.turn,
+        agent: self.class.agent, arguments: { "task" => task })
+      child = self.class.build_child(task: task, context: context)
+      child.run!
+      SubAgentTool.result(child.store.load_turn(child.id))
     end
   end
 end

data/lib/turnkit/system_prompt.rb

@@ -7,7 +7,7 @@ module TurnKit
     PROMPT_MODES = %i[full minimal task none].freeze
     MODE_SECTIONS = {
       full: DEFAULT_SECTIONS,
-      minimal: %i[agent sub_agent instructions behavior tools environment],
+      minimal: %i[agent sub_agent instructions behavior loaded_skills available_skills tools environment],
       task: DEFAULT_SECTIONS,
       none: []
     }.freeze
@@ -181,7 +181,7 @@ module TurnKit
     end
 
     def tools_section
-      tools = agent.effective_tools
+      tools = agent.effective_tools(turn: turn)
 
       if tools.empty?
         tagged("tools_available", "(none)\n\nNo tools are available for this turn.")
@@ -197,9 +197,7 @@ module TurnKit
     end
 
     def subject_section
-      return nil unless conversation.subject&.respond_to?(:to_prompt)
-
-      value = conversation.subject.to_prompt.to_s.strip
+      value = conversation.subject_prompt.strip
       return nil if value.empty?
 
       untrusted_section(
@@ -211,9 +209,11 @@ module TurnKit
     end
 
     def live_context_section
-      contributions = Array(TurnKit.context_contributors).filter_map do |contributor|
+      contributors = agent.context_contributors
+      contributions = contributors.filter_map do |contributor|
         normalize_context_contribution(contributor.call(prompt_build_context))
       end
+      contributions.unshift(normalize_context_contribution(name: "run_context", content: JSON.generate(turn.context), trusted: false)) unless turn.context.empty?
       return nil if contributions.empty?
 
       body = contributions.map do |contribution|
@@ -280,7 +280,7 @@ module TurnKit
         "stable_chars" => stable.length,
         "dynamic_chars" => dynamic.length,
         "sections" => sections.map(&:to_s),
-        "tool_count" => agent.effective_tools.length
+        "tool_count" => agent.effective_tools(turn: turn).length
       }
     end
 

data/lib/turnkit/tool.rb

@@ -54,6 +54,17 @@ module TurnKit
         @ends_turn || false
       end
 
+      # :unknown is the safe default for external effects. :replay_safe means
+      # the application/tool honors ToolContext#idempotency_key on retries.
+      def recovery(value = nil)
+        if value
+          value = value.to_sym
+          raise ArgumentError, "recovery must be :unknown or :replay_safe" unless %i[unknown replay_safe].include?(value)
+          @recovery = value
+        end
+        @recovery || (superclass.respond_to?(:recovery) ? superclass.recovery : :unknown)
+      end
+
       def completion_message(result)
         case @completion_message
         when nil

data/lib/turnkit/tool_runner.rb

@@ -7,14 +7,25 @@ module TurnKit
     end
 
     def dispatch(tool_calls)
+      waiting = false
       tool_calls.each_with_index do |tool_call, index|
-        execution = run(tool_call)
+        control = turn.control_boundary!
+        return control if control
+        # Fan out a contiguous group of subagents, but never reorder ordinary
+        # tools across it or execute past a terminal tool.
+        return :waiting if waiting && !subagent?(tool_for(tool_call.name))
+        execution = run(tool_call, defer_result: waiting)
+        return execution if %i[paused steered].include?(execution)
+        if execution == :waiting
+          waiting = true
+          next
+        end
         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
+      waiting ? :waiting : nil
     end
 
     def completion_message(execution)
@@ -25,11 +36,30 @@ module TurnKit
     private
       attr_reader :turn
 
-      def run(tool_call)
-        execution = ToolExecution.new(create_execution(tool_call))
-        heartbeat!
-
+      def run(tool_call, defer_result: false)
+        @defer_result = defer_result
         tool = tool_for(tool_call.name)
+        existing = turn.store.list_tool_executions(turn_id: turn.id).find { |row| row["tool_call_id"] == tool_call.id }
+        if existing && !%w[pending running].include?(existing["status"])
+          execution = ToolExecution.new(existing)
+          append_result_once(execution, tool_call, execution.result || execution.error, error: !execution.completed? && !execution.cancelled?)
+          return execution
+        end
+
+        denied = nil
+        execution = turn.store.atomic do
+          execution = ToolExecution.new(existing || create_execution(tool_call))
+          unless existing
+            begin
+              turn.execution_budget(excluding: execution.id).count_tool_execution!(tool_call.name)
+            rescue BudgetError => error
+              denied = error
+              finish_error(execution, tool_call, error.message, details: { "class" => error.class.name, "budget_denied" => true })
+            end
+          end
+          execution
+        end
+        raise denied if denied
 
         unless tool
           return finish_error(execution, tool_call, "unknown tool: #{tool_call.name}")
@@ -39,20 +69,35 @@ 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
+        if execution.status == "pending" && !subagent?(tool) && ![WaitTool, LaunchAgentTool, SendMessageTool].include?(tool)
+          claimed = turn.store.claim_tool_execution(execution.id, from: "pending", to: "running", started_at: Clock.now)
+          raise LostClaim, "tool execution claim was revoked" unless claimed
+          execution = ToolExecution.new(claimed)
         end
 
         context = ToolContext.new(turn: turn, execution: execution)
         payload = begin
-          normalize_payload(call_tool(tool, tool_call.arguments, context: context))
+          Authorization.authorize!(:tool, principal: context.principal, turn: turn, tool: tool, arguments: tool_call.arguments)
+          # Observe cancellation/reconciliation immediately before crossing the
+          # external-effect boundary. Calls already sent cannot be recalled.
+          control = turn.control_boundary!
+          return control if control
+          if turn.background? && subagent?(tool)
+            return delegate(tool, tool_call, context)
+          end
+          value = call_tool(tool, tool_call.arguments, context: context)
+          return value if tool == LaunchAgentTool && %i[paused steered waiting].include?(value)
+          return :waiting if value == :waiting && tool == WaitTool
+          normalize_payload(value)
+        rescue LostClaim
+          raise
         rescue BudgetError => error
           finish_error(execution, tool_call, error.message, details: { "class" => error.class.name, "budget_denied" => true })
           raise
+        rescue AuthorizationError => error
+          return finish_error(execution, tool_call, error.message, details: { "class" => error.class.name, "authorization_denied" => true })
         rescue StandardError => error
+          raise if turn.background? && !error.is_a?(ToolError)
           return finish_error(execution, tool_call, error.message, details: { "class" => error.class.name })
         end
         finish_success(execution, tool_call, payload)
@@ -63,7 +108,7 @@ module TurnKit
           "turn_id" => turn.id,
           "tool_call_id" => tool_call.id,
           "tool_name" => tool_call.name,
-          "status" => "running",
+          "status" => turn.background? && (subagent?(tool_for(tool_call.name)) || [WaitTool, LaunchAgentTool, SendMessageTool].include?(tool_for(tool_call.name))) ? "pending" : "running",
           "arguments" => tool_call.arguments,
           "started_at" => Clock.now
         )
@@ -71,11 +116,12 @@ module TurnKit
 
       def finish_success(execution, tool_call, payload)
         json = payload.to_json
-        attrs = turn.store.claim_tool_execution(execution.id, from: "running", to: "completed", result: payload, completed_at: Clock.now)
+        attrs = turn.store.atomic do
+          row = turn.store.claim_tool_execution(execution.id, from: execution.status, to: "completed", result: payload, completed_at: Clock.now)
+          append_result_once(execution, tool_call, payload) if row
+          row
+        end
         return superseded_execution(execution) unless attrs
-
-        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
@@ -83,11 +129,12 @@ module TurnKit
       def finish_error(execution, tool_call, message, details: nil)
         error = { "message" => message.to_s, "details" => details }.compact
         json = error.to_json
-        attrs = turn.store.claim_tool_execution(execution.id, from: "running", to: "failed", error: error, completed_at: Clock.now)
+        attrs = turn.store.atomic do
+          row = turn.store.claim_tool_execution(execution.id, from: execution.status, to: "failed", error: error, completed_at: Clock.now)
+          append_result_once(execution, tool_call, error, error: true) if row
+          row
+        end
         return superseded_execution(execution) unless attrs
-
-        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
@@ -98,11 +145,14 @@ module TurnKit
         ToolExecution.new(turn.store.load_tool_execution(execution.id))
       end
 
-      def append_result(execution, tool_call, payload, json: payload.to_json, error: false)
+      def append_result_once(execution, tool_call, payload, error: false)
+        return if @defer_result
+        return if turn.store.list_messages(turn.conversation.id).any? { |row| row["tool_execution_id"] == execution.id }
+
         message = turn.conversation.append_message(
           role: "tool",
           kind: "tool_result",
-          content: [ { "type" => "tool_result", "tool_call_id" => tool_call.id, "text" => json, "error" => error } ],
+          content: [ { "type" => "tool_result", "tool_call_id" => tool_call.id, "text" => payload.to_json, "error" => error } ],
           turn_id: turn.id,
           tool_execution_id: execution.id,
           metadata: { "tool_name" => tool_call.name }
@@ -112,42 +162,56 @@ module TurnKit
 
       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.claim_tool_execution(execution.id, from: "running", to: "cancelled", result: payload, completed_at: Clock.now)
-          next unless attrs
-
-          append_result(ToolExecution.new(attrs), call, payload)
-          turn.emit("tool_call.skipped", id: call.id, name: call.name)
+          turn.store.atomic do
+            next if turn.store.list_tool_executions(turn_id: turn.id).any? { |row| row["tool_call_id"] == call.id }
+            payload = { "skipped" => true, "message" => "not executed: turn ended by #{terminal.name}" }
+            execution = ToolExecution.new(create_execution(call))
+            attrs = turn.store.claim_tool_execution(execution.id, from: execution.status, to: "cancelled", result: payload, completed_at: Clock.now)
+            append_result_once(ToolExecution.new(attrs), call, payload)
+            turn.emit("tool_call.skipped", id: call.id, name: call.name)
+          end
         end
       end
 
-      def heartbeat!
-        turn.send(:heartbeat!)
+      def subagent?(tool)
+        tool.is_a?(Class) && tool < SubAgentTool
+      end
+
+      def delegate(tool, call, context)
+        arguments = tool.validate_arguments(call.arguments)
+        Authorization.authorize!(:launch_agent, principal: context.principal, turn: turn, agent: tool.agent, arguments: arguments)
+        TurnKit.resolve_agent(tool.agent.name)
+        child = turn.store.atomic_graph do
+          turn.store.atomic(Background.root_conversation(turn.store, turn.store.load_turn(turn.id))) do
+            control = turn.control_boundary!
+            next control if control
+            row = turn.store.list_turns(root_turn_id: turn.root_turn_id).find { |candidate| candidate["parent_tool_execution_id"] == context.execution.id }
+            unless row
+              built = tool.build_child(task: arguments.fetch("task"), context: context)
+              row = turn.store.update_turn(built.id, submitted_at: Clock.now)
+            end
+            Background.wait(turn, [row.fetch("id")])
+            row
+          end
+        end
+        return child if child.is_a?(Symbol)
+        unless Background::TERMINAL.include?(child["status"])
+          Background.enqueue(child.fetch("id")) if child["status"] == "pending"
+          return :waiting
+        end
+        finish_success(context.execution, call, SubAgentTool.result(child))
       end
 
       def tool_for(name)
-        turn.agent.effective_tools.find { |tool| tool.tool_name == name.to_s }
+        turn.agent.effective_tools(turn: turn).find { |tool| tool.tool_name == name.to_s }
       end
 
-      # Heartbeats while the tool runs so a tool slower than TurnKit.timeout
-      # keeps its turn's stale anchor fresh and is not falsely reconciled.
       def call_tool(tool, arguments, context:)
-        interval = (TurnKit.timeout || 300) / 3.0
-        heartbeat = Thread.new do
-          loop do
-            sleep interval
-            heartbeat!
-          end
-        end
-
         if tool.is_a?(Class)
           tool.call(arguments, context: context)
         else
           tool.class.invoke(tool, arguments, context: context)
         end
-      ensure
-        heartbeat.kill
       end
 
       def normalize_payload(value)