Add shared state utilities for streaming translators

- Create sdk/translator/state.go with:
- StreamState: Base struct for response metadata, timestamps, finish reasons
- ToolCallState/ToolCallAccumulator: Generic tool call accumulation
- ContentBuffer: Text and reasoning content accumulation
- StreamingState: Combined state for streaming translators
- FinishReasonMapper: Bidirectional finish reason mapping
- Helper functions for ID generation

- Create comprehensive unit tests in sdk/translator/state_test.go

- Migrate Claude translator to use shared state:
- Use embedded translator.StreamState
- Replace local ToolCallAccumulator with shared sdk version
- Use DefaultFinishReasonMapper for stop reason conversion
- Simplify both streaming and non-streaming functions

Co-Authored-By: Claude <noreply@anthropic.com>

internal/translator/claude/openai/chat-completions/claude_openai_response.go

@@ -12,6 +12,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/router-for-me/CLIProxyAPI/v6/sdk/translator"
 	"github.com/tidwall/gjson"
 	"github.com/tidwall/sjson"
 )
@@ -20,20 +21,12 @@ var (
 	dataTag = []byte("data:")
 )
 
-// ConvertAnthropicResponseToOpenAIParams holds parameters for response conversion
+// ConvertAnthropicResponseToOpenAIParams holds parameters for response conversion.
+// It embeds the shared StreamState and uses ToolCallAccumulator from the SDK.
 type ConvertAnthropicResponseToOpenAIParams struct {
-	CreatedAt    int64
-	ResponseID   string
-	FinishReason string
-	// Tool calls accumulator for streaming
-	ToolCallsAccumulator map[int]*ToolCallAccumulator
-}
-
-// ToolCallAccumulator holds the state for accumulating tool call data
-type ToolCallAccumulator struct {
-	ID        string
-	Name      string
-	Arguments strings.Builder
+	translator.StreamState
+	// ToolCalls manages tool call accumulation using the shared SDK utility.
+	ToolCalls *translator.ToolCallAccumulator
 }
 
 // ConvertClaudeResponseToOpenAI converts Claude Code streaming response format to OpenAI Chat Completions format.
