turnkit 0.4.0 → 0.4.2

data/lib/turnkit/tool.rb

@@ -25,6 +25,7 @@ module TurnKit
         name = name.to_s
         raise ArgumentError, "unknown parameter type: #{type}" unless TYPES.include?(type)
         raise ArgumentError, "invalid parameter name: #{name}" unless NAME_PATTERN.match?(name)
+        raise ArgumentError, "context is a reserved parameter name" if name == "context"
         raise ArgumentError, "duplicate parameter: #{name}" if parameters.any? { |param| param.fetch(:name) == name }
         raise ArgumentError, "enum values are required for enum parameter: #{name}" if type == :enum && Array(enum).empty?
 
@@ -113,23 +114,15 @@ module TurnKit
       end
 
       def call(arguments = {}, context:)
-        instance = begin
-          new
-        rescue ArgumentError => error
-          raise if error.message !~ /wrong number of arguments|missing keyword/
+        required = instance_method(:initialize).parameters.any? { |kind, _| %i[req keyreq].include?(kind) }
+        raise ToolError, "#{tool_name} requires constructor arguments; register an instance instead" if required
 
-          raise ToolError, "#{tool_name} requires constructor arguments; register an instance instead"
-        end
-        invoke(instance, arguments, context: context)
+        invoke(new, arguments, context: context)
       end
 
       def invoke(instance, arguments = {}, context:)
         keyword_arguments = symbolize(validate_arguments(arguments))
-        if accepts_turnkit_context?(instance)
-          instance.call(**keyword_arguments, turnkit_context: context)
-        else
-          instance.call(**keyword_arguments, context: context)
-        end
+        instance.call(**keyword_arguments, context: context)
       end
 
       private
@@ -172,10 +165,6 @@ module TurnKit
           SchemaCheck.validate!(value, schema_for(param), error_class: ToolValidationError, label: param.fetch(:name))
         end
 
-        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

data/lib/turnkit/turn.rb

@@ -43,7 +43,7 @@ module TurnKit
       @started_at = @record["started_at"]
       emit("turn.started", status: status, model: model)
       agent.effective_client.validate!(model: model)
-      @budget = Budget.resume(store: store, root_turn_id: root_turn_id, limits: budget_limits)
+      @budget = Budget.resume(store: store, root_turn_id: root_turn_id, limits: agent.budget_limits)
       revisions_used = 0
       loop do
         budget.check!(depth: depth)
@@ -113,7 +113,15 @@ module TurnKit
     end
 
     def policy_audit
-      (@record["options"] || {})["policy_audit"]
+      options = @record["options"] || {}
+      options.dig("state", "policy_audit") || options["policy_audit"]
+    end
+
+    # Reads iterations from options["state"], falling back to the legacy
+    # top-level key for turns persisted before the state split.
+    def self.iterations_for(record)
+      options = record["options"] || {}
+      (options.dig("state", "iterations") || options["iterations"]).to_i
     end
 
     def usage
@@ -168,23 +176,13 @@ module TurnKit
     end
 
     def paint(prompt, model:, provider: nil, size: nil, assume_model_exists: nil, input_images: nil, mask: nil, params: {}, metadata: {}, client: nil)
-      claimed_standalone = false
-      case status
-      when "pending"
-        claimed = store.claim_turn(id, from: "pending", to: "running", started_at: Clock.now, heartbeat_at: Clock.now)
-        raise Error, "turn is already running" unless claimed
-
+      claimed = claim_standalone!("paint")
+      if claimed
         @record = claimed
         @started_at = @record["started_at"]
-        @budget = Budget.resume(store: store, root_turn_id: root_turn_id, limits: budget_limits)
-        claimed_standalone = true
         emit("turn.started", status: status, model: model)
-      when "running"
-        # Image tools call this while their parent turn is running.
-      else
-        raise Error, "cannot paint for #{status} turn"
+        @budget = Budget.resume(store: store, root_turn_id: root_turn_id, limits: agent.budget_limits)
       end
