openai 0.115.0 → 0.116.0

data/lib/openai/helpers/responses_websocket/incremental.rb

@@ -5,30 +5,88 @@ module OpenAI
     # Optional, caller-fed provisional output for one WebSocket lane.
     # Feed the events returned by lane.receive; use a separate instance per lane.
     # This helper never reads, closes, or writes to a connection. Tools are data.
-    #
-    # Output is provisional and may be unavailable when the wire omitted its
-    # scaffolding, or a known output update cannot be represented. Terminal events
-    # are retained exactly as received, never filled from provisional output.
-    # Call reset to discard all retained state.
+    # Terminal events stay exact; provisional facts never manufacture a Response.
     class IncrementalResponse
       include OpenAI::WebSocket::Protocol
 
+      STATUS_ITEMS = {
+        "response.code_interpreter_call.in_progress" => ["code_interpreter_call", "in_progress"],
+        "response.code_interpreter_call.interpreting" => ["code_interpreter_call", "interpreting"],
+        "response.code_interpreter_call.completed" => ["code_interpreter_call", "completed"],
+        "response.file_search_call.in_progress" => ["file_search_call", "in_progress"],
+        "response.file_search_call.searching" => ["file_search_call", "searching"],
+        "response.file_search_call.completed" => ["file_search_call", "completed"],
+        "response.web_search_call.in_progress" => ["web_search_call", "in_progress"],
+        "response.web_search_call.searching" => ["web_search_call", "searching"],
+        "response.web_search_call.completed" => ["web_search_call", "completed"],
+        "response.image_generation_call.in_progress" => ["image_generation_call", "in_progress"],
+        "response.image_generation_call.generating" => ["image_generation_call", "generating"],
+        "response.image_generation_call.completed" => ["image_generation_call", "completed"],
+        "response.mcp_call.in_progress" => ["mcp_call", "in_progress"],
+        "response.mcp_call.completed" => ["mcp_call", "completed"],
+        "response.mcp_call.failed" => ["mcp_call", "failed"]
+      }.freeze
+      private_constant :STATUS_ITEMS
+
       attr_reader :phase
 
       def initialize
         reset
       end
 
-      # A detached provisional output snapshot, or nil when unavailable/terminal.
-      #
-      # This materializes the whole output and costs time proportional to its
-      # size. Use the original event's delta for per-delta progress. Read output
-      # at boundaries such as response.output_item.done when a full, corrected
-      # view is needed; replace a displayed view instead of appending its prefix.
-      # Repeated full snapshots of a growing response necessarily copy growing
-      # amounts of data.
+      # Detached typed output: the truthful contiguous projectable prefix.
+      # Sparse or incomplete records stop this prefix; detailed_snapshot retains
+      # their actual indices. Full reads cost time proportional to retained data.
+      # Use original deltas for per-event progress and read snapshots at boundaries.
       def output
-        @output&.map { |item| copy(item) }
+        return unless @phase == :provisional
+
+        result = []
+        while (record = @items[result.length])
+          break unless record[:full]
+
+          result <<
+            OpenAI::Internal::Type::Converter.coerce(
+              OpenAI::Responses::ResponseOutputItem,
+              project_item(record)
+            )
+        end
+
+        result
+      end
+
+      # Detached observed facts, including sparse indices and response metadata.
+      # This is not a complete Response. No absent item/part type is inferred.
+      def detailed_snapshot
+        return if @phase.nil? || @phase == :unavailable
+
+        if @phase == :terminal
+          data = @terminal_event.deep_to_h
+          response = data[:response]
+          items = response.is_a?(Hash) && response[:output].is_a?(Array) ? response[:output] : []
+          records = items.map { |item| make_record(item, full: true) }
+          rows = records.each_with_index.map { |record, index| detailed_item(index, record) }
+          return copy(
+            phase: @phase,
+            stream_id: data[:stream_id],
+            response_id: response.is_a?(Hash) ? response[:id] : nil,
+            terminal_type: data[:type],
+            response: response.is_a?(Hash) ? response.reject { |key, _| key == :output } : nil,
+            output: rows,
+            output_text: observed_text(records)
+          )
+        end
+
+        indices = @items.keys.sort
+        copy(
+          phase: @phase,
+          stream_id: @stream_id,
+          response_id: @response && @response[:id],
+          terminal_type: nil,
+          response: @response,
+          output: indices.map { |index| detailed_item(index, @items.fetch(index)) },
+          output_text: observed_text(indices.map { |index| @items.fetch(index) })
+        )
       end
 
       # The exact consumed completion, failure, incomplete, or error event.
