turnkit 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8ca23035231ccf58df8389aa2e845bb3e8874b1a23d33a8e8ffb8b793c533fe
-  data.tar.gz: 1f1bafaf7eb330caa119504846b9960989f116780b5ea364fdbe4e7c47869db2
+  metadata.gz: 2a276982d34a5c7685f9512e29f1843942166c67bdb59c94ebc38b727213ffe3
+  data.tar.gz: 8ad4edfdc514c24a918441734c4c10294e7d1c45b08b7594f19db7e3294edd61
 SHA512:
-  metadata.gz: dbe5569a73d9118776e207567a515642d9fc59923de34b5084499623f36798e9c826832bf35d7f8105b9272252edb6da244faf896f9509e59e571d9db7f9022f
-  data.tar.gz: 31b2decb3c2336eafd7f943eaff23cf149b88c67067b75c785f9cd71960349a9f89a20da5dfd1d415fb1f7e083f9e061514f359568c4a5b92fc44426a8e05fcd
+  metadata.gz: 5bff210317826da7bd796b0271006b76c2ed301dbd9070248529efd8c14e3b2d43414258373f6c709a1496f91004764227ff2453073be0040ac0d5bde4eb3d77
+  data.tar.gz: ed8c88ae93a81983f2284e3ed69c018a1e05abd4b2ae081db2160a937c1e4e42fdece546baac10ca8c976e94da54354275f15d80d5dc4cc60cb55e919a78e8d1

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.7.0 - 2026-09-10
+
+- Add destination-oriented `Conversation#post`, durable input/request receipts,
+  authorized transcript cursor reads, and cooperative `pause!`, `resume!`, and
+  `steer!` controls on turns/runs, including parent-linked subtree controls.
+- Preserve in-flight results while skipping stale tool proposals before steering;
+  keep paused conversations closed to automatic wake and retain dependency waits.
+- Enqueue newly eligible joined turns in the same maintenance pass, and serialize
+  MemoryStore message insertion with sequence allocation for cursor catchup.
+- Project busy-time deliveries at their receiving turn's context boundary so
+  earlier steering cannot override next-turn input or split prior tool exchanges.
+- Support optional RubyLLM 2.0.0.rc2 with `protocol: :responses`, opaque provider
+  replay, single-response `generate`, and updated usage/media APIs. Keep RubyLLM
+  1.16 compatibility and the stable development dependency; no separate HTTP
+  adapter or tool executor. Add live Astra/xhigh Rails 8.1/Sidekiq validation.
+- Preserve complete native Anthropic/Gemini thinking/tool blocks across durable
+  reload, steering and recovery, without exposing opaque state in UI/activity.
+  Avoid duplicate raw Gemini calls and double-counted native thinking on 1.16;
+  validate Claude Opus 4.8/high and Gemini 3.1 Pro/high on both SDK versions.
+- No migration on the 0.6.0 schema. Add `paused` to application/custom-store status
+  handling and upgrade workers together before enabling controls. Existing
+  delivery retry payloads remain compatible. See `docs/interactive-research.md`.
+
 ## 0.6.0 - 2026-09-06
 
 ### Added

data/README.md

@@ -7,6 +7,17 @@
 Build durable Ruby and Rails agents with conversations, runs, orchestrator agents,
 tools, skills, output audits, sub-agents, and persistence.
 
+For interactive long-running work, use `conversation.post(text, key:, principal:)`
+for next-turn input and `turn.steer!(text, key:, principal:)` to revise the active
+plan. `turn.pause!`/`resume!` preserve progress and release background workers;
+use `descendants: :cascade` for a research subtree. See
+[interactive research](docs/interactive-research.md) for exact interruption
+boundaries, durable receipts, approval gates, and Rails integration.
+For GPT-6 Astra tools, opt into the pinned RubyLLM 2 release candidate and
+[Responses protocol](docs/interactive-research.md#gpt-6-astra-and-provider-continuation-state).
+The [live validation app](examples/interactive_validation/README.md) exercises
+these controls with Rails 8.1, PostgreSQL, Sidekiq, and actual Astra/xhigh requests.
+
 ## Installation
 
 Add this line to your application's **Gemfile**:

data/lib/turnkit/active_record_store.rb

@@ -166,7 +166,7 @@ module TurnKit
 
     def busy_conversation?(id, include_pending: true)
       turns = turn_class.where(conversation_uid: id)
-      active = turns.where(status: %w[running waiting])
+      active = turns.where(status: %w[running waiting paused])
       active = active.or(turns.where(status: "pending").where.not(submitted_at: nil)) if include_pending
       active.exists?
     end

data/lib/turnkit/adapters/ruby_llm.rb

@@ -10,9 +10,16 @@ module TurnKit
         openrouter: "OPENROUTER_API_KEY"
       }.freeze
 
+      def initialize(protocol: nil)
+        @protocol = protocol
+      end
+
       def validate!(model:)
         ensure_ruby_llm!
         raise ModelAccessError, "model is required" if model.to_s.empty?