-
       image_client = client || agent.effective_client
       request = {
         prompt: prompt,
@@ -201,41 +199,75 @@ module TurnKit
       image_client.validate!(model: model)
       emit("image.requested", request.except(:input_images, :mask))
       result = call_image_client(image_client, request)
-      result_cost = Cost.from_usage(result.usage, model: result.model || model)
-      add_usage!(result.usage, cost: result_cost)
-      budget.add_cost!(result_cost.total)
+      result_cost = apply_result_cost(result, model: model)
       image = result.images.first
       raise Error, "image client returned no image" unless image
       raise Error, "image client returned image without url or data" if image.url.to_s.empty? && image.data.to_s.empty?
 
       persist_image_message(image)
       emit("image.completed", image: image.to_h, model: image.model || model, provider: image.provider || provider&.to_s, mime_type: image.mime_type, usage: result.usage.to_h, cost: result_cost.to_h, metadata: metadata || {})
-      complete_with_output(image.url.to_s, output_data: { "type" => "image", "images" => [ image.to_h ] }, audit: check_policy(image.url.to_s, output_data: { "type" => "image", "images" => [ image.to_h ] })) if claimed_standalone
+      complete_with_output(image.url.to_s, output_data: { "type" => "image", "images" => [ image.to_h ] }, audit: check_policy(image.url.to_s, output_data: { "type" => "image", "images" => [ image.to_h ] })) if claimed
       image
     rescue StandardError => error
-      if claimed_standalone
-        update!(status: "failed", error: { "class" => error.class.name, "message" => error.message }, completed_at: Clock.now)
-        emit("turn.failed", error: { "class" => error.class.name, "message" => error.message })
+      fail_standalone!(error) if claimed
+      raise
+    end
+
+    def view_media(media, objective:, model:, provider: nil, output_schema: nil, params: {}, metadata: {}, client: nil)
+      claimed = claim_standalone!("view media")
+      if claimed
+        @record = claimed
+        @started_at = @record["started_at"]
+        emit("turn.started", status: status, model: model)
+        @budget = Budget.resume(store: store, root_turn_id: root_turn_id, limits: agent.budget_limits)
       end
+      media_input = MediaInput.wrap(media)
+      media_client = client || agent.effective_client
+      request = {
+        media: media_input,
+        objective: objective,
+        model: model,
+        provider: provider,
+        output_schema: output_schema,
+        params: params || {},
+        metadata: { turn_id: id, conversation_id: conversation.id }.merge(metadata || {})
+      }
+
+      media_client.validate!(model: model)
+      emit("media.requested", request.except(:media).merge(media: media_input.to_h))
+      result = call_media_client(media_client, request)
+      result_cost = apply_result_cost(result, model: model)
+      analysis = result.media_analyses.first
+      raise Error, "media client returned no media analysis" unless analysis
+
+      persist_media_analysis_message(analysis)
+      output_data = { "type" => "media_analysis", "media_analyses" => [ analysis.to_h ] }
+      emit("media.completed", analysis: analysis.to_h, model: analysis.model || model, provider: analysis.provider || provider&.to_s, media: media_input.to_h, usage: result.usage.to_h, cost: result_cost.to_h, metadata: metadata || {})
+      complete_with_output(analysis.text, output_data: output_data, audit: check_policy(analysis.text, output_data: output_data)) if claimed
+      analysis
+    rescue StandardError => error
+      emit("media.failed", error: { "class" => error.class.name, "message" => error.message }, metadata: metadata || {}) if status == "running" || claimed
+      fail_standalone!(error) if claimed
       raise
     end
 
     private
       def model_request
         prompt = SystemPrompt.new(agent: agent, turn: self, conversation: conversation, mode: prompt_mode || agent.effective_prompt_mode(turn: self))
-        instructions = case agent.system_prompt
+        instructions, dynamic_instructions = case agent.system_prompt
         when nil
-          prompt.to_s
+          [ prompt.stable, prompt.dynamic ]
         when String
-          agent.system_prompt
+          [ agent.system_prompt, nil ]
         else
-          agent.system_prompt.call(prompt).to_s
+          [ agent.system_prompt.call(prompt).to_s, nil ]
         end
         ModelRequest.new(
           model: model,
           messages: llm_messages,
           tools: agent.effective_tools,
           instructions: instructions,
+          dynamic_instructions: dynamic_instructions,
           thinking: thinking,
           output_schema: output_schema,
           metadata: { turn_id: id, conversation_id: conversation.id },
@@ -243,38 +275,27 @@ module TurnKit
         )
       end
 
+      # Clients implement the TurnKit::Client keyword contract. See client.rb.
       def call_client(request, client: agent.effective_client)
-        kwargs = {
+        client.chat(
           model: request.model,
           messages: request.messages,
           tools: request.tools,
           instructions: request.instructions,
+          dynamic_instructions: request.dynamic_instructions,
           thinking: request.thinking,
           output_schema: request.output_schema,
           metadata: request.metadata,
           on_event: ->(event) { emit_event(event) }
-        }
-        accepted = chat_keyword_names(client)
-        kwargs = kwargs.slice(*accepted) unless accepted.include?(:keyrest)
-        client.chat(**kwargs)
-      end
-
-      def chat_keyword_names(client)
-        client.method(:chat).parameters.filter_map do |kind, name|
-          return [ :keyrest ] if kind == :keyrest
-
-          name if %i[key keyreq].include?(kind)
-        end
+        )
       end
 
       def call_image_client(client, request)
-        kwargs = request.merge(on_event: ->(event) { emit_event(event) })
-        accepted = client.method(:paint).parameters.filter_map do |kind, name|
-          return client.paint(**kwargs) if kind == :keyrest
+        client.paint(**request, on_event: ->(event) { emit_event(event) })
+      end
 
-          name if %i[key keyreq].include?(kind)
-        end
-        client.paint(**kwargs.slice(*accepted))
+      def call_media_client(client, request)
+        client.view_media(**request, on_event: ->(event) { emit_event(event) })
       end
 
       def llm_messages
@@ -337,6 +358,9 @@ module TurnKit
         elsif result.image?
           message = conversation.append_message(role: "assistant", kind: "image", content: result.images.map { |image| image.to_h.merge("type" => "image") }, turn_id: id, metadata: { "output_data" => result.output_data }.compact)
           emit("message.created", message_id: message.id, role: message.role, kind: message.kind)
+        elsif result.media_analysis?
+          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)
           emit("message.created", message_id: message.id, role: message.role, kind: message.kind)