@@ -37,60 +95,65 @@ module OpenAI
       end
 
       def reset
-        @state = OpenAI::Helpers::Streaming::ResponseStreamState.new(text_format: nil)
         @phase = nil
-        @output = nil
+        @items = {}
+        @ids = {}
+        @command_bounds = {}
+        @response = nil
+        @stream_id = nil
         @terminal_event = nil
         nil
       end
 
       def add(event)
-        case event
-        when OpenAI::Responses::UnknownServerEvent
-          return
-        when
-            OpenAI::Responses::ResponseCompletedEvent,
-            OpenAI::Responses::ResponseFailedEvent,
-            OpenAI::Responses::ResponseIncompleteEvent,
-            OpenAI::Responses::ResponsesServerEvent::ResponseWsError
+        return if event.is_a?(OpenAI::Responses::UnknownServerEvent)
+
+        type = event[:type].to_s
+        if %w[response.completed response.failed response.incomplete error].include?(type)
           reset
           @terminal_event = copy(event)
           @phase = :terminal
-        when OpenAI::Responses::ResponseCreatedEvent
+          return
+        end
+
+        return if @phase == :terminal && type != "response.created"
+
+        if %w[response.created response.queued response.in_progress].include?(type)
           response = copy(event)[:response]
           unless response.is_a?(OpenAI::Responses::Response) &&
               (response[:output].nil? || response[:output].is_a?(Array))
             raise SessionError, "Invalid Responses WebSocket created response."
           end
 
-          reset
-          @output = response[:output] || []
-          @phase = :provisional
-        when
-            OpenAI::Responses::ResponseOutputItemAddedEvent,
-            OpenAI::Responses::ResponseOutputItemDoneEvent,
-            OpenAI::Responses::ResponseContentPartAddedEvent,
-            OpenAI::Responses::ResponseContentPartDoneEvent,
-            OpenAI::Responses::ResponseTextDeltaEvent,
-            OpenAI::Responses::ResponseTextDoneEvent,
-            OpenAI::Responses::ResponseFunctionCallArgumentsDeltaEvent,
-            OpenAI::Responses::ResponseFunctionCallArgumentsDoneEvent,
-            OpenAI::Responses::ResponseCustomToolCallInputDeltaEvent,
-            OpenAI::Responses::ResponseCustomToolCallInputDoneEvent,
-            OpenAI::Responses::ResponseRefusalDeltaEvent,
-            OpenAI::Responses::ResponseRefusalDoneEvent,
-            OpenAI::Responses::ResponseOutputTextAnnotationAddedEvent
-          return if @phase == :unavailable || @phase == :terminal
-
-          apply_output(copy(event))
-        else
-          # A full output snapshot must not leave stale fields after unsupported
-          # indexed updates. Unknown raw events and progress events are not output.
-          if @phase != :terminal &&
-              event.class.known_fields.key?(:output_index) &&
-              event[:type].to_s.end_with?(".added", ".delta", ".done", ".partial_image")
-            unavailable
+          reset if type == "response.created"
+          return if @phase == :unavailable
+
+          data = response.deep_to_h
+          @response = data.reject { |key, _| key == :output }
+          @stream_id = copy(event[:stream_id])
+          if data[:output].is_a?(Array) || type == "response.created"
+            @items = {}
+            @ids = {}
+            @command_bounds = {}
+            (data[:output] || []).each_with_index do |item, index|
+              replace_item(index, item)
+              break if @phase == :unavailable
+            end
           end
