ag-ui-protocol 0.1.4 → 0.2.0

data/lib/ag_ui_protocol/core/types.rb

@@ -21,11 +21,10 @@ module AgUiProtocol
       # ```ruby
       #
       # AgUiProtocol::Core::Types::Role
-      # # => ["developer", "system", "assistant", "user", "tool", "activity"]
+      # # => ["developer", "system", "assistant", "user", "tool", "activity", "reasoning"]
       #
       # ```
-      # @category Message Types
-      Role = ["developer", "system", "assistant", "user", "tool", "activity"].freeze
+      Role = ["developer", "system", "assistant", "user", "tool", "activity", "reasoning"].freeze
 
       # Base model for protocol entities.
       #
@@ -41,7 +40,7 @@ module AgUiProtocol
         # @return [Hash<Symbol, Object>, raise NotImplementedError]
         sig { returns(T::Hash[Symbol, T.untyped]) }
         def to_h
-          raise NotImplementedError, 'Implement this method by concrect class'
+          raise NotImplementedError, "Implement this method in a concrete subclass"
         end
 
         # Returns a JSON-ready representation.
@@ -119,14 +118,23 @@ module AgUiProtocol
         sig { returns(FunctionCall) }
         attr_reader :function
 
+        sig { returns(T.nilable(String)) }
+        attr_reader :encrypted_value
+
         # @param id [String] Unique identifier for the tool call
         # @param function [FunctionCall, Hash] Function name and arguments
         # @param type [String] Type of the tool call
-        sig { params(id: String, function: T.untyped, type: String).void }
-        def initialize(id:, function:, type: 'function')
+        # @param encrypted_value [String] Encrypted tool call value for zero-data-retention mode
+        sig { params(id: String, function: T.untyped, type: String, encrypted_value: T.nilable(String)).void }
+        def initialize(id:, function:, type: 'function', encrypted_value: nil)
           @id = id
           @type = type
-          @function = function.is_a?(FunctionCall) ? function : FunctionCall.new(**function)
+          @function = if function.is_a?(FunctionCall)
+                       function
+                     else
+                       FunctionCall.new(**function.transform_keys(&:to_sym))
+                     end
+          @encrypted_value = encrypted_value
         end
 
         sig { returns(T::Hash[Symbol, T.untyped]) }
@@ -134,7 +142,8 @@ module AgUiProtocol
           {
             id: @id,
             type: @type,
-            function: @function
+            function: @function,
+            encrypted_value: @encrypted_value
           }
         end
       end
@@ -147,22 +156,35 @@ module AgUiProtocol
         sig { returns(String) }
         attr_reader :role
 
-        sig { returns(T.nilable(T.any(String, T::Array[T.any(TextInputContent, BinaryInputContent)]))) }
+        sig { returns(T.nilable(T.any(String, T::Array[T.any(TextInputContent, BinaryInputContent, ImageInputContent, AudioInputContent, VideoInputContent, DocumentInputContent)]))) }
         attr_reader :content
 
         sig { returns(T.nilable(String)) }
         attr_reader :name
 
+        sig { returns(T.nilable(String)) }
+        attr_reader :encrypted_value
+
         # @param id [String] Unique identifier for the message
         # @param role [String] Role of the message sender
         # @param content [Object] Text content of the message
         # @param name [String] Optional name of the sender
-        sig { params(id: String, role: String, content: T.nilable(T.any(String, T::Array[T.any(TextInputContent, BinaryInputContent)])), name: T.nilable(String)).void }
-        def initialize(id:, role:, content: nil, name: nil)
+        # @param encrypted_value [String] Encrypted content for zero-data-retention mode
+        sig do
+          params(
+            id: String,
+            role: String,
+            content: T.nilable(T.any(String, T::Array[T.any(TextInputContent, BinaryInputContent, ImageInputContent, AudioInputContent, VideoInputContent, DocumentInputContent)])),
+            name: T.nilable(String),
+            encrypted_value: T.nilable(String)
+          ).void
+        end
+        def initialize(id:, role:, content: nil, name: nil, encrypted_value: nil)
           @id = id
           @role = role
           @content = content
           @name = name
+          @encrypted_value = encrypted_value
         end
 
         sig { returns(T::Hash[Symbol, T.untyped]) }
@@ -171,7 +193,8 @@ module AgUiProtocol
             id: @id,
             role: @role,
             content: @content,
-            name: @name
+            name: @name,
+            encrypted_value: @encrypted_value
           }
         end
       end
@@ -247,13 +270,23 @@ module AgUiProtocol
 
         # @param id [String] Unique identifier for the message
         # @param content [Object] Text content of the message
-        # @param tool_calls [Array<ToolCall, Hash>] Tool calls made in this message
+        # @param tool_calls [Array<ToolCall, Hash>] Tool calls made in this message; Hashes are normalized to ToolCall instances.
         # @param name [String] Name of the sender
-        sig { params(id: String, content: T.untyped, tool_calls: T.nilable(T::Array[ToolCall]), name: T.nilable(String)).void }
-        def initialize(id:, content: nil, tool_calls: nil, name: nil)
-          super(id: id, role: "assistant", content: content, name: name)
+        # @param encrypted_value [String] Encrypted content for zero-data-retention mode
+        sig do
+          params(
+            id: String,
+            content: T.untyped,
+            tool_calls: T.nilable(T::Array[T.any(ToolCall, T::Hash[T.any(Symbol, String), T.untyped])]),
+            name: T.nilable(String),
+            encrypted_value: T.nilable(String)
+          ).void
+        end
+        def initialize(id:, content: nil, tool_calls: nil, name: nil, encrypted_value: nil)
+          super(id: id, role: "assistant", content: content, name: name, encrypted_value: encrypted_value)
           @tool_calls = tool_calls&.map do |tc|
-            tc.is_a?(ToolCall) ? tc : ToolCall.new(**tc)
+            next tc if tc.is_a?(ToolCall)
+            ToolCall.new(**tc.transform_keys(&:to_sym))
           end
         end
 
@@ -344,8 +377,8 @@ module AgUiProtocol
           ).void
         end
         def initialize(mime_type:, type: "binary", id: nil, url: nil, data: nil, filename: nil)
-          if [id, url, data].all?(&:nil?)
-            raise ArgumentError, "BinaryInputContent requires id, url, or data to be provided."
+          if [id, url, data].none? { |v| v.is_a?(String) && !v.empty? }
+            raise ArgumentError, "BinaryInputContent requires at least one of id, url, or data to be a non-empty string"
           end
 
           @type = type
@@ -384,34 +417,47 @@ module AgUiProtocol
       # ```
       # @category Message Types
       class UserMessage < BaseMessage
-        sig { returns(String) }
-        attr_reader :id
-
-        sig { returns(String) }
-        attr_reader :role
-
-        sig { returns(T.any(String, T::Array[T.any(TextInputContent, BinaryInputContent)])) }
-        attr_reader :content
-
-        sig { returns(T.nilable(String)) }
-        attr_reader :name
-
         # @param id [String] Unique identifier for the message
-        # @param content [String, Array<TextInputContent | BinaryInputContent>] Either a plain text string or an ordered list of multimodal fragments
+        # @param content [String, Array<TextInputContent | BinaryInputContent | ImageInputContent | AudioInputContent | VideoInputContent | DocumentInputContent | Hash>] Accepted shapes: a String for plain text, or an Array whose elements are either *InputContent Models (TextInputContent, BinaryInputContent, ImageInputContent, AudioInputContent, VideoInputContent, DocumentInputContent) OR Hashes with a `type:` key (`text`, `binary`, `image`, `audio`, `video`, `document`); Hash entries are normalized internally to the corresponding Model.
         # @param name [String] Optional name of the sender
-        sig { params(id: String, content: T.any(String, T::Array[T.any(TextInputContent, BinaryInputContent)]), name: T.nilable(String)).void }
-        def initialize(id:, content:, name: nil)
-          super(id: id, role: "user", content: normalize_user_content(content), name: name)
+        # @param encrypted_value [String] Encrypted content for zero-data-retention mode
+        sig do
+          params(
+            id: String,
+            content: T.any(
+              String,
+              T::Array[T.any(
+                TextInputContent, BinaryInputContent, ImageInputContent, AudioInputContent, VideoInputContent, DocumentInputContent,
+                T::Hash[T.any(Symbol, String), T.untyped]
+              )]
+            ),
+            name: T.nilable(String),
+            encrypted_value: T.nilable(String)
+          ).void
+        end
+        def initialize(id:, content:, name: nil, encrypted_value: nil)
+          super(id: id, role: "user", content: normalize_user_content(content), name: name, encrypted_value: encrypted_value)
         end
 
-        sig { params(content: T.any(String, T::Array[T.any(TextInputContent, BinaryInputContent)])).returns(T.any(String, T::Array[T.any(TextInputContent, BinaryInputContent)])) }
+        sig do
+          params(
+            content: T.any(
+              String,
+              T::Array[T.any(
+                TextInputContent, BinaryInputContent, ImageInputContent, AudioInputContent, VideoInputContent, DocumentInputContent,
+                T::Hash[T.any(Symbol, String), T.untyped]
+              )]
+            )
+          ).returns(T.any(String, T::Array[T.any(TextInputContent, BinaryInputContent, ImageInputContent, AudioInputContent, VideoInputContent, DocumentInputContent)]))
+        end
         def normalize_user_content(content)
           if content.is_a?(Array)
             content.map do |c|
               if c.is_a?(Model)
                 c
               elsif c.is_a?(Hash)
-                case c[:type] || c["type"]
+                src_type = c[:type] || c["type"]
+                case src_type
                 when "text"
                   TextInputContent.new(text: c[:text] || c["text"])
                 when "binary"
@@ -420,13 +466,21 @@ module AgUiProtocol
                     id: c[:id] || c["id"],
                     url: c[:url] || c["url"],
                     data: c[:data] || c["data"],
-                    filename: c[:filename] || c["filename"]
+                    filename: c[:filename] || c["filename"] || c[:fileName] || c["fileName"]
                   )
+                when "image"
+                  ImageInputContent.new(source: c[:source] || c["source"], metadata: c[:metadata] || c["metadata"])
+                when "audio"
+                  AudioInputContent.new(source: c[:source] || c["source"], metadata: c[:metadata] || c["metadata"])
+                when "video"
+                  VideoInputContent.new(source: c[:source] || c["source"], metadata: c[:metadata] || c["metadata"])
+                when "document"
+                  DocumentInputContent.new(source: c[:source] || c["source"], metadata: c[:metadata] || c["metadata"])
                 else
-                  c
+                  raise ArgumentError, "Unknown content type: #{src_type.inspect}"
                 end
               else
-                c
+                raise ArgumentError, "Unknown content type: #{c.class}"
               end
             end
           else
@@ -434,15 +488,6 @@ module AgUiProtocol
           end
         end
 
-        sig { returns(T::Hash[Symbol, T.untyped]) }
-        def to_h
-          {
-            id: @id,
-            role: @role,
-            content: @content,
-            name: @name
-          }
-        end
       end
 
       # Tool result message.
@@ -458,15 +503,6 @@ module AgUiProtocol
       # ```
       # @category Message Types
       class ToolMessage < BaseMessage
-        sig { returns(String) }
-        attr_reader :id
-
-        sig { returns(String) }
-        attr_reader :role
-
-        sig { returns(String) }
-        attr_reader :content
-
         sig { returns(String) }
         attr_reader :tool_call_id
 
@@ -477,27 +513,30 @@ module AgUiProtocol
         # @param content [String] Tool result content.
         # @param tool_call_id [String] ID of the tool call this message responds to.
         # @param error [String] Error payload if the tool call failed.
-        sig { params(id: String, content: String, tool_call_id: String, error: T.nilable(String)).void }
-        def initialize(id:, content:, tool_call_id:, error: nil)
-          super(id: id, role: "tool", content: content)
+        # @param encrypted_value [String] Encrypted tool message value for zero-data-retention mode
+        sig { params(id: String, content: String, tool_call_id: String, error: T.nilable(String), encrypted_value: T.nilable(String)).void }
+        def initialize(id:, content:, tool_call_id:, error: nil, encrypted_value: nil)
+          super(id: id, role: "tool", content: content, encrypted_value: encrypted_value)
           @tool_call_id = tool_call_id
           @error = error
         end
 
         sig { returns(T::Hash[Symbol, T.untyped]) }
         def to_h
-          {
-            id: @id,
-            role: @role,
-            content: @content,
+          super.merge(
             tool_call_id: @tool_call_id,
             error: @error
-          }
+          )
         end
       end
 
       # Represents structured activity progress emitted between chat messages.
       #
+      # ActivityMessage intentionally does NOT inherit from BaseMessage because its
+      # `content` is a structured Hash rather than text/multimodal, which is
+      # incompatible with BaseMessage#content's type. It still appears alongside
+      # other messages in the stream but is modeled as its own shape.
+      #
       # ```ruby
       #
       # msg = AgUiProtocol::Core::Types::ActivityMessage.new(
@@ -508,7 +547,7 @@ module AgUiProtocol
       #
       # ```
       # @category Message Types
-      class ActivityMessage < BaseMessage
+      class ActivityMessage < Model
         sig { returns(String) }
         attr_reader :id
 
@@ -527,7 +566,7 @@ module AgUiProtocol
         sig { params(id: String, activity_type: String, content: T::Hash[T.any(Symbol, String), T.untyped]).void }
         def initialize(id:, activity_type:, content:)
           @id = id
-          @role = 'activity'
+          @role = "activity"
           @activity_type = activity_type
           @content = content
         end
@@ -538,7 +577,8 @@ module AgUiProtocol
             id: @id,
             role: @role,
             activity_type: @activity_type,
-            content: @content
+            # `content` is an arbitrary user-supplied payload — preserve keys verbatim on the wire.
+            content: @content.nil? ? nil : AgUiProtocol::Util::Opaque.new(@content)
           }
         end
       end
@@ -610,7 +650,453 @@ module AgUiProtocol
           {
             name: @name,
             description: @description,
-            parameters: @parameters
+            # `parameters` is a JSON Schema document supplied by the user — preserve keys verbatim.
+            parameters: @parameters.nil? ? nil : AgUiProtocol::Util::Opaque.new(@parameters)
+          }
+        end
+      end
+
+      # Represents a data source for multimodal input content using base64-encoded data.
+      #
+      # ```ruby
+      #
+      # source = AgUiProtocol::Core::Types::InputContentDataSource.new(
+      #   value: "base64encoded...",
+      #   mime_type: "image/png"
+      # )
+      #
+      # ```
+      class InputContentDataSource < Model
+        sig { returns(String) }
+        attr_reader :type
+
+        sig { returns(String) }
+        attr_reader :value
+
+        sig { returns(String) }
+        attr_reader :mime_type
+
+        # @param value [String] Base64 encoded content
+        # @param mime_type [String] MIME type of the content
+        # @param type [String] Identifies the source type
+        sig { params(value: String, mime_type: String, type: String).void }
+        def initialize(value:, mime_type:, type: "data")
+          @type = type
+          @value = value
+          @mime_type = mime_type
+        end
+
+        sig { returns(T::Hash[Symbol, T.untyped]) }
+        def to_h
+          {
+            type: @type,
+            value: @value,
+            mime_type: @mime_type
+          }
+        end
+      end
+
+      # Represents a URL source for multimodal input content.
+      #
+      # ```ruby
+      #
+      # source = AgUiProtocol::Core::Types::InputContentUrlSource.new(
+      #   value: "https://example.com/image.png",
+      #   mime_type: "image/png"
+      # )
+      #
+      # ```
+      class InputContentUrlSource < Model
+        sig { returns(String) }
+        attr_reader :type
+
+        sig { returns(String) }
+        attr_reader :value
+
+        sig { returns(T.nilable(String)) }
+        attr_reader :mime_type
+
+        # @param value [String] URL string
+        # @param mime_type [String] Optional MIME type
+        # @param type [String] Identifies the source type
+        sig { params(value: String, mime_type: T.nilable(String), type: String).void }
+        def initialize(value:, mime_type: nil, type: "url")
+          @type = type
+          @value = value
+          @mime_type = mime_type
+        end
+
+        sig { returns(T::Hash[Symbol, T.untyped]) }
+        def to_h
+          {
+            type: @type,
+            value: @value,
+            mime_type: @mime_type
+          }
+        end
+      end
+
+      # Represents an image content fragment inside a multimodal user message.
+      #
+      # ```ruby
+      #
+      # content = AgUiProtocol::Core::Types::ImageInputContent.new(
+      #   source: { type: "url", value: "https://example.com/cat.png", mime_type: "image/png" }
+      # )
+      #
+      # ```
+      class ImageInputContent < Model
+        sig { returns(String) }
+        attr_reader :type
+
+        sig { returns(T.any(InputContentDataSource, InputContentUrlSource)) }
+        attr_reader :source
+
+        sig { returns(T.untyped) }
+        attr_reader :metadata
+
+        # @param source [InputContentDataSource, InputContentUrlSource, Hash] Content source
+        # @param metadata [Object] Optional metadata
+        # @param type [String] Identifies the fragment type
+        sig { params(source: T.untyped, metadata: T.untyped, type: String).void }
+        def initialize(source:, metadata: nil, type: "image")
+          @type = type
+          @source = source.is_a?(Hash) ? build_source(source) : source
+          @metadata = metadata
+        end
+
+        sig { returns(T::Hash[Symbol, T.untyped]) }
+        def to_h
+          {
+            type: @type,
+            source: @source,
+            metadata: @metadata
+          }
+        end
+
+        private
+
+        def build_source(hash)
+          src_type = hash[:type] || hash["type"]
+          value = hash[:value] || hash["value"]
+          mime_type = hash[:mime_type] || hash["mime_type"] || hash[:mimeType] || hash["mimeType"]
+          case src_type
+          when "data"
+            InputContentDataSource.new(value: value, mime_type: mime_type)
+          when "url"
+            InputContentUrlSource.new(value: value, mime_type: mime_type)
+          else
+            raise ArgumentError, "Unknown source type: #{src_type.inspect}"
+          end
+        end
+      end
+
+      # Represents an audio content fragment inside a multimodal user message.
+      #
+      # ```ruby
+      #
+      # content = AgUiProtocol::Core::Types::AudioInputContent.new(
+      #   source: { type: "url", value: "https://example.com/audio.mp3", mime_type: "audio/mp3" }
+      # )
+      #
+      # ```
+      class AudioInputContent < Model
+        sig { returns(String) }
+        attr_reader :type
+
+        sig { returns(T.any(InputContentDataSource, InputContentUrlSource)) }
+        attr_reader :source
+
+        sig { returns(T.untyped) }
+        attr_reader :metadata
+
+        # @param source [InputContentDataSource, InputContentUrlSource, Hash] Content source
+        # @param metadata [Object] Optional metadata
+        # @param type [String] Identifies the fragment type
+        sig { params(source: T.untyped, metadata: T.untyped, type: String).void }
+        def initialize(source:, metadata: nil, type: "audio")
+          @type = type
+          @source = source.is_a?(Hash) ? build_source(source) : source
+          @metadata = metadata
+        end
+
+        sig { returns(T::Hash[Symbol, T.untyped]) }
+        def to_h
+          {
+            type: @type,
+            source: @source,
+            metadata: @metadata
+          }
+        end
+
+        private
+
+        def build_source(hash)
+          src_type = hash[:type] || hash["type"]
+          value = hash[:value] || hash["value"]
+          mime_type = hash[:mime_type] || hash["mime_type"] || hash[:mimeType] || hash["mimeType"]
+          case src_type
+          when "data"
+            InputContentDataSource.new(value: value, mime_type: mime_type)
+          when "url"
+            InputContentUrlSource.new(value: value, mime_type: mime_type)
+          else
+            raise ArgumentError, "Unknown source type: #{src_type.inspect}"
+          end
+        end
+      end
+
+      # Represents a video content fragment inside a multimodal user message.
+      #
+      # ```ruby
+      #
+      # content = AgUiProtocol::Core::Types::VideoInputContent.new(
+      #   source: { type: "url", value: "https://example.com/video.mp4", mime_type: "video/mp4" }
+      # )
+      #
+      # ```
+      class VideoInputContent < Model
+        sig { returns(String) }
+        attr_reader :type
+
+        sig { returns(T.any(InputContentDataSource, InputContentUrlSource)) }
+        attr_reader :source
+
+        sig { returns(T.untyped) }
+        attr_reader :metadata
+
+        # @param source [InputContentDataSource, InputContentUrlSource, Hash] Content source
+        # @param metadata [Object] Optional metadata
+        # @param type [String] Identifies the fragment type
+        sig { params(source: T.untyped, metadata: T.untyped, type: String).void }
+        def initialize(source:, metadata: nil, type: "video")
+          @type = type
+          @source = source.is_a?(Hash) ? build_source(source) : source
+          @metadata = metadata
+        end
+
+        sig { returns(T::Hash[Symbol, T.untyped]) }
+        def to_h
+          {
+            type: @type,
+            source: @source,
+            metadata: @metadata
+          }
+        end
+
+        private
+
+        def build_source(hash)
+          src_type = hash[:type] || hash["type"]
+          value = hash[:value] || hash["value"]
+          mime_type = hash[:mime_type] || hash["mime_type"] || hash[:mimeType] || hash["mimeType"]
+          case src_type
+          when "data"
+            InputContentDataSource.new(value: value, mime_type: mime_type)
+          when "url"
+            InputContentUrlSource.new(value: value, mime_type: mime_type)
+          else
+            raise ArgumentError, "Unknown source type: #{src_type.inspect}"
+          end
+        end
+      end
+
+      # Represents a document content fragment inside a multimodal user message.
+      #
+      # ```ruby
+      #
+      # content = AgUiProtocol::Core::Types::DocumentInputContent.new(
+      #   source: { type: "url", value: "https://example.com/doc.pdf", mime_type: "application/pdf" }
+      # )
+      #
+      # ```
+      class DocumentInputContent < Model
+        sig { returns(String) }
+        attr_reader :type
+
+        sig { returns(T.any(InputContentDataSource, InputContentUrlSource)) }
+        attr_reader :source
+
+        sig { returns(T.untyped) }
+        attr_reader :metadata
+
+        # @param source [InputContentDataSource, InputContentUrlSource, Hash] Content source
+        # @param metadata [Object] Optional metadata
+        # @param type [String] Identifies the fragment type
+        sig { params(source: T.untyped, metadata: T.untyped, type: String).void }
+        def initialize(source:, metadata: nil, type: "document")
+          @type = type
+          @source = source.is_a?(Hash) ? build_source(source) : source
+          @metadata = metadata
+        end
+
+        sig { returns(T::Hash[Symbol, T.untyped]) }
+        def to_h
+          {
+            type: @type,
+            source: @source,
+            metadata: @metadata
+          }
+        end
+
+        private
+
+        def build_source(hash)
+          src_type = hash[:type] || hash["type"]
+          value = hash[:value] || hash["value"]
+          mime_type = hash[:mime_type] || hash["mime_type"] || hash[:mimeType] || hash["mimeType"]
+          case src_type
+          when "data"
+            InputContentDataSource.new(value: value, mime_type: mime_type)
+          when "url"
+            InputContentUrlSource.new(value: value, mime_type: mime_type)
+          else
+            raise ArgumentError, "Unknown source type: #{src_type.inspect}"
+          end
+        end
+      end
+
+      # Represents a reasoning message from an agent with chain-of-thought content.
+      #
+      # ```ruby
+      #
+      # msg = AgUiProtocol::Core::Types::ReasoningMessage.new(
+      #   id: "reason_1",
+      #   content: "Let me think through this step by step...",
+      #   encrypted_value: nil
+      # )
+      #
+      # ```
+      class ReasoningMessage < BaseMessage
+
+        sig { returns(String) }
+        attr_reader :content
+
+        # @param id [String] Unique identifier for the message
+        # @param content [String] Reasoning content (plaintext when not encrypted)
+        # @param encrypted_value [String] Encrypted reasoning content when in zero-data-retention mode
+        sig { params(id: String, content: String, encrypted_value: T.nilable(String)).void }
+        def initialize(id:, content:, encrypted_value: nil)
+          super(id: id, role: "reasoning", content: content, encrypted_value: encrypted_value)
+        end
+      end
+
+      # Represents an interrupt that occurred during agent execution for human-in-the-loop workflows.
+      #
+      # ```ruby
+      #
+      # interrupt = AgUiProtocol::Core::Types::Interrupt.new(
+      #   id: "int_1",
+      #   reason: "input_required",
+      #   message: "Please provide additional information"
+      # )
+      #
+      # ```
+      class Interrupt < Model
+        sig { returns(String) }
+        attr_reader :id
+
+        sig { returns(String) }
+        attr_reader :reason
+
+        sig { returns(T.nilable(String)) }
+        attr_reader :message
+
+        sig { returns(T.nilable(String)) }
+        attr_reader :tool_call_id
+
+        sig { returns(T.untyped) }
+        attr_reader :response_schema
+
+        sig { returns(T.nilable(String)) }
+        attr_reader :expires_at
+
+        sig { returns(T.untyped) }
+        attr_reader :metadata
+
+        # @param id [String] Unique identifier
+        # @param reason [String] Reason for the interrupt
+        # @param message [String] Human-readable message
+        # @param tool_call_id [String] Associated tool call if applicable
+        # @param response_schema [Object] JSON schema for response
+        # @param expires_at [String] ISO timestamp when interrupt expires
+        # @param metadata [Object] Arbitrary metadata
+        sig do
+          params(
+            id: String,
+            reason: String,
+            message: T.nilable(String),
+            tool_call_id: T.nilable(String),
+            response_schema: T.untyped,
+            expires_at: T.nilable(String),
+            metadata: T.untyped
+          ).void
+        end
+        def initialize(id:, reason:, message: nil, tool_call_id: nil, response_schema: nil, expires_at: nil, metadata: nil)
+          @id = id
+          @reason = reason
+          @message = message
+          @tool_call_id = tool_call_id
+          @response_schema = response_schema
+          @expires_at = expires_at
+          @metadata = metadata
+        end
+
+        sig { returns(T::Hash[Symbol, T.untyped]) }
+        def to_h
+          {
+            id: @id,
+            reason: @reason,
+            message: @message,
+            tool_call_id: @tool_call_id,
+            # `response_schema` is a JSON Schema document supplied by the user — preserve keys verbatim.
+            response_schema: @response_schema.nil? ? nil : AgUiProtocol::Util::Opaque.new(@response_schema),
+            expires_at: @expires_at,
+            # `metadata` is arbitrary user-defined key/value data — preserve keys verbatim.
+            metadata: @metadata.nil? ? nil : AgUiProtocol::Util::Opaque.new(@metadata)
+          }
+        end
+      end
+
+      # Represents an entry for resuming an interrupted run.
+      #
+      # ```ruby
+      #
+      # entry = AgUiProtocol::Core::Types::ResumeEntry.new(
+      #   interrupt_id: "int_1",
+      #   status: "resolved",
+      #   payload: { "answer" => "42" }
+      # )
+      #
+      # ```
+      class ResumeEntry < Model
+        sig { returns(String) }
+        attr_reader :interrupt_id
+
+        # Free-form string; protocol values are "resolved" or "cancelled" but not enforced by this SDK.
+        sig { returns(T.nilable(String)) }
+        attr_reader :status
+
+        sig { returns(T.untyped) }
+        attr_reader :payload
+
+        # @param interrupt_id [String] ID of the interrupt being resolved
+        # @param status [String] Resolution status (free-form; protocol values are "resolved" or "cancelled")
+        # @param payload [Object] Response payload for the interrupt
+        sig { params(interrupt_id: String, status: T.nilable(String), payload: T.untyped).void }
+        def initialize(interrupt_id:, status: nil, payload: nil)
+          @interrupt_id = interrupt_id
+          @status = status
+          @payload = payload
+        end
+
+        sig { returns(T::Hash[Symbol, T.untyped]) }
+        def to_h
+          {
+            interrupt_id: @interrupt_id,
+            status: @status,
+            # `payload` is the user's resume response — preserve keys verbatim.
+            payload: @payload.nil? ? nil : AgUiProtocol::Util::Opaque.new(@payload)
           }
         end
       end
@@ -644,7 +1130,7 @@ module AgUiProtocol
         sig { returns(T.untyped) }
         attr_reader :state
 
-        sig { returns(T::Array[BaseMessage]) }
+        sig { returns(T::Array[T.any(BaseMessage, ActivityMessage)]) }
         attr_reader :messages
 
         sig { returns(T::Array[Tool]) }
@@ -656,30 +1142,35 @@ module AgUiProtocol
         sig { returns(T.untyped) }
         attr_reader :forwarded_props
 
+        sig { returns(T.nilable(T::Array[ResumeEntry])) }
+        attr_reader :resume
+
         # @param thread_id [String] ID of the conversation thread
         # @param run_id [String] ID of the current run
         # @param state [Object] Current state of the agent
-        # @param messages [Array<BaseMessage>] List of messages in the conversation
+        # @param messages [Array<BaseMessage, ActivityMessage>] List of messages in the conversation
         # @param tools [Array<Tool>] List of tools available to the agent
         # @param context [Array<Context>] List of context objects provided to the agent
         # @param forwarded_props [Object] Additional properties forwarded to the agent
         # @param parent_run_id [String] Lineage pointer for branching/time travel
-        # @raise [ArgumentError] if messages is not an Array of BaseMessage
+        # @param resume [Array<ResumeEntry>] Entries for resuming interrupted runs
+        # @raise [ArgumentError] if messages is not an Array of BaseMessage or ActivityMessage
         sig do
           params(
             thread_id: String,
             run_id: String,
             state: T.untyped,
-            messages: T::Array[BaseMessage],
+            messages: T::Array[T.any(BaseMessage, ActivityMessage)],
             tools: T::Array[Tool],
             context: T::Array[Context],
             forwarded_props: T.untyped,
-            parent_run_id: T.nilable(String)
+            parent_run_id: T.nilable(String),
+            resume: T.nilable(T::Array[ResumeEntry])
           ).void.checked(:always)
         end
-        def initialize(thread_id:, run_id:, state:, messages:, tools:, context:, forwarded_props:, parent_run_id: nil)
-          unless messages.is_a?(Array) && messages.all? { |m| m.is_a?(BaseMessage) }
-            raise ArgumentError, "messages must be an Array of BaseMessage"
+        def initialize(thread_id:, run_id:, state:, messages:, tools:, context:, forwarded_props:, parent_run_id: nil, resume: nil)
+          unless messages.is_a?(Array) && messages.all? { |m| m.is_a?(BaseMessage) || m.is_a?(ActivityMessage) }
+            raise ArgumentError, "messages must be an Array of BaseMessage or ActivityMessage"
           end
           unless tools.is_a?(Array) && tools.all? { |m| m.is_a?(Tool) }
             raise ArgumentError, "tools must be an Array of Tool"
@@ -687,6 +1178,9 @@ module AgUiProtocol
           unless context.is_a?(Array) && context.all? { |m| m.is_a?(Context) }
             raise ArgumentError, "context must be an Array of Context"
           end
+          unless resume.nil? || (resume.is_a?(Array) && resume.all? { |r| r.is_a?(ResumeEntry) })
+            raise ArgumentError, "resume must be an Array of ResumeEntry"
+          end
 
           @thread_id = thread_id
           @run_id = run_id
@@ -696,6 +1190,7 @@ module AgUiProtocol
           @tools = tools
           @context = context
           @forwarded_props = forwarded_props
+          @resume = resume
         end
 
         sig { returns(T::Hash[Symbol, T.untyped]) }
@@ -704,11 +1199,14 @@ module AgUiProtocol
             thread_id: @thread_id,
             run_id: @run_id,
             parent_run_id: @parent_run_id,
-            state: @state,
+            # `state` is the agent's user-defined state object — preserve keys verbatim.
+            state: @state.nil? ? nil : AgUiProtocol::Util::Opaque.new(@state),
             messages: @messages,
             tools: @tools,
             context: @context,
-            forwarded_props: @forwarded_props
+            # `forwarded_props` is arbitrary user-defined key/value data — preserve keys verbatim.
+            forwarded_props: @forwarded_props.nil? ? nil : AgUiProtocol::Util::Opaque.new(@forwarded_props),
+            resume: @resume
           }
         end
       end