feat(schema): wire OpenAI ReasoningExtension into Reasoning block (#1063)

Author: mrh997

adk/middlewares/summarization/finalizer_builder.go

@@ -60,8 +60,6 @@ type TypedFinalizerBuilder[M adk.MessageType] struct {
 
 // FinalizerBuilder is a backward-compatible alias for TypedFinalizerBuilder
 // specialized with *schema.Message.
-//
-// Deprecated: use TypedFinalizerBuilder[*schema.Message] instead.
 type FinalizerBuilder = TypedFinalizerBuilder[*schema.Message]
 
 // NewTypedFinalizer creates a new TypedFinalizerBuilder.
@@ -88,8 +86,6 @@ func NewTypedFinalizer[M adk.MessageType]() *TypedFinalizerBuilder[M] {
 
 // NewFinalizer creates a new FinalizerBuilder that builds a FinalizeFunc
 // by chaining handlers.
-//
-// Deprecated: use NewTypedFinalizer[*schema.Message] instead.
 func NewFinalizer() *FinalizerBuilder {
 	return &FinalizerBuilder{}
 }

schema/agentic_message.go

@@ -165,6 +165,7 @@ type ContentBlock struct {
 	MCPToolApprovalResponse *MCPToolApprovalResponse `json:"mcp_tool_approval_response,omitempty"`
 
 	// StreamingMeta contains metadata for streaming responses.
+	// Only set for streaming responses.
 	StreamingMeta *StreamingMeta `json:"streaming_meta,omitempty"`
 
 	// Extra contains additional information for the content block.
@@ -285,6 +286,9 @@ type Reasoning struct {
 	// Signature contains encrypted reasoning tokens.
 	// Required by some models when passing reasoning text back.
 	Signature string `json:"signature,omitempty"`
+
+	// OpenAIExtension is the extension for OpenAI.
+	OpenAIExtension *openai.ReasoningExtension `json:"openai_extension,omitempty"`
 }
 
 type FunctionToolCall struct {
@@ -1303,20 +1307,35 @@ func genericGetTFromContentBlocks[T any](blocks []*ContentBlock, checkAndGetter
 	return ret, nil
 }
 
-func concatReasoning(reasons []*Reasoning) (*Reasoning, error) {
+func concatReasoning(reasons []*Reasoning) (ret *Reasoning, err error) {
 	if len(reasons) == 0 {
 		return nil, fmt.Errorf("no reasoning found")
 	}
 
-	ret := &Reasoning{}
+	ret = &Reasoning{}
+
+	openaiExtensions := make([]*openai.ReasoningExtension, 0, len(reasons))
 
 	for _, r := range reasons {
+		if r == nil {
+			continue
+		}
 		if r.Text != "" {
 			ret.Text += r.Text
 		}
 		if r.Signature != "" {
 			ret.Signature += r.Signature
 		}
+		if r.OpenAIExtension != nil {
+			openaiExtensions = append(openaiExtensions, r.OpenAIExtension)
+		}
+	}
+
+	if len(openaiExtensions) > 0 {
+		ret.OpenAIExtension, err = openai.ConcatReasoningExtensions(openaiExtensions)
+		if err != nil {
+			return nil, fmt.Errorf("failed to concat openai reasoning extensions: %w", err)
+		}
 	}
 
 	return ret, nil

schema/openai/extension.go

@@ -38,6 +38,19 @@ type AssistantGenTextExtension struct {
 	Annotations []*TextAnnotation `json:"annotations,omitempty"`
 }
 
+type ReasoningExtension struct {
+	// Content is the reasoning text content.
+	Content []*ReasoningContent `json:"content,omitempty"`
+}
+
+type ReasoningContent struct {
+	// Index specifies the index position of this content in the final response.
+	// Only available in streaming response.
+	Index *int `json:"index,omitempty"`
+
+	Text string `json:"text,omitempty"`
+}
+
 type ResponseError struct {
 	Code    ResponseErrorCode `json:"code,omitempty"`
 	Message string            `json:"message,omitempty"`
@@ -57,6 +70,8 @@ type OutputRefusal struct {
 }
 
 type TextAnnotation struct {
+	// Index specifies the index position of this annotation in the final response.
+	// Only available in streaming response.
 	Index int `json:"index,omitempty"`
 
 	Type TextAnnotationType `json:"type,omitempty"`
@@ -167,6 +182,62 @@ func ConcatAssistantGenTextExtensions(chunks []*AssistantGenTextExtension) (*Ass
 	return ret, nil
 }
 
+// ConcatReasoningExtensions concatenates multiple ReasoningExtension chunks into a single one.
+func ConcatReasoningExtensions(chunks []*ReasoningExtension) (*ReasoningExtension, error) {
+	if len(chunks) == 0 {
+		return nil, fmt.Errorf("no reasoning extension found")
+	}
+
+	ret := &ReasoningExtension{}
+
+	var (
+		indices        []int
+		indexToContent = map[int]*ReasoningContent{}
+		hasIndexed     bool
+		hasUnindexed   bool
+	)
+
+	for _, ext := range chunks {
+		if ext == nil {
+			continue
+		}
+		for _, c := range ext.Content {
+			if c == nil {
+				continue
+			}
+
+			if c.Index == nil {
+				hasUnindexed = true
+				ret.Content = append(ret.Content, &ReasoningContent{Text: c.Text})
+				continue
+			}
+
+			hasIndexed = true
+			idx := *c.Index
+			if existing, ok := indexToContent[idx]; ok {
+				existing.Text += c.Text
+			} else {
+				indexToContent[idx] = &ReasoningContent{Text: c.Text}
+				indices = append(indices, idx)
+			}
+		}
+	}
+
+	if hasIndexed && hasUnindexed {
+		return nil, fmt.Errorf("reasoning content chunks mix indexed and non-indexed content")
+	}
+
+	if hasIndexed {
+		sort.Ints(indices)
+		ret.Content = make([]*ReasoningContent, 0, len(indices))
+		for _, idx := range indices {
+			ret.Content = append(ret.Content, indexToContent[idx])
+		}
+	}
+
+	return ret, nil
+}
+
 // ConcatResponseMetaExtensions concatenates multiple ResponseMetaExtension chunks into a single one.
 func ConcatResponseMetaExtensions(chunks []*ResponseMetaExtension) (*ResponseMetaExtension, error) {
 	if len(chunks) == 0 {

schema/openai/extension_test.go

@@ -20,6 +20,8 @@ import (
 	"testing"
 
 	"github.com/stretchr/testify/assert"
+
+	"github.com/cloudwego/eino/internal/generic"
 )
 
 func TestConcatResponseMetaExtensions(t *testing.T) {
@@ -191,3 +193,76 @@ func TestConcatAssistantGenTextExtensions(t *testing.T) {
 		assert.Error(t, err)
 	})
 }
+
+func TestConcatReasoningExtensions(t *testing.T) {
+	t.Run("empty chunks - error", func(t *testing.T) {
+		_, err := ConcatReasoningExtensions(nil)
+		assert.Error(t, err)
+	})
+
+	t.Run("single extension", func(t *testing.T) {
+		ext := &ReasoningExtension{
+			Content: []*ReasoningContent{
+				{Text: "hello", Index: generic.PtrOf(0)},
+			},
+		}
+
+		result, err := ConcatReasoningExtensions([]*ReasoningExtension{ext})
+		assert.NoError(t, err)
+		assert.Len(t, result.Content, 1)
+		assert.Equal(t, "hello", result.Content[0].Text)
+	})
+
+	t.Run("streaming scenario - same index concatenated, ordered by index", func(t *testing.T) {
+		exts := []*ReasoningExtension{
+			{Content: []*ReasoningContent{{Text: "he", Index: generic.PtrOf(0)}}},
+			{Content: []*ReasoningContent{{Text: "first", Index: generic.PtrOf(1)}}},
+			{Content: []*ReasoningContent{{Text: "llo", Index: generic.PtrOf(0)}}},
+		}
+
+		result, err := ConcatReasoningExtensions(exts)
+		assert.NoError(t, err)
+		assert.Len(t, result.Content, 2)
+		assert.Nil(t, result.Content[0].Index)
+		assert.Equal(t, "hello", result.Content[0].Text)
+		assert.Nil(t, result.Content[1].Index)
+		assert.Equal(t, "first", result.Content[1].Text)
+	})
+
+	t.Run("nil extension and nil content skipped", func(t *testing.T) {
+		exts := []*ReasoningExtension{
+			nil,
+			{Content: []*ReasoningContent{nil, {Text: "ok", Index: generic.PtrOf(0)}}},
+		}
+
+		result, err := ConcatReasoningExtensions(exts)
+		assert.NoError(t, err)
+		assert.Len(t, result.Content, 1)
+		assert.Equal(t, "ok", result.Content[0].Text)
+	})
+
+	t.Run("all unindexed - appended in arrival order", func(t *testing.T) {
+		exts := []*ReasoningExtension{
+			{Content: []*ReasoningContent{{Text: "he"}}},
+			{Content: []*ReasoningContent{{Text: "llo"}}},
+		}
+
+		result, err := ConcatReasoningExtensions(exts)
+		assert.NoError(t, err)
+		assert.Len(t, result.Content, 2)
+		assert.Nil(t, result.Content[0].Index)
+		assert.Equal(t, "he", result.Content[0].Text)
+		assert.Nil(t, result.Content[1].Index)
+		assert.Equal(t, "llo", result.Content[1].Text)
+	})
+
+	t.Run("mixed indexed and unindexed - error", func(t *testing.T) {
+		exts := []*ReasoningExtension{
+			{Content: []*ReasoningContent{{Text: "indexed", Index: generic.PtrOf(0)}}},
+			{Content: []*ReasoningContent{{Text: "no meta"}}},
+		}
+
+		_, err := ConcatReasoningExtensions(exts)
+		assert.Error(t, err)
+	})
+}