turnkit 0.5.0 → 0.7.0

data/lib/turnkit/memory_store.rb

@@ -1,16 +1,41 @@
 # frozen_string_literal: true
 
+require "monitor"
+
 module TurnKit
   class MemoryStore < Store
     def initialize
-      @mutex = Mutex.new
+      @mutex = Monitor.new
       @conversations = {}
       @turns = {}
       @messages = {}
       @tool_executions = {}
+      @deliveries = {}
+      @delivery_keys = {}
+      @waits = {}
       @message_sequences = Hash.new(0)
+      @transaction_depth = 0
     end
 
+    def atomic(_conversation_id)
+      @mutex.synchronize do
+        snapshot = Marshal.dump([@conversations, @turns, @messages, @tool_executions, @deliveries, @delivery_keys, @waits, @message_sequences]) if @transaction_depth.zero?
+        @transaction_depth += 1
+        committed = false
+        begin
+          result = yield
+          committed = true
+          result
+        ensure
+          @transaction_depth -= 1
+          if snapshot && !committed
+            @conversations, @turns, @messages, @tool_executions, @deliveries, @delivery_keys, @waits, @message_sequences = Marshal.load(snapshot)
+          end
+        end
+      end
+    end
+    def atomic_graph(&block) = atomic(nil, &block)
+
     def create_conversation(attributes)
       record = Record.conversation(attributes)
 
@@ -33,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)
@@ -89,6 +116,86 @@ module TurnKit
       end
     end
 
+    def list_submitted_turns(limit: nil)
+      @mutex.synchronize do
+        rows = @turns.values.select { |turn| turn["submitted_at"] }.sort_by { |turn| [ turn["created_at"].to_f, turn["id"] ] }
+        rows = rows.first(limit) if limit
+        rows.map { |turn| duplicate(turn) }
+      end
+    end
+
+    def list_actionable_turns(limit:)
+      @mutex.synchronize do
+        @turns.values.select { |turn| turn["submitted_at"] && %w[pending waiting running].include?(turn["status"]) }
+          .sort_by { |turn| [ turn["updated_at"].to_f, turn["id"] ] }.first(limit).map { |turn| duplicate(turn) }
+      end
+    end
+
+    def list_stale_inline_turns(before:, limit:)
+      @mutex.synchronize do
+        @turns.values.select { |row| !row["submitted_at"] && %w[pending running].include?(row["status"]) &&
+          (row["heartbeat_at"] || row["started_at"] || row["created_at"]) < before }
+          .sort_by { |row| [row["updated_at"].to_f, row["id"]] }.first(limit).map { |row| duplicate(row) }
+      end
+    end
+
+    def create_delivery(attributes)
+      record = Record.delivery(attributes)
+      @mutex.synchronize do
+        existing_id = @delivery_keys[record.fetch("key")]
+        if existing_id
+          existing = @deliveries.fetch(existing_id)
+          Record.assert_delivery_retry!(existing, record)
+          return duplicate(existing)
+        end
+
+        @deliveries[record.fetch("id")] = record
+        @delivery_keys[record.fetch("key")] = record.fetch("id")
+        duplicate(record)
+      end
+    end
+
+    def load_delivery(id)
+      @mutex.synchronize { duplicate(@deliveries.fetch(id)) }
+    end
+
+    def update_delivery(id, attributes)
+      attrs = Record.delivery_update(attributes)
+      @mutex.synchronize do
+        @deliveries.fetch(id).merge!(attrs)
+        duplicate(@deliveries.fetch(id))
+      end
+    end
+
+    def list_deliveries(source_conversation_id: nil, destination_conversation_id: nil, pending: false, limit: nil)
+      @mutex.synchronize do
+        rows = @deliveries.values
+        rows = rows.select { |row| row["source_conversation_id"] == source_conversation_id } if source_conversation_id
+        rows = rows.select { |row| row["destination_conversation_id"] == destination_conversation_id } if destination_conversation_id
+        rows = rows.select { |row| row["delivered_at"].nil? } if pending
+        rows = rows.sort_by { |row| [ row["created_at"].to_f, row["id"] ] }
+        rows = rows.first(limit) if limit
+        rows.map { |row| duplicate(row) }
+      end
+    end
+
+    def create_wait(turn_id:, target_turn_id:)
+      @mutex.synchronize do
+        wait = { "turn_id" => turn_id, "target_turn_id" => target_turn_id }
+        @waits[[ turn_id, target_turn_id ]] ||= wait
+        duplicate(@waits.fetch([ turn_id, target_turn_id ]))
+      end
+    end
+
+    def list_waits(turn_id: nil, target_turn_id: nil)
+      @mutex.synchronize do
+        rows = @waits.values
+        rows = rows.select { |row| row["turn_id"] == turn_id } if turn_id
+        rows = rows.select { |row| row["target_turn_id"] == target_turn_id } if target_turn_id
+        rows.map { |row| duplicate(row) }
+      end
+    end
+
     def create_tool_execution(attributes)
       record = Record.tool_execution(attributes)
 
