lex-llm 0.6.2 → 0.6.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92e15ead2801ddcfdb692c3135b0a8774bf6ffbc137e70562afaf107dcd182da
-  data.tar.gz: 79ac6bb87c7c57f22857982096fe7818f1d07de3c62b7dbd114588451ed494cb
+  metadata.gz: 6401d7f1b284c2cee7577ff84c1ee099f5a8ae872c51e8a8410c8627c8514a16
+  data.tar.gz: 1ae7e5ff99ee54f5aae6dcc1a8cad4c65c9537d6c2ede8992cdd93d4c2933b9c
 SHA512:
-  metadata.gz: c46aaae88b383e6ffd8e24076d64287b7fd04bc0c3108b7f7b760807b5ce38d3b49b88294c5cf183d289255ccfecdf2c6513b63646ac3178cf79136f837f67d2
-  data.tar.gz: 4ca741e7ea3dcd3bfee9ad59a30a0379a130a3a885f344ad9b0e60509b0d4c18e5ef1e2e2bdf8c0c818e313a493357f475c60d7c27219df1c9302a77b2cebfbf
+  metadata.gz: 7575751b784ebe46be8c03591d748fc81e62695ea3142972bc3257f72e44c1822b8d9438ed1f2958c27287f10bcb0ebe4af5081e85f08e57f6ecf10e47c6c253
+  data.tar.gz: 5a7a68f00cce655fe2912e64350c302044cbabc2bafd874d03683d40502e9edfdfc2a987bb7c591ee9d302df0e2a89cae1040c6b22f71e72f1c5700988dd57eb

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.6.4 - 2026-06-30
+
+### Fixed
+- **Canonical Data structs now serialize correctly via MultiJson/Oj/::JSON** — all 10 `Data.define` canonical structs (`ToolCall`, `Message`, `ContentBlock`, `Chunk`, `Params`, `Request`, `Response`, `Thinking`, `ToolDefinition`, `Usage`) now implement `as_json` and `to_json`, delegating to their existing `#to_h` method. Without these callbacks, `MultiJson.dump` (and any JSON encoder) fell back to `obj.to_s` on canonical structs, producing the Ruby `#inspect` dump (e.g. `#<data Legion::Extensions::Llm::Canonical::ToolCall id="toolu_bdrk_...", ...>`) wherever a struct appeared inside a Hash/Array being serialized. This leaked into:
+  - Client responses (`/v1/chat/completions`, `/v1/messages`, `/v1/responses`) — `tool_calls` in assistant message history appeared as inspect strings instead of structured JSON objects, breaking LangGraph/Freelens supervisors that expect structured routing decisions.
+  - Ledger persistence (`llm_message_inference_requests.request_json`) — tool_calls stored as unparseable Ruby inspect strings, breaking history reconstruction on subsequent turns.
+  - AMQP wire payloads — any consumer receiving a message containing canonical structs saw inspect strings instead of structured data.
+  - Debug echo-request (`X-Legion-Debug: echo-request`) — canonical request snapshot contained inspect strings for any `tool_calls` in message history.
+
+  The fix is structural: canonical structs now self-enforce correct JSON serialization at the architectural boundary (per Amendment A of the N×N routing design), so every downstream consumer — ledger, AMQP publisher, client translator, debug formatter — serializes correctly without needing to call `.to_h` explicitly.
+
+## 0.6.3 - 2026-06-25
+
+### Fixed
+- `ContentBlock.from_hash` rescues `NoMethodError` when content arrays contain corrupted String elements (serialized `#inspect` output from prior storage bugs) — returns a text block instead of crashing with `undefined method 'transform_keys' for an instance of String`.
+- `ContentBlock.from_hash` normalizes `output_text`/`input_text` types to `:text` via `TEXT_TYPE_ALIASES` so Responses API content blocks are recognized by `text?` and extracted by `Message#text`.
+- `ContentBlock#to_s` returns clean text for all text-type blocks; `#inspect` returns a concise debug representation instead of the full 18-field Data.define dump.
+- `Canonical::Message#to_s` delegates to `#text` to prevent Array#inspect leaking struct internals into string contexts.
+
 ## 0.6.2 - 2026-06-20
 
 ### Fixed

data/lib/legion/extensions/llm/canonical/chunk.rb

@@ -162,6 +162,15 @@ module Legion
             }.compact
           end
 
+          # MultiJson/Oj/::JSON callback — prevents Data.define #inspect leak into JSON.
+          def as_json(*)
+            to_h
+          end
+
+          def to_json(*)
+            to_h.to_json(*)
+          end
+
           # Type predicate helpers.
           def text_delta? = type == :text_delta
           def thinking_delta? = type == :thinking_delta

data/lib/legion/extensions/llm/canonical/content_block.rb

@@ -6,6 +6,7 @@ module Legion
       module Canonical
         # Typed content block with media_type support per G20a.
         # Ports field vocabulary from Legion::LLM::Types::ContentBlock.