+
+          @phase = :provisional unless @phase == :unavailable
+          return
+        end
+
+        return if @phase == :unavailable
+
+        data = copy(event).deep_to_h
+        @stream_id ||= data[:stream_id]
+        if (status = STATUS_ITEMS[type])
+          record = item_for(data, status.first)
+          record[:item][:status] = status.last if record
+        else
+          apply_output(type, data, event.class)
         end
 
         nil
@@ -98,134 +161,417 @@ module OpenAI
 
       private
 
-      def apply_output(event)
-        index = event[:output_index]
-        unless @output && index.is_a?(Integer) && index >= 0 && index <= @output.length
-          return unavailable
-        end
-
-        case event
-        when OpenAI::Responses::ResponseOutputItemDoneEvent
-          # Replace the entire item: done may reduce its content or change its ID.
-          @output[index] = event.item
-          @state = OpenAI::Helpers::Streaming::ResponseStreamState.new(text_format: nil)
-        when OpenAI::Responses::ResponseOutputItemAddedEvent
-          return unavailable unless index == @output.length
-
-          @state.accumulate_output(event, @output)
-        when OpenAI::Responses::ResponseFunctionCallArgumentsDoneEvent
-          item = @output[index]
-          unless item.is_a?(OpenAI::Responses::ResponseFunctionToolCall) &&
-              item.id == event.item_id &&
-              event[:arguments].is_a?(String)
-            return unavailable
+      def apply_output(type, data, event_class)
+        case type
+        when "response.output_item.added", "response.output_item.done"
+          return unavailable unless valid_index?(data[:output_index]) && data[:item].is_a?(Hash)
+
+          replace_item(data[:output_index], data[:item])
+        when
+            "response.content_part.added",
+            "response.content_part.done",
+            "response.reasoning_summary_part.added",
+            "response.reasoning_summary_part.done"
+          summary = type.start_with?("response.reasoning_summary")
+          index = data[summary ? :summary_index : :content_index]
+          part = data[:part]
+          return unavailable unless valid_index?(index) && part.is_a?(Hash)
+
+          kind = summary || part[:type].to_s == "reasoning_text" ? "reasoning" : "message"
+          record = item_for(data, kind)
+          put_part(record, summary ? :summary : :content, index, part) if record
+        when
+            "response.function_call_arguments.delta",
+            "response.function_call_arguments.done",
+            "response.custom_tool_call_input.delta",
+            "response.custom_tool_call_input.done",
+            "response.mcp_call_arguments.delta",
+            "response.mcp_call_arguments.done",
+            "response.code_interpreter_call_code.delta",
+            "response.code_interpreter_call_code.done"
+          kind, field = case type
+          when /function_call_arguments/
+            ["function_call", :arguments]
+          when /custom_tool_call_input/
+            ["custom_tool_call", :input]
+          when /mcp_call_arguments/
+            ["mcp_call", :arguments]
+          else
+            ["code_interpreter_call", :code]
+          end
+
+          done = type.end_with?(".done")
+          value = data[done ? field : :delta]
+          return unavailable unless value.is_a?(String)
+
+          record = item_for(data, kind)
+          if record
+            update_string(record[:item], field, value, done: done, nullable: field == :code, required: record[:full])
           end
 
-          item.arguments = event[:arguments]
         when