+        if @protocol && !::RubyLLM::Chat.method_defined?(:generate)
+          raise ConfigError, "protocol selection requires RubyLLM 2.0 (currently 2.0.0.rc2)"
+        end
 
         configure_from_environment
         provider = provider_for(model)
@@ -27,13 +34,18 @@ module TurnKit
         ensure_ruby_llm!
         configure_from_environment
 
-        chat = ::RubyLLM.chat(model: model)
+        validate!(model: model) if @protocol
+        chat = ::RubyLLM.chat(**{ model: model, protocol: @protocol }.compact)
+        chat.with_provider_options(metadata: metadata.transform_values(&:to_s)) if @protocol == :responses && metadata
         add_instructions(chat, instructions, dynamic_instructions, model: model)
         chat.with_temperature(temperature) if temperature
         apply_thinking(chat, thinking)
         chat.with_schema(normalize_schema(output_schema)) if output_schema
-        Array(tools).each { |tool| chat.with_tool(ruby_llm_tool(tool)) }
-        Array(messages).each { |message| add_message(chat, message) }
+        Array(tools).each do |tool|
+          chat.respond_to?(:with_tool) ? chat.with_tool(ruby_llm_tool(tool)) : chat.with_tools(ruby_llm_tool(tool))
+        end
+        tool_names = {}
+        Array(messages).each { |message| add_message(chat, message, provider: chat.model.provider, tool_names: tool_names) }
 
         response = complete_without_tool_execution(chat)
         normalize_response(response, model: model)
@@ -56,7 +68,7 @@ module TurnKit
           size: size || "1024x1024",
           with: input_images,
           mask: mask,
-          params: params || {}
+          **{ (::RubyLLM::Chat.method_defined?(:generate) ? :provider_options : :params) => params || {} }
         )
         normalize_image_response(image, model: model, provider: provider, params: { "size" => size || "1024x1024" }.merge(params || {}), metadata: metadata)
       rescue ConfigError
@@ -69,13 +81,24 @@ module TurnKit
         ensure_ruby_llm!
         configure_from_environment
         media_input = MediaInput.wrap(media)
-        content = ::RubyLLM::Content.new(objective.to_s)
-        content.add_attachment(media_input.attachment_source, filename: media_input.filename)
 
         chat = ::RubyLLM.chat(model: model)
         chat.with_schema(normalize_schema(output_schema)) if output_schema
-        chat.with_params(**params) if params && !params.empty?
-        chat.add_message(role: :user, content: content)
+        if params && !params.empty?
+          if ::RubyLLM::Chat.method_defined?(:generate)
+            chat.with_provider_options(**params)
+          else
+            chat.with_params(**params)
+          end
+        end
+        if ::RubyLLM::Chat.method_defined?(:generate)
+          attachment = ::RubyLLM::Attachment.new(media_input.attachment_source, filename: media_input.filename)
+          chat.add_message(role: :user, content: objective.to_s, attachments: [attachment])
+        else
+          content = ::RubyLLM::Content.new(objective.to_s)
+          content.add_attachment(media_input.attachment_source, filename: media_input.filename)
+          chat.add_message(role: :user, content: content)
+        end
 
         response = complete_without_tool_execution(chat)
         normalize_media_analysis_response(response, media: media_input, model: model, provider: provider, params: params || {}, metadata: metadata)
@@ -133,12 +156,10 @@ module TurnKit
           end
         end
 
-        # RubyLLM has no public API to request a completion without executing
-        # tool calls, so this depends on the private RubyLLM::Chat#provider_completion
-        # (added in ruby_llm 1.16). TurnKit must run tools itself (to persist
-        # executions and enforce budgets). Guarded by a canary test in the
-        # suite; revisit when RubyLLM exposes a public equivalent.
+        # 2.0's public generate requests one completion without executing tools.
+        # 1.16 needs its private provider_completion, guarded by a canary test.
         def complete_without_tool_execution(chat)
+          return chat.generate if chat.respond_to?(:generate)
           unless chat.respond_to?(:provider_completion, true)
             raise ConfigError, "TurnKit::Adapters::RubyLLM requires ruby_llm >= 1.16 (RubyLLM::Chat#provider_completion not found)"
           end
@@ -146,15 +167,31 @@ module TurnKit
           chat.send(:provider_completion)
         end
 
-        def add_message(chat, message)
+        def add_message(chat, message, provider: nil, tool_names: {})
           role = (message[:role] || message["role"]).to_sym
           content = message[:content] || message["content"] || ""
