claude-agent-sdk 1.1.0 → 1.2.1

data/lib/claude_agent_sdk/railtie.rb

@@ -57,11 +57,18 @@ module ClaudeAgentSDK
     #    the interlock keeps a reload from unloading code under it until the
     #    whole SDK call returns.
     # 3. Otherwise (production: no reloading, concurrency allowed) — run the
-    #    callback inside `Rails.application.executor.wrap`.
+    #    callback inside the executor (see .run_in_executor).
     #
     # The configuration is read on every call, so the same wrapper is correct
     # in every environment.
     #
+    # The wrapper reports nothing to `Rails.error`, in any branch. An exception
+    # that escapes a callback reaches the code that called the SDK, whose own
+    # layer (the request middleware, ActiveJob) reports it with its context;
+    # the failures the SDK handles itself — a hook or tool error answered to
+    # the CLI, a swallowed observer error, a cancellation — are not errors of
+    # the application.
+    #
     # @return [Proc] a callable suitable for `callback_wrapper:`
     # @example config/initializers/claude_agent_sdk.rb
     #   ClaudeAgentSDK.configure do |config|
@@ -71,7 +78,7 @@ module ClaudeAgentSDK
       lambda do |invocation|
         app = ::Rails.application
         next invocation.call if app.nil? || app.executor.active?
-        next app.executor.wrap { invocation.call } unless executor_locks?(app.config)
+        next run_in_executor(app.executor, invocation) unless executor_locks?(app.config)
 
         begin
           invocation.call
@@ -81,6 +88,24 @@ module ClaudeAgentSDK
       end
     end
 
+    # `executor.wrap { invocation.call }` minus its error report. `wrap`
+    # rescues what passes through it (every Exception on Rails 8.1, 8.0.2+
+    # and 7.2.3+; StandardError before) and reports it to `Rails.error` as
+    # unhandled, from a callback thread that has none of the caller's
+    # context — and Rails then skips the same exception as already reported
+    # when it reaches the request or job. It reported the SDK's own
+    # cancellations and the callback failures the SDK answers or swallows,
+    # too. `run!` / `complete!` run the same hooks.
+    def self.run_in_executor(executor, invocation)
+      execution = executor.run!
+      begin
+        invocation.call
+      ensure
+        execution.complete!
+      end
+    end
+    private_class_method :run_in_executor
+
     # Whether railties registered a process-wide lock hook on the executor
     # (Rails::Application::Finisher, initializer
     # :configure_executor_for_concurrency).

data/lib/claude_agent_sdk/sdk_mcp_server.rb

@@ -36,6 +36,9 @@ module ClaudeAgentSDK
   # mangled into nonsense parameter lists ("additionalProperties" as a
   # required string param). A $ref-only schema without type: 'object' remains
   # indistinguishable from a params hash — declare the type alongside $ref.
+  # For the same reason { type: :object } is this prebuilt accept-any-object
+  # schema even though :object is also a shorthand type: a simple schema with
+  # an object parameter literally named type has to spell it { type: Hash }.
   # @api private
   def self.prebuilt_json_schema?(schema)
     return false unless schema.is_a?(Hash)
@@ -67,13 +70,16 @@ module ClaudeAgentSDK
   # @api private
   def self.ruby_type_to_json_schema(type)
     # Class#=== matches instances, not the class object used in { id: Integer }.
-    type = { String => :string, Integer => :integer, Float => :float,
-             TrueClass => :boolean, FalseClass => :boolean }.fetch(type, type)
+    type = { String => :string, Integer => :integer, Float => :float, TrueClass => :boolean,
+             FalseClass => :boolean, Array => :array, Hash => :object }.fetch(type, type)
     case type
     when :string, String then { type: 'string' }
     when :integer, Integer then { type: 'integer' }
     when :float, Float, :number then { type: 'number' }
     when :boolean, TrueClass, FalseClass then { type: 'boolean' }
+    # The class or the Symbol only. An Array or Hash VALUE ([String], a nested
+    # schema fragment) is not a shorthand and falls through like before.
+    when :array, :object then { type: type.to_s }
     else { type: 'string' } # rubocop:disable Lint/DuplicateBranch -- default fallback; the :string arm stays explicit
     end
   end
@@ -301,13 +307,25 @@ module ClaudeAgentSDK
         ClaudeAgentSDK.normalize_tool_result(tool.handler.call(arguments))
       end
 