@@ -120,17 +227,6 @@ module TurnKit
       end
     end
 
-    def reconcile_stale_turns(before:)
-      @mutex.synchronize do
-        @turns.values.filter_map do |turn|
-          next unless %w[pending running].include?(turn["status"]) && stale_anchor(turn) && stale_anchor(turn) < before
-
-          turn.merge!("status" => "stale", "completed_at" => Clock.now, "updated_at" => Clock.now)
-          duplicate(turn)
-        end
-      end
-    end
-
     private
       def stringify(hash)
         hash.transform_keys(&:to_s)
@@ -140,8 +236,5 @@ module TurnKit
         Marshal.load(Marshal.dump(value))
       end
 
-      def stale_anchor(turn)
-        turn["heartbeat_at"] || turn["started_at"] || turn["created_at"]
-      end
   end
 end

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/reconciliation.rb

@@ -4,8 +4,8 @@ module TurnKit
   # Reconciles turns abandoned by a dead worker: atomically marks them stale,
   # marks their unfinished tool executions interrupted, and appends synthetic
   # error tool results so the persisted transcript stays structurally complete
-  # for continuation. TurnKit never reruns an interrupted tool; the synthetic
-  # result tells the continued model the outcome is unknown.
+  # for continuation. Unknown effects are not replayed; Background separately
+  # retries tools whose integrations explicitly declare replay safety.
   module Reconciliation
     INTERRUPTED_MESSAGE = "Tool execution was interrupted before a result was recorded. " \
       "It is unknown whether the operation ran; do not assume it did or did not."
@@ -13,15 +13,17 @@ module TurnKit
     module_function
 
     def reconcile!(before:)
-      TurnKit.store.reconcile_stale_turns(before: before).each do |turn|
+      reconciled = TurnKit.store.reconcile_stale_turns(before: before)
+      reconciled.each do |turn|
         emit("turn.stale", turn)
         executions = interrupt_tool_executions(turn)
         repair_transcript(turn, executions)
       end
+      Background.reconcile(before: before) if TurnKit.store.list_actionable_turns(limit: 1).any?
+      reconciled
     end
 
-    def interrupt_tool_executions(turn)
-      store = TurnKit.store
+    def interrupt_tool_executions(turn, store: TurnKit.store)
       store.list_tool_executions(turn_id: turn.fetch("id")).map do |execution|
         next execution unless %w[pending running].include?(execution.fetch("status"))
 
@@ -39,11 +41,10 @@ module TurnKit
       end
     end
 
-    def repair_transcript(turn, executions)
-      store = TurnKit.store
+    def repair_transcript(turn, executions, store: TurnKit.store)
       messages = store.list_messages(turn.fetch("conversation_id"))
       resolved = messages
-        .select { |message| message["kind"] == "tool_result" }
+        .select { |message| message["turn_id"] == turn.fetch("id") && message["kind"] == "tool_result" }
         .flat_map { |message| message["content"].map { |part| part["tool_call_id"] } }
 
       messages
@@ -52,14 +53,16 @@ module TurnKit
         .reject { |part| resolved.include?(part["id"]) }
         .each do |part|
           execution = executions.find { |candidate| candidate["tool_call_id"] == part["id"] }
+          known = execution && %w[completed failed cancelled].include?(execution["status"])
+          payload = known ? execution["result"] || execution["error"] : { "error" => true, "message" => INTERRUPTED_MESSAGE }
           message = store.append_message(
             "conversation_id" => turn.fetch("conversation_id"),
             "turn_id" => turn.fetch("id"),
             "role" => "tool",
             "kind" => "tool_result",
-            "content" => [ { "type" => "tool_result", "tool_call_id" => part["id"], "text" => { "error" => true, "message" => INTERRUPTED_MESSAGE }.to_json, "error" => true } ],
+            "content" => [ { "type" => "tool_result", "tool_call_id" => part["id"], "text" => payload.to_json, "error" => !known || execution["status"] == "failed" } ],
             "tool_execution_id" => execution&.fetch("id"),
-            "metadata" => { "tool_name" => part["name"], "interrupted" => true }
+            "metadata" => { "tool_name" => part["name"], "interrupted" => !known }
           )
           emit("message.created", turn, message_id: message.fetch("id"), role: "tool", kind: "tool_result")
         end