+          kind = { "openai" => "openai_responses", "anthropic" => "anthropic", "gemini" => "gemini" }[provider.to_s]
+          replay = Array(message[:provider_parts] || message["provider_parts"]).find { |part| part["kind"] == kind } if kind
+          calls = ruby_llm_tool_calls(message[:tool_calls] || message["tool_calls"])
+          raw_content = replay&.fetch("data")
+          if raw_content && %w[anthropic gemini].include?(kind) && !::RubyLLM::Chat.method_defined?(:generate)
+            content = ::RubyLLM::Content::Raw.new(raw_content)
+            raw_content = nil
+            if kind == "gemini"
+              # 1.16 appends normalized calls after Raw content. Omit those
+              # duplicates and supply names for its positional function results.
+              calls&.each { |id, call| tool_names[id] = call.name }
+              calls = nil
+            end
+          end
+          call_id = message[:tool_call_id] || message["tool_call_id"]
           chat.add_message(
             {
               role: role,
               content: content,
-              tool_calls: ruby_llm_tool_calls(message[:tool_calls] || message["tool_calls"]),
-              tool_call_id: message[:tool_call_id] || message["tool_call_id"]
+              raw_content: raw_content,
+              tool_calls: calls,
+              tool_call_id: tool_names.fetch(call_id, call_id)
             }.compact
           )
         end
@@ -176,6 +213,10 @@ module TurnKit
           content = content.to_s.strip
           return if content.empty?
 
+          if ::RubyLLM::Chat.method_defined?(:generate)
+            chat.add_message(role: :system, content: content, cache_until_here: cache)
+            return
+          end
           if cache
             content = ::RubyLLM::Providers::Anthropic::Content.new(content, cache: true)
           end
@@ -207,7 +248,7 @@ module TurnKit
           Class.new(::RubyLLM::Tool) do
             define_singleton_method(:name) { tool.tool_name }
             description tool.description
-            params tool.input_schema
+            respond_to?(:params) ? params(tool.input_schema) : parameters(tool.input_schema)
 
             define_method(:execute) do |**arguments|
               raise ToolError, "tools must be executed by TurnKit turns, not the RubyLLM adapter"
@@ -216,6 +257,10 @@ module TurnKit
         end
 
         def normalize_response(response, model:)
+          raw = response.raw.body if response.respond_to?(:raw) && response.raw.respond_to?(:body)
+          if raw.is_a?(Hash) && raw["object"] == "response" && raw["status"] != "completed"
+            raise ModelError, "OpenAI Responses #{raw['status']}: #{raw.dig('incomplete_details', 'reason')}"
+          end
           tool_calls = Array(response.respond_to?(:tool_calls) ? response.tool_calls&.values : []).map do |call|
             ToolCall.new(id: call.id, name: call.name, arguments: call.arguments)
           end
@@ -233,7 +278,7 @@ module TurnKit
             output_data: response_data(response),
             tool_calls: tool_calls,
             usage: usage,
-            model: response.respond_to?(:model_id) ? response.model_id : model
+            model: response_model(response, model)
           )
         end
 
@@ -248,6 +293,14 @@ module TurnKit
             text = content.to_s
             text.empty? ? [] : [ { "type" => "text", "text" => text } ]
           end.compact
+          raw = response.raw.body if response.respond_to?(:raw) && response.raw.respond_to?(:body)
+          if raw.is_a?(Hash) && raw["object"] == "response"
+            parts << { "type" => "provider", "kind" => "openai_responses", "data" => raw.fetch("output") }
+          elsif raw.is_a?(Hash) && raw["type"] == "message" && raw["role"] == "assistant"
+            parts << { "type" => "provider", "kind" => "anthropic", "data" => raw.fetch("content") }
+          elsif raw.is_a?(Hash) && raw.dig("candidates", 0, "content", "parts")
+            parts << { "type" => "provider", "kind" => "gemini", "data" => raw.dig("candidates", 0, "content", "parts") }
+          end
           parts + Array(tool_calls).map { |call| { "type" => "tool_call", "id" => call.id, "name" => call.name, "arguments" => call.arguments } }
         end
 
@@ -281,7 +334,25 @@ module TurnKit
         end
 
         def token_value(response, method)
-          response.respond_to?(method) ? response.public_send(method).to_i : 0
+          if response.respond_to?(method)
+            value = response.public_send(method).to_i
+            raw = response.raw.body if response.respond_to?(:raw) && response.raw.respond_to?(:body)
+            native = raw.is_a?(Hash) && (raw["candidates"] || raw["type"] == "message")
+            # Native 1.16 providers also include thinking in their output count.
+            return native && method == :output_tokens ? value - thinking_token_value(response) : value
+          end
+          return 0 unless response.respond_to?(:tokens)
+
+          key = { input_tokens: :input, output_tokens: :output, cached_tokens: :cache_read,
+            cache_creation_tokens: :cache_write, thinking_tokens: :thinking, reasoning_tokens: :thinking }.fetch(method)
+          value = response.tokens.public_send(key).to_i
+          # RubyLLM 2.0 includes thinking in output; TurnKit buckets are additive.
+          method == :output_tokens ? value - response.tokens.thinking.to_i : value
+        end
+
+        def response_model(response, fallback)
+          return response.model if response.respond_to?(:model)
+          response.respond_to?(:model_id) ? response.model_id : fallback
         end
 
         def thinking_token_value(response)
@@ -305,7 +376,7 @@ module TurnKit
             data: image.respond_to?(:data) ? image.data : nil,
             mime_type: image.respond_to?(:mime_type) ? image.mime_type : nil,
             revised_prompt: image.respond_to?(:revised_prompt) ? image.revised_prompt : nil,
-            model: image.respond_to?(:model_id) ? image.model_id : model,
+            model: response_model(image, model),
             provider: provider&.to_s,
             usage: usage,
             params: params,
@@ -327,7 +398,7 @@ module TurnKit
           part = MediaAnalysisResult.new(
             text: response_text(response),
             data: response_data(response),
-            model: response.respond_to?(:model_id) ? response.model_id : model,
+            model: response_model(response, model),
             provider: provider&.to_s,
             usage: usage,
             params: params,
@@ -339,6 +410,7 @@ module TurnKit
         end
 
         def image_usage_value(image, key)
+          return image.tokens.public_send(key == "input_tokens" ? :input : :output).to_i if image.respond_to?(:tokens)
           usage = image.respond_to?(:usage) ? image.usage || {} : {}
           (usage[key] || usage[key.to_sym]).to_i
         end

data/lib/turnkit/background.rb

@@ -41,11 +41,11 @@ module TurnKit
       store.load_conversation(callback) if callback
       store.atomic(root_conversation(store, store.load_turn(turn.id))) do
         record = store.load_turn(turn.id)
-        raise Error, "only pending turns can be submitted" unless record["status"] == "pending"
+        raise Error, "only pending or paused turns can be submitted" unless %w[pending paused].include?(record["status"])
         options = record.fetch("options")
         options = options.merge("callback_conversation_id" => callback) if callback
         store.update_turn(turn.id, submitted_at: record["submitted_at"] || Clock.now, options: options,
-          status: ready?(store, turn.id) ? "pending" : "waiting")
+          status: record["status"] == "paused" ? "paused" : ready?(store, turn.id) ? "pending" : "waiting")
       end
       enqueue(turn.id)
       turn.reload
@@ -90,7 +90,7 @@ module TurnKit
           next if !state["phase"] && !ready?(store, current.fetch("id")) && !deadline_exceeded?(store, current)
           if current["submitted_at"]
             others = store.list_turns(conversation_id: current.fetch("conversation_id")).reject { |row| row["id"] == current["id"] }
-            next if others.any? { |row| %w[running waiting].include?(row["status"]) }
+            next if others.any? { |row| %w[running waiting paused].include?(row["status"]) }
             first = ([current] + others.select { |row| row["submitted_at"] && row["status"] == "pending" }).min_by { |row| [row["created_at"], row["id"]] }
             next unless first["id"] == current["id"]
           end
@@ -150,7 +150,7 @@ module TurnKit
         message = store.append_message(
           "conversation_id" => destination, "role" => "user", "kind" => "text",
           "text" => delivery.fetch("payload").fetch("text"),
-          "metadata" => { "delivery_id" => delivery.fetch("id"), "source_conversation_id" => delivery["source_conversation_id"], "source_turn_id" => delivery["source_turn_id"] }
+          "metadata" => { "delivery_id" => delivery.fetch("id"), "principal" => delivery.dig("payload", "principal"), "source_conversation_id" => delivery["source_conversation_id"], "source_turn_id" => delivery["source_turn_id"] }
         )
         store.update_delivery(delivery.fetch("id"), message_id: message.fetch("id"), delivered_at: Clock.now)
         wake(destination, store: store)
@@ -242,7 +242,7 @@ module TurnKit
       end
       turns.group_by { |record| record.fetch("conversation_id") }.each do |conversation_id, records|
         next if store.busy_conversation?(conversation_id, include_pending: false)
-        record = records.find { |row| row["status"] == "pending" }
+        record = records.map { |row| store.load_turn(row.fetch("id")) }.find { |row| row["status"] == "pending" }
         if record
           rotated = store.claim_turn(record.fetch("id"), from: "pending", to: "pending")
           enqueue(record.fetch("id")) if rotated

data/lib/turnkit/client.rb

@@ -4,7 +4,9 @@ module TurnKit
   # The adapter contract. TurnKit calls clients with the full keyword
   # signatures below. Custom adapters should subclass TurnKit::Client (or
   # accept the same keywords) and must not execute tools themselves; TurnKit
-  # runs tools and persists their results.
+  # runs tools and persists their results. Messages may include :provider_parts
+  # for opaque continuation state from Result parts with type "provider".
+  # Adapters should consume only their own provider kind, never display it.
   class Client
     def validate!(model:)
       true

data/lib/turnkit/conversation.rb

@@ -20,6 +20,37 @@ module TurnKit
       append_message(role: "user", kind: "text", text: text, metadata: metadata)
     end
 
+    # Destination-oriented, durable next-turn input. The destination is also
+    # the delivery's source; the application need not create a sender agent.
+    def post(text, key:, principal: nil)
+      Authorization.authorize!(:send_message, principal: principal, source_conversation: id, destination_conversation: id)
+      delivery = store.create_delivery("source_conversation_id" => id, "destination_conversation_id" => id,
+        "key" => key, "payload" => { "text" => text, "principal" => principal })
+      Background.enqueue
+      delivery
+    end
+
+    def messages_after(sequence, principal: nil)
+      Authorization.authorize!(:read_messages, principal: principal, destination_conversation: id)
+      messages.select { |message| message.sequence > sequence }.map do |message|
+        # Provider thinking/signature parts are not application progress.
+        attrs = message.to_h
+        attrs["content"] = Array(attrs["content"]).reject { |part| %w[thinking provider].include?(part["type"]) }
+        Message.new(attrs)
+      end
+    end
+
+    def input_status(delivery_id, principal: nil)
+      Authorization.authorize!(:read_control, principal: principal, destination_conversation: id)
+      delivery = store.load_delivery(delivery_id)
+      raise ArgumentError, "delivery belongs to another conversation" unless delivery["destination_conversation_id"] == id
+      applied = store.list_turns(conversation_id: id).filter_map do |row|
+        request = row.dig("options", "state", "delivery_requests", delivery_id)
+        { "turn_id" => row.fetch("id"), "request_id" => request } if request
+      end.first
+      delivery.merge("application" => applied, "status" => applied ? "applied" : "pending")
+    end
+
     def subject_prompt
       subject.respond_to?(:to_prompt) ? subject.to_prompt.to_s : metadata["turnkit_subject_prompt"].to_s
     end

data/lib/turnkit/coordination_tools.rb

@@ -30,6 +30,11 @@ module TurnKit
       TurnKit.resolve_agent(agent.name)
       child = nil
       parent.store.atomic do
+        control = parent.control_boundary!
+        if control
+          child = control
+          next
+        end
         existing = parent.store.list_turns(root_turn_id: parent.root_turn_id).find { |row| row["parent_tool_execution_id"] == context.execution.id }
         if existing
           child = existing
@@ -40,6 +45,7 @@ module TurnKit
           child = parent.store.update_turn(built.id, submitted_at: Clock.now, options: options)
         end
       end
+      return child if child.is_a?(Symbol)
       Background.enqueue(child.fetch("id"))
       SubAgentTool.result(child)
     end

data/lib/turnkit/cost.rb

@@ -73,13 +73,13 @@ module TurnKit
       return new unless defined?(::RubyLLM) && model
 
       model_info = ::RubyLLM.models.find(model)
-      tokens = ::RubyLLM::Tokens.new(
-        input: usage.input_tokens,
-        output: usage.output_tokens,
-        cached: usage.cached_tokens,
-        cache_creation: usage.cache_write_tokens,
-        thinking: usage.thinking_tokens
-      )
+      tokens = if ::RubyLLM::Chat.method_defined?(:generate)
+        ::RubyLLM::Tokens.new(input: usage.input_tokens, output: usage.output_tokens + usage.thinking_tokens,
+          cache_read: usage.cached_tokens, cache_write: usage.cache_write_tokens, thinking: usage.thinking_tokens)
+      else
+        ::RubyLLM::Tokens.new(input: usage.input_tokens, output: usage.output_tokens,
+          cached: usage.cached_tokens, cache_creation: usage.cache_write_tokens, thinking: usage.thinking_tokens)
+      end
       from_hash(::RubyLLM::Cost.new(tokens: tokens, model: model_info).to_h)
     rescue ::RubyLLM::ModelNotFoundError
       new

data/lib/turnkit/memory_store.rb

@@ -58,11 +58,13 @@ module TurnKit
     end
 
     def append_message(attributes)
-      attrs = stringify(attributes)
-      attrs["sequence"] ||= next_message_sequence(attrs.fetch("conversation_id"))
-      message = Record.message(attrs)
-      @mutex.synchronize { @messages[message.fetch("id")] = message }
-      duplicate(message)
+      @mutex.synchronize do
+        attrs = stringify(attributes)
+        attrs["sequence"] ||= next_message_sequence(attrs.fetch("conversation_id"))
+        message = Record.message(attrs)
+        @messages[message.fetch("id")] = message
+        duplicate(message)
+      end
     end
 
     def list_messages(conversation_id, through_sequence: nil, turn_id: nil)

data/lib/turnkit/message_projection.rb

@@ -33,7 +33,10 @@ module TurnKit
           { role: :assistant, content: [ CONTEXT_SUMMARY_PREFIX, message.text ].reject(&:empty?).join("\n\n") }
         ]
       else
-        [ to_h ]
+        projected = to_h
+        provider_parts = message.content.select { |part| part["type"] == "provider" }
+        projected[:provider_parts] = provider_parts if provider_parts.any?
+        [ projected ]
       end
     end
 

data/lib/turnkit/record.rb

@@ -2,7 +2,7 @@
 
 module TurnKit
   module Record
-    TURN_STATUSES = %w[pending waiting running completed failed cancelled stale].freeze
+    TURN_STATUSES = %w[pending waiting paused running completed failed cancelled stale].freeze
     TOOL_EXECUTION_STATUSES = %w[pending running completed failed cancelled interrupted].freeze
 
     TURN_UPDATE_KEYS = %w[status options usage cost error output_text output_data submitted_at claim_token started_at heartbeat_at completed_at].freeze

data/lib/turnkit/run.rb

@@ -52,6 +52,19 @@ module TurnKit
       self
     end
 
+    def pause!(**options)
+      turn.pause!(**options)
+      self
+    end
+
+    def resume!(**options)
+      turn.resume!(**options)
+      self
+    end
+
+    def steer!(text, **options) = turn.steer!(text, **options)
+    def control_state(**options) = turn.control_state(**options)
+
     def reload
       turn.reload
       self

data/lib/turnkit/store.rb

@@ -27,7 +27,7 @@ module TurnKit
 
     # 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].include?(row["status"]) || (include_pending && row["submitted_at"] && row["status"] == "pending") }
+      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)

data/lib/turnkit/tool_runner.rb

@@ -9,10 +9,13 @@ module TurnKit
     def dispatch(tool_calls)
       waiting = false
       tool_calls.each_with_index do |tool_call, index|
+        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
@@ -77,11 +80,13 @@ module TurnKit
           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.
-          turn.store.atomic { true }
+          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
@@ -178,6 +183,8 @@ module TurnKit
         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)
@@ -187,6 +194,7 @@ module TurnKit
             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

data/lib/turnkit/turn.rb

@@ -2,6 +2,7 @@
 
 module TurnKit
   class Turn
+    include TurnControls
     STATUSES = Record::TURN_STATUSES
 
     attr_reader :agent, :conversation, :store, :budget, :depth
@@ -77,7 +78,10 @@ module TurnKit
     end
 
     def suspend!
-      update!(status: "waiting", claim_token: nil)
+      store.atomic do
+        reload
+        update!(status: @record.dig("options", "controls", "pause_requested") ? "paused" : "waiting", claim_token: nil)
+      end
     end
 
     # Revokes the local claim. An already-sent remote request cannot be
@@ -292,6 +296,12 @@ module TurnKit
 
       def execute
         loop do
+          control = control_boundary!
+          break if control == :paused
+          if control == :waiting
+            suspend!
+            break
+          end
           @budget = execution_budget
           budget.check!(depth: depth)
           state = @record.dig("options", "state") || {}
@@ -301,6 +311,9 @@ module TurnKit
             TurnKit::Compaction.maybe_compact!(self)
             request = model_request
             emit_model_requested("model.requested", request)
+            control = control_boundary!
+            break if control == :paused
+            next if control
             result = call_client(request)
             cost = Cost.from_usage(result.usage, model: result.model || model)
             store.atomic do
@@ -314,6 +327,8 @@ module TurnKit
           when "tools"
             runner = ToolRunner.new(self)
             terminal = runner.dispatch(Result.new(parts: state.fetch("parts")).tool_calls)
+            break if terminal == :paused
+            next if terminal == :steered
             if terminal == :waiting
               suspend!
               break
@@ -338,7 +353,7 @@ module TurnKit
               emit("output_policy.revision", violation_count: audit.violations.length, attempt: revisions_used + 1)
             else
               complete_with_output(candidate, output_data: state["output_data"], audit: audit)
-              break
+              break unless status == "running"
             end
           end
         end
@@ -383,7 +398,7 @@ module TurnKit
           dynamic_instructions: dynamic_instructions,
           thinking: thinking,
           output_schema: output_schema,
-          metadata: { turn_id: id, conversation_id: conversation.id },
+          metadata: { turn_id: id, conversation_id: conversation.id, request_id: @record.dig("options", "state", "request_id") },
           report: prompt.report
         )
       end
@@ -412,7 +427,22 @@ module TurnKit
       end
 
       def llm_messages
-        MessageProjection.for(TurnKit::Compaction.project(conversation.messages_for_turn(self)))
+        messages = TurnKit::Compaction.project(conversation.messages_for_turn(self))
+        # Delivery time is not application time. A next-turn message can arrive
+        # between an earlier turn's tool call/result or before its steering.
+        # Keep UI sequence order intact, but place each delivery at the frozen
+        # context boundary of its first receiving turn in the provider input.
+        turns = store.list_turns(conversation_id: conversation.id)
+        messages = messages.sort_by do |message|
+          delivery_id = message.metadata["delivery_id"]
+          receiver = if delivery_id
+            turns.find { |row| row.dig("options", "state", "delivery_requests", delivery_id) } ||
+              turns.find { |row| row["context_message_sequence"] >= message.sequence &&
+                (row["submitted_at"] || row["started_at"] || row["id"] == id) }
+          end
+          receiver ? [receiver.fetch("context_message_sequence"), 1, message.sequence] : [message.sequence, 0, 0]
+        end
+        MessageProjection.for(messages)
       end
 
       def emit_model_requested(type, request)
@@ -475,7 +505,7 @@ module TurnKit
           message = conversation.append_message(role: "assistant", kind: "media_analysis", content: result.media_analyses.map { |analysis| analysis.to_h.merge("type" => "media_analysis") }, 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)
+          message = conversation.append_message(role: "assistant", kind: "text", content: result.parts, 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
@@ -505,10 +535,14 @@ module TurnKit
         else
           attrs[:status] = "completed"
         end
-        store.atomic(Background.root_conversation(store, @record)) do
+        controlled = store.atomic(Background.root_conversation(store, @record)) do
+          control = control_boundary!
+          next control if control
           update_state!("policy_audit" => audit.to_h) if audit
           update!(attrs)
+          nil
         end
+        return if controlled
         emit("output_policy.completed", clean: audit.clean?, violation_count: audit.violations.length) if audit
 
         if failed?
@@ -576,7 +610,19 @@ module TurnKit
         store.atomic do
           @budget = execution_budget
           budget.count_iteration!
-          update_state!("iterations" => Turn.iterations_for(@record) + 1)
+          request_id = SecureRandom.uuid
+          options = store.load_turn(id).fetch("options")
+          controls = options["controls"] || {}
+          inputs = controls.fetch("inputs", []).map do |input|
+            input["message_id"] && !input["request_id"] ? input.merge("request_id" => request_id) : input
+          end
+          update!(options: options.merge("controls" => controls.merge("inputs" => inputs)))
+          deliveries = options.dig("state", "delivery_requests") || {}
+          conversation.messages_for_turn(self).each do |message|
+            delivery_id = message.metadata["delivery_id"]
+            deliveries[delivery_id] ||= request_id if delivery_id
+          end
+          update_state!("iterations" => Turn.iterations_for(@record) + 1, "request_id" => request_id, "delivery_requests" => deliveries)
         end
       end
 
@@ -584,7 +630,7 @@ module TurnKit
       # write-once turn configuration. Reads fall back to the legacy top-level
       # keys for turns persisted before the split.
       def update_state!(changes)
-        options = @record["options"] || {}
+        options = store.load_turn(id)["options"] || {}
         update!(options: options.merge("state" => (options["state"] || {}).merge(changes)))
       end
 

data/lib/turnkit/turn_controls.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module TurnKit
+  # Human controls share the execution root lock. Options are the durable
+  # source of truth; no callbacks or job payloads are needed for recovery.
+  module TurnControls
+    def pause!(descendants: :retain, principal: nil)
+      control_tree(:pause, descendants, principal) do |row|
+        controls = row.dig("options", "controls") || {}
+        attrs = { options: row.fetch("options").merge("controls" => controls.merge("pause_requested" => true)) }
+        attrs[:status] = "paused" unless row["status"] == "running"
+        @base_store.update_turn(row.fetch("id"), attrs)
+      end
+      reload
+    end
+
+    def resume!(descendants: :retain, principal: nil)
+      control_tree(:resume, descendants, principal) do |row|
+        controls = row.dig("options", "controls") || {}
+        attrs = { options: row.fetch("options").merge("controls" => controls.merge("pause_requested" => false)) }
+        if row["status"] == "paused"
+          attrs[:status] = Background.ready?(@base_store, row.fetch("id")) ? "pending" : "waiting"
+        end
+        @base_store.update_turn(row.fetch("id"), attrs)
+      end
+      Background.enqueue if background?
+      reload
+    end
+
+    def steer!(text, key:, principal: nil, descendants: :retain)
+      raise ArgumentError, "key must be a nonempty string" unless key.is_a?(String) && !key.empty?
+      text = text.to_s
+      principal = JSON.parse(JSON.generate(principal))
+      receipts = []
+      control_tree(:steer, descendants, principal) do |row|
+        controls = row.dig("options", "controls") || {}
+        inputs = controls.fetch("inputs", [])
+        existing = inputs.find { |input| input["key"] == key }
+        if existing
+          unless existing["text"] == text && existing["principal"] == principal
+            raise ToolError, "steering key is already used for a different input"
+          end
+          receipts << existing
+          next
+        end
+        if Background::TERMINAL.include?(row["status"]) || row["status"] == "stale"
+          raise Error, "cannot steer a #{row['status']} turn; post next-turn input instead" if row["id"] == id
+          next
+        end
+        input = { "id" => SecureRandom.uuid, "key" => key, "text" => text,
+          "principal" => principal, "turn_id" => row.fetch("id"), "sequence" => inputs.length + 1 }
+        @base_store.update_turn(row.fetch("id"), options: row.fetch("options").merge(
+          "controls" => controls.merge("inputs" => inputs + [input])))
+        receipts << input
+      end
+      receipts
+    end
+
+    def control_state(principal: nil)
+      Authorization.authorize!(:read_control, principal: principal, turn: self)
+      row = @base_store.load_turn(id)
+      { "status" => row.fetch("status"), "controls" => row.dig("options", "controls") || {} }
+    end
+
+    # Called before dispatching another unit of work, never during a remote
+    # call. The lock acquisition is the dispatch/control linearization point.
+    def control_boundary!
+      store.atomic do
+        reload
+        if @record.dig("options", "controls", "pause_requested")
+          update!(status: "paused", claim_token: nil)
+          next :paused
+        end
+        inputs = @record.dig("options", "controls", "inputs") || []
+        pending = inputs.reject { |input| input["message_id"] }
+        next unless pending.any?
+        unless Background.ready?(store, id)
+          next Background.deadline_exceeded?(store, @record) ? nil : :waiting
+        end
+
+        executions = store.list_tool_executions(turn_id: id)
+        parts = @record.dig("options", "state", "parts") || []
+        parts.select { |part| part["type"] == "tool_call" }.each do |part|
+          execution = executions.find { |row| row["tool_call_id"] == part["id"] }
+          child = store.list_turns(root_turn_id: root_turn_id).find { |row| execution && row["parent_tool_execution_id"] == execution["id"] }
+          if child && Background::TERMINAL.include?(child["status"]) && %w[pending running].include?(execution["status"])
+            store.claim_tool_execution(execution.fetch("id"), from: execution.fetch("status"), to: "completed",
+              result: SubAgentTool.result(child), completed_at: Clock.now)
+          elsif !execution
+            store.create_tool_execution("turn_id" => id, "tool_call_id" => part.fetch("id"), "tool_name" => part.fetch("name"),
+              "arguments" => part["arguments"], "status" => "cancelled", "completed_at" => Clock.now,
+              "result" => { "skipped" => true, "message" => "not executed: superseded by human steering" })
+          end
+        end
+        executions = Reconciliation.interrupt_tool_executions(@record, store: store)
+        # Complete known results and close unexecuted proposals before adding
+        # human input: providers require a result for every assistant tool ID.
+        Reconciliation.repair_transcript(@record, executions, store: store)
+        pending.each do |input|
+          message = conversation.append_message(role: "user", kind: "text", text: input.fetch("text"), turn_id: id,
+            metadata: { "steering_id" => input.fetch("id"), "principal" => input["principal"] })
+          input["message_id"] = message.id
+        end
+        options = @record.fetch("options")
+        update!(options: options.merge("controls" => options.fetch("controls").merge("inputs" => inputs)))
+        update_state!("phase" => "model", "parts" => nil, "candidate" => nil, "output_data" => nil, "terminal_tool_name" => nil)
+        :steered
+      end
+    end
+
+    private
+      def control_tree(action, descendants, principal)
+        raise ArgumentError, "descendants must be :retain or :cascade" unless %i[retain cascade].include?(descendants)
+        @base_store.atomic(Background.root_conversation(@base_store, @record)) do
+          rows = [@base_store.load_turn(id)]
+          if descendants == :cascade
+            all = @base_store.list_turns(root_turn_id: root_turn_id)
+            loop do
+              ids = rows.map { |row| row.fetch("id") }
+              added = all.select { |row| ids.include?(row["parent_turn_id"]) && !ids.include?(row["id"]) }
+              break if added.empty?
+              rows.concat(added)
+            end
+          end
+          rows.each do |row|
+            Authorization.authorize!(action, principal: principal,
+              turn: row["id"] == id ? self : Background.load_turn(row.fetch("id"), store: @base_store), descendants: descendants)
+          end
+          rows.each do |row|
+            next if action != :steer && (Background::TERMINAL.include?(row["status"]) || row["status"] == "stale")
+            yield row
+          end
+        end
+      end
+  end
+end

data/lib/turnkit/version.rb

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

data/lib/turnkit.rb

@@ -45,6 +45,7 @@ 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_controls"
 require_relative "turnkit/turn"
 require_relative "turnkit/usage"
 require_relative "turnkit/run"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: turnkit
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Sam Couch
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-09-06 00:00:00.000000000 Z
+date: 2026-09-10 00:00:00.000000000 Z
 dependencies: []
 description: TurnKit is a Ruby/Rails agent runtime for durable AI conversations, application
   runs, orchestrator agents, tool calling, skills, sub-agents, context compaction,
@@ -82,6 +82,7 @@ files:
 - lib/turnkit/tool_execution.rb
 - lib/turnkit/tool_runner.rb
 - lib/turnkit/turn.rb
+- lib/turnkit/turn_controls.rb
 - lib/turnkit/usage.rb
 - lib/turnkit/version.rb
 - lib/turnkit/view_media_tool.rb