-      # Guard before flexible_fetch: it raises on non-Hash inputs.
-      content = result.is_a?(Hash) ? ClaudeAgentSDK.flexible_fetch(result, 'content', 'content') : nil
-      return error_tool_result("Tool '#{name}' must return a hash with :content key") unless content
+      # Guard before flexible_fetch: it raises on non-Hash inputs. This first
+      # diagnostic is about the KEY: a present false or nil is a wrong value
+      # and gets the Array diagnostic below, like any other non-Array.
+      unless result.is_a?(Hash) && (result.key?(:content) || result.key?('content'))
+        return error_tool_result("Tool '#{name}' must return a hash with :content key")
+      end
+
+      content = ClaudeAgentSDK.flexible_fetch(result, 'content', 'content')
+      # A String or a single block here is not a result an MCP client accepts.
+      unless content.is_a?(Array)
+        return error_tool_result("Tool '#{name}' must return :content as an Array of content blocks " \
+                                 "(got #{content.class})")
+      end
 
       result
-    rescue StandardError => e
-      # Bare e.message like Python's str(e) — no prefix.
+    rescue *FiberBoundary::CALLBACK_FAILURES => e
+      # Bare e.message like Python's str(e) — no prefix. The list, not just
+      # StandardError: a handler's NotImplementedError, LoadError or
+      # SystemStackError is a tool failure the model should read as well.
       error_tool_result(e.message)
     end
 
@@ -412,7 +430,7 @@ module ClaudeAgentSDK
     end
 
     # Create dynamic Tool classes from tool definitions
-    def create_tool_classes(tools) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- builds each dynamic MCP::Tool subclass inline
+    def create_tool_classes(tools) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity -- builds each dynamic MCP::Tool subclass inline
       # Captured so the dynamic class can resolve the effective scheduling
       # mode at call time — same pattern as prompt classes.
       sdk_server = self
@@ -444,16 +462,22 @@ module ClaudeAgentSDK
             end
 
             def input_schema_value
-              # Full-schema construction: the gem JSON-round-trips and
-              # validates against the draft4 metaschema. additionalProperties/
-              # enum/description survive. Empty required arrays are stripped —
-              # draft4's metaschema mandates non-empty required (Python's
-              # modern jsonschema accepts []). Schemas the draft4 metaschema
-              # rejects (numeric exclusiveMinimum, $ref/$defs — valid modern
-              # JSON Schema that Python accepts) fall back to a permissive
-              # schema with a one-time warning: the tool keeps working with
-              # argument validation disabled instead of being permanently
-              # uncallable while tools/list advertises it as healthy.
+              # Full-schema construction: the gem JSON-round-trips the schema
+              # and validates it against the JSON Schema 2020-12 metaschema
+              # (every mcp version this gem supports; older ones used draft4).
+              # additionalProperties/enum/description survive, and so do a
+              # numeric exclusiveMinimum and same-document $ref/$defs. Empty
+              # required arrays are stripped — a holdover from draft4, whose
+              # metaschema mandated a non-empty required.
+              #
+              # A schema the gem refuses (ArgumentError: a draft4-style
+              # boolean exclusiveMinimum, an unknown type, a $ref that leaves
+              # the document, an invalid pattern, ...) falls back to a
+              # permissive schema with a warning, once per tool: the tool
+              # keeps working with argument validation disabled instead of
+              # being permanently uncallable while tools/list advertises it
+              # as healthy. (The warning's "not draft4-compatible" wording
+              # dates from the draft4 days.)
               @input_schema_value ||= begin
                 schema = ClaudeAgentSDK.normalize_tool_schema(@tool_def.input_schema)
                 schema = schema.except(:required) if schema[:required].is_a?(Array) && schema[:required].empty?
@@ -493,11 +517,21 @@ module ClaudeAgentSDK
 
               # Guard BEFORE flexible_fetch: on a non-Hash it raises
               # TypeError/NoMethodError, surfacing garbage instead of the
-              # friendly message.
-              raise "Tool '#{@tool_def.name}' must return a hash with :content key" unless result.is_a?(Hash)
+              # friendly message. This first diagnostic is about the KEY: a
+              # present false or nil is a wrong value and gets the Array
+              # diagnostic below, like any other non-Array.
+              unless result.is_a?(Hash) && (result.key?(:content) || result.key?('content'))
+                raise "Tool '#{@tool_def.name}' must return a hash with :content key"
+              end
 
               content = ClaudeAgentSDK.flexible_fetch(result, 'content', 'content')
