ag-ui-protocol 0.1.5 → 0.2.0

data/lib/ag_ui_protocol/encoder/event_encoder.rb

@@ -39,11 +39,10 @@ module AgUiProtocol
     # ### Implementation Details
     #
     # Internally, the encoder converts events to JSON and formats them as Server-Sent
-    # Events with the following structure:
+    # Events with the following structure (each event terminated by two literal
+    # newline characters, shown here as escape sequences):
     #
-    # ```
-    # data: {json-serialized event}\n\n
-    # ```
+    #   data: {json-serialized event}\n\n
     #
     # This format allows clients to receive a continuous stream of events and process
     # them as they arrive.

data/lib/ag_ui_protocol/util.rb

@@ -8,13 +8,48 @@ module AgUiProtocol
   # Utility methods for encoding events.
   module Util
     extend T::Sig
+
+    # Marks a value as opaque user-supplied payload that MUST pass through
+    # serialization unchanged — no key camelization, no nil compaction, no
+    # recursive normalization.
+    #
+    # Use this for fields where the AG-UI protocol carries arbitrary
+    # user-defined Hash content (e.g., `metadata`, `custom`, `response_schema`,
+    # JSON Patch op payloads, raw upstream events). Schema-typed fields whose
+    # keys are part of the protocol contract MUST NOT be wrapped — those still
+    # need camelCase rewriting on the wire.
+    #
+    # The wrapper unwraps to its original `value` at the camelization boundary
+    # in {Util.deep_transform_keys_to_camel}. Keys inside the wrapped value
+    # (and any nested Hashes/Arrays within it) are preserved verbatim.
+    class Opaque
+      extend T::Sig
+
+      sig { returns(T.untyped) }
+      attr_reader :value
+
+      sig { params(value: T.untyped).void }
+      def initialize(value)
+        @value = value
+      end
+    end
+
     module_function
 
     # @param value [Object]
     # @return [Object]
     sig { params(value: T.untyped).returns(T.untyped) }
     def normalize_value(value)
-      if value.is_a?(AgUiProtocol::Core::Types::Model)
+      case value
+      when Opaque
+        # Preserve the wrapper so downstream stages can recognize and skip it.
+        value
+      when Time
+        # AG-UI protocol wire format for BaseEvent.timestamp is epoch
+        # milliseconds (matches Python SDK `Optional[int]` and TypeScript
+        # `z.number().optional()`).
+        (value.to_f * 1000).to_i
+      when AgUiProtocol::Core::Types::Model
         value.to_h
       else
         value
@@ -38,6 +73,10 @@ module AgUiProtocol
     def deep_compact(value)
       value = normalize_value(value)
       case value
+      when Opaque
+        # Opaque payloads are pass-through: do not recurse into their content
+        # and do not strip nils. The wrapper is unwrapped during camelization.
+        value
       when Hash
         value.transform_values { |v| deep_compact(v) unless v.nil? }.tap(&:compact!)
       when Array
@@ -55,6 +94,10 @@ module AgUiProtocol
     def deep_transform_keys_to_camel(value)
       value = normalize_value(value)
       case value
+      when Opaque
+        # Unwrap and emit the inner value verbatim — keys (including nested
+        # Hash keys and Array elements) are preserved as supplied by the user.
+        value.value
       when Hash
         value.each_with_object({}) do |(k, v), acc|
           acc[camelize_key(k)] = deep_transform_keys_to_camel(v)

data/lib/ag_ui_protocol/version.rb

@@ -2,5 +2,5 @@
 
 module AgUiProtocol
   # The version of the protocol.
-  VERSION = "0.1.5"
+  VERSION = "0.2.0"
 end

data/lib/ag_ui_protocol.rb

@@ -7,6 +7,7 @@ require_relative "ag_ui_protocol/version"
 require_relative "ag_ui_protocol/util"
 require_relative "ag_ui_protocol/core/types"
 require_relative "ag_ui_protocol/core/events"
+require_relative "ag_ui_protocol/core/capabilities"
 require_relative "ag_ui_protocol/encoder/event_encoder"
 
 module AgUiProtocol

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ag-ui-protocol
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.2.0
 platform: ruby
 authors:
 - Buk
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-11 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -146,6 +145,7 @@ extra_rdoc_files: []
 files:
 - lib/ag-ui-protocol.rb
 - lib/ag_ui_protocol.rb
+- lib/ag_ui_protocol/core/capabilities.rb
 - lib/ag_ui_protocol/core/events.rb
 - lib/ag_ui_protocol/core/types.rb
 - lib/ag_ui_protocol/encoder/event_encoder.rb
@@ -160,7 +160,6 @@ metadata:
   documentation_uri: https://github.com/ag-ui-protocol/ag-ui/blob/main/sdks/community/ruby/README.md
   changelog_uri: https://github.com/ag-ui-protocol/ag-ui/tree/main/sdks/community/ruby/CHANGELOG.md
   homepage_uri: https://docs.ag-ui.com/introduction
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -175,8 +174,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.14
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Ruby SDK for AG-UI protocol
 test_files: []