Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

fix(agent): normalize Gemini thought-signature metadata (#19691)

p0ny8588a6ecbd3f
diff --git a/backend/api/v1/ai_service.go b/backend/api/v1/ai_service.go
index 5c7005c2c6..0c2f1044eb 100644
--- a/backend/api/v1/ai_service.go
+++ b/backend/api/v1/ai_service.go
@@ -110,6 +110,92 @@ type chatOpenAIToolCallParsed struct {
} `json:"function"`
}
+type chatToolCallMetadata struct {
+ OpenAIToolCall json.RawMessage `json:"openAIToolCall,omitempty"`
+ GeminiThoughtSignature string `json:"geminiThoughtSignature,omitempty"`
+}
+
+type chatOpenAIToolCallProviderFields struct {
+ ExtraContent struct {
+ Google struct {
+ ThoughtSignature string `json:"thought_signature,omitempty"`
+ } `json:"google,omitempty"`
+ } `json:"extra_content,omitempty"`
+}
+
+func parseChatToolCallMetadata(raw string) (chatToolCallMetadata, bool) {
+ metadataBytes := bytes.TrimSpace([]byte(raw))
+ if len(metadataBytes) == 0 {
+ return chatToolCallMetadata{}, false
+ }
+ var metadata chatToolCallMetadata
+ if err := json.Unmarshal(metadataBytes, &metadata); err != nil {
+ return chatToolCallMetadata{}, false
+ }
+ if len(metadata.OpenAIToolCall) == 0 && metadata.GeminiThoughtSignature == "" {
+ return chatToolCallMetadata{}, false
+ }
+ return metadata, true
+}
+
+func buildChatToolCallMetadata(rawOpenAIToolCall json.RawMessage, geminiThoughtSignature string) (*string, error) {
+ metadata := chatToolCallMetadata{
+ OpenAIToolCall: rawOpenAIToolCall,
+ GeminiThoughtSignature: geminiThoughtSignature,
+ }
+ if metadata.GeminiThoughtSignature == "" {
+ metadata.GeminiThoughtSignature = extractGeminiThoughtSignatureFromOpenAIToolCall(rawOpenAIToolCall)
+ }
+ if len(metadata.OpenAIToolCall) == 0 && metadata.GeminiThoughtSignature == "" {
+ return nil, nil
+ }
+ metadataBytes, err := json.Marshal(metadata)
+ if err != nil {
+ return nil, err
+ }
+ metadataString := string(metadataBytes)
+ return &metadataString, nil
+}
+
+func openAIToolCallFromMetadata(raw string) json.RawMessage {
+ if metadata, ok := parseChatToolCallMetadata(raw); ok {
+ return metadata.OpenAIToolCall
+ }
+ metadataBytes := bytes.TrimSpace([]byte(raw))
+ if len(metadataBytes) == 0 || !json.Valid(metadataBytes) {
+ return nil
+ }
+ return json.RawMessage(metadataBytes)
+}
+
+func geminiThoughtSignatureFromMetadata(raw string) string {
+ if metadata, ok := parseChatToolCallMetadata(raw); ok {
+ if metadata.GeminiThoughtSignature != "" {
+ return metadata.GeminiThoughtSignature
+ }
+ return extractGeminiThoughtSignatureFromOpenAIToolCall(metadata.OpenAIToolCall)
+ }
+ metadataBytes := bytes.TrimSpace([]byte(raw))
+ if len(metadataBytes) == 0 {
+ return ""
+ }
+ if json.Valid(metadataBytes) {
+ return extractGeminiThoughtSignatureFromOpenAIToolCall(json.RawMessage(metadataBytes))
+ }
+ return string(metadataBytes)
+}
+
+func extractGeminiThoughtSignatureFromOpenAIToolCall(raw json.RawMessage) string {
+ if len(raw) == 0 {
+ return ""
+ }
+ var providerFields chatOpenAIToolCallProviderFields
+ if err := json.Unmarshal(raw, &providerFields); err != nil {
+ return ""
+ }
+ return providerFields.ExtraContent.Google.ThoughtSignature
+}
+
func (*AIService) chatOpenAI(ctx context.Context, aiSetting *storepb.AISetting, request *v1pb.AIChatRequest) (*connect.Response[v1pb.AIChatResponse], error) {
payload := chatOpenAIRequest{
Model: aiSetting.Model,
@@ -126,22 +212,24 @@ func (*AIService) chatOpenAI(ctx context.Context, aiSetting *storepb.AISetting,
msg.ToolCallID = *m.ToolCallId
}
for _, tc := range m.ToolCalls {
- if tc.Metadata != nil && *tc.Metadata != "" {
- // Replay the raw tool call JSON exactly as received from the provider.
- // This preserves provider-specific fields like Gemini's thought_signature.
- msg.ToolCalls = append(msg.ToolCalls, json.RawMessage(*tc.Metadata))
- } else {
- // Construct a standard OpenAI tool call.
- raw, _ := json.Marshal(chatOpenAIToolUse{
- ID: tc.Id,
- Type: "function",
- Function: chatOpenAIFunctionCallRef{
- Name: tc.Name,
- Arguments: tc.Arguments,
- },
- })
- msg.ToolCalls = append(msg.ToolCalls, json.RawMessage(raw))
+ if tc.Metadata != nil {
+ if rawToolCall := openAIToolCallFromMetadata(*tc.Metadata); len(rawToolCall) > 0 {
+ // Replay the raw tool call JSON exactly as received from the provider.
+ // This preserves provider-specific fields like Gemini's thought_signature.
+ msg.ToolCalls = append(msg.ToolCalls, rawToolCall)
+ continue
+ }
}
+ // Construct a standard OpenAI tool call.
+ raw, _ := json.Marshal(chatOpenAIToolUse{
+ ID: tc.Id,
+ Type: "function",
+ Function: chatOpenAIFunctionCallRef{
+ Name: tc.Name,
+ Arguments: tc.Arguments,
+ },
+ })
+ msg.ToolCalls = append(msg.ToolCalls, json.RawMessage(raw))
}
payload.Messages = append(payload.Messages, msg)
}
@@ -196,14 +284,17 @@ func (*AIService) chatOpenAI(ctx context.Context, aiSetting *storepb.AISetting,
if err := json.Unmarshal(rawTC, &parsed); err != nil {
return nil, errors.Errorf("failed to parse tool call: %s", err)
}
- // Store the entire raw JSON as metadata so we can replay it exactly,
- // preserving any provider-specific fields (e.g., Gemini thought_signature).
- rawStr := string(rawTC)
+ // Store provider-specific tool metadata in a structured envelope so each
+ // adapter can replay only the fields it understands.
+ metadata, err := buildChatToolCallMetadata(rawTC, "")
+ if err != nil {
+ return nil, errors.Errorf("failed to encode tool call metadata: %s", err)
+ }
toolCall := &v1pb.AIChatToolCall{
Id: parsed.ID,
Name: parsed.Function.Name,
Arguments: parsed.Function.Arguments,
- Metadata: &rawStr,
+ Metadata: metadata,
}
result.ToolCalls = append(result.ToolCalls, toolCall)
}
@@ -383,12 +474,12 @@ type chatGeminiPart struct {
Text string `json:"text,omitempty"`
FunctionCall *chatGeminiFunctionCall `json:"functionCall,omitempty"`
FunctionResponse *chatGeminiFunctionResult `json:"functionResponse,omitempty"`
+ ThoughtSignature string `json:"thoughtSignature,omitempty"`
}
type chatGeminiFunctionCall struct {
- Name string `json:"name"`
- Args any `json:"args"`
- ThoughtSignature string `json:"thoughtSignature,omitempty"`
+ Name string `json:"name"`
+ Args any `json:"args"`
}
type chatGeminiFunctionResult struct {
@@ -415,8 +506,9 @@ type chatGeminiResponse struct {
}
type chatGeminiResponsePart struct {
- Text string `json:"text,omitempty"`
- FunctionCall *chatGeminiFunctionCall `json:"functionCall,omitempty"`
+ Text string `json:"text,omitempty"`
+ FunctionCall *chatGeminiFunctionCall `json:"functionCall,omitempty"`
+ ThoughtSignature string `json:"thoughtSignature,omitempty"`
}
func (*AIService) chatGemini(ctx context.Context, aiSetting *storepb.AISetting, request *v1pb.AIChatRequest) (*connect.Response[v1pb.AIChatResponse], error) {
@@ -445,16 +537,16 @@ func (*AIService) chatGemini(ctx context.Context, aiSetting *storepb.AISetting,
if err := json.Unmarshal([]byte(tc.Arguments), &args); err != nil {
args = tc.Arguments
}
- fc := &chatGeminiFunctionCall{
- Name: tc.Name,
- Args: args,
+ part := chatGeminiPart{
+ FunctionCall: &chatGeminiFunctionCall{
+ Name: tc.Name,
+ Args: args,
+ },
}
if tc.Metadata != nil {
- fc.ThoughtSignature = *tc.Metadata
+ part.ThoughtSignature = geminiThoughtSignatureFromMetadata(*tc.Metadata)
}
- parts = append(parts, chatGeminiPart{
- FunctionCall: fc,
- })
+ parts = append(parts, part)
}
payload.Contents = append(payload.Contents, chatGeminiContent{
Role: "model",
@@ -542,8 +634,12 @@ func (*AIService) chatGemini(ctx context.Context, aiSetting *storepb.AISetting,
Name: part.FunctionCall.Name,
Arguments: string(args),
}
- if part.FunctionCall.ThoughtSignature != "" {
- tc.Metadata = &part.FunctionCall.ThoughtSignature
+ if part.ThoughtSignature != "" {
+ metadata, err := buildChatToolCallMetadata(nil, part.ThoughtSignature)
+ if err != nil {
+ return nil, errors.Errorf("failed to encode Gemini tool metadata: %s", err)
+ }
+ tc.Metadata = metadata
}
result.ToolCalls = append(result.ToolCalls, tc)
}
diff --git a/backend/api/v1/ai_service_test.go b/backend/api/v1/ai_service_test.go
new file mode 100644
index 0000000000..1e3b19a979
--- /dev/null
+++ b/backend/api/v1/ai_service_test.go
@@ -0,0 +1,135 @@
+package v1
+
+import (
+ "encoding/json"
+ "testing"
+
+ "github.com/stretchr/testify/require"
+)
+
+func TestChatGeminiPartMarshalsThoughtSignatureOnPart(t *testing.T) {
+ t.Parallel()
+
+ payload := chatGeminiRequest{
+ Contents: []chatGeminiContent{{
+ Role: "model",
+ Parts: []chatGeminiPart{{
+ FunctionCall: &chatGeminiFunctionCall{
+ Name: "list_tables",
+ Args: map[string]any{"database": "db"},
+ },
+ ThoughtSignature: "sig-123",
+ }},
+ }},
+ }
+
+ payloadBytes, err := json.Marshal(payload)
+ require.NoError(t, err)
+
+ var raw map[string]any
+ require.NoError(t, json.Unmarshal(payloadBytes, &raw))
+
+ contents, ok := raw["contents"].([]any)
+ require.True(t, ok)
+ require.Len(t, contents, 1)
+
+ content, ok := contents[0].(map[string]any)
+ require.True(t, ok)
+
+ parts, ok := content["parts"].([]any)
+ require.True(t, ok)
+ require.Len(t, parts, 1)
+
+ part, ok := parts[0].(map[string]any)
+ require.True(t, ok)
+ require.Equal(t, "sig-123", part["thoughtSignature"])
+
+ functionCall, ok := part["functionCall"].(map[string]any)
+ require.True(t, ok)
+ require.Equal(t, "list_tables", functionCall["name"])
+ require.NotContains(t, functionCall, "thoughtSignature")
+}
+
+func TestChatGeminiResponsePartUnmarshalsThoughtSignatureFromPart(t *testing.T) {
+ t.Parallel()
+
+ var part chatGeminiResponsePart
+ err := json.Unmarshal([]byte(`{
+ "functionCall": {
+ "name": "list_tables",
+ "args": {"database": "db"}
+ },
+ "thoughtSignature": "sig-123"
+ }`), &part)
+ require.NoError(t, err)
+ require.NotNil(t, part.FunctionCall)
+ require.Equal(t, "list_tables", part.FunctionCall.Name)
+ require.Equal(t, "sig-123", part.ThoughtSignature)
+}
+
+func TestBuildChatToolCallMetadataExtractsGeminiThoughtSignature(t *testing.T) {
+ t.Parallel()
+
+ rawToolCall := json.RawMessage(`{
+ "id": "call-1",
+ "type": "function",
+ "function": {
+ "name": "get_page_state",
+ "arguments": "{}"
+ },
+ "extra_content": {
+ "google": {
+ "thought_signature": "sig-123"
+ }
+ }
+ }`)
+
+ metadata, err := buildChatToolCallMetadata(rawToolCall, "")
+ require.NoError(t, err)
+ require.NotNil(t, metadata)
+ require.Equal(t, "sig-123", geminiThoughtSignatureFromMetadata(*metadata))
+ require.JSONEq(t, string(rawToolCall), string(openAIToolCallFromMetadata(*metadata)))
+}
+
+func TestGeminiThoughtSignatureFromMetadataSupportsLegacyFormats(t *testing.T) {
+ t.Parallel()
+
+ t.Run("legacy raw tool call with thought signature", func(t *testing.T) {
+ t.Parallel()
+
+ metadata := `{
+ "id": "call-1",
+ "type": "function",
+ "function": {
+ "name": "get_page_state",
+ "arguments": "{}"
+ },
+ "extra_content": {
+ "google": {
+ "thought_signature": "sig-legacy"
+ }
+ }
+ }`
+ require.Equal(t, "sig-legacy", geminiThoughtSignatureFromMetadata(metadata))
+ })
+
+ t.Run("legacy raw tool call without thought signature", func(t *testing.T) {
+ t.Parallel()
+
+ metadata := `{
+ "id": "call-2",
+ "type": "function",
+ "function": {
+ "name": "search_api",
+ "arguments": "{}"
+ }
+ }`
+ require.Empty(t, geminiThoughtSignatureFromMetadata(metadata))
+ })
+
+ t.Run("native Gemini thought signature string", func(t *testing.T) {
+ t.Parallel()
+
+ require.Equal(t, "sig-native", geminiThoughtSignatureFromMetadata("sig-native"))
+ })
+}