@@ -348,6 +372,11 @@ module TurnKit
         emit("message.created", message_id: message.id, role: message.role, kind: message.kind)
       end
 
+      def persist_media_analysis_message(analysis)
+        message = conversation.append_message(role: "assistant", kind: "media_analysis", content: [ analysis.to_h.merge("type" => "media_analysis") ], turn_id: id, metadata: { "output_data" => { "type" => "media_analysis", "media_analyses" => [ analysis.to_h ] } })
+        emit("message.created", message_id: message.id, role: message.role, kind: message.kind)
+      end
+
       def append_terminal_completion(runner, execution)
         message = runner.completion_message(execution)
         assistant = conversation.append_message(role: "assistant", kind: "text", text: message, turn_id: id)
@@ -382,8 +411,7 @@ module TurnKit
       end
 
       def persist_policy_audit(audit)
-        options = (@record["options"] || {}).merge("policy_audit" => audit.to_h)
-        update!(options: options)
+        update_state!("policy_audit" => audit.to_h)
         emit("output_policy.completed", clean: audit.clean?, violation_count: audit.violations.length)
       end
 
@@ -435,23 +463,50 @@ module TurnKit
 
       def count_iteration!
         budget.count_iteration!
-        options = (@record["options"] || {}).merge("iterations" => (@record.dig("options", "iterations").to_i + 1))
-        update!(options: options)
+        update_state!("iterations" => Turn.iterations_for(@record) + 1)
+      end
+
+      # Runtime state lives under options["state"]; the rest of options is
+      # 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"] || {}
+        update!(options: options.merge("state" => (options["state"] || {}).merge(changes)))
       end
 
       def heartbeat!
         update!(heartbeat_at: Clock.now)
       end
 