-              raise "Tool '#{@tool_def.name}' must return a hash with :content key" if content.nil?
+              # A String or a single block Hash would go out as it is, and the
+              # CLI rejects that frame against its schema: the model is told
+              # the SERVER returned a malformed result and never sees the text.
+              unless content.is_a?(Array)
+                raise "Tool '#{@tool_def.name}' must return :content as an Array of content blocks " \
+                      "(got #{content.class})"
+              end
 
               is_error = ClaudeAgentSDK.flexible_fetch(result, 'isError', 'is_error')
               structured_content = ClaudeAgentSDK.flexible_fetch(result, 'structuredContent', 'structured_content')
@@ -507,12 +541,15 @@ module ClaudeAgentSDK
                 error: !!is_error,
                 structured_content: structured_content
               )
-            rescue StandardError => e
+            rescue *FiberBoundary::CALLBACK_FAILURES => e
               # Report handler failures in-band HERE rather than letting them
               # reach the gem: mcp >= 1.2 deliberately drops e.message from
               # its "Internal error calling tool X" wrapper (CWE-209), which
               # would hide the text the model needs to self-correct. Bare
               # e.message like Python's str(e) and #call_tool — no prefix.
+              # The list, not just StandardError: the gem rescues only
+              # StandardError, so a handler's NotImplementedError / LoadError /
+              # SystemStackError would pass it unanswered.
               # Nothing gem-internal can be swallowed here today: handlers get
               # no server_context, so MCP::CancelledError never originates
               # inside this method. Revisit if cancellation is ever plumbed in.
@@ -606,7 +643,17 @@ module ClaudeAgentSDK
   #
   # @param name [String] Unique identifier for the tool
   # @param description [String] Human-readable description
-  # @param input_schema [Hash] Schema defining input parameters
+  # @param input_schema [Hash] Schema defining input parameters: a full JSON
+  #   Schema (+{ type: 'object', properties: ... }+), or the shorthand
+  #   +{ name: type }+, in which every parameter is required and each type is
+  #   +String+ / +:string+, +Integer+ / +:integer+, +Float+ / +:float+ /
+  #   +:number+, +TrueClass+ / +FalseClass+ / +:boolean+, +Array+ / +:array+
+  #   or +Hash+ / +:object+
+  # @param annotations [Hash, nil] MCP tool annotations (+title+,
+  #   +readOnlyHint+, ...). +maxResultSizeChars+ is also forwarded as
+  #   +_meta['anthropic/maxResultSizeChars']+, the form the CLI reads
+  # @param meta [Hash, nil] The tool's +_meta+. Merged with the size hint
+  #   derived from +annotations+; a key given here wins
   # @param handler [Proc] Block that implements the tool logic. It returns a
   #   String, sent to Claude as a single text block, or a Hash with a
   #   +:content+ Array of MCP content blocks plus optional +:is_error+ /
@@ -641,11 +688,16 @@ module ClaudeAgentSDK
   def self.create_tool(name, description, input_schema, annotations: nil, meta: nil, &handler)
     raise ArgumentError, 'Block required for tool handler' unless handler
 
-    # Auto-populate _meta with maxResultSizeChars from annotations if present
+    # Auto-populate _meta with maxResultSizeChars from annotations if present.
+    # An explicit meta: is merged with that hint rather than replacing it (an
+    # unrelated key used to drop it); a size key the caller sets itself wins,
+    # in either spelling — adding the String key beside a Symbol one would
+    # put the same JSON key in the frame twice.
+    size_key = 'anthropic/maxResultSizeChars'
     resolved_meta = meta
-    if resolved_meta.nil? && annotations
+    if annotations.is_a?(Hash) && (meta.nil? || (meta.is_a?(Hash) && meta.keys.none? { |key| key.to_s == size_key }))
       max_chars = annotations[:maxResultSizeChars] || annotations['maxResultSizeChars']
-      resolved_meta = { 'anthropic/maxResultSizeChars' => max_chars } if max_chars
+      resolved_meta = { size_key => max_chars }.merge(meta || {}) if max_chars
     end
 
     # tools/call arrives from the CLI with the name as a JSON String; the mcp