data/lib/turnkit/record.rb

@@ -2,10 +2,11 @@
 
 module TurnKit
   module Record
-    TURN_STATUSES = %w[pending 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 started_at heartbeat_at completed_at].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
+    DELIVERY_UPDATE_KEYS = %w[message_id delivered_at].freeze
     TOOL_EXECUTION_UPDATE_KEYS = %w[status result error started_at completed_at].freeze
 
     module_function
@@ -13,11 +14,12 @@ module TurnKit
     def conversation(attributes)
       attrs = stringify(attributes)
       now = Clock.now
+      subject_type, subject_id = subject_pair(attrs["subject"])
       {
         "id" => attrs["id"] || Id.generate(:conversation),
         "agent_name" => attrs["agent_name"],
         "model" => attrs["model"],
-        "subject" => attrs["subject"],
+        "subject" => attrs["subject"] && { "type" => subject_type, "id" => subject_id }.compact,
         "metadata" => attrs["metadata"] || {},
         "created_at" => attrs["created_at"] || now,
         "updated_at" => attrs["updated_at"] || now
@@ -50,6 +52,8 @@ module TurnKit
         "error" => attrs["error"],
         "output_text" => attrs["output_text"],
         "output_data" => attrs["output_data"],
+        "submitted_at" => attrs["submitted_at"],
+        "claim_token" => attrs["claim_token"],
         "started_at" => attrs["started_at"],
         "heartbeat_at" => attrs["heartbeat_at"],
         "completed_at" => attrs["completed_at"],
@@ -58,6 +62,35 @@ module TurnKit
       }
     end
 
+    def delivery(attributes)
+      attrs = stringify(attributes)
+      {
+        "id" => attrs["id"] || Id.generate(:delivery),
+        "source_conversation_id" => attrs.fetch("source_conversation_id"),
+        "destination_conversation_id" => attrs.fetch("destination_conversation_id"),
+        "source_turn_id" => attrs["source_turn_id"],
+        "key" => attrs.fetch("key"),
+        "payload" => JSON.parse(JSON.generate(attrs["payload"] || {})),
+        "message_id" => attrs["message_id"],
+        "delivered_at" => attrs["delivered_at"],
+        "created_at" => attrs["created_at"] || Clock.now
+      }
+    end
+
+    def assert_delivery_retry!(existing, requested)
+      keys = %w[source_conversation_id destination_conversation_id source_turn_id payload]
+      unless existing.slice(*keys) == requested.slice(*keys)
+        raise ToolError, "delivery key is already used for a different message"
+      end
+    end
+
+    def delivery_update(attributes)
+      attrs = stringify(attributes)
+      unknown = attrs.keys - DELIVERY_UPDATE_KEYS
+      raise ArgumentError, "unknown delivery update attributes: #{unknown.join(", ")}" if unknown.any?
+      attrs
+    end
+
     def tool_execution(attributes)
       attrs = stringify(attributes)
       status = attrs["status"] || "pending"

data/lib/turnkit/run.rb

@@ -37,6 +37,34 @@ module TurnKit
       self
     end
 
+    def perform_later(callback: nil)
+      turn.perform_later(callback: callback)
+      self
+    end
+
+    def wait_for(*targets)
+      turn.wait_for(*targets)
+      self
+    end
+
+    def cancel!(descendants: :retain, principal: nil)
+      turn.cancel!(descendants: descendants, principal: principal)
+      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/skill.rb

@@ -4,23 +4,24 @@ require "yaml"
 
 module TurnKit
   class Skill
-    attr_reader :key, :name, :description, :content
+    attr_reader :key, :name, :description, :content, :tools
 
-    def self.from_file(path, key: nil, name: nil, description: "")
+    def self.from_file(path, key: nil, name: nil, description: "", tools: [])
       content, metadata = parse_file(File.read(path))
       base = File.basename(path, File.extname(path))