-      def budget_limits
-        {
-          max_iterations: agent.max_iterations || TurnKit.max_iterations,
-          timeout: agent.timeout || TurnKit.timeout,
-          max_depth: agent.max_depth || TurnKit.max_depth,
-          max_tool_executions: agent.max_tool_executions || TurnKit.max_tool_executions,
-          max_tool_executions_by_name: agent.max_tool_executions_by_name || TurnKit.max_tool_executions_by_name,
-          max_spend: agent.max_spend || TurnKit.max_spend
-        }
+      # Claims a pending turn for a standalone media call. Returns the claimed
+      # record when this call owns turn completion, nil when running inside a parent
+      # turn (media tools call paint/view_media while their turn is running).
+      # Callers perform any post-claim setup after assignment, so later errors
+      # still fail the claimed turn.
+      def claim_standalone!(action)
+        case status
+        when "pending"
+          claimed = store.claim_turn(id, from: "pending", to: "running", started_at: Clock.now, heartbeat_at: Clock.now)
+          raise Error, "turn is already running" unless claimed
+
+          claimed
+        when "running"
+          nil
+        else
+          raise Error, "cannot #{action} for #{status} turn"
+        end
+      end
+
+      def fail_standalone!(error)
+        update!(status: "failed", error: { "class" => error.class.name, "message" => error.message }, completed_at: Clock.now)
+        emit("turn.failed", error: { "class" => error.class.name, "message" => error.message })
+      end
+
+      def apply_result_cost(result, model:)
+        cost = Cost.from_usage(result.usage, model: result.model || model)
+        add_usage!(result.usage, cost: cost)
+        budget.add_cost!(cost.total)
+        cost
       end
 
       def aggregate_cost(current, cost)

data/lib/turnkit/version.rb

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

data/lib/turnkit/view_media_tool.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module TurnKit
+  class ViewMediaTool < Tool
+    class << self
+      %i[model provider output_schema params].each do |name|
+        define_method(name) do |value = nil|
+          instance_variable_set("@#{name}", value) unless value.nil?
+          instance_variable_get("@#{name}")
+        end
+      end
+    end
+
+    def call(context:, **arguments)
+      context.turn.view_media(
+        media(**arguments),
+        objective: objective(**arguments),
+        model: self.class.model,
+        provider: self.class.provider,
+        output_schema: self.class.output_schema,
+        params: self.class.params || {},
+        metadata: metadata(**arguments)
+      ).to_h
+    end
+
+    def metadata(**)
+      {}
+    end
+  end
+end

data/lib/turnkit.rb

@@ -17,25 +17,26 @@ require_relative "turnkit/event"
 require_relative "turnkit/model_request"
 require_relative "turnkit/schema_check"
 require_relative "turnkit/agent"
-require_relative "turnkit/workflow"
 require_relative "turnkit/client"
 require_relative "turnkit/conversation"
 require_relative "turnkit/message"
 require_relative "turnkit/record"
 require_relative "turnkit/image_result"
+require_relative "turnkit/media_input"
+require_relative "turnkit/media_analysis_result"
 require_relative "turnkit/result"
 require_relative "turnkit/skill"
 require_relative "turnkit/output_audit"
 require_relative "turnkit/output_policy"
 require_relative "turnkit/prompt_data"
 require_relative "turnkit/prompt_context"
-require_relative "turnkit/prompt_contribution"
 require_relative "turnkit/system_prompt"
 require_relative "turnkit/store"
 require_relative "turnkit/memory_store"
 require_relative "turnkit/compaction"
 require_relative "turnkit/tool"
 require_relative "turnkit/image_tool"
+require_relative "turnkit/view_media_tool"
 require_relative "turnkit/tool_call"
 require_relative "turnkit/tool_execution"
 require_relative "turnkit/sub_agent_tool"
@@ -47,9 +48,7 @@ require_relative "turnkit/usage"
 require_relative "turnkit/run"
 require_relative "turnkit/adapters/codex"
 require_relative "turnkit/adapters/ruby_llm"
-require_relative "turnkit/stores/active_record_store"
-
-require_relative "turnkit/rails/railtie" if defined?(Rails)
+require_relative "turnkit/active_record_store"
 
 module TurnKit
   class << self
@@ -62,10 +61,7 @@ module TurnKit
     attr_accessor :cost_rates, :cost_calculator
     attr_accessor :prompt_sections, :prompt_behavior, :available_skills
     attr_accessor :prompt_data_max_chars, :context_contributors
-    attr_accessor :system_prompt_contributors, :model_prompt_contributors
     attr_accessor :on_event