-            OpenAI::Responses::ResponseCustomToolCallInputDeltaEvent,
-            OpenAI::Responses::ResponseCustomToolCallInputDoneEvent
-          item = @output[index]
-          unless item.is_a?(OpenAI::Responses::ResponseCustomToolCall) && item.id == event.item_id
+            "response.output_text.delta",
+            "response.output_text.done",
+            "response.refusal.delta",
+            "response.refusal.done",
+            "response.reasoning_text.delta",
+            "response.reasoning_text.done",
+            "response.reasoning_summary_text.delta",
+            "response.reasoning_summary_text.done"
+          summary = type.start_with?("response.reasoning_summary")
+          reasoning = type.start_with?("response.reasoning")
+          refusal = type.start_with?("response.refusal")
+          field = refusal ? :refusal : :text
+          done = type.end_with?(".done")
+          value = data[done ? field : :delta]
+          index = data[summary ? :summary_index : :content_index]
+          return unavailable unless value.is_a?(String) && valid_index?(index)
+          return unavailable unless data[:logprobs].nil? || data[:logprobs].is_a?(Array)
+
+          record = item_for(data, reasoning ? "reasoning" : "message")
+          return unless record
+
+          kind = reasoning ? (summary ? "summary_text" : "reasoning_text") : (refusal ? "refusal" : "output_text")
+          part = part_for(record, summary ? :summary : :content, index, kind)
+          return unless part
+          return unless update_string(part[:part], field, value, done: done, required: part[:full])
+
+          if type.start_with?("response.output_text") && !data[:logprobs].nil?
+            if done
+              part[:part][:logprobs] = data[:logprobs]
+            else
+              old = part[:part][:logprobs]
+              return unavailable unless old.nil? || old.is_a?(Array)
+
+              (part[:part][:logprobs] ||= []).concat(data[:logprobs])
+            end
+          end
+
+        when "response.output_text.annotation.added"
+          index = data[:content_index]
+          annotation_index = data[:annotation_index]
+          unless valid_index?(index) &&
+              valid_index?(annotation_index) &&
+              data.key?(:annotation) &&
+              (data[:annotation].nil? || data[:annotation].is_a?(Hash))
             return unavailable
           end
 
-          if event.is_a?(OpenAI::Responses::ResponseCustomToolCallInputDeltaEvent)
-            return unavailable unless item[:input].is_a?(String) && event[:delta].is_a?(String)
+          record = item_for(data, "message")
+          return unless record
+
+          part = part_for(record, :content, index, "output_text")
+          return unless part
+          return unavailable if part[:part].key?(:annotations) && !part[:part][:annotations].is_a?(Array)
+
+          part[:annotations][annotation_index] = data[:annotation]
+          sync_array(part[:part][:annotations], part[:annotations], annotation_index)
+        when
+            "response.shell_call_command.added",
+            "response.shell_call_command.delta",
+            "response.shell_call_command.done"
+          done = !type.end_with?(".delta")
+          value = data[done ? :command : :delta]
+          index = data[:command_index]
+          return unavailable unless value.is_a?(String) && valid_index?(index)
+
+          record = item_for(data, "shell_call", identity: false)
+          return unless record
 
-            item.input << event[:delta]
+          if done
+            record[:commands][index] = value
           else
-            return unavailable unless event[:input].is_a?(String)
+            return unavailable if record[:commands].key?(index) && !record[:commands][index].is_a?(String)
 
-            item.input = event[:input]
+            (record[:commands][index] ||= +"") << value
           end
-        else
-          item = @output[index]
-          if event.is_a?(OpenAI::Responses::ResponseFunctionCallArgumentsDeltaEvent)
-            unless item.is_a?(OpenAI::Responses::ResponseFunctionToolCall) &&
-                item.id == event.item_id &&
-                event.delta.is_a?(String)
+
+          commands = record[:item].dig(:action, :commands)
+          sync_array(commands, record[:commands], index)
+          update_bound(record, data[:output_index])
+        when "response.shell_call_output_content.delta", "response.shell_call_output_content.done"
+          index = data[:command_index]
+          done = type.end_with?(".done")
+          value = data[done ? :output : :delta]
+          return unavailable unless valid_index?(index)
+          if done
+            return unavailable unless value.is_a?(Array)
+          else
+            unless value.is_a?(Hash) &&
+                value.all? { |key, entry| !%i[stdout stderr].include?(key) || entry.is_a?(String) }
               return unavailable
             end
+          end
+
+          record = item_for(data, "shell_call_output")
+          return unless record
+
+          bound = @command_bounds[record[:item][:call_id]]
+          return unavailable if bound && index >= bound[:count]
+
+          if done
+            record[:content][index] = make_part({output: value}, full: false)
           else