@@ -52,12 +45,15 @@ type ToolCallAccumulator struct {
 func ConvertClaudeResponseToOpenAI(_ context.Context, modelName string, originalRequestRawJSON, requestRawJSON, rawJSON []byte, param *any) []string {
 	if *param == nil {
 		*param = &ConvertAnthropicResponseToOpenAIParams{
-			CreatedAt:    0,
-			ResponseID:   "",
-			FinishReason: "",
+			ToolCalls: translator.NewToolCallAccumulator(),
 		}
 	}
 
+	state := (*param).(*ConvertAnthropicResponseToOpenAIParams)
+	if state.ToolCalls == nil {
+		state.ToolCalls = translator.NewToolCallAccumulator()
+	}
+
 	if !bytes.HasPrefix(rawJSON, dataTag) {
 		return []string{}
 	}
@@ -75,31 +71,26 @@ func ConvertClaudeResponseToOpenAI(_ context.Context, modelName string, original
 	}
 
 	// Set response ID and creation time
-	if (*param).(*ConvertAnthropicResponseToOpenAIParams).ResponseID != "" {
-		template, _ = sjson.Set(template, "id", (*param).(*ConvertAnthropicResponseToOpenAIParams).ResponseID)
+	if state.ResponseID != "" {
+		template, _ = sjson.Set(template, "id", state.ResponseID)
 	}
-	if (*param).(*ConvertAnthropicResponseToOpenAIParams).CreatedAt > 0 {
-		template, _ = sjson.Set(template, "created", (*param).(*ConvertAnthropicResponseToOpenAIParams).CreatedAt)
+	if state.CreatedAt > 0 {
+		template, _ = sjson.Set(template, "created", state.CreatedAt)
 	}
 
 	switch eventType {
 	case "message_start":
 		// Initialize response with message metadata when a new message begins
 		if message := root.Get("message"); message.Exists() {
-			(*param).(*ConvertAnthropicResponseToOpenAIParams).ResponseID = message.Get("id").String()
-			(*param).(*ConvertAnthropicResponseToOpenAIParams).CreatedAt = time.Now().Unix()
+			state.ResponseID = message.Get("id").String()
+			state.EnsureTimestamp()
 
-			template, _ = sjson.Set(template, "id", (*param).(*ConvertAnthropicResponseToOpenAIParams).ResponseID)
+			template, _ = sjson.Set(template, "id", state.ResponseID)
 			template, _ = sjson.Set(template, "model", modelName)
-			template, _ = sjson.Set(template, "created", (*param).(*ConvertAnthropicResponseToOpenAIParams).CreatedAt)
+			template, _ = sjson.Set(template, "created", state.CreatedAt)
 
 			// Set initial role to assistant for the response
 			template, _ = sjson.Set(template, "choices.0.delta.role", "assistant")
-
-			// Initialize tool calls accumulator for tracking tool call progress
-			if (*param).(*ConvertAnthropicResponseToOpenAIParams).ToolCallsAccumulator == nil {
-				(*param).(*ConvertAnthropicResponseToOpenAIParams).ToolCallsAccumulator = make(map[int]*ToolCallAccumulator)
-			}
 		}
 		return []string{template}
 
@@ -109,19 +100,11 @@ func ConvertClaudeResponseToOpenAI(_ context.Context, modelName string, original
 			blockType := contentBlock.Get("type").String()
 
 			if blockType == "tool_use" {
-				// Start of tool call - initialize accumulator to track arguments
+				// Start of tool call - create using shared accumulator
 				toolCallID := contentBlock.Get("id").String()
 				toolName := contentBlock.Get("name").String()
-				index := int(root.Get("index").Int())
 
-				if (*param).(*ConvertAnthropicResponseToOpenAIParams).ToolCallsAccumulator == nil {
-					(*param).(*ConvertAnthropicResponseToOpenAIParams).ToolCallsAccumulator = make(map[int]*ToolCallAccumulator)
-				}
-
-				(*param).(*ConvertAnthropicResponseToOpenAIParams).ToolCallsAccumulator[index] = &ToolCallAccumulator{
-					ID:   toolCallID,
-					Name: toolName,
-				}
+				state.ToolCalls.CreateNext(toolCallID, toolName)
 
 				// Don't output anything yet - wait for complete tool call
 				return []string{}
@@ -149,13 +132,11 @@ func ConvertClaudeResponseToOpenAI(_ context.Context, modelName string, original
 					hasContent = true
 				}
 			case "input_json_delta":
-				// Tool use input delta - accumulate arguments for tool calls
+				// Tool use input delta - accumulate arguments using shared utility
 				if partialJSON := delta.Get("partial_json"); partialJSON.Exists() {
 					index := int(root.Get("index").Int())
-					if (*param).(*ConvertAnthropicResponseToOpenAIParams).ToolCallsAccumulator != nil {
-						if accumulator, exists := (*param).(*ConvertAnthropicResponseToOpenAIParams).ToolCallsAccumulator[index]; exists {
-							accumulator.Arguments.WriteString(partialJSON.String())
-						}
+					if tc := state.ToolCalls.Get(index); tc != nil {
+						tc.WriteArguments(partialJSON.String())
 					}
 				}
 				// Don't output anything yet - wait for complete tool call
@@ -171,24 +152,19 @@ func ConvertClaudeResponseToOpenAI(_ context.Context, modelName string, original
 	case "content_block_stop":
 		// End of content block - output complete tool call if it's a tool_use block
 		index := int(root.Get("index").Int())
-		if (*param).(*ConvertAnthropicResponseToOpenAIParams).ToolCallsAccumulator != nil {
-			if accumulator, exists := (*param).(*ConvertAnthropicResponseToOpenAIParams).ToolCallsAccumulator[index]; exists {
-				// Build complete tool call with accumulated arguments
-				arguments := accumulator.Arguments.String()
-				if arguments == "" {
-					arguments = "{}"
-				}
-				template, _ = sjson.Set(template, "choices.0.delta.tool_calls.0.index", index)
-				template, _ = sjson.Set(template, "choices.0.delta.tool_calls.0.id", accumulator.ID)
-				template, _ = sjson.Set(template, "choices.0.delta.tool_calls.0.type", "function")
-				template, _ = sjson.Set(template, "choices.0.delta.tool_calls.0.function.name", accumulator.Name)
-				template, _ = sjson.Set(template, "choices.0.delta.tool_calls.0.function.arguments", arguments)
-
-				// Clean up the accumulator for this index
-				delete((*param).(*ConvertAnthropicResponseToOpenAIParams).ToolCallsAccumulator, index)
+		if tc := state.ToolCalls.MarkComplete(index); tc != nil {
+			// Build complete tool call with accumulated arguments
+			arguments := tc.GetArguments()
+			template, _ = sjson.Set(template, "choices.0.delta.tool_calls.0.index", tc.Index)
+			template, _ = sjson.Set(template, "choices.0.delta.tool_calls.0.id", tc.ID)
+			template, _ = sjson.Set(template, "choices.0.delta.tool_calls.0.type", "function")
+			template, _ = sjson.Set(template, "choices.0.delta.tool_calls.0.function.name", tc.Name)
+			template, _ = sjson.Set(template, "choices.0.delta.tool_calls.0.function.arguments", arguments)
+
+			// Clean up the accumulator for this index
+			state.ToolCalls.Remove(index)
 
-				return []string{template}
-			}
+			return []string{template}
 		}
 		return []string{}
 
@@ -196,8 +172,8 @@ func ConvertClaudeResponseToOpenAI(_ context.Context, modelName string, original
 		// Handle message-level changes including stop reason and usage
 		if delta := root.Get("delta"); delta.Exists() {
 			if stopReason := delta.Get("stop_reason"); stopReason.Exists() {
-				(*param).(*ConvertAnthropicResponseToOpenAIParams).FinishReason = mapAnthropicStopReasonToOpenAI(stopReason.String())
-				template, _ = sjson.Set(template, "choices.0.finish_reason", (*param).(*ConvertAnthropicResponseToOpenAIParams).FinishReason)
+				state.FinishReason = translator.DefaultFinishReasonMapper.ToOpenAI(stopReason.String())
+				template, _ = sjson.Set(template, "choices.0.finish_reason", state.FinishReason)
 			}
 		}
 
@@ -238,22 +214,6 @@ func ConvertClaudeResponseToOpenAI(_ context.Context, modelName string, original
 	}
 }
 
-// mapAnthropicStopReasonToOpenAI maps Anthropic stop reasons to OpenAI stop reasons
-func mapAnthropicStopReasonToOpenAI(anthropicReason string) string {
-	switch anthropicReason {
-	case "end_turn":
-		return "stop"
-	case "tool_use":
-		return "tool_calls"
-	case "max_tokens":
-		return "length"
-	case "stop_sequence":
-		return "stop"
-	default:
-		return "stop"
-	}
-}
-
 // ConvertClaudeResponseToOpenAINonStream converts a non-streaming Claude Code response to a non-streaming OpenAI response.
 // This function processes the complete Claude Code response and transforms it into a single OpenAI-compatible
 // JSON response. It handles message content, tool calls, reasoning content, and usage metadata, combining all
@@ -287,7 +247,7 @@ func ConvertClaudeResponseToOpenAINonStream(_ context.Context, _ string, origina
 	var stopReason string
 	var contentParts []string
 	var reasoningParts []string
-	toolCallsAccumulator := make(map[int]*ToolCallAccumulator)
+	toolCallsAccumulator := translator.NewToolCallAccumulator()
 
 	for _, chunk := range chunks {
 		root := gjson.ParseBytes(chunk)
@@ -310,12 +270,10 @@ func ConvertClaudeResponseToOpenAINonStream(_ context.Context, _ string, origina
 					// Start of thinking/reasoning content - skip for now as it's handled in delta
 					continue
 				} else if blockType == "tool_use" {
-					// Initialize tool call accumulator for this index
-					index := int(root.Get("index").Int())
-					toolCallsAccumulator[index] = &ToolCallAccumulator{
-						ID:   contentBlock.Get("id").String(),
-						Name: contentBlock.Get("name").String(),
-					}
+					// Initialize tool call accumulator for this index using shared utility
+					toolCallID := contentBlock.Get("id").String()
+					toolName := contentBlock.Get("name").String()
+					toolCallsAccumulator.CreateNext(toolCallID, toolName)
 				}
 			}
 
@@ -335,11 +293,11 @@ func ConvertClaudeResponseToOpenAINonStream(_ context.Context, _ string, origina
 						reasoningParts = append(reasoningParts, thinking.String())
 					}
 				case "input_json_delta":
-					// Accumulate tool call arguments
+					// Accumulate tool call arguments using shared utility
 					if partialJSON := delta.Get("partial_json"); partialJSON.Exists() {
 						index := int(root.Get("index").Int())
-						if accumulator, exists := toolCallsAccumulator[index]; exists {
-							accumulator.Arguments.WriteString(partialJSON.String())
+						if tc := toolCallsAccumulator.Get(index); tc != nil {
+							tc.WriteArguments(partialJSON.String())
 						}
 					}
 				}
@@ -348,10 +306,9 @@ func ConvertClaudeResponseToOpenAINonStream(_ context.Context, _ string, origina
 		case "content_block_stop":
 			// Finalize tool call arguments for this index when content block ends
 			index := int(root.Get("index").Int())
-			if accumulator, exists := toolCallsAccumulator[index]; exists {
-				if accumulator.Arguments.Len() == 0 {
-					accumulator.Arguments.WriteString("{}")
-				}
+			if tc := toolCallsAccumulator.Get(index); tc != nil {
+				// Ensure arguments are not empty (GetArguments returns "{}" by default)
+				_ = tc.GetArguments()
 			}
 
 		case "message_delta":
@@ -391,41 +348,29 @@ func ConvertClaudeResponseToOpenAINonStream(_ context.Context, _ string, origina
 	}
 
 	// Set tool calls if any were accumulated during processing
-	if len(toolCallsAccumulator) > 0 {
+	if toolCallsAccumulator.HasAny() {
 		toolCallsCount := 0
-		maxIndex := -1
-		for index := range toolCallsAccumulator {
-			if index > maxIndex {
-				maxIndex = index
-			}
-		}
-
-		for i := 0; i <= maxIndex; i++ {
-			accumulator, exists := toolCallsAccumulator[i]
-			if !exists {
-				continue
-			}
-
-			arguments := accumulator.Arguments.String()
+		for _, tc := range toolCallsAccumulator.GetOrdered() {
+			arguments := tc.GetArguments()
 
 			idPath := fmt.Sprintf("choices.0.message.tool_calls.%d.id", toolCallsCount)
 			typePath := fmt.Sprintf("choices.0.message.tool_calls.%d.type", toolCallsCount)
 			namePath := fmt.Sprintf("choices.0.message.tool_calls.%d.function.name", toolCallsCount)
 			argumentsPath := fmt.Sprintf("choices.0.message.tool_calls.%d.function.arguments", toolCallsCount)
 
-			out, _ = sjson.Set(out, idPath, accumulator.ID)
+			out, _ = sjson.Set(out, idPath, tc.ID)
 			out, _ = sjson.Set(out, typePath, "function")
-			out, _ = sjson.Set(out, namePath, accumulator.Name)
+			out, _ = sjson.Set(out, namePath, tc.Name)
 			out, _ = sjson.Set(out, argumentsPath, arguments)
 			toolCallsCount++
 		}
 		if toolCallsCount > 0 {
 			out, _ = sjson.Set(out, "choices.0.finish_reason", "tool_calls")
 		} else {
-			out, _ = sjson.Set(out, "choices.0.finish_reason", mapAnthropicStopReasonToOpenAI(stopReason))
+			out, _ = sjson.Set(out, "choices.0.finish_reason", translator.DefaultFinishReasonMapper.ToOpenAI(stopReason))
 		}
 	} else {
-		out, _ = sjson.Set(out, "choices.0.finish_reason", mapAnthropicStopReasonToOpenAI(stopReason))
+		out, _ = sjson.Set(out, "choices.0.finish_reason", translator.DefaultFinishReasonMapper.ToOpenAI(stopReason))
 	}
 
 	return out

sdk/translator/state.go

@@ -0,0 +1,328 @@
+// Package translator provides types and functions for converting chat requests and responses between different schemas.
+// This file contains shared state utilities for streaming response translators.
+package translator
+
+import (
+	"fmt"
+	"strings"
+	"sync/atomic"
+	"time"
+)
+
+// StreamState provides common state fields for streaming response translators.
+// Embed this struct into translator-specific state types.
+type StreamState struct {
+	// ResponseID is the unique identifier for the response.
+	ResponseID string
+	// CreatedAt is the Unix timestamp when the response was created.
+	CreatedAt int64
+	// Model is the name of the model being used.
+	Model string
+	// SequenceNum is used for ordered events (e.g., OpenAI Responses API).
+	SequenceNum int
+	// FinishReason is the mapped finish reason in target format.
+	FinishReason string
+	// NativeFinishReason is the original finish reason from the source.
+	NativeFinishReason string
+	// InputTokens tracks the number of input tokens used.
+	InputTokens int64
+	// OutputTokens tracks the number of output tokens used.
+	OutputTokens int64
+	// UsageSeen indicates whether usage data has been processed.
+	UsageSeen bool
+}
+
+// Reset clears the state for reuse.
+func (s *StreamState) Reset() {
+	s.ResponseID = ""
+	s.CreatedAt = 0
+	s.Model = ""
+	s.SequenceNum = 0
+	s.FinishReason = ""
+	s.NativeFinishReason = ""
+	s.InputTokens = 0
+	s.OutputTokens = 0
+	s.UsageSeen = false
+}
+
+// NextSequence returns the next sequence number for event ordering.
+func (s *StreamState) NextSequence() int {
+	s.SequenceNum++
+	return s.SequenceNum
+}
+
+// EnsureTimestamp sets CreatedAt to current time if not already set.
+func (s *StreamState) EnsureTimestamp() int64 {
+	if s.CreatedAt == 0 {
+		s.CreatedAt = time.Now().Unix()
+	}
+	return s.CreatedAt
+}
+
+// ToolCallState tracks the state of a single tool/function call being accumulated.
+type ToolCallState struct {
+	// ID is the unique identifier for this tool call.
+	ID string
+	// Name is the name of the tool/function.
+	Name string
+	// Index is the position of this tool call in the sequence.
+	Index int
+	// Arguments accumulates the JSON arguments for this tool call.
+	Arguments strings.Builder
+	// Complete indicates whether this tool call has been fully received.
+	Complete bool
+}
+
+// GetArguments returns the accumulated arguments, defaulting to "{}" if empty.
+func (t *ToolCallState) GetArguments() string {
+	args := t.Arguments.String()
+	if args == "" {
+		return "{}"
+	}
+	return args
+}
+
+// WriteArguments appends partial argument JSON.
+func (t *ToolCallState) WriteArguments(partial string) {
+	t.Arguments.WriteString(partial)
+}
+
+// ToolCallAccumulator manages multiple concurrent tool calls indexed by position.
+type ToolCallAccumulator struct {
+	// calls maps index -> tool call state.
+	calls map[int]*ToolCallState
+	// ordered tracks the order of indices for deterministic iteration.
+	ordered []int
+	// nextIndex tracks the next available index for new calls.
+	nextIndex int
+}
+
+// NewToolCallAccumulator creates a new accumulator.
+func NewToolCallAccumulator() *ToolCallAccumulator {
+	return &ToolCallAccumulator{
+		calls:     make(map[int]*ToolCallState),
+		ordered:   make([]int, 0),
+		nextIndex: 0,
+	}
+}
+
+// Get retrieves a tool call by index, returning nil if not found.
+func (t *ToolCallAccumulator) Get(index int) *ToolCallState {
+	return t.calls[index]
+}
+
+// GetOrCreate retrieves or creates a tool call at the given index.
+func (t *ToolCallAccumulator) GetOrCreate(index int) *ToolCallState {
+	if tc, exists := t.calls[index]; exists {
+		return tc
+	}
+	tc := &ToolCallState{Index: index}
+	t.calls[index] = tc
+	t.ordered = append(t.ordered, index)
+	return tc
+}
+
+// CreateNext creates a new tool call at the next available index.
+func (t *ToolCallAccumulator) CreateNext(id, name string) *ToolCallState {
+	tc := &ToolCallState{
+		ID:    id,
+		Name:  name,
+		Index: t.nextIndex,
+	}
+	t.calls[t.nextIndex] = tc
+	t.ordered = append(t.ordered, t.nextIndex)
+	t.nextIndex++
+	return tc
+}
+
+// MarkComplete marks a tool call as complete and returns it.
+func (t *ToolCallAccumulator) MarkComplete(index int) *ToolCallState {
+	if tc, exists := t.calls[index]; exists {
+		tc.Complete = true
+		return tc
+	}
+	return nil
+}
+
+// Remove deletes a tool call from the accumulator (cleanup after processing).
+func (t *ToolCallAccumulator) Remove(index int) {
+	delete(t.calls, index)
+	// Rebuild ordered slice
+	newOrdered := make([]int, 0, len(t.calls))
+	for _, idx := range t.ordered {
+		if idx != index {
+			newOrdered = append(newOrdered, idx)
+		}
+	}
+	t.ordered = newOrdered
+}
+
+// HasAny returns true if any tool calls are being tracked.
+func (t *ToolCallAccumulator) HasAny() bool {
+	return len(t.calls) > 0
+}
+
+// Count returns the number of tracked tool calls.
+func (t *ToolCallAccumulator) Count() int {
+	return len(t.calls)
+}
+
+// GetOrdered returns tool calls in the order they were created.
+func (t *ToolCallAccumulator) GetOrdered() []*ToolCallState {
+	result := make([]*ToolCallState, 0, len(t.ordered))
+	for _, idx := range t.ordered {
+		if tc, exists := t.calls[idx]; exists {
+			result = append(result, tc)
+		}
+	}
+	return result
+}
+
+// Reset clears all accumulated state.
+func (t *ToolCallAccumulator) Reset() {
+	t.calls = make(map[int]*ToolCallState)
+	t.ordered = make([]int, 0)
+	t.nextIndex = 0
+}
+
+// ContentBuffer accumulates text and reasoning content.
+type ContentBuffer struct {
+	// Text accumulates the main text content.
+	Text strings.Builder
+	// Reasoning accumulates reasoning/thinking content.
+	Reasoning strings.Builder
+}
+
+// Reset clears the buffers.
+func (c *ContentBuffer) Reset() {
+	c.Text.Reset()
+	c.Reasoning.Reset()
+}
+
+// HasContent returns true if any content has been accumulated.
+func (c *ContentBuffer) HasContent() bool {
+	return c.Text.Len() > 0 || c.Reasoning.Len() > 0
+}
+
+// StreamingState combines all common state for streaming translators.
+type StreamingState struct {
+	StreamState
+	// ToolCalls tracks accumulated tool calls.
+	ToolCalls *ToolCallAccumulator
+	// Content accumulates text and reasoning content.
+	Content ContentBuffer
+	// InTextBlock indicates whether currently processing a text block.
+	InTextBlock bool
+	// InToolBlock indicates whether currently processing a tool block.
+	InToolBlock bool
+	// InReasoningBlock indicates whether currently processing a reasoning block.
+	InReasoningBlock bool
+	// CurrentMessageID is the ID of the current message being processed.
+	CurrentMessageID string
+	// CurrentToolCallID is the ID of the current tool call being processed.
+	CurrentToolCallID string
+	// CurrentReasoningID is the ID of the current reasoning block being processed.
+	CurrentReasoningID string
+}
+
+// NewStreamingState creates a fully initialized streaming state.
+func NewStreamingState() *StreamingState {
+	return &StreamingState{
+		ToolCalls: NewToolCallAccumulator(),
+	}
+}
+
+// Reset clears all state for reuse.
+func (s *StreamingState) Reset() {
+	s.StreamState.Reset()
+	s.ToolCalls.Reset()
+	s.Content.Reset()
+	s.InTextBlock = false
+	s.InToolBlock = false
+	s.InReasoningBlock = false
+	s.CurrentMessageID = ""
+	s.CurrentToolCallID = ""
+	s.CurrentReasoningID = ""
+}
+
+// FinishReasonMapper provides bidirectional finish reason mapping.
+type FinishReasonMapper struct {
+	toOpenAI   map[string]string
+	fromOpenAI map[string]string
+}
+
+// NewFinishReasonMapper creates a mapper with standard OpenAI mappings.
+func NewFinishReasonMapper() *FinishReasonMapper {
+	return &FinishReasonMapper{
+		toOpenAI: map[string]string{
+			// Anthropic/Claude
+			"end_turn":      "stop",
+			"tool_use":      "tool_calls",
+			"max_tokens":    "length",
+			"stop_sequence": "stop",
+			// Gemini
+			"STOP":       "stop",
+			"MAX_TOKENS": "length",
+			"SAFETY":     "content_filter",
+			"RECITATION": "content_filter",
+			"OTHER":      "stop",
+			// Codex
+			"completed": "stop",
+		},
+		fromOpenAI: map[string]string{
+			"stop":           "end_turn",
+			"tool_calls":     "tool_use",
+			"length":         "max_tokens",
+			"content_filter": "SAFETY",
+		},
+	}
+}
+
+// ToOpenAI converts a provider-specific finish reason to OpenAI format.
+func (m *FinishReasonMapper) ToOpenAI(reason string) string {
+	if mapped, ok := m.toOpenAI[reason]; ok {
+		return mapped
+	}
+	return "stop" // default
+}
+
+// FromOpenAI converts an OpenAI finish reason to provider-specific format.
+func (m *FinishReasonMapper) FromOpenAI(reason string) string {
+	if mapped, ok := m.fromOpenAI[reason]; ok {
+		return mapped
+	}
+	return "STOP" // default
+}
+
+// RegisterMapping adds or overrides a mapping.
+func (m *FinishReasonMapper) RegisterMapping(providerReason, openAIReason string) {
+	m.toOpenAI[providerReason] = openAIReason
+	m.fromOpenAI[openAIReason] = providerReason
+}
+
+// DefaultFinishReasonMapper is the package-level default mapper.
+var DefaultFinishReasonMapper = NewFinishReasonMapper()
+
+// Process-wide unique ID generators.
+var (
+	responseIDCounter     uint64
+	functionCallIDCounter uint64
+)
+
+// GenerateResponseID creates a unique response ID with optional prefix.
+func GenerateResponseID(prefix string) string {
+	counter := atomic.AddUint64(&responseIDCounter, 1)
+	if prefix != "" {
+		return fmt.Sprintf("%s_%x_%d", prefix, time.Now().UnixNano(), counter)
+	}
+	return fmt.Sprintf("resp_%x_%d", time.Now().UnixNano(), counter)
+}
+
+// GenerateFunctionCallID creates a unique function call ID.
+func GenerateFunctionCallID(name string) string {
+	counter := atomic.AddUint64(&functionCallIDCounter, 1)
+	if name != "" {
+		return fmt.Sprintf("call_%s_%d_%d", name, time.Now().UnixNano(), counter)
+	}
+	return fmt.Sprintf("call_%d_%d", time.Now().UnixNano(), counter)
+}

sdk/translator/state_test.go

@@ -0,0 +1,462 @@
+package translator
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestStreamState(t *testing.T) {
+	t.Run("Reset clears all fields", func(t *testing.T) {
+		s := StreamState{
+			ResponseID:         "test-id",
+			CreatedAt:          12345,
+			Model:              "gpt-4",
+			SequenceNum:        10,
+			FinishReason:       "stop",
+			NativeFinishReason: "end_turn",
+			InputTokens:        100,
+			OutputTokens:       50,
+			UsageSeen:          true,
+		}
+
+		s.Reset()
+
+		if s.ResponseID != "" {
+			t.Errorf("Expected ResponseID to be empty, got %s", s.ResponseID)
+		}
+		if s.CreatedAt != 0 {
+			t.Errorf("Expected CreatedAt to be 0, got %d", s.CreatedAt)
+		}
+		if s.Model != "" {
+			t.Errorf("Expected Model to be empty, got %s", s.Model)
+		}
+		if s.SequenceNum != 0 {
+			t.Errorf("Expected SequenceNum to be 0, got %d", s.SequenceNum)
+		}
+		if s.FinishReason != "" {
+			t.Errorf("Expected FinishReason to be empty, got %s", s.FinishReason)
+		}
+		if s.NativeFinishReason != "" {
+			t.Errorf("Expected NativeFinishReason to be empty, got %s", s.NativeFinishReason)
+		}
+		if s.InputTokens != 0 {
+			t.Errorf("Expected InputTokens to be 0, got %d", s.InputTokens)
+		}
+		if s.OutputTokens != 0 {
+			t.Errorf("Expected OutputTokens to be 0, got %d", s.OutputTokens)
+		}
+		if s.UsageSeen {
+			t.Error("Expected UsageSeen to be false")
+		}
+	})
+
+	t.Run("NextSequence increments correctly", func(t *testing.T) {
+		s := StreamState{}
+
+		if s.NextSequence() != 1 {
+			t.Errorf("Expected first sequence to be 1, got %d", s.SequenceNum)
+		}
+		if s.NextSequence() != 2 {
+			t.Errorf("Expected second sequence to be 2, got %d", s.SequenceNum)
+		}
+		if s.NextSequence() != 3 {
+			t.Errorf("Expected third sequence to be 3, got %d", s.SequenceNum)
+		}
+	})
+
+	t.Run("EnsureTimestamp sets timestamp when zero", func(t *testing.T) {
+		s := StreamState{}
+
+		ts := s.EnsureTimestamp()
+		if ts == 0 {
+			t.Error("Expected timestamp to be set")
+		}
+		if s.CreatedAt != ts {
+			t.Errorf("Expected CreatedAt to match returned timestamp, got %d vs %d", s.CreatedAt, ts)
+		}
+	})
+
+	t.Run("EnsureTimestamp preserves existing timestamp", func(t *testing.T) {
+		s := StreamState{CreatedAt: 12345}
+
+		ts := s.EnsureTimestamp()
+		if ts != 12345 {
+			t.Errorf("Expected timestamp to remain 12345, got %d", ts)
+		}
+	})
+}
+
+func TestToolCallState(t *testing.T) {
+	t.Run("GetArguments returns empty object when no arguments", func(t *testing.T) {
+		tc := &ToolCallState{}
+		args := tc.GetArguments()
+		if args != "{}" {
+			t.Errorf("Expected '{}', got %s", args)
+		}
+	})
+
+	t.Run("GetArguments returns accumulated arguments", func(t *testing.T) {
+		tc := &ToolCallState{}
+		tc.Arguments.WriteString(`{"key": "value"}`)
+		args := tc.GetArguments()
+		if args != `{"key": "value"}` {
+			t.Errorf("Expected '{\"key\": \"value\"}', got %s", args)
+		}
+	})
+
+	t.Run("WriteArguments appends content", func(t *testing.T) {
+		tc := &ToolCallState{}
+		tc.WriteArguments(`{"a":`)
+		tc.WriteArguments(`1}`)
+
+		expected := `{"a":1}`
+		if tc.Arguments.String() != expected {
+			t.Errorf("Expected '%s', got %s", expected, tc.Arguments.String())
+		}
+	})
+}
+
+func TestToolCallAccumulator(t *testing.T) {
+	t.Run("NewToolCallAccumulator creates empty accumulator", func(t *testing.T) {
+		a := NewToolCallAccumulator()
+		if a == nil {
+			t.Fatal("Expected non-nil accumulator")
+		}
+		if a.HasAny() {
+			t.Error("Expected HasAny to be false for new accumulator")
+		}
+		if a.Count() != 0 {
+			t.Errorf("Expected Count to be 0, got %d", a.Count())
+		}
+	})
+
+	t.Run("Get returns nil for non-existent index", func(t *testing.T) {
+		a := NewToolCallAccumulator()
+		if a.Get(0) != nil {
+			t.Error("Expected Get to return nil for non-existent index")
+		}
+	})
+
+	t.Run("GetOrCreate creates new tool call", func(t *testing.T) {
+		a := NewToolCallAccumulator()
+		tc := a.GetOrCreate(0)
+		if tc == nil {
+			t.Fatal("Expected non-nil tool call")
+		}
+		if tc.Index != 0 {
+			t.Errorf("Expected index 0, got %d", tc.Index)
+		}
+		if !a.HasAny() {
+			t.Error("Expected HasAny to be true after creating tool call")
+		}
+		if a.Count() != 1 {
+			t.Errorf("Expected Count to be 1, got %d", a.Count())
+		}
+	})
+
+	t.Run("GetOrCreate returns existing tool call", func(t *testing.T) {
+		a := NewToolCallAccumulator()
+		tc1 := a.GetOrCreate(0)
+		tc1.Name = "test-function"
+
+		tc2 := a.GetOrCreate(0)
+		if tc2.Name != "test-function" {
+			t.Error("Expected to get existing tool call")
+		}
+		if a.Count() != 1 {
+			t.Errorf("Expected Count to still be 1, got %d", a.Count())
+		}
+	})
+
+	t.Run("CreateNext assigns incremental indices", func(t *testing.T) {
+		a := NewToolCallAccumulator()
+
+		tc1 := a.CreateNext("id1", "func1")
+		tc2 := a.CreateNext("id2", "func2")
+
+		if tc1.Index != 0 {
+			t.Errorf("Expected first index to be 0, got %d", tc1.Index)
+		}
+		if tc2.Index != 1 {
+			t.Errorf("Expected second index to be 1, got %d", tc2.Index)
+		}
+		if tc1.ID != "id1" || tc1.Name != "func1" {
+			t.Error("Expected first tool call to have correct ID and Name")
+		}
+		if tc2.ID != "id2" || tc2.Name != "func2" {
+			t.Error("Expected second tool call to have correct ID and Name")
+		}
+	})
+
+	t.Run("MarkComplete marks tool call as complete", func(t *testing.T) {
+		a := NewToolCallAccumulator()
+		a.CreateNext("id1", "func1")
+
+		tc := a.MarkComplete(0)
+		if tc == nil {
+			t.Fatal("Expected non-nil tool call")
+		}
+		if !tc.Complete {
+			t.Error("Expected tool call to be marked complete")
+		}
+	})
+
+	t.Run("MarkComplete returns nil for non-existent index", func(t *testing.T) {
+		a := NewToolCallAccumulator()
+		if a.MarkComplete(0) != nil {
+			t.Error("Expected MarkComplete to return nil for non-existent index")
+		}
+	})
+
+	t.Run("Remove deletes tool call", func(t *testing.T) {
+		a := NewToolCallAccumulator()
+		a.CreateNext("id1", "func1")
+		a.CreateNext("id2", "func2")
+
+		a.Remove(0)
+
+		if a.Count() != 1 {
+			t.Errorf("Expected Count to be 1 after removal, got %d", a.Count())
+		}
+		if a.Get(0) != nil {
+			t.Error("Expected Get(0) to return nil after removal")
+		}
+		if a.Get(1) == nil {
+			t.Error("Expected Get(1) to still exist")
+		}
+	})
+
+	t.Run("GetOrdered returns tool calls in creation order", func(t *testing.T) {
+		a := NewToolCallAccumulator()
+		a.CreateNext("id1", "func1")
+		a.CreateNext("id2", "func2")
+		a.CreateNext("id3", "func3")
+
+		ordered := a.GetOrdered()
+		if len(ordered) != 3 {
+			t.Fatalf("Expected 3 ordered tool calls, got %d", len(ordered))
+		}
+		if ordered[0].ID != "id1" || ordered[1].ID != "id2" || ordered[2].ID != "id3" {
+			t.Error("Expected tool calls in creation order")
+		}
+	})
+
+	t.Run("Reset clears all state", func(t *testing.T) {
+		a := NewToolCallAccumulator()
+		a.CreateNext("id1", "func1")
+		a.CreateNext("id2", "func2")
+
+		a.Reset()
+
+		if a.HasAny() {
+			t.Error("Expected HasAny to be false after reset")
+		}
+		if a.Count() != 0 {
+			t.Errorf("Expected Count to be 0 after reset, got %d", a.Count())
+		}
+	})
+}
+
+func TestContentBuffer(t *testing.T) {
+	t.Run("HasContent returns false for empty buffer", func(t *testing.T) {
+		cb := ContentBuffer{}
+		if cb.HasContent() {
+			t.Error("Expected HasContent to be false for empty buffer")
+		}
+	})
+
+	t.Run("HasContent returns true with text", func(t *testing.T) {
+		cb := ContentBuffer{}
+		cb.Text.WriteString("hello")
+		if !cb.HasContent() {
+			t.Error("Expected HasContent to be true with text")
+		}
+	})
+
+	t.Run("HasContent returns true with reasoning", func(t *testing.T) {
+		cb := ContentBuffer{}
+		cb.Reasoning.WriteString("thinking...")
+		if !cb.HasContent() {
+			t.Error("Expected HasContent to be true with reasoning")
+		}
+	})
+
+	t.Run("Reset clears both buffers", func(t *testing.T) {
+		cb := ContentBuffer{}
+		cb.Text.WriteString("text")
+		cb.Reasoning.WriteString("reasoning")
+
+		cb.Reset()
+
+		if cb.Text.Len() != 0 {
+			t.Error("Expected Text to be empty after reset")
+		}
+		if cb.Reasoning.Len() != 0 {
+			t.Error("Expected Reasoning to be empty after reset")
+		}
+		if cb.HasContent() {
+			t.Error("Expected HasContent to be false after reset")
+		}
+	})
+}
+
+func TestStreamingState(t *testing.T) {
+	t.Run("NewStreamingState creates initialized state", func(t *testing.T) {
+		s := NewStreamingState()
+		if s == nil {
+			t.Fatal("Expected non-nil state")
+		}
+		if s.ToolCalls == nil {
+			t.Error("Expected ToolCalls to be initialized")
+		}
+	})
+
+	t.Run("Reset clears all fields", func(t *testing.T) {
+		s := NewStreamingState()
+		s.ResponseID = "test-id"
+		s.InTextBlock = true
+		s.InToolBlock = true
+		s.InReasoningBlock = true
+		s.CurrentMessageID = "msg-id"
+		s.CurrentToolCallID = "tool-id"
+		s.CurrentReasoningID = "reasoning-id"
+		s.ToolCalls.CreateNext("id", "func")
+		s.Content.Text.WriteString("text")
+
+		s.Reset()
+
+		if s.ResponseID != "" {
+			t.Error("Expected ResponseID to be cleared")
+		}
+		if s.InTextBlock || s.InToolBlock || s.InReasoningBlock {
+			t.Error("Expected block flags to be false")
+		}
+		if s.CurrentMessageID != "" || s.CurrentToolCallID != "" || s.CurrentReasoningID != "" {
+			t.Error("Expected current IDs to be cleared")
+		}
+		if s.ToolCalls.HasAny() {
+			t.Error("Expected ToolCalls to be cleared")
+		}
+		if s.Content.HasContent() {
+			t.Error("Expected Content to be cleared")
+		}
+	})
+}
+
+func TestFinishReasonMapper(t *testing.T) {
+	t.Run("ToOpenAI maps known reasons", func(t *testing.T) {
+		m := NewFinishReasonMapper()
+
+		testCases := []struct {
+			input    string
+			expected string
+		}{
+			{"end_turn", "stop"},
+			{"tool_use", "tool_calls"},
+			{"max_tokens", "length"},
+			{"STOP", "stop"},
+			{"MAX_TOKENS", "length"},
+			{"SAFETY", "content_filter"},
+			{"completed", "stop"},
+		}
+
+		for _, tc := range testCases {
+			result := m.ToOpenAI(tc.input)
+			if result != tc.expected {
+				t.Errorf("ToOpenAI(%s) = %s, expected %s", tc.input, result, tc.expected)
+			}
+		}
+	})
+
+	t.Run("ToOpenAI returns default for unknown reasons", func(t *testing.T) {
+		m := NewFinishReasonMapper()
+		result := m.ToOpenAI("unknown_reason")
+		if result != "stop" {
+			t.Errorf("Expected default 'stop', got %s", result)
+		}
+	})
+
+	t.Run("FromOpenAI maps known reasons", func(t *testing.T) {
+		m := NewFinishReasonMapper()
+
+		testCases := []struct {
+			input    string
+			expected string
+		}{
+			{"stop", "end_turn"},
+			{"tool_calls", "tool_use"},
+			{"length", "max_tokens"},
+			{"content_filter", "SAFETY"},
+		}
+
+		for _, tc := range testCases {
+			result := m.FromOpenAI(tc.input)
+			if result != tc.expected {
+				t.Errorf("FromOpenAI(%s) = %s, expected %s", tc.input, result, tc.expected)
+			}
+		}
+	})
+
+	t.Run("FromOpenAI returns default for unknown reasons", func(t *testing.T) {
+		m := NewFinishReasonMapper()
+		result := m.FromOpenAI("unknown")
+		if result != "STOP" {
+			t.Errorf("Expected default 'STOP', got %s", result)
+		}
+	})
+
+	t.Run("RegisterMapping adds new mapping", func(t *testing.T) {
+		m := NewFinishReasonMapper()
+		m.RegisterMapping("custom_reason", "custom_openai")
+
+		if m.ToOpenAI("custom_reason") != "custom_openai" {
+			t.Error("Expected new mapping to work in ToOpenAI direction")
+		}
+		if m.FromOpenAI("custom_openai") != "custom_reason" {
+			t.Error("Expected new mapping to work in FromOpenAI direction")
+		}
+	})
+}
+
+func TestGenerateResponseID(t *testing.T) {
+	t.Run("generates unique IDs", func(t *testing.T) {
+		id1 := GenerateResponseID("")
+		id2 := GenerateResponseID("")
+
+		if id1 == id2 {
+			t.Error("Expected unique IDs")
+		}
+	})
+
+	t.Run("includes prefix when provided", func(t *testing.T) {
+		id := GenerateResponseID("chatcmpl")
+		if !strings.HasPrefix(id, "chatcmpl_") {
+			t.Errorf("Expected ID to start with 'chatcmpl_', got %s", id)
+		}
+	})
+
+	t.Run("default prefix is resp_", func(t *testing.T) {
+		id := GenerateResponseID("")
+		if !strings.HasPrefix(id, "resp_") {
+			t.Errorf("Expected ID to start with 'resp_', got %s", id)
+		}
+	})
+}
+
+func TestGenerateFunctionCallID(t *testing.T) {
+	t.Run("generates unique IDs", func(t *testing.T) {
+		id1 := GenerateFunctionCallID("")
+		id2 := GenerateFunctionCallID("")
+
+		if id1 == id2 {
+			t.Error("Expected unique IDs")
+		}
+	})
+
+	t.Run("includes name when provided", func(t *testing.T) {
+		id := GenerateFunctionCallID("get_weather")
+		if !strings.Contains(id, "get_weather") {
+			t.Errorf("Expected ID to contain 'get_weather', got %s", id)
+		}
+	})
+}