data/lib/claude_agent_sdk/session_assembly.rb

@@ -0,0 +1,311 @@
+# frozen_string_literal: true
+
+require_relative 'fiber_boundary'
+require_relative 'message_parser'
+require_relative 'query'
+require_relative 'session_resume'
+require_relative 'subprocess_cli_transport'
+
+module ClaudeAgentSDK
+  # The three things every dispatch of a session's user code needs — its
+  # resolved observers, where callbacks run (callback_scheduling) and the
+  # middleware around them (callback_wrapper) — held in one place, so that
+  # no call site threads them by hand. A context holder, nothing deeper: each
+  # method is the module function it names, called with the triple.
+  #
+  # Scheduling and wrapper are fixed for the life of the object. The
+  # observers can be replaced, and each call below reads the ones there are
+  # at that moment: query() never replaces them; Client keeps one Dispatch
+  # for its lifetime and puts in the observers it resolves on each connect,
+  # so a receive loop still running from before a reconnect notifies the
+  # current ones.
+  #
+  # @api private
+  class Dispatch
+    # For what takes the pair as its own arguments (Query, the transcript
+    # mirror batcher).
+    attr_reader :scheduling, :wrapper
+
+    # Replace the observers, with a new Array: the one being replaced may be
+    # in the middle of a notification, and is never changed in place.
+    attr_writer :observers
+
+    def initialize(observers, scheduling:, wrapper:)
+      @observers = observers
+      @scheduling = scheduling
+      @wrapper = wrapper
+    end
+
+    # See ClaudeAgentSDK.notify_observers.
+    def notify(method, *)
+      ClaudeAgentSDK.notify_observers(@observers, method, *, scheduling: @scheduling, wrapper: @wrapper)
+    end
+
+    # See ClaudeAgentSDK.observing_prompt_stream.
+    def observing_stream(prompt)
+      ClaudeAgentSDK.observing_prompt_stream(prompt, @observers, scheduling: @scheduling, wrapper: @wrapper)
+    end
+
+    # See FiberBoundary.invoke_iteration.
+    def invoke_iteration(block, message)
+      FiberBoundary.invoke_iteration(block, message, scheduling: @scheduling, wrapper: @wrapper)
+    end
+  end
+
+  # The resources of one session and what is done with them: acquiring the
+  # transport, the Query on top of it and (for a store-backed resume) the
+  # materialized config dir; writing prompts; delivering messages; disposing
+  # of all three.
+  #
+  # This is implementation shared by the two entry points, ClaudeAgentSDK.query
+  # and Client, not a lifecycle of its own. When to connect, what observers are
+  # told, which error wins and whether stdin is closed after a prompt differ
+  # between the two and stay with them; so nothing here notifies on_error or
+  # on_close, and nothing here rescues.
+  #
+  # @api private
+  class SessionAssembly
+    # For #write_prompt: stamp with the verbatim_prompts value #connect captured.
+    CAPTURED = :captured
+
+    # The session's control-protocol handler: nil before #connect and after
+    # #close_resources. The only state that is read from outside.
+    attr_reader :query_handler
+
+    # Acquires nothing. +transport_source+ says where the transport comes from:
+    #
+    #   { instance: transport }          one the caller built (query(transport:))
+    #   { class: klass, args: kwargs }   one to construct as klass.new(options, **kwargs)
+    #
+    # +configured_options+ are the options after can_use_tool routing and
+    # validation; #connect may replace them with a copy repointed at a
+    # materialized resume.
+    def initialize(configured_options, dispatch:, transport_source:)
+      @options = configured_options
+      @dispatch = dispatch
+      @transport_source = transport_source
+      @transport = nil
+      @query_handler = nil
+      @materialized = nil
+      @verbatim_prompts = false
+    end
+
+    # Acquire, in order: the materialized resume (when it applies) and the
+    # options repointed at it, the transport, its connection, the Query, the
+    # transcript mirror (before the read loop starts, so that it sees every
+    # transcript_mirror frame), the read loop, the handshake.
+    #
+    # Each resource is recorded before the next step that can fail and nothing
+    # is rolled back here: whatever a step raises propagates, and the caller's
+    # own rescue calls #close_resources.
+    def connect
+      @transport = acquire_transport
+      @transport.connect
+
+      # Read once, here: after the transport connected (its #connect may still
+      # change the options it was given) and before the Query is built. The
+      # Query stamps streamed prompts with this value, and #write_prompt /
+      # #write_message stamp theirs with it too unless told otherwise, so one
+      # session marks all of them alike.
+      @verbatim_prompts = @options.verbatim_prompts?
+      @query_handler = build_query_handler
+      install_transcript_mirror
+
+      @query_handler.start
+      @query_handler.initialize_protocol
+    end
+
+    # Write a String prompt as one user message. The caller notifies
+    # on_user_prompt first: the order is its own, and so is what may happen to
+    # the options in between.
+    #
+    #   verbatim: CAPTURED       the value #connect captured (Client)
+    #   verbatim: :current       read from the options the session runs on, now
+    #                            (query(): after its on_user_prompt notification)
+    #   verbatim: true / false   that value
+    #
+    # The options the session runs on are the repointed copy when a
+    # store-backed resume was materialized, the configured ones otherwise.
+    def write_prompt(prompt, session_id:, verbatim: CAPTURED)
+      message = {
+        type: 'user',
+        message: { role: 'user', content: prompt },
+        parent_tool_use_id: nil,
+        session_id: session_id
+      }
+      writeln(Query.serialize_user_message(message, verbatim_value(verbatim)))
+    end
+
+    # Write one user message that already has its shape (a Hash, or a JSONL
+    # String), stamped with the captured verbatim_prompts value. Serialized
+    # first: a message that cannot be marked raises before anything is written.
+    def write_message(message)
+      writeln(Query.serialize_user_message(message, @verbatim_prompts))
+    end
+
+    # Stream an Enumerable prompt as the session's input, in the background.
+    # The task is tracked on the Query, so closing it stops the stream;
+    # Query#stream_input closes stdin once the stream is exhausted and its
+    # last run is over, and swallows the stream's own errors with a warning.
+    # Observers get on_user_prompt for each user message before it is written.
+    def stream_prompt_in_background(prompt)
+      handler = @query_handler
+      observed = @dispatch.observing_stream(prompt)
+      handler.spawn_task { handler.stream_input(observed) }
+    end
+
+    # Deliver the session's messages to +block+: parse each frame, notify
+    # on_message, then invoke the block across the FiberBoundary. Returns the
+    # value of the block's `break` when it broke. With until_result: true the
+    # ResultMessage is the last message delivered.
+    #
+    # Loop control stays on this fiber, the one that dequeues: both breaks
+    # happen here, never inside the hop (a `break` in a proc on another thread
+    # raises LocalJumpError; Dispatch#invoke_iteration hands it back as a
+    # Break). Errors propagate; notifying on_error is the caller's.
+    def deliver(block, until_result: false)
+      @query_handler.receive_messages do |data|
+        message = MessageParser.parse(data)
+        next unless message
+
+        @dispatch.notify(:on_message, message)
+        signal = @dispatch.invoke_iteration(block, message)
+        break signal.value if signal.is_a?(FiberBoundary::Break)
+        break if until_result && message.is_a?(ResultMessage)
+      end
+    end
+
+    # Dispose of whatever #connect acquired, however far it got: close the
+    # Query (which flushes the transcript mirror and closes the transport),
+    # close the transport, decide what happens to the materialized resume dir.
+    #
+    #   always_close_transport: true    the transport is closed in an ensure of
+    #                                   its own, also when closing the Query
+    #                                   raised (Client)
+    #   always_close_transport: false   the transport is closed only when no
+    #                                   Query was built (query())
+    #
+    # Transport#close is idempotent, so the second close is harmless. The
+    # nested ensures run every later step when an earlier one raises, and the
+    # last error raised is the one that propagates.
+    #
+    # A block, when given, is called once both closes are behind and before
+    # the materialized dir is dealt with — also when a close raised. From
+    # there on nothing of the session can be used any more, while removing
+    # the directory can still take a while (it retries, sleeping, when the
+    # directory is busy) and lets other tasks run meanwhile: the caller marks
+    # itself disconnected in the block, so that calls made in that window are
+    # refused instead of reaching a session that is half gone.
+    def close_resources(always_close_transport:)
+      # Kept past the nil-out below: whether the mirror dropped batches is
+      # final only after #close ran its last flush.
+      handler = @query_handler
+      begin
+        handler&.close
+      ensure
+        @query_handler = nil
+        begin
+          @transport&.close if always_close_transport || handler.nil?
+        ensure
+          @transport = nil
+          yield if block_given?
+          dispose_of_materialized_resume(handler)
+        end
+      end
+    end
+
+    private
+
+    # An injected transport was built before any repointing could reach it,
+    # so nothing is materialized for it. A class is constructed after
+    # materialization, with the repointed options.
+    def acquire_transport
+      return @transport_source.fetch(:instance) if @transport_source.key?(:instance)
+
+      transport_class = @transport_source.fetch(:class)
+      materialize_resume if @options.session_store && spawns_cli_locally?(transport_class)
+      transport_class.new(@options, **@transport_source.fetch(:args))
+    end
+
+    # The materialized config dir and --resume reach a transport only through
+    # the options it is constructed with, and mean something only to one that
+    # spawns the CLI on this host with them: SubprocessCLITransport or a
+    # subclass of it (ancestry, not identity). The source may be a duck-typed
+    # factory rather than a Class.
+    def spawns_cli_locally?(transport_class)
+      transport_class.is_a?(Class) && transport_class <= SubprocessCLITransport
+    end
+
+    # Resume-from-store: load the session from the store into a temp
+    # CLAUDE_CONFIG_DIR and repoint the options at it (env + --resume). The
+    # directory is recorded before the repointing, so a failure there still
+    # leaves it to #close_resources.
+    def materialize_resume
+      @materialized = SessionResume.materialize_resume_session(@options)
+      @options = SessionResume.apply_materialized_options(@options, @materialized) if @materialized
+    end
+
+    # The one place a Query is built from options. Streaming mode with the
+    # control protocol, always (as in the Python SDK): agents travel in the
+    # initialize request rather than in CLI arguments, clear of ARG_MAX.
+    def build_query_handler
+      Query.new(
+        transport: @transport,
+        is_streaming_mode: true,
+        can_use_tool: @options.can_use_tool,
+        hooks: ClaudeAgentSDK.convert_hooks_to_internal_format(@options.hooks),
+        sdk_mcp_servers: ClaudeAgentSDK.extract_sdk_mcp_servers(@options.mcp_servers),
+        agents: @options.agents,
+        exclude_dynamic_sections: ClaudeAgentSDK.extract_exclude_dynamic_sections(@options.system_prompt),
+        system_prompt_snapshot: ClaudeAgentSDK.extract_system_prompt_snapshot(@options.system_prompt),
+        skills: @options.skills,
+        forward_subagent_text: @options.forward_subagent_text?,
+        agent_progress_summaries: @options.agent_progress_summaries,
+        callback_scheduling: @dispatch.scheduling,
+        callback_wrapper: @dispatch.wrapper,
+        verbatim_prompts: @verbatim_prompts,
+        run_end_ceiling_ms: Query.run_end_ceiling_ms(@options.env)
+      )
+    end
+
+    # Mirror transcripts to the session_store, if one is configured.
+    def install_transcript_mirror
+      return unless @options.session_store
+
+      handler = @query_handler
+      handler.set_transcript_mirror_batcher(
+        SessionResume.build_mirror_batcher(
+          store: @options.session_store,
+          env: @options.env,
+          on_error: ->(key, message) { handler.report_mirror_error(key, message) },
+          eager: @options.session_store_flush.to_s == 'eager',
+          callback_wrapper: @dispatch.wrapper
+        )
+      )
+    end
+
+    def verbatim_value(verbatim)
+      case verbatim
+      when CAPTURED then @verbatim_prompts
+      when :current then @options.verbatim_prompts?
+      else verbatim
+      end
+    end
+
+    def writeln(string)
+      @transport.write(string.end_with?("\n") ? string : "#{string}\n")
+    end
+
+    # The materialized resume dir holds a redacted .credentials.json copy, so
+    # it is removed once the subprocess has exited — unless the mirror dropped
+    # batches: the store copy is then incomplete and the dir holds the only
+    # copy of the dropped turns, so it is preserved (scrubbed of credentials)
+    # with a warning instead.
+    def dispose_of_materialized_resume(handler)
+      return unless @materialized
+
+      handler&.mirror_batches_dropped? ? @materialized.preserve_transcripts : @materialized.cleanup
+      @materialized = nil
+    end
+  end
+end