-            part_index = event[:content_index]
-            unless item.is_a?(OpenAI::Responses::ResponseOutputMessage) &&
-                item.id == event.item_id &&
-                item.content.is_a?(Array) &&
-                part_index.is_a?(Integer) &&
-                part_index >= 0 &&
-                part_index <= item.content.length
+            part = record[:content][index] ||= make_part({}, full: false)
+            value.each do |key, entry|
+              if %i[stdout stderr].include?(key)
+                update_string(part[:part], key, entry, done: false)
+              else
+                part[:part][key] = entry
+              end
+            end
+          end
+
+        when "response.image_generation_call.partial_image"
+          # Image bytes are deliberately not accumulated. Status remains useful.
+          nil
+        else
+          if event_class.known_fields.key?(:output_index) &&
+              type.end_with?(".added", ".delta", ".done", ".partial_image")
+            unavailable
+          end
+        end
+      end
+
+      def item_for(data, kind, identity: true)
+        index = data[:output_index]
+        return unavailable unless valid_index?(index)
+
+        record = @items[index]
+        return unavailable if record && record[:kind] && record[:kind] != kind
+        if identity
+          id = data[:item_id]
+          return unavailable unless id.is_a?(String)
+          return unavailable if @ids.key?(id) && @ids[id] != index
+          if record
+            item = record[:item]
+            if item.key?(:id)
+              return unavailable unless item[:id] == id
+            elsif record[:full] && !%w[function_call custom_tool_call].include?(kind)
               return unavailable
             end
 
-            case event
-            when OpenAI::Responses::ResponseContentPartDoneEvent
-              item.content[part_index] = event.part
-              return
-            when OpenAI::Responses::ResponseContentPartAddedEvent
-              return unavailable unless part_index == item.content.length
-            when OpenAI::Responses::ResponseTextDoneEvent
-              part = item.content[part_index]
-              unless part.is_a?(OpenAI::Responses::ResponseOutputText) &&
-                  event[:text].is_a?(String) &&
-                  (event[:logprobs].nil? || event[:logprobs].is_a?(Array))
-                return unavailable
-              end
+            return unavailable if record[:bound_id] && record[:bound_id] != id
+          end
+        end
 
-              part.text = event[:text]
-              part.logprobs = event[:logprobs] unless event[:logprobs].nil?
-              return
-            when OpenAI::Responses::ResponseTextDeltaEvent
-              part = item.content[part_index]
-              unless part.is_a?(OpenAI::Responses::ResponseOutputText) &&
-                  part.text.is_a?(String) &&
-                  event.delta.is_a?(String) &&
-                  (event[:logprobs].nil? || event[:logprobs].is_a?(Array)) &&
-                  (part[:logprobs].nil? || part[:logprobs].is_a?(Array))
-                return unavailable
-              end
+        record ||= (@items[index] = make_record({}, full: false))
+        record[:kind] ||= kind
+        if identity
+          record[:bound_id] = data[:item_id]
+          record[:item][:id] = data[:item_id] unless record[:full]
+          @ids[data[:item_id]] = index
+        end
 
-              unless event[:logprobs].nil?
-                part.logprobs = [] if part[:logprobs].nil?
-                part[:logprobs].concat(event[:logprobs])
-              end
+        @phase = :provisional
+        record
+      end
 
-            when OpenAI::Responses::ResponseRefusalDeltaEvent, OpenAI::Responses::ResponseRefusalDoneEvent
-              part = item.content[part_index]
-              return unavailable unless part.is_a?(OpenAI::Responses::ResponseOutputRefusal)
+      def replace_item(index, item)
+        id = item[:id]
+        return unavailable if id.is_a?(String) && @ids.key?(id) && @ids[id] != index
 