-    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"
@@ -84,8 +80,6 @@ module TurnKit
   self.prompt_data_max_chars = 20_000
   self.available_skills = []
   self.context_contributors = []
-  self.system_prompt_contributors = []
-  self.model_prompt_contributors = {}
   self.on_event = nil
   self.output_policy_model = nil
   self.output_policy_thinking = { effort: :low }
@@ -94,14 +88,6 @@ module TurnKit
     yield self
   end
 
-  def self.model
-    default_model
-  end
-
-  def self.model=(value)
-    self.default_model = value
-  end
-
   def self.reconcile_stale!(before: Clock.now - (timeout || 300))
     store.find_stale_turns(before: before).each do |turn|
       store.update_turn(turn.fetch("id"), "status" => "stale", "completed_at" => Clock.now)
@@ -116,4 +102,9 @@ module TurnKit
     image_client = client || self.client
     image_client.paint(prompt: prompt, model: model, provider: provider, size: size, assume_model_exists: assume_model_exists, input_images: input_images, mask: mask, params: params, metadata: metadata).images.first
   end
+
+  def self.view_media(media, objective:, model:, provider: nil, output_schema: nil, params: {}, metadata: {}, client: nil)
+    media_client = client || self.client
+    media_client.view_media(media: media, objective: objective, model: model, provider: provider, output_schema: output_schema, params: params, metadata: metadata).media_analyses.first
+  end
 end

metadata

@@ -1,31 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: turnkit
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.2
 platform: ruby
 authors:
 - Sam Couch
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-19 00:00:00.000000000 Z
-dependencies:
-- !ruby/object:Gem::Dependency
-  name: ruby_llm
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.14'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.14'
+date: 2026-07-02 00:00:00.000000000 Z
+dependencies: []
 description: TurnKit is a Ruby/Rails agent runtime for durable AI conversations, application
-  runs, reusable workflows, tool calling, skills, sub-agents, context compaction,
+  runs, orchestrator agents, tool calling, skills, sub-agents, context compaction,
   and persistence.
 email:
 - sam@samcouch.com
@@ -37,7 +23,16 @@ files:
 - LICENSE.md
 - README.md
 - UPGRADE.md
+- UPGRADE_TO_0_4_2.md
+- lib/generators/turnkit/install/templates/conversation.rb
+- lib/generators/turnkit/install/templates/create_turnkit_tables.rb
+- lib/generators/turnkit/install/templates/initializer.rb
+- lib/generators/turnkit/install/templates/message.rb
+- lib/generators/turnkit/install/templates/tool_execution.rb
+- lib/generators/turnkit/install/templates/turn.rb
+- lib/generators/turnkit/install_generator.rb
 - lib/turnkit.rb
+- lib/turnkit/active_record_store.rb
 - lib/turnkit/adapters/codex.rb
 - lib/turnkit/adapters/ruby_llm.rb
 - lib/turnkit/agent.rb
@@ -49,17 +44,12 @@ files:
 - lib/turnkit/cost.rb
 - lib/turnkit/error.rb
 - lib/turnkit/event.rb
-- lib/turnkit/generators/turnkit/install/templates/conversation.rb
-- lib/turnkit/generators/turnkit/install/templates/create_turnkit_tables.rb
-- lib/turnkit/generators/turnkit/install/templates/initializer.rb
-- lib/turnkit/generators/turnkit/install/templates/message.rb
-- lib/turnkit/generators/turnkit/install/templates/tool_execution.rb
-- lib/turnkit/generators/turnkit/install/templates/turn.rb
-- lib/turnkit/generators/turnkit/install_generator.rb
 - lib/turnkit/id.rb
 - lib/turnkit/image_result.rb
 - lib/turnkit/image_tool.rb
 - lib/turnkit/load_skill_tool.rb
+- lib/turnkit/media_analysis_result.rb
+- lib/turnkit/media_input.rb
 - lib/turnkit/memory_store.rb
 - lib/turnkit/message.rb
 - lib/turnkit/message_projection.rb
@@ -67,16 +57,13 @@ files:
 - lib/turnkit/output_audit.rb
 - lib/turnkit/output_policy.rb
 - lib/turnkit/prompt_context.rb
-- lib/turnkit/prompt_contribution.rb
 - lib/turnkit/prompt_data.rb
-- lib/turnkit/rails/railtie.rb
 - lib/turnkit/record.rb
 - lib/turnkit/result.rb
 - lib/turnkit/run.rb
 - lib/turnkit/schema_check.rb
 - lib/turnkit/skill.rb
 - lib/turnkit/store.rb
-- lib/turnkit/stores/active_record_store.rb
 - lib/turnkit/sub_agent_tool.rb
 - lib/turnkit/system_prompt.rb
 - lib/turnkit/tool.rb
@@ -86,7 +73,7 @@ files:
 - lib/turnkit/turn.rb
 - lib/turnkit/usage.rb
 - lib/turnkit/version.rb
-- lib/turnkit/workflow.rb
+- lib/turnkit/view_media_tool.rb
 homepage: https://github.com/samuelcouch/turnkit
 licenses:
 - MIT
@@ -114,5 +101,6 @@ requirements: []
 rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
-summary: Ruby/Rails agent runtime for durable AI conversations, runs, and workflows.
+summary: Ruby/Rails agent runtime for durable AI conversations, runs, and orchestrator
+  agents.
 test_files: []

data/lib/turnkit/prompt_contribution.rb

@@ -1,13 +0,0 @@
-# frozen_string_literal: true
-
-module TurnKit
-  class PromptContribution
-    attr_accessor :stable_prefix, :dynamic_suffix, :section_overrides
-
-    def initialize(stable_prefix: nil, dynamic_suffix: nil, section_overrides: nil)
-      @stable_prefix = stable_prefix.to_s
-      @dynamic_suffix = dynamic_suffix.to_s
-      @section_overrides = (section_overrides || {}).transform_keys(&:to_sym)
-    end
-  end
-end

data/lib/turnkit/rails/railtie.rb

@@ -1,9 +0,0 @@
-# frozen_string_literal: true
-
-module TurnKit
-  class Railtie < Rails::Railtie
-    generators do
-      require_relative "../generators/turnkit/install_generator"
-    end
-  end
-end

data/lib/turnkit/workflow.rb

@@ -1,58 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "agent"
-
-module TurnKit
-  class Workflow
-    ORCHESTRATOR_PREAMBLE = <<~TEXT.strip
-      You are an autonomous task orchestrator. Navigate from the application
-      request to a final output without asking the user follow-up questions.
-
-      Use the available tools to gather context, inspect sources, take actions,
-      persist outputs, and verify work. Use loaded skills as reusable workflow
-      patterns. Iterate when work needs missing context, critique, revision, or
-      verification.
-
-      When multiple independent items need the same kind of fetch or read, and
-      an available batch tool can handle them in one call, prefer the batch tool
-      over repeated one-item tool calls.
-
-      Stop when the task is complete, when the available context and tools are
-      sufficient for the best possible answer, or when further iteration would
-      not materially improve the result. Respect runtime, cost, and iteration
-      limits.
-    TEXT
-
-    DEFAULT_INSTRUCTIONS = ORCHESTRATOR_PREAMBLE
-
-    attr_reader :name, :options
-
-    def initialize(name: "workflow", instructions: nil, preamble: true, **options)
-      @name = name.to_s
-      raise ArgumentError, "name is required" if @name.empty?
-
-      @options = options.merge(
-        name: @name,
-        prompt_mode: options.fetch(:prompt_mode, :task),
-        instructions: compose_instructions(instructions, preamble: preamble)
-      ).freeze
-      @agent = Agent.new(**@options)
-    end
-
-    def run(prompt = nil, task: nil, input: nil, async: false, subject: nil, metadata: {}, **overrides)
-      agent(**overrides).run(task || prompt, input: input, async: async, subject: subject, metadata: metadata)
-    end
-
-    def agent(**overrides)
-      overrides.empty? ? @agent : Agent.new(**@options.merge(overrides.compact))
-    end
-
-    private
-      def compose_instructions(instructions, preamble:)
-        parts = []
-        parts << ORCHESTRATOR_PREAMBLE if preamble
-        parts << instructions.to_s.strip unless instructions.to_s.strip.empty?
-        parts.join("\n\n")
-      end
-  end
-end