-      new(key: key || base, name: name || metadata["name"] || base.tr("_-", " ").split.map(&:capitalize).join(" "), description: description.to_s.empty? ? metadata["description"].to_s : description, content: content)
+      new(key: key || base, name: name || metadata["name"] || base.tr("_-", " ").split.map(&:capitalize).join(" "), description: description.to_s.empty? ? metadata["description"].to_s : description, content: content, tools: tools)
     end
 
     def self.from_directory(path, pattern: "*.md")
       Dir.glob(File.join(path, pattern)).sort.map { |file| from_file(file) }
     end
 
-    def initialize(key:, name:, content:, description: "")
+    def initialize(key:, name:, content:, description: "", tools: [])
       @key = key.to_s
       @name = name.to_s
       @description = description.to_s
       @content = content.to_s
+      @tools = Array(tools).dup.freeze
       raise ArgumentError, "key is required" if @key.empty?
       raise ArgumentError, "name is required" if @name.empty?
       raise ArgumentError, "content is required" if @content.empty?

data/lib/turnkit/specialists.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "net/http"
+require "pathname"
+require "uri"
+
+module TurnKit
+  # Small, composable factories for common specialist agents. The returned
+  # objects are ordinary Agent and Tool instances and may be further configured
+  # or subclassed by applications.
+  module Specialists
+    ORACLE_INSTRUCTIONS = <<~TEXT.strip
+      Act as an expert advisor. Inspect the supplied read-only sources before
+      drawing conclusions. Complete the requested analysis, distinguish facts
+      from recommendations, state material uncertainty, and return the full
+      result. Never claim to have changed application state.
+    TEXT
+
+    LIBRARIAN_INSTRUCTIONS = <<~TEXT.strip
+      Research the configured external GitHub repository using the repository
+      tool. Read the relevant files and history, not merely repository titles.
+      Return a complete answer with source URLs for factual claims and identify
+      the ref or comparison used. Do not imply that repository state was changed.
+    TEXT
+
+    PAINTER_INSTRUCTIONS = <<~TEXT.strip
+      Create or edit the requested image with the image tool. Translate the task
+      into a precise visual prompt, pass all relevant reference images and mask,
+      and return the generated image artifact. Generation is permitted only when
+      the application authorization gate allows the tool call.
+    TEXT
+
+    class ReadOnlyTool < Tool
+      recovery :replay_safe
+      def self.read_only? = true
+      def read_only? = true
+    end
+
+    class ReadFile < ReadOnlyTool
+      tool_name "read_file"
+      description "Read a UTF-8 text file beneath the configured root."
+      parameter :path, :string, required: true, description: "Path relative to the configured root."
+
+      def initialize(root:, max_bytes: 100_000)
+        @root = Pathname(root).expand_path.realpath
+        @max_bytes = Integer(max_bytes)
+      end
+
+      def call(path:, context:)
+        target = confined_path(path)
+        raise ToolError, "not a file: #{path}" unless target.file?
+        raise ToolError, "file exceeds #{@max_bytes} bytes" if target.size > @max_bytes
+
+        { "path" => target.relative_path_from(@root).to_s, "content" => target.binread.force_encoding(Encoding::UTF_8) }
+      rescue Errno::ENOENT, Errno::EACCES, ArgumentError => error
+        raise ToolError, "cannot read #{path}: #{error.message}"
+      end
+
+      private
+
+      def confined_path(path)
+        candidate = @root.join(path.to_s).realpath
+        prefix = @root.to_s + File::SEPARATOR
+        raise ToolError, "path is outside configured root" unless candidate == @root || candidate.to_s.start_with?(prefix)
+
+        candidate
+      end
+    end
+
+    class GitHubRepository < ReadOnlyTool
+      tool_name "github_repository_read"
+      description "Read files, repository metadata, commits, diffs, and issues from one configured GitHub repository."
+      parameter :operation, :enum, required: true, enum: %w[repository file history diff issues issue comments]
+      parameter :path, :string, description: "Repository-relative file path (file operation)."
+      parameter :ref, :string, description: "Branch, tag, or commit for file/history operations."
+      parameter :base, :string, description: "Base ref for a diff."
+      parameter :head, :string, description: "Head ref for a diff."
+      parameter :number, :integer, description: "Issue number."
+      parameter :state, :enum, enum: %w[open closed all], default: "open"
+      parameter :page, :integer, default: 1
+
+      API_HOST = "api.github.com"
+
+      def initialize(repository:, client: nil, token: ENV["GITHUB_TOKEN"])
+        @repository = normalize_repository(repository)
+        @client = client || method(:http_get)
+        @token = token.to_s
+      end
+
+      def call(operation:, path: nil, ref: nil, base: nil, head: nil, number: nil, state: "open", page: 1, context:)
+        endpoint, query = endpoint_for(operation, path: path, ref: ref, base: base, head: head,
+          number: number, state: state, page: page)
+        uri = URI::HTTPS.build(host: API_HOST, path: "/repos/#{@repository}#{endpoint.empty? ? '' : '/' + endpoint}", query: URI.encode_www_form(query))
+        response = @client.call(uri: uri, headers: headers)
+        status, body = unpack_response(response)
+        raise ToolError, "GitHub API returned HTTP #{status}" unless status.between?(200, 299)
+
+        data = JSON.parse(body)
+        if operation == "file" && data.is_a?(Hash) && data["encoding"] == "base64"
+          data = data.merge("content" => Base64.decode64(data.fetch("content")))
+        end
+        { "repository" => @repository, "operation" => operation, "source" => source_url(operation, data, uri), "data" => data }
+      rescue JSON::ParserError => error
+        raise ToolError, "invalid GitHub API response: #{error.message}"
+      end
+
+      private
+
+      def normalize_repository(value)
+        repository = value.to_s
+        raise ArgumentError, "repository must be owner/name" unless repository.match?(%r{\A[A-Za-z0-9][A-Za-z0-9_-]*/[A-Za-z0-9_.-]+\z}) && !%w[. ..].include?(repository.split('/').last)
+
+        repository
+      end
+
+      def endpoint_for(operation, path:, ref:, base:, head:, number:, state:, page:)
+        case operation
+        when "repository" then [ "", {} ]
+        when "file"
+          raise ToolValidationError, "path is required for file" if path.to_s.empty?
+          raise ToolValidationError, "invalid repository path" if path.to_s.split("/").include?("..") || path.to_s.start_with?("/")
+          [ "contents/#{path.to_s.split('/').map { |part| escape_segment(part) }.join('/')}", compact_query(ref: ref) ]
+        when "history" then [ "commits", compact_query(sha: ref, path: path, page: page, per_page: 30) ]
+        when "diff"
+          raise ToolValidationError, "base and head are required for diff" if base.to_s.empty? || head.to_s.empty?
+          [ "compare/#{escape_segment(base)}...#{escape_segment(head)}", {} ]
+        when "issues" then [ "issues", compact_query(state: state, page: page, per_page: 30) ]
+        when "issue"
+          raise ToolValidationError, "number is required for issue" unless number
+          [ "issues/#{Integer(number)}", {} ]
+        when "comments"
+          raise ToolValidationError, "positive issue number is required" unless number && number.positive?
+          [ "issues/#{number}/comments", compact_query(page: page, per_page: 30) ]
+        else raise ToolValidationError, "unknown operation: #{operation}"
+        end
+      end
+
+      def escape_segment(value) = URI.encode_www_form_component(value.to_s).gsub("+", "%20")
+      def compact_query(**values) = values.reject { |_key, value| value.nil? || value.to_s.empty? }
+
+      def headers
+        result = { "Accept" => "application/vnd.github+json", "User-Agent" => "TurnKit" }
+        result["Authorization"] = "Bearer #{@token}" unless @token.empty?
+        result
+      end
+
+      def http_get(uri:, headers:)
+        raise ToolError, "unsafe GitHub API endpoint" unless uri.is_a?(URI::HTTPS) && uri.host == API_HOST && uri.port == 443
+
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: 10, read_timeout: 45) { |http| http.get(uri.request_uri, headers) }
+        # Redirects are deliberately not followed, preventing credentials from
+        # being forwarded to a different endpoint.
+        [ response.code.to_i, response.body.to_s ]
+      end
+
+      def unpack_response(response)
+        return [ Integer(response[0]), response[1].to_s ] if response.is_a?(Array) && response.length == 2
+        return [ Integer(response.code), response.body.to_s ] if response.respond_to?(:code) && response.respond_to?(:body)
+
+        raise ToolError, "GitHub client must return [status, body] or an HTTP response"
+      end
+
+      def source_url(operation, data, uri)
+        return data["html_url"] if data.is_a?(Hash) && data["html_url"].to_s.start_with?("https://github.com/")
+        return data.first["html_url"] if data.is_a?(Array) && data.first.is_a?(Hash) && data.first["html_url"].to_s.start_with?("https://github.com/")
+
+        uri.to_s
+      end
+    end
+
+    class PaintImage < ImageTool
+      tool_name "paint_image"
+      description "Generate or edit an image after application authorization."
+      parameter :prompt, :string, required: true
+      parameter :reference_images, :array, default: [], items: :string
+      parameter :mask, :string
+      terminal! { |result| JSON.generate(result) }
+
+      def initialize(model:, authorization:, provider: nil, size: nil, params: {}, max_reference_images: nil)
+        raise ArgumentError, "authorization must be callable" unless authorization.respond_to?(:call)
+        @image_model, @authorization, @provider, @size = model, authorization, provider, size
+        @params, @max_reference_images = params, max_reference_images
+      end
+
+      def call(prompt:, reference_images: [], mask: nil, context:)
+        references = Array(reference_images)
+        if @max_reference_images && references.length > Integer(@max_reference_images)
+          raise ToolValidationError, "reference_images exceeds configured limit of #{@max_reference_images}"
+        end
+        request = { prompt: prompt, model: @image_model, provider: @provider, size: @size,
+          input_images: references, mask: mask, params: @params }
+        raise ToolError, "image generation was not authorized" unless @authorization.call(request.dup, context: context) == true
+
+        image = context.turn.paint(request.delete(:prompt), **request, metadata: { "specialist" => "painter" })
+        message = context.turn.conversation.messages.reverse.find(&:image?)
+        { "conversation_id" => context.turn.conversation.id, "image_message_id" => message.id,
+          "image" => image.to_h.reject { |key, _| key == "data" } }
+      end
+    end
+
+    module_function
+
+    def oracle(model:, tools: nil, root: Dir.pwd, client: nil, instructions: nil, **agent_options)
+      require_model!(model)
+      configured = tools.nil? ? [ ReadFile.new(root: root) ] : Array(tools)
+      validate_read_only!(configured + skill_tools(agent_options))
+      raise ArgumentError, "read-only specialists cannot delegate to unchecked subagents" if Array(agent_options[:sub_agents]).any?
+      Agent.new(name: "oracle", description: "Read-only expert analysis and advice.", model: model,
+        tools: configured, client: client, instructions: combine(ORACLE_INSTRUCTIONS, instructions), **agent_options, inherit_globals: false)
+    end
+
+    def librarian(repository:, model:, client: nil, github_client: nil, token: ENV["GITHUB_TOKEN"], tools: [], instructions: nil, **agent_options)
+      require_model!(model)
+      repository_tool = GitHubRepository.new(repository: repository, client: github_client, token: token)
+      validate_read_only!(Array(tools) + skill_tools(agent_options))
+      raise ArgumentError, "read-only specialists cannot delegate to unchecked subagents" if Array(agent_options[:sub_agents]).any?
+      Agent.new(name: "librarian", description: "Source-backed research in an external GitHub repository.", model: model,
+        tools: [ repository_tool, *Array(tools) ], client: client,
+        instructions: combine(LIBRARIAN_INSTRUCTIONS, instructions), **agent_options, inherit_globals: false)
+    end
+
+    def painter(model:, image_model:, authorization:, client: nil, tools: [], instructions: nil, provider: nil, size: nil,
+      params: {}, max_reference_images: nil, **agent_options)
+      require_model!(model)
+      require_model!(image_model)
+      image_tool = PaintImage.new(model: image_model, authorization: authorization, provider: provider, size: size,
+        params: params, max_reference_images: max_reference_images)
+      Agent.new(name: "painter", description: "Authorized image generation and editing.", model: model,
+        tools: [ image_tool, *Array(tools) ], client: client,
+        instructions: combine(PAINTER_INSTRUCTIONS, instructions), **agent_options, inherit_globals: false)
+    end
+
+    def skill_tools(options)
+      (Array(options[:skills]) + Array(options[:available_skills])).flat_map(&:tools)
+    end
+    private_class_method :skill_tools
+
+    def validate_read_only!(tools)
+      invalid = tools.reject { |tool| tool.respond_to?(:read_only?) && tool.read_only? == true }
+      raise ArgumentError, "read-only specialist tools must explicitly report read_only? == true" if invalid.any?
+    end
+    private_class_method :validate_read_only!
+
+    def require_model!(model)
+      raise ArgumentError, "model is required" if model.nil? || model.to_s.empty?
+    end
+    private_class_method :require_model!
+
+    def combine(base, extra) = [ base, extra.to_s.strip ].reject(&:empty?).join("\n\n")
+    private_class_method :combine
+  end
+end