OpenRouter with Gemini 3 pro

[bassamsdata]

Updated: 5/12/2025 - Now it handle reasoning correctly.

I've been using OpenRouter quite a lot recently, and since I wanted to try Gemini 3 Pro which requires an additional thought_signature for fcuntion calling I noticed that OpenRouter handles reasoning a bit differently.

From what I understand, the current OpenAI adapter doesn't extract reasoning_details from responses and also strips extra_content when building requests. Because of that, it seems we may need to rebuild chat_output and form_messages for full compatibility.

If anyone has a cleaner or more elegant solution, I d really appreciate if you can share it!
Below is a working OpenRouter adapter:

            openrouter_new = function()
              return require("codecompanion.adapters").extend("openai", {
                url = "https://openrouter.ai/api/v1/chat/completions",
                env = {
                  api_key = openrouter_api_key(),
                },
                headers = {
                  ["HTTP-Referer"] = "https://github.com/codecompanion-test",
                  ["X-Title"] = "CodeCompanion Tool Testing",
                },
                handlers = {
                  -- REQUIRED OVERRIDES for OpenRouter reasoning tokens and Gemini thought signatures
                  --
                  -- Why these handlers are necessary:
                  -- 1. chat_output: OpenRouter sends reasoning_details → we extract and pass as extra
                  -- 2. parse_message_meta: Convert reasoning_details to output.reasoning for display
                  -- 3. form_messages: We convert extra_content → reasoning_details at MESSAGE level (API format)
                  --
                  -- References:
                  -- - https://openrouter.ai/docs/guides/best-practices/reasoning-tokens
                  -- - https://openrouter.ai/docs/guides/features/tool-calling#interleaved-thinking

                  form_messages = function(self, messages)
                    return {
                      messages = vim
                        .iter(messages)
                        :map(function(m)
                          local tool_calls, reasoning_details = nil, nil

                          -- Preserve reasoning data in messages for models that need it
                          if m.reasoning and m.reasoning._data then
                            reasoning_details = reasoning_details or {}
                            -- Handle encrypted reasoning (thought signatures from Gemini, etc.)
                            if m.reasoning._data.encrypted then
                              table.insert(reasoning_details, {
                                type = "reasoning.encrypted",
                                data = m.reasoning._data.encrypted,
                                id = m.reasoning._data.id,
                                format = m.reasoning._data.format or "openrouter-v1",
                                index = #reasoning_details,
                              })
                            end
                          end

                          -- Extract thought signatures from tool_calls and convert to reasoning_details
                          if m.tools and m.tools.calls then
                            tool_calls = vim
                              .iter(m.tools.calls)
                              :map(function(tc)
                                if tc.extra_content and tc.extra_content.google then
                                  reasoning_details = reasoning_details or {}
                                  table.insert(reasoning_details, {
                                    type = "reasoning.encrypted",
                                    data = tc.extra_content.google.thought_signature,
                                    id = tc.id,
                                    format = "google-gemini-v1",
                                    index = #reasoning_details,
                                  })
                                end
                                return {
                                  id = tc.id,
                                  type = tc.type,
                                  ["function"] = tc["function"],
                                }
                              end)
                              :totable()
                          end

                          local msg = {
                            role = m.role,
                            content = m.content,
                            tool_calls = tool_calls,
                            tool_call_id = m.tools and m.tools.call_id or nil,
                          }
                          if reasoning_details then
                            msg.reasoning_details = reasoning_details
                          end
                          return msg
                        end)
                        :totable(),
                    }
                  end,

                  -- Extract reasoning content from OpenRouter's reasoning_details
                  -- This is called by chat.init.lua after chat_output to process extra fields
                  -- Reference: https://openrouter.ai/docs/guides/best-practices/reasoning-tokens#responses-api-shape
                  parse_message_meta = function(self, data)
                    local extra = data.extra
                    if not extra or not extra.reasoning_details then
                      return data
                    end

                    local reasoning_content = {}
                    local reasoning_data = {}

                    for _, detail in ipairs(extra.reasoning_details) do
                      -- Handle different reasoning detail types
                      -- Types: reasoning.text, reasoning.summary, reasoning.encrypted
                      if detail.type == "reasoning.text" and detail.text then
                        table.insert(reasoning_content, detail.text)
                        -- Store signature if present for later use
                        if detail.signature then
                          reasoning_data.signature = detail.signature
                        end
                      elseif detail.type == "reasoning.summary" and detail.summary then
                        table.insert(reasoning_content, detail.summary)
                      elseif detail.type == "reasoning.encrypted" and detail.data then
                        -- Store encrypted data for preserving in subsequent requests
                        reasoning_data.encrypted = detail.data
                        reasoning_data.id = detail.id
                        reasoning_data.format = detail.format
                      end
                    end

                    -- Set reasoning output if we have any content
                    if #reasoning_content > 0 then
                      data.output.reasoning = data.output.reasoning or {}
                      data.output.reasoning.content =
                        table.concat(reasoning_content, "\n\n")
                      if next(reasoning_data) then
                        data.output.reasoning._data = reasoning_data
                      end
                    elseif next(reasoning_data) then
                      -- Even without visible content, preserve encrypted reasoning data
                      data.output.reasoning = data.output.reasoning or {}
                      data.output.reasoning._data = reasoning_data
                    end

                    -- Don't show empty content as a response
                    if data.output.content == "" then
                      data.output.content = nil
                    end

                    return data
                  end,

                  chat_output = function(self, data, tools)
                    local adapter_utils = require("codecompanion.utils.adapters")
                    if not data or data == "" then
                      return nil
                    end

                    local data_mod = type(data) == "table" and data.body
                      or adapter_utils.clean_streamed_data(data)
                    local ok, json =
                      pcall(vim.json.decode, data_mod, { luanil = { object = true } })
                    if not ok or not json.choices or #json.choices == 0 then
                      return nil
                    end

                    -- Extract thought signature from reasoning_details
                    -- Note: In parallel calls (same response), only first tool gets signature
                    -- In sequential calls (multi-step), each response has its own signature
                    local function get_signature(reasoning_details)
                      if not reasoning_details then
                        return nil
                      end
                      for _, detail in ipairs(reasoning_details) do
                        if detail.type == "reasoning.encrypted" and detail.data then
                          return { google = { thought_signature = detail.data } }
                        end
                      end
                    end

                    -- Convert OpenRouter reasoning_details to extra_content for tool calls
                    if self.opts.tools and tools then
                      for _, choice in ipairs(json.choices) do
                        local delta = self.opts.stream and choice.delta or choice.message
                        local signature = get_signature(delta and delta.reasoning_details)

                        if delta and delta.tool_calls then
                          -- For parallel calls: only first tool in THIS response gets signature
                          -- For sequential calls: each response has 1 tool, so it always gets signature
                          local is_parallel = #delta.tool_calls > 1

                          for i, tool in ipairs(delta.tool_calls) do
                            local tool_index = tool.index and tonumber(tool.index) or i
                            local id = tool.id
                              or string.format("call_%s_%s", json.created, i)

                            -- Attach signature to first tool in parallel calls, or to all tools in sequential calls
                            local should_attach_signature = signature
                              and (not is_parallel or i == 1)

                            if self.opts.stream then
                              -- Find or create tool in streaming mode
                              local existing = vim.iter(tools):find(function(t)
                                return t._index == tool_index
                              end)
                              if existing then
                                if tool["function"] and tool["function"]["arguments"] then
                                  existing["function"]["arguments"] = (
                                    existing["function"]["arguments"] or ""
                                  )
                                    .. tool["function"]["arguments"]
                                end
                                if
                                  should_attach_signature and not existing.extra_content
                                then
                                  existing.extra_content = signature
                                end
                              else
                                table.insert(tools, {
                                  _index = tool_index,
                                  id = id,
                                  type = tool.type,
                                  ["function"] = {
                                    name = tool["function"]["name"],
                                    arguments = tool["function"]["arguments"] or "",
                                  },
                                  extra_content = should_attach_signature and signature
                                    or nil,
                                })
                              end
                            else
                              table.insert(tools, {
                                _index = i,
                                id = id,
                                type = tool.type,
                                ["function"] = {
                                  name = tool["function"]["name"],
                                  arguments = tool["function"]["arguments"] or "",
                                },
                                extra_content = should_attach_signature and signature
                                  or nil,
                              })
                            end
                          end
                        end
                      end
                    end

                    local choice = json.choices[1]
                    local delta = self.opts.stream and choice.delta or choice.message

                    if not delta then
                      return nil
                    end

                    -- Build extra fields for parse_message_meta to process
                    local extra = nil
                    if delta.reasoning_details then
                      extra = { reasoning_details = delta.reasoning_details }
                    end

                    return {
                      status = "success",
                      output = { role = delta.role, content = delta.content },
                      extra = extra,
                    }
                  end,
                },
                schema = {
                  model = {
                    default = "google/gemini-3-pro-preview",
                    choices = function(self)
                      return get_openrouter_tool_models()
                    end,
                  },
                  provider = {
                    order = 11,
                    mapping = "parameters",
                    type = "map",
                    optional = true,
                    desc = "OpenRouter provider configuration with Cerebras/Groq priority",
                    default = {
                      order = { "cerebras", "groq", "deepinfra" }, -- Prioritize Cerebras then DeepInfra then Groq
                      allow_fallbacks = true,
                      data_collection = "deny", -- Block providers that store data for training
                        -- stylua: ignore start
                        ignore = {
                          -- Providers that may train on prompts
                          "chutes", "deepseek", "nineteen", "openinference", "stealth", "targon",
                          -- Providers with unknown data retention periods (poor transparency)
                          "ai21", "aionlabs", "alibaba", "avian", "cloudflare", "crofai", "crusoe",
                          "enfer", "friendli", "gmicloud", "hyperbolic", "lambda", "liquid", "minimax",
                          "ncompass", "novitaai",  "ubicloud", "wandb",
                          -- "openai",
                        }, -- Block providers with poor privacy practices or unclear policies
                      -- stylua: ignore end
                      -- require_parameters = false, -- Allow providers that don't support all parameters
                    },
                    subtype = {
                      order = {
                        type = "list",
                        subtype = { type = "string" },
                        desc = "Preferred provider order (Cerebras, then Groq)",
                        optional = true,
                      },
                      allow_fallbacks = {
                        type = "boolean",
                        desc = "Allow fallback providers when primary is unavailable",
                        default = true,
                        optional = true,
                      },
                      data_collection = {
                        type = "enum",
                        desc = "Data collection policy - deny blocks training providers",
                        choices = { "allow", "deny" },
                        default = "deny",
                        optional = true,
                      },
                      ignore = {
                        type = "list",
                        subtype = { type = "string" },
                        desc = "Providers to block (AI21, AionLabs)",
                        optional = true,
                      },
                      require_parameters = {
                        type = "boolean",
                        desc = "Only use providers supporting all parameters",
                        default = false,
                        optional = true,
                      },
                    },
                  },
                },
              })
            end,

Note: I disable any providers that don't meet my privacy requirements or that train on user data.

Also, for model selection, I use a function called get_openrouter_tool_models() that returns all models with function-calling support. I'm happy to share it if anyone needs it just let me know!

Thank you

edit1: correct some code and indentation
edit2: add note

[olimorris]

We recently merged a PR that allows "extra" fields to be persisted through to the chat buffer and handled accordingly. I did recently add support for Gemini 3 in the Gemini adapter.

I'm working on a PR to allow Gemini 3 for Copilot which will be making use of "extra".

[bassamsdata]

Thanks so much for the update and for all the recent work on this!

For my use case, if not "GitHub copilot", I mainly stick with OpenRouter because it's very convenient for testing different models quickly.
I did notice the updates to the OpenAI adapter, but I wasn't able to get it working on my end. The first tool call works correctly, but subsequent tool calls trigger an error like: Additional data, function call default_api:file_search, position 2. This might just be related to how OpenRouter structures its responses, I'm not entirely sure.

I shared my attempt here in case someone has a cleaner or more idiomatic approach.

Here's an example of the OpenRouter response shape I m seeing:

    tools = {
      calls = { {
          _index = 0,
          extra_content = {
            google = {
              thought_signature = ""
            }
          },
          ["function"] = {
            arguments = '{}',
            name = "insert_edit_into_file"
          },
          id = "tool_insert_edit_into_file_vfVzp3FHRj2YbximS8yM",
          type = "function"
        }, {
          _index = 1,
          ["function"] = {
            arguments = '{}',
            name = "insert_edit_into_file"
          },
          id = "tool_insert_edit_into_file_CD6A02dUmI8X7Z7AIl69",
          type = "function"
        }, {
          _index = 2,
          ["function"] = {
            arguments = '{}',
            name = "insert_edit_into_file"
          },
          id = "tool_insert_edit_into_file_J2xLTAzOS3QeFTlcE70E",
          type = "function"
        } }
    }

Thanks again for your work on this really appreciate it!