-              if event.is_a?(OpenAI::Responses::ResponseRefusalDeltaEvent)
-                return unavailable unless part[:refusal].is_a?(String) && event[:delta].is_a?(String)
+        if (old = @items[index])
+          @ids.delete(old[:bound_id]) if old[:bound_id]
+          call_id = old[:item][:call_id]
+          @command_bounds.delete(call_id) if @command_bounds[call_id]&.fetch(:index) == index
+        end
 
-                part.refusal << event[:delta]
-              else
-                return unavailable unless event[:refusal].is_a?(String)
+        record = @items[index] = make_record(item, full: true)
+        @ids[id] = index if id.is_a?(String)
+        update_bound(record, index)
+        @phase = :provisional
+      end
 
-                part.refusal = event[:refusal]
-              end
+      def make_record(item, full:)
+        kind = item[:type]&.to_s
+        {
+          item: item,
+          full: full,
+          kind: kind,
+          bound_id: item[:id],
+          content: part_collection?(kind, :content) ? indexed_parts(item[:content]) : {},
+          summary: part_collection?(kind, :summary) ? indexed_parts(item[:summary]) : {},
+          commands: kind == "shell_call" && item[:action].is_a?(Hash) && item[:action][:commands].is_a?(Array) ? item[
+            :action
+          ][:commands]
+            .each_with_index
+            .to_h { |value, index| [index, value] } : {}
+        }
+      end
 
-              return
-            when OpenAI::Responses::ResponseOutputTextAnnotationAddedEvent
-              part = item.content[part_index]
-              annotation_index = event[:annotation_index]
-              unless part.is_a?(OpenAI::Responses::ResponseOutputText) &&
-                  part[:annotations].is_a?(Array) &&
-                  annotation_index.is_a?(Integer) &&
-                  annotation_index >= 0 &&
-                  annotation_index <= part[:annotations].length &&
-                  (event[:annotation].is_a?(OpenAI::Internal::Type::BaseModel) || event[:annotation].is_a?(Hash))
-                return unavailable
-              end
+      def indexed_parts(parts)
+        return {} unless parts.is_a?(Array)
+
+        parts.each_with_index.to_h { |part, index| [index, make_part(part, full: true)] }
+      end
+
+      def make_part(part, full:)
+        {
+          part: part,
+          full: full,
+          kind: part[:type]&.to_s,
+          annotations: part[:type].to_s == "output_text" && part[:annotations].is_a?(Array) ? part[:annotations]
+            .each_with_index
+            .to_h { |value, index|
+              [index, value]
+            } : {}
+        }
+      end
+
+      def part_for(record, collection, index, kind)
+        part = record[collection][index]
+        return unavailable if part && part[:kind] && part[:kind] != kind
+
+        part ||= (record[collection][index] = make_part({}, full: false))
+        part[:kind] ||= kind
+        part
+      end
+
+      def put_part(record, collection, index, part)
+        record[collection][index] = make_part(part, full: true)
+        sync_array(record[:item][collection], record[collection], index) { |value| value[:part] }
+      end
+
+      # Grow only through actual contiguous observations, never through a hole.
+      def sync_array(array, values, index)
+        return unless array.is_a?(Array)
+
+        if index < array.length
+          value = values[index]
+          array[index] = block_given? ? yield(value) : value
+        end
+
+        while values.key?(array.length)
+          value = values[array.length]
+          array << (block_given? ? yield(value) : value)
+        end
+      end
+
+      def update_bound(record, index)
+        return unless record[:kind] == "shell_call"
+
+        call_id = record[:item][:call_id]
+        commands = record[:item].dig(:action, :commands)
+        return unless call_id.is_a?(String)
+
+        if commands.is_a?(Array) && commands.length == record[:commands].length
+          @command_bounds[call_id] = {index: index, count: commands.length}
+        else
+          @command_bounds.delete(call_id)
+        end
+      end
+
+      def update_string(fields, field, value, done:, nullable: false, required: false)
+        if done
+          fields[field] = value
+        else
+          return unavailable if required && !fields.key?(field)
+
+          old = fields[field]
+          return unavailable if fields.key?(field) && !old.is_a?(String) && !(nullable && old.nil?)
 
-              # The event and output use distinct annotation union types.
-              # Snapshot copying reconstructs this value as an output annotation.
-              part[:annotations][annotation_index] = event[:annotation]
-              return
+          (fields[field] ||= +"") << value
+        end
+
+        true
+      end
+
+      def project_item(record)
+        item = record[:item].dup
+        %i[content summary].each do |collection|
+          parts = record[collection]
+          unless part_collection?(record[:kind], collection) &&
+              (item[collection].is_a?(Array) || parts[0]&.fetch(:full))
+            next
+          end
+
+          item[collection] = []
+          while (part = parts[item[collection].length]) && part[:full]
+            value = part[:part].dup
+            if part[:kind] == "output_text" && (value[:annotations].is_a?(Array) || part[:annotations].key?(0))
+              value[:annotations] = prefix(part[:annotations])
             end
+
+            item[collection] << value
           end
+        end
+
+        if record[:kind] == "shell_call" && item.dig(:action, :commands).is_a?(Array)
+          item[:action] = item[:action].dup
+          item[:action][:commands] = prefix(record[:commands])
+        end
+
+        copy(item)
+      end
 
-          @state.accumulate_output(event, @output)
+      def prefix(values)
+        result = []
+        while values.key?(result.length)
+          value = values[result.length]
+          break if value.nil?
+
+          result << value
         end
+
+        result
+      end
+
+      def detailed_item(index, record)
+        item = record[:item].dup
+        result = {output_index: index, item: item}
+        %i[content summary].each do |collection|
+          parts = record[collection]
+          full_array = part_collection?(record[:kind], collection) && item[collection].is_a?(Array)
+          next unless full_array || !parts.empty?
+
+          item.delete(collection) if full_array
+          key = record[:kind] == "shell_call_output" ? :command_index : (collection == :summary ? :summary_index : :content_index)
+          result[collection] = parts.keys.sort.map do |part_index|
+            part = parts.fetch(part_index)
+            value = part[:part].dup
+            if part[:kind] == "output_text" && (value[:annotations].is_a?(Array) || !part[:annotations].empty?)
+              value.delete(:annotations)
+              value[:annotations] = part[:annotations].keys.sort.map do |annotation_index|
+                {annotation_index: annotation_index, annotation: part[:annotations].fetch(annotation_index)}
+              end
+            end
+
+            {key => part_index, :part => value}
+          end
+        end
+
+        if record[:kind] == "shell_call" && (item.dig(:action, :commands).is_a?(Array) || !record[:commands].empty?)
+          item[:action] = item[:action].dup if item[:action].is_a?(Hash)
+          item[:action]&.delete(:commands)
+          result[:commands] = record[:commands].keys.sort.map do |command_index|
+            {command_index: command_index, command: record[:commands].fetch(command_index)}
+          end
+        end
+
+        result
+      end
+
+      def observed_text(records)
+        records
+          .flat_map do |record|
+            next [] unless record[:kind] == "message"
+
+            record[:content].keys.sort.filter_map do |index|
+              part = record[:content].fetch(index)
+              text = part[:part][:text]
+              text if part[:kind] == "output_text" && text.is_a?(String)
+            end
+          end
+          .join
+      end
+
+      def part_collection?(kind, collection)
+        kind == "reasoning" || (kind == "message" && collection == :content)
+      end
+
+      def valid_index?(index)
+        index.is_a?(Integer) && index >= 0
       end
 
       def unavailable
@@ -234,8 +580,8 @@ module OpenAI
         nil
       end
 
-      # BaseModel's recursive representation copies containers but retains string
-      # references. Returned snapshots and incoming events must not share strings.
+      # BaseModel's recursive representation retains strings. Both incoming data
+      # and read views must cross this copy boundary before their owner can mutate.
       def copy(value)
         data = OpenAI::Internal::Type::BaseModel.recursively_to_h(value, convert: false)
         data = parse_json(generate_json(data))