+        # rubocop:disable Lint/ConstantDefinitionInBlock -- required for Data.define block scope
         ContentBlock = ::Data.define(
           :type, :text, :data, :source_type, :media_type,
           :detail, :name, :file_id,
@@ -13,6 +14,8 @@ module Legion
           :source, :start_index, :end_index,
           :code, :message, :cache_control
         ) do
+          TEXT_TYPE_ALIASES = %i[text output_text input_text].freeze
+
           # Build a text content block.
           def self.text(content, cache_control: nil)
             new(
@@ -64,12 +67,17 @@ module Legion
           end
 
           # Build from a Hash (raw provider response or deserialized wire payload).
+          # Rescues NoMethodError from corrupted inputs (e.g. String elements from
+          # prior serialization bugs where ContentBlock#inspect leaked into storage).
           def self.from_hash(source)
             return nil if source.nil?
 
             h = source.transform_keys(&:to_sym)
             type_raw = h.delete(:type)
-            h[:type] = type_raw&.to_sym if type_raw
+            if type_raw
+              type_sym = type_raw.to_sym
+              h[:type] = TEXT_TYPE_ALIASES.include?(type_sym) ? :text : type_sym
+            end
 
             new(
               type: h[:type],
@@ -91,6 +99,10 @@ module Legion
               message: h[:message],
               cache_control: h[:cache_control]
             )
+          rescue NoMethodError => e
+            Legion::Logging.log.warn('[canonical][content_block] from_hash received non-Hash input ' \
+                                     "(#{source.class}): #{e.message}")
+            text(source.to_s)
           end
 
           # Serialize to a Hash for AMQP/fleet/wire transport.
@@ -98,9 +110,31 @@ module Legion
             super.compact
           end
 
+          # MultiJson/Oj/::JSON callback — prevents Data.define #inspect leak into JSON.
+          def as_json(*)
+            to_h
+          end
+
+          def to_json(*)
+            to_h.to_json(*)
+          end
+
+          # Human-readable string — prevents #inspect leaking into user-facing output.
+          def to_s
+            return "[tool_use:#{name}]" if type == :tool_use
+            return '[image]' if type == :image
+
+            text.to_s
+          end
+
+          # Concise inspect — prevents raw Data.define dump in Array#inspect output.
+          def inspect
+            "#<ContentBlock:#{type} #{to_s.slice(0, 80).inspect}>"
+          end
+
           # Whether this block carries textual content.
           def text?
-            type == :text
+            TEXT_TYPE_ALIASES.include?(type)
           end
 
           # Whether this block carries thinking/reasoning content.
@@ -120,6 +154,7 @@ module Legion
         end
 
         ContentBlock::CONTENT_BLOCK_TYPES = %i[text thinking tool_use tool_result image audio video].freeze
+        # rubocop:enable Lint/ConstantDefinitionInBlock
       end
     end
   end

data/lib/legion/extensions/llm/canonical/message.rb

@@ -123,6 +123,20 @@ module Legion
             super.compact
           end
 
+          # MultiJson/Oj/::JSON callback — prevents Data.define #inspect leak into JSON.
+          def as_json(*)
+            to_h
+          end
+
+          def to_json(*)
+            to_h.to_json(*)
+          end
+
+          # Human-readable string — prevents #inspect leaking into user-facing output.
+          def to_s
+            text
+          end
+
           # Minimal provider-facing hash (role + text content).
           def to_provider_hash
             { role: role.to_s, content: text }.compact

data/lib/legion/extensions/llm/canonical/params.rb

@@ -53,6 +53,15 @@ module Legion
           def to_h
             super.compact
           end
+
+          # MultiJson/Oj/::JSON callback — prevents Data.define #inspect leak into JSON.
+          def as_json(*)
+            to_h
+          end
+
+          def to_json(*)
+            to_h.to_json(*)
+          end
         end
         # rubocop:enable Lint/ConstantDefinitionInBlock
       end

data/lib/legion/extensions/llm/canonical/request.rb

@@ -92,6 +92,15 @@ module Legion
             }.compact
           end
 
+          # MultiJson/Oj/::JSON callback — prevents Data.define #inspect leak into JSON.
+          def as_json(*)
+            to_h
+          end
+
+          def to_json(*)
+            to_h.to_json(*)
+          end
+
           def self.normalize_tools(tools)
             return {} if tools.nil? || tools.empty?
 

data/lib/legion/extensions/llm/canonical/response.rb

@@ -104,6 +104,15 @@ module Legion
             end
           end
 
+          # MultiJson/Oj/::JSON callback — prevents Data.define #inspect leak into JSON.
+          def as_json(*)
+            to_h
+          end
+
+          def to_json(*)
+            to_h.to_json(*)
+          end
+
           # Whether the response includes tool calls.
           def tool_call?
             !tool_calls.nil? && !tool_calls.empty?

data/lib/legion/extensions/llm/canonical/thinking.rb

@@ -31,6 +31,15 @@ module Legion
             super.compact
           end
 
