feat: support Google Gemini thought signatures

Implements support for capturing and relaying 'thought signatures'
required by Google Gemini 3 Pro for function calling. See
https://ai.google.dev/gemini-api/docs/thought-signatures "Thought
signatures are encrypted representations of the model's internal thought
process and are used to preserve reasoning context across multi-turn
interactions."

This change does the following:

- Persist thought signatures in tool call state and pass them back via
  `extra_content`.
- Add `skipThoughtSignatureValidator` config to bypass validation for custom tool calls.
- Register `gemini-3-pro-preview` model.

🤖 Generated with [eca](https://eca.dev)

Co-Authored-By: eca <[email protected]>

Author: ArthurHeymans

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Support Google Gemini thought signatures.
+- Support `gemini-3-pro-preview` model.
 - Support `~` in dynamic string parser.
 - Support removing nullable values from LLM request body if the value in extraPayload is null. #232
 

docs/configuration.md

@@ -582,6 +582,7 @@ To configure, add your OTLP collector config via `:otlp` map following [otlp aut
             completionUrlRelativePath?: string;
             thinkTagStart?: string;
             thinkTagEnd?: string;
+            skipThoughtSignatureValidator?: boolean;
             models: {[key: string]: {
               modelName?: string;
               extraPayload?: {[key: string]: any}

src/eca/config.clj

@@ -82,7 +82,8 @@
                          :key "${env:GOOGLE_API_KEY}"
                          :requiresAuth? true
                          :models {"gemini-2.0-flash" {}
-                                  "gemini-2.5-pro" {}}}
+                                  "gemini-2.5-pro" {}
+                                  "gemini-3-pro-preview" {}}}
                "ollama" {:url "${env:OLLAMA_API_URL:http://localhost:11434}"}}
    :defaultBehavior "agent"
    :behavior {"agent" {:systemPrompt "${classpath:prompts/agent_behavior.md}"

src/eca/features/chat.clj

@@ -560,6 +560,7 @@
            :server (:server event-data)
            :arguments (:arguments event-data)
            :origin (:origin event-data)
+           :thought-signature (:thought-signature event-data)
            :decision-reason {:code :none
                              :text "No reason"})
 
@@ -1124,7 +1125,7 @@
                                      :finish (do (add-to-history! {:role "assistant"
                                                                    :content [{:type :text :text @received-msgs*}]})
                                                  (finish-chat-prompt! :idle chat-ctx))))
-            :on-prepare-tool-call (fn [{:keys [id full-name arguments-text]}]
+            :on-prepare-tool-call (fn [{:keys [id full-name arguments-text thought-signature]}]
                                     (assert-chat-not-stopped! chat-ctx)
                                     (let [tool (tool-by-full-name full-name all-tools)]
                                       (transition-tool-call! db* chat-ctx id :tool-prepare
@@ -1133,6 +1134,7 @@
                                                               :full-name full-name
                                                               :origin (:origin tool)
                                                               :arguments-text arguments-text
+                                                              :thought-signature thought-signature
                                                               :summary (f.tools/tool-call-summary all-tools full-name nil config)})))
             :on-tools-called (on-tools-called! chat-ctx received-msgs* add-to-history!)
             :on-reason (fn [{:keys [status id text external-id]}]

src/eca/llm_api.clj

@@ -160,6 +160,7 @@
           :tools tools
           :think-tag-start "<thought>"
           :think-tag-end "</thought>"
+          :skip-thought-signature-validator? (get-in provider-config [:skipThoughtSignatureValidator])
           :extra-payload (merge {:parallel_tool_calls false}
                                 (when reason?
                                   {:extra_body {:google {:thinking_config {:include_thoughts true}}}})

src/eca/llm_providers/openai_chat.clj

@@ -70,9 +70,13 @@
   (let [tools-to-call (->> (:choices body)
                            (mapcat (comp :tool_calls :message))
                            (map (fn [tool-call]
-                                  {:id (:id tool-call)
-                                   :full-name (:name (:function tool-call))
-                                   :arguments (json/parse-string (:arguments (:function tool-call)))})))]
+                                  (cond-> {:id (:id tool-call)
+                                           :full-name (:name (:function tool-call))
+                                           :arguments (json/parse-string (:arguments (:function tool-call)))}
+                                    ;; Preserve Google Gemini thought signatures
+                                    (get-in tool-call [:extra_content :google :thought_signature])
+                                    (assoc :thought-signature
+                                           (get-in tool-call [:extra_content :google :thought_signature]))))))]
     {:usage (parse-usage (:usage body))
      :reason-id (str (random-uuid))
      :tools-to-call tools-to-call
@@ -129,13 +133,22 @@
 
 (defn ^:private transform-message
   "Transform a single ECA message to OpenAI format. Returns nil for unsupported roles."
-  [{:keys [role content] :as _msg} supports-image? think-tag-start think-tag-end]
+  [{:keys [role content] :as _msg} supports-image? think-tag-start think-tag-end skip-thought-signature-validator?]
   (case role
     "tool_call" {:type :tool-call ; Special marker for accumulation
-                 :data {:id (:id content)
-                        :type "function"
-                        :function {:name (:full-name content)
-                                   :arguments (json/generate-string (:arguments content))}}}
+                 :data (cond-> {:id (:id content)
+                                :type "function"
+                                :function {:name (:full-name content)
+                                           :arguments (json/generate-string (:arguments content))}}
+                         ;; Preserve Google Gemini thought signatures if present
+                         (:thought-signature content)
+                         (assoc-in [:extra_content :google :thought_signature]
+                                   (:thought-signature content))
+                         ;; Use bypass signature when thought signature is missing and bypass is enabled
+                         (and skip-thought-signature-validator?
+                              (not (:thought-signature content)))
+                         (assoc-in [:extra_content :google :thought_signature]
+                                   "skip_thought_signature_validator"))}
     "tool_call_output" {:role "tool"
                         :tool_call_id (:id content)
                         :content (llm-util/stringfy-tool-result content)}
@@ -196,9 +209,9 @@
    'assistant' role message, not as separate messages. This function ensures compliance
    with that requirement by accumulating tool calls and flushing them into assistant
    messages when a non-tool_call message is encountered."
-  [messages supports-image? think-tag-start think-tag-end]
+  [messages supports-image? think-tag-start think-tag-end skip-thought-signature-validator?]
   (->> messages
-       (map #(transform-message % supports-image? think-tag-start think-tag-end))
+       (map #(transform-message % supports-image? think-tag-start think-tag-end skip-thought-signature-validator?))
        (remove nil?)
        accumulate-tool-calls
        (filter valid-message?)))
@@ -295,15 +308,15 @@
    Compatible with OpenRouter and other OpenAI-compatible providers."
   [{:keys [model user-messages instructions temperature api-key api-url url-relative-path
            past-messages tools extra-payload extra-headers supports-image?
-           think-tag-start think-tag-end http-client]}
+           think-tag-start think-tag-end skip-thought-signature-validator? http-client]}
    {:keys [on-message-received on-error on-prepare-tool-call on-tools-called on-reason on-usage-updated] :as callbacks}]
   (let [think-tag-start (or think-tag-start "<think>")
         think-tag-end (or think-tag-end "</think>")
         stream? (boolean callbacks)
         messages (vec (concat
                        (when instructions [{:role "system" :content instructions}])
-                       (normalize-messages past-messages supports-image? think-tag-start think-tag-end)
-                       (normalize-messages user-messages supports-image? think-tag-start think-tag-end)))
+                       (normalize-messages past-messages supports-image? think-tag-start think-tag-end skip-thought-signature-validator?)
+                       (normalize-messages user-messages supports-image? think-tag-start think-tag-end skip-thought-signature-validator?)))
 
         body (deep-merge
               (assoc-some
@@ -333,7 +346,7 @@
                                   (when-let [{:keys [new-messages]} (on-tools-called tools-to-call)]
                                     (let [new-messages-list (vec (concat
                                                                   (when instructions [{:role "system" :content instructions}])
-                                                                  (normalize-messages new-messages supports-image? think-tag-start think-tag-end)))
+                                                                  (normalize-messages new-messages supports-image? think-tag-start think-tag-end skip-thought-signature-validator?)))
                                           new-rid (llm-util/gen-rid)]
                                       (reset! tool-calls* {})
                                       (base-chat-request!
@@ -406,8 +419,10 @@
                                           (on-message-received {:type :text :text buf}))
                                         (reset! content-buffer* "")))
                                     (doseq [tool-call (:tool_calls delta)]
-                                      (let [{:keys [index id function]} tool-call
+                                      (let [{:keys [index id function extra_content]} tool-call
                                             {name :name args :arguments} function
+                                            ;; Extract Google Gemini thought signature if present
+                                            thought-signature (get-in extra_content [:google :thought_signature])
                                             ;; Use RID as key to avoid collisions between API requests
                                             tool-key (str rid "-" index)
                                             ;; Create globally unique tool call ID for client
@@ -421,7 +436,9 @@
                                                  (cond-> (or existing {:index index})
                                                    unique-id (assoc :id unique-id)
                                                    name (assoc :full-name name)
-                                                   args (update :arguments-text (fnil str "") args))))
+                                                   args (update :arguments-text (fnil str "") args)
+                                                   ;; Store thought signature for Google Gemini
+                                                   thought-signature (assoc :thought-signature thought-signature))))
                                         (when-let [updated-tool-call (get @tool-calls* tool-key)]
                                           (when (and (:id updated-tool-call)
                                                      (:full-name updated-tool-call)

test/eca/features/chat_tool_call_state_test.clj

@@ -35,6 +35,7 @@
               :server "eca"
               :arguments tool-arguments
               :origin tool-origin
+              :thought-signature nil
               :decision-reason {:code :none
                                 :text "No reason"}}
              (#'f.chat/get-tool-call-state @db* chat-id tool-call-id))

test/eca/llm_providers/openai_chat_test.clj

@@ -34,7 +34,8 @@
            {:role "assistant" :content "I found 2 files"}]
           true
           thinking-start-tag
-          thinking-end-tag))))
+          thinking-end-tag
+          false))))
 
   (testing "Skips unsupported message types"
     (is (match?
@@ -48,7 +49,8 @@
                    {:role "assistant" :content "Hi"}]
                   true
                   thinking-start-tag
-                  thinking-end-tag))))))
+                  thinking-end-tag
+                  false))))))
 
 (deftest extract-content-test
   (testing "String input"
@@ -103,7 +105,8 @@
                      :arguments {:location "NYC"}}}
           true
           thinking-start-tag
-          thinking-end-tag))))
+          thinking-end-tag
+          false))))
 
   (testing "Tool call output transformation"
     (is (match?
@@ -116,15 +119,17 @@
                      :output {:contents [{:type :text :text "Sunny, 75°F"}]}}}
           true
           thinking-start-tag
-          thinking-end-tag))))
+          thinking-end-tag
+          false))))
 
   (testing "Unsupported role returns nil"
     (is (nil?
          (#'llm-providers.openai-chat/transform-message
           {:role "unsupported" :content "test"}
           true
           thinking-start-tag
-          thinking-end-tag)))))
+          thinking-end-tag
+          false)))))
 
 (deftest accumulate-tool-calls-test
   (testing "Multiple sequential tool calls get grouped"
@@ -166,6 +171,80 @@
     (is (#'llm-providers.openai-chat/valid-message?
          {:role "user" :content "Hello world"}))))
 
+(deftest thought-signature-test
+  (testing "Tool call with thought signature is preserved"
+    (is (match?
+         {:type :tool-call
+          :data {:id "call-123"
+                 :type "function"
+                 :function {:name "eca__get_weather"
+                            :arguments "{\"location\":\"Paris\"}"}
+                 :extra_content {:google {:thought_signature "signature-abc-123"}}}}
+         (#'llm-providers.openai-chat/transform-message
+          {:role "tool_call"
+           :content {:id "call-123"
+                     :full-name "eca__get_weather"
+                     :arguments {:location "Paris"}
+                     :thought-signature "signature-abc-123"}}
+          true
+          thinking-start-tag
+          thinking-end-tag
+          false))))
+
+  (testing "Tool call without thought signature when bypass is disabled"
+    (is (match?
+         {:type :tool-call
+          :data {:id "call-456"
+                 :type "function"
+                 :function {:name "eca__get_weather"
+                            :arguments "{\"location\":\"London\"}"}}}
+         (#'llm-providers.openai-chat/transform-message
+          {:role "tool_call"
+           :content {:id "call-456"
+                     :full-name "eca__get_weather"
+                     :arguments {:location "London"}}}
+          true
+          thinking-start-tag
+          thinking-end-tag
+          false))))
+
+  (testing "Tool call without thought signature gets bypass when enabled"
+    (is (match?
+         {:type :tool-call
+          :data {:id "call-789"
+                 :type "function"
+                 :function {:name "eca__get_weather"
+                            :arguments "{\"location\":\"Tokyo\"}"}
+                 :extra_content {:google {:thought_signature "skip_thought_signature_validator"}}}}
+         (#'llm-providers.openai-chat/transform-message
+          {:role "tool_call"
+           :content {:id "call-789"
+                     :full-name "eca__get_weather"
+                     :arguments {:location "Tokyo"}}}
+          true
+          thinking-start-tag
+          thinking-end-tag
+          true))))
+
+  (testing "Tool call with thought signature is not overridden by bypass"
+    (is (match?
+         {:type :tool-call
+          :data {:id "call-999"
+                 :type "function"
+                 :function {:name "eca__get_weather"
+                            :arguments "{\"location\":\"Berlin\"}"}
+                 :extra_content {:google {:thought_signature "original-signature"}}}}
+         (#'llm-providers.openai-chat/transform-message
+          {:role "tool_call"
+           :content {:id "call-999"
+                     :full-name "eca__get_weather"
+                     :arguments {:location "Berlin"}
+                     :thought-signature "original-signature"}}
+          true
+          thinking-start-tag
+          thinking-end-tag
+          true)))))
+
 (defn process-text-think-aware [texts]
   (let [content-buffer* (atom "")
         reasoning-type* (atom nil)