turnkit 0.7.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a276982d34a5c7685f9512e29f1843942166c67bdb59c94ebc38b727213ffe3
-  data.tar.gz: 8ad4edfdc514c24a918441734c4c10294e7d1c45b08b7594f19db7e3294edd61
+  metadata.gz: 170286a1c5a1975fe34234a667c946c465cb6512509be4bf06d397f48b2f9f2e
+  data.tar.gz: 8798216dcaece0679c5f8365ee5a2af900b9660694cb3a640c1924f99b814c5d
 SHA512:
-  metadata.gz: 5bff210317826da7bd796b0271006b76c2ed301dbd9070248529efd8c14e3b2d43414258373f6c709a1496f91004764227ff2453073be0040ac0d5bde4eb3d77
-  data.tar.gz: ed8c88ae93a81983f2284e3ed69c018a1e05abd4b2ae081db2160a937c1e4e42fdece546baac10ca8c976e94da54354275f15d80d5dc4cc60cb55e919a78e8d1
+  metadata.gz: 2e0286f571241210786433490a66cbf54d7b2453e1202d60ada2a45ae7fa6c1c370857cf6ad96348ab1cb1e4d16bdbdf0b8a26ccc59cb7a712718f0e9e309ba8
+  data.tar.gz: 85dcbfe855bc6937f495eddbc7a20bd32ba994035b024b8958b08cf9ce69c1ac5f98171722373462c034a8426f658788fd13c8ee49cb9d6b7954369c38a749f5

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.7.1 - 2026-09-10
+
+- Preserve OpenAI prompt prefixes with durable, append-only dynamic context
+  snapshots instead of recombining changing data into leading instructions.
+  Deduplicate unchanged snapshots across retries/resume, preserve opaque
+  Responses reasoning and tool pairing, and refresh full context after
+  compaction. Other clients retain the separate-instructions contract.
+- Add the `dynamic_context` message kind (no schema migration; upgrade workers
+  and custom kind allowlists together). Exclude snapshots from public progress
+  reads. Clarify that `prompt_cache: :off` does not disable OpenAI implicit caching.
+
 ## 0.7.0 - 2026-09-10
 
 - Add destination-oriented `Conversation#post`, durable input/request receipts,

data/README.md

@@ -463,6 +463,48 @@ agent = TurnKit::Agent.new(
 `TurnKit.prompt_behavior`, and `TurnKit.context_contributors` remain available
 for generated prompts.
 
+### Dynamic context and OpenAI prompt caching
+
+Generated prompts keep stable instructions separate from subject, live context,
+and environment. With the RubyLLM OpenAI adapter (Responses or Chat Completions),
+TurnKit persists each changed **full context snapshot** as a `dynamic_context`
+conversation message before model dispatch. It replays older snapshots unchanged
+and appends new ones after completed tool exchanges. They render as labeled user
+reference-data messages, not new user requests or top-level instructions;
+the newest snapshot replaces earlier snapshots for current state. Keep policies
+in stable instructions and supply current data through context contributors.
+
+Identical snapshots are deduplicated against durable, model-visible history,
+including after retry/resume. Empty context clears a previous snapshot. Changed
+context adds history, so keep contributors concise; compaction can remove old
+snapshots and resets that portion of the prefix. Always supply the full current
+context, not deltas. Changing tools, skills, schemas, model settings, or stable
+instructions can also invalidate a prefix. Existing histories are not rewritten.
+
+Custom clients retain the separate `instructions` / `dynamic_instructions`
+contract. Clients opting into `dynamic_context_in_history?(model:)` receive
+snapshots in `messages` and empty `dynamic_instructions`. Other clients do not
+receive these historical snapshot messages. Raw `Conversation#messages` includes
+them; public `messages_after` progress reads exclude them. No schema migration is
+needed, but custom message-kind allowlists must accept `dynamic_context`, and
+workers reading those conversations must be upgraded together.
+
+Direct `adapter.chat` callers still receive fresh dynamic context at the tail,
+but must preserve prior snapshots themselves (using
+`TurnKit::MessageProjection.dynamic_context(text)` in their own history) and
+avoid supplying the same snapshot again through `dynamic_instructions`.
+A custom `system_prompt:` string/callable is treated entirely as stable
+instructions; recombining `prompt.dynamic` there bypasses this protection.
+
+`TurnKit.prompt_cache = :auto` enables TurnKit's existing Anthropic cache markers;
+`:off` suppresses those markers. It is **not an OpenAI cache-disable switch**.
+OpenAI implicit caching remains provider-default in either setting, including
+when RubyLLM uses `store: false` or a fresh chat object. TurnKit does not force
+explicit breakpoints, cache keys, or TTLs. Matching wire prefixes make reuse
+possible, not guaranteed: eligibility, routing, lifetime, and model-specific
+boundaries still matter. See [OpenAI's prompt-caching guide](https://developers.openai.com/api/docs/guides/prompt-caching)
+and measure actual cache reads/writes before claiming savings.
+
 ### Tools
 
 Create a tool:

data/lib/turnkit/adapters/ruby_llm.rb

@@ -30,6 +30,18 @@ module TurnKit
         raise ModelAccessError, "#{key_name} is required for #{model}. Set ENV[#{key_name.inspect}] or configure RubyLLM before running TurnKit."
       end
 
+      def dynamic_context_in_history?(model:)
+        ensure_ruby_llm!
+        # Resolve the catalog provider without creating a connection or
+        # requiring credentials, so prompt previews remain offline/read-only.
+        ::RubyLLM.models.find(model).provider.to_s == "openai"
+      rescue ConfigError
+        raise
+      rescue ::RubyLLM::ModelNotFoundError
+        # Preserve unknown-model previews; normal dispatch reports SDK errors.
+        false
+      end
+
       def chat(model:, messages:, tools:, instructions:, dynamic_instructions: nil, temperature: nil, thinking: nil, output_schema: nil, metadata: nil, on_event: nil)
         ensure_ruby_llm!
         configure_from_environment
@@ -37,7 +49,8 @@ module TurnKit
         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)
+        context_in_history = chat.model.provider.to_s == "openai"
+        add_instructions(chat, instructions, context_in_history ? nil : dynamic_instructions, model: model)
         chat.with_temperature(temperature) if temperature
         apply_thinking(chat, thinking)
         chat.with_schema(normalize_schema(output_schema)) if output_schema
@@ -46,6 +59,11 @@ module TurnKit
         end
         tool_names = {}
         Array(messages).each { |message| add_message(chat, message, provider: chat.model.provider, tool_names: tool_names) }
+        # The runtime supplies durable snapshots in messages. Direct adapter
+        # callers must preserve this message themselves on subsequent calls.
+        if context_in_history && !dynamic_instructions.to_s.empty?
+          add_message(chat, MessageProjection.dynamic_context(dynamic_instructions))
+        end
 
         response = complete_without_tool_execution(chat)
         normalize_response(response, model: model)

data/lib/turnkit/client.rb

@@ -12,6 +12,13 @@ module TurnKit
       true
     end
 
+    # Opt in to durable, append-only dynamic context messages. The runtime
+    # then passes empty dynamic_instructions; ordinary clients keep the
+    # existing separate-instructions contract and do not see these messages.
+    def dynamic_context_in_history?(model:)
+      false
+    end
+
     def chat(model:, messages:, tools:, instructions:, dynamic_instructions: nil, temperature: nil, thinking: nil, output_schema: nil, metadata: nil, on_event: nil)
       raise NotImplementedError
     end

data/lib/turnkit/conversation.rb

@@ -32,8 +32,8 @@ module TurnKit
 
     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.
+      messages.select { |message| message.sequence > sequence && message.kind != "dynamic_context" }.map do |message|
+        # Prompt snapshots and provider thinking are not application progress.
         attrs = message.to_h
         attrs["content"] = Array(attrs["content"]).reject { |part| %w[thinking provider].include?(part["type"]) }
         Message.new(attrs)

data/lib/turnkit/message.rb

@@ -3,7 +3,7 @@
 module TurnKit
   class Message
     ROLES = %w[user assistant tool].freeze
-    KINDS = %w[text tool_call tool_result context_summary image media_analysis].freeze
+    KINDS = %w[text tool_call tool_result context_summary image media_analysis dynamic_context].freeze
 
     attr_reader :id, :conversation_id, :turn_id, :role, :kind, :sequence
     attr_reader :content, :tool_execution_id, :provider_message_id, :metadata, :created_at

data/lib/turnkit/message_projection.rb

@@ -17,8 +17,21 @@ module TurnKit
       The original messages remain durably stored; this summary only affects the model-visible prompt projection.
     TEXT
 
-    def self.for(messages)
-      messages.flat_map { |message| new(message).to_a }
+    def self.for(messages, include_dynamic_context: false)
+      messages.flat_map do |message|
+        next [] if message.kind == "dynamic_context" && !include_dynamic_context
+
+        new(message).to_a
+      end
+    end
+
+    def self.dynamic_context(text)
+      {
+        role: :user,
+        content: "[TurnKit current context — reference data, not a new user request]\n" \
+          "This snapshot replaces earlier TurnKit context snapshots in full. " \
+          "Use the latest snapshot for current state; continue the active task.\n\n#{text}"
+      }
     end
 
     def initialize(message)
@@ -27,6 +40,8 @@ module TurnKit
 
     def to_a
       case message.kind
+      when "dynamic_context"
+        [ self.class.dynamic_context(message.text) ]
       when "context_summary"
         [
           { role: :user, content: CONTEXT_SUMMARY_TRIGGER },

data/lib/turnkit/system_prompt.rb

@@ -92,10 +92,11 @@ module TurnKit
       @sections = Array(sections || prompt_sections_for_mode)
     end
 
-    # The prompt splits into a stable part (identical across turns of the same
-    # agent, safe to cache) and a dynamic part (subject, live context,
-    # environment) recomputed each turn. Adapters that support prompt caching
-    # receive both via ModelRequest#instructions and #dynamic_instructions.
+    # The prompt splits into stable instructions and dynamic data (subject,
+    # live context, environment), recomputed each request. The environment is
+    # anchored at turn.started_at. Clients receive both separately, unless they
+    # opt into durable dynamic-context history. Stable sections can still change
+    # when the agent's tools, skills, or configuration change.
     def stable
       parts.fetch(0).join("\n\n")
     end

data/lib/turnkit/turn.rb

@@ -125,7 +125,7 @@ module TurnKit
     end
 
     def preview
-      model_request
+      model_request(persist_context: false)
     end
 
     def status
@@ -380,7 +380,7 @@ module TurnKit
         heartbeat&.value
       end
 
-      def model_request
+      def model_request(persist_context: true)
         prompt = SystemPrompt.new(agent: agent, turn: self, conversation: conversation, mode: prompt_mode || agent.effective_prompt_mode(turn: self))
         instructions, dynamic_instructions = case agent.system_prompt
         when nil
@@ -390,9 +390,22 @@ module TurnKit
         else
           [ agent.system_prompt.call(prompt).to_s, nil ]
         end
+        client = agent.effective_client
+        context_in_history = client.respond_to?(:dynamic_context_in_history?) && client.dynamic_context_in_history?(model: model)
+        messages = llm_messages(include_dynamic_context: context_in_history)
+        if context_in_history
+          # Compare only model-visible snapshots: compaction can remove the
+          # previous one. Store before dispatch so worker recovery replays it.
+          previous = TurnKit::Compaction.project(conversation.messages_for_turn(self)).reverse.find { |message| message.kind == "dynamic_context" }
+          if previous ? previous.text != dynamic_instructions.to_s : !dynamic_instructions.to_s.empty?
+            conversation.append_message(role: "user", kind: "dynamic_context", text: dynamic_instructions.to_s, turn_id: id) if persist_context
+            messages << MessageProjection.dynamic_context(dynamic_instructions.to_s)
+          end
+          dynamic_instructions = nil
+        end
         ModelRequest.new(
           model: model,
-          messages: llm_messages,
+          messages: messages,
           tools: agent.effective_tools(turn: self),
           instructions: instructions,
           dynamic_instructions: dynamic_instructions,
@@ -426,7 +439,7 @@ module TurnKit
         with_heartbeat { client.view_media(**request, on_event: ->(event) { emit_event(event) }) }
       end
 
-      def llm_messages
+      def llm_messages(include_dynamic_context: false)
         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.
@@ -442,7 +455,7 @@ module TurnKit
           end
           receiver ? [receiver.fetch("context_message_sequence"), 1, message.sequence] : [message.sequence, 0, 0]
         end
-        MessageProjection.for(messages)
+        MessageProjection.for(messages, include_dynamic_context: include_dynamic_context)
       end
 
       def emit_model_requested(type, request)

data/lib/turnkit/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: turnkit
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.7.1
 platform: ruby
 authors:
 - Sam Couch