+          # MultiJson/Oj/::JSON callback — prevents Data.define #inspect leak into JSON.
+          def as_json(*)
+            to_h
+          end
+
+          def to_json(*)
+            to_h.to_json(*)
+          end
+
           # Whether this thinking block has any content.
           def empty?
             content.nil? && signature.nil?

data/lib/legion/extensions/llm/canonical/tool_call.rb

@@ -106,6 +106,16 @@ module Legion
             super.compact
           end
 
+          # MultiJson/Oj/::JSON callback for unknown types — without this, fallback is
+          # obj.to_s which for Data.define returns the #inspect dump and leaks into JSON.
+          def as_json(*)
+            to_h
+          end
+
+          def to_json(*)
+            to_h.to_json(*)
+          end
+
           # Subset for audit/ledger emission.
           def to_audit_hash
             {

data/lib/legion/extensions/llm/canonical/tool_definition.rb

@@ -91,6 +91,15 @@ module Legion
               parameters: parameters
             }.compact.reject { |k, v| k == :description && v == '' }
           end
+
+          # MultiJson/Oj/::JSON callback — prevents Data.define #inspect leak into JSON.
+          def as_json(*)
+            to_h
+          end
+
+          def to_json(*)
+            to_h.to_json(*)
+          end
         end
       end
     end

data/lib/legion/extensions/llm/canonical/usage.rb

@@ -61,6 +61,15 @@ module Legion
             super.compact
           end
 
+          # MultiJson/Oj/::JSON callback — prevents Data.define #inspect leak into JSON.
+          def as_json(*)
+            to_h
+          end
+
+          def to_json(*)
+            to_h.to_json(*)
+          end
+
           # Total tokens across all categories.
           def total_tokens
             [input_tokens, output_tokens, cache_read_tokens, cache_write_tokens,

data/lib/legion/extensions/llm/version.rb

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Llm
-      VERSION = '0.6.2'
+      VERSION = '0.6.4'
     end
   end
 end

data/spec/legion/extensions/llm/canonical/content_block_spec.rb

@@ -166,6 +166,52 @@ RSpec.describe Legion::Extensions::Llm::Canonical::ContentBlock do
     end
   end
 
+  describe 'Responses API type normalization (output_text/input_text)' do
+    it 'normalizes output_text to :text via from_hash' do
+      block = described_class.from_hash(type: 'output_text', text: 'The seat templates')
+
+      expect(block.type).to eq(:text)
+      expect(block.text).to eq('The seat templates')
+      expect(block.text?).to be true
+    end
+
+    it 'normalizes input_text to :text via from_hash' do
+      block = described_class.from_hash(type: 'input_text', text: 'user message')
+
+      expect(block.type).to eq(:text)
+      expect(block.text?).to be true
+    end
+
+    it 'returns text content from to_s for output_text blocks' do
+      block = described_class.from_hash(type: 'output_text', text: "The seat templates don't")
+
+      expect(block.to_s).to eq("The seat templates don't")
+    end
+
+    it 'does not leak #inspect struct into Array#to_s' do
+      blocks = [described_class.from_hash(type: 'output_text', text: 'hello')]
+
+      expect(blocks.inspect).not_to include('data Legion::Extensions')
+      expect(blocks.inspect).not_to include('source_type=nil')
+    end
+  end
+
+  describe '#to_s' do
+    it 'returns text for text blocks' do
+      expect(described_class.text('hello').to_s).to eq('hello')
+    end
+
+    it 'returns placeholder for tool_use blocks' do
+      block = described_class.tool_use(id: '1', name: 'bash', input: {})
+      expect(block.to_s).to eq('[tool_use:bash]')
+    end
+
+    it 'returns placeholder for image blocks' do
+      block = described_class.image(data: 'x', media_type: 'image/png')
+      expect(block.to_s).to eq('[image]')
+    end
+  end
+
   describe 'round-trip' do
     it 'preserves text block through from_hash/to_h' do
       original = { type: 'text', text: 'hello world' }

data/spec/legion/extensions/llm/canonical/message_spec.rb

@@ -163,6 +163,29 @@ RSpec.describe Legion::Extensions::Llm::Canonical::Message do
 
       expect(msg.text).to eq('')
     end
+
+    it 'extracts text from output_text ContentBlock array (Responses API / Codex)' do
+      msg = described_class.from_hash(
+        role: :assistant,
+        content: [{ type: 'output_text', text: "The seat templates don't" }]
+      )
+
+      expect(msg.text).to eq("The seat templates don't")
+      expect(msg.text).not_to include('#<data')
+      expect(msg.text).not_to include('ContentBlock')
+    end
+
+    it 'extracts text from mixed output_text and text blocks' do
+      msg = described_class.from_hash(
+        role: :assistant,
+        content: [
+          { type: 'output_text', text: 'first ' },
+          { type: 'text', text: 'second' }
+        ]
+      )
+
+      expect(msg.text).to eq('first second')
+    end
   end
 
   describe '#to_h' do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-llm
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.6.4
 platform: ruby
 authors:
 - LegionIO