feat(adapters): support extra fields in OpenAI adapter (#2359)

Author: Davidyz

doc/codecompanion.txt

@@ -1,4 +1,4 @@
-*codecompanion.txt*        For NVIM v0.11        Last change: 2025 November 17
+*codecompanion.txt*        For NVIM v0.11        Last change: 2025 November 19
 
 ==============================================================================
 Table of Contents                            *codecompanion-table-of-contents*
@@ -643,7 +643,7 @@ CodeCompanion, you simply need to follow their Getting Started
 <https://docs.augmentcode.com/cli/overview#getting-started> guide.
 
 
-SETUP: DOCKER CAGENT ~
+SETUP: CAGENT ~
 
 To use Docker’s Cagent <https://github.com/docker/cagent> within
 CodeCompanion, you need to follow these steps:
@@ -878,9 +878,10 @@ The configuration for both types of adapters is exactly the same, however they
 sit within their own tables (`adapters.http.*` and `adapters.acp.*`) and have
 different options available. HTTP adapters use `models` to allow users to
 select the specific LLM they’d like to interact with. ACP adapters use
-`commands` to allow users to customize their interaction with agents (e.g.�
-enabling `yolo` mode). As there is a lot of shared functionality between the
-two adapters, it is recommend that you read this page alongside the ACP one.
+`commands` to allow users to customize their interaction with agents
+(e.g. enabling `yolo` mode). As there is a lot of shared functionality between
+the two adapters, it is recommend that you read this page alongside the ACP
+one.
 
 
 CHANGING THE DEFAULT ADAPTER ~
@@ -912,7 +913,7 @@ the adapter’s URL, headers, parameters and other fields at runtime.
 
 Supported `env` value types: - **Plain environment variable name (string)**: if
 the value is the name of an environment variable that has already been set
-(e.g.� `"HOME"` or `"GEMINI_API_KEY"`), the plugin will read the value. -
+(e.g. `"HOME"` or `"GEMINI_API_KEY"`), the plugin will read the value. -
 **Command (string prefixed with cmd:)**: any value that starts with `cmd:` will
 be executed via the shell. Example: `"cmd:op read
 op://personal/Gemini/credential --no-newline"`. - **Function**: you can provide
@@ -1287,6 +1288,88 @@ the plugin:
 <
 
 
+SETUP: OPENROUTER WITH REASONING OUTPUT ~
+
+>lua
+    require("codecompanion").setup({
+      adapters = {
+        http = {
+          openrouter = function()
+            return require("codecompanion.adapters").extend("openai_compatible", {
+              env = {
+                url = "https://openrouter.ai/api",
+                api_key = "OPENROUTER_API_KEY",
+                chat_url = "/v1/chat/completions",
+              },
+              handlers = {
+                parse_message_meta = function(self, data)
+                  local extra = data.extra
+                  if extra and extra.reasoning then
+                    data.output.reasoning = { content = extra.reasoning }
+                    if data.output.content == "" then
+                      data.output.content = nil
+                    end
+                  end
+                  return data
+                end,
+              },
+            })
+          end,
+        },
+      },
+      strategies = {
+        chat = {
+          adapter = "openrouter",
+        },
+        inline = {
+          adapter = "openrouter",
+        },
+      },
+    })
+<
+
+
+SETUP: LLAMA.CPP WITH --REASONING-FORMAT DEEPSEEK ~
+
+>lua
+    require("codecompanion").setup({
+      adapters = {
+        http = {
+          ["llama.cpp"] = function()
+            return require("codecompanion.adapters").extend("openai_compatible", {
+              env = {
+                url = "http://127.0.0.1:8080", -- replace with your llama.cpp instance
+                api_key = "TERM",
+                chat_url = "/v1/chat/completions",
+              },
+              handlers = {
+                parse_message_meta = function(self, data)
+                  local extra = data.extra
+                  if extra and extra.reasoning_content then
+                    data.output.reasoning = { content = extra.reasoning_content }
+                    if data.output.content == "" then
+                      data.output.content = nil
+                    end
+                  end
+                  return data
+                end,
+              },
+            })
+          end,
+        },
+      },
+      strategies = {
+        chat = {
+          adapter = "llama.cpp",
+        },
+        inline = {
+          adapter = "llama.cpp",
+        },
+      },
+    })
+<
+
+
 CHAT BUFFER                          *codecompanion-configuration-chat-buffer*
 
 By default, CodeCompanion provides a "chat" strategy that uses a dedicated
@@ -2869,7 +2952,7 @@ The fastest way to copy an LLM’s code output is with `gy`. This will yank the
 nearest codeblock.
 
 
-APPLYING AN LLM€�S EDITS TO A BUFFER OR FILE ~
+APPLYING AN LLM’S EDITS TO A BUFFER OR FILE ~
 
 The |codecompanion-usage-chat-buffer-tools-files| tool, combined with the
 |codecompanion-usage-chat-buffer-variables.html-buffer| variable or
@@ -4922,6 +5005,7 @@ These handlers parse LLM responses:
 - `response.parse_chat` - Format chat output for the chat buffer
 - `response.parse_inline` - Format output for inline insertion
 - `response.parse_tokens` - Extract token count from the response
+- `response.parse_meta` - Process non-standard fields in the response (currently only supported by OpenAI-based adapters)
 
 
 TOOL HANDLERS
@@ -4936,7 +5020,7 @@ These handlers manage tool/function calling:
   as a great reference to understand how they’re working with the output of the
   API
 
-OPENAI€�S API OUTPUT
+OPENAI’S API OUTPUT
 
 If we reference the OpenAI documentation
 <https://platform.openai.com/docs/guides/text-generation/chat-completions-api>
@@ -5141,6 +5225,53 @@ we have data in our response:
 <
 
 
+RESPONSE.PARSE_META
+
+Some OpenAI-compatible API providers like deepseek, Gemini and OpenRouter
+implement a superset of the standard specification, and provide reasoning
+tokens/summaries within their response. The non-standard fields in the
+`message` (non-streaming)
+<https://platform.openai.com/docs/api-reference/chat/object#chat-object-choices-message>
+or `delta` (streaming)
+<https://platform.openai.com/docs/api-reference/chat-streaming/streaming#chat_streaming-streaming-choices-delta>
+object are captured by the OpenAI adapter and can be used to extract the
+reasoning.
+
+For example, the DeepSeek API provides the reasoning tokens in the
+`delta.reasoning_content` field. We can therefore use the following
+`parse_meta` handler to extract the reasoning tokens and put them into the
+appropriate output fields:
+
+>lua
+    handlers = {
+      response = {
+        ---@param self CodeCompanion.HTTPAdapter
+        --- `data` is the output of the `parse_chat` handler
+        ---@param data {status: string, output: {role: string?, content: string?}, extra: table}
+        ---@return {status: string, output: {role: string?, content: string?, reasoning:{content: string?}?}}
+        parse_meta = function(self, data)
+          local extra = data.extra
+          if extra.reasoning_content then
+            -- codecompanion expect the reasoning tokens in this format
+            data.output.reasoning = { content = extra.reasoning_content } 
+            -- so that codecompanion doesn't mistake this as a normal response with empty string as the content
+            if data.output.content == "" then
+              data.output.content = nil
+            end
+          end
+          return data
+        end
+      }
+    }
+<
+
+Notes:
+
+1. You don’t always have to set `data.output.content` to `nil`. This is mostly intended for `streaming`, and you may encounter issues in non-stream mode if you do that.
+2. It’s expected that the processed `data` table is returned at the end.
+3. For adapters that are using the legacy flat handler formats, this handler should be named `handlers.parse_message_meta`. The function signature stays the same.
+
+
 REQUEST.BUILD_PARAMETERS
 
 For the purposes of the OpenAI adapter, no additional parameters need to be
@@ -6796,7 +6927,7 @@ tool to function. In the case of Anthropic, we insert additional headers.
 <
 
 Some adapter tools can be a `hybrid` in terms of their implementation. That is,
-they’re an adapter tool that requires a client-side component (i.e.� a
+they’re an adapter tool that requires a client-side component (i.e. a
 built-in tool). This is the case for the
 |codecompanion-usage-chat-buffer-tools-memory| tool from Anthropic. To allow
 for this, ensure that the tool definition in `available_tools` has

doc/configuration/adapters.md

@@ -378,3 +378,82 @@ require("codecompanion").setup({
 }),
 ```
 
+## Setup: OpenRouter with Reasoning Output
+
+```lua 
+require("codecompanion").setup({
+  adapters = {
+    http = {
+      openrouter = function()
+        return require("codecompanion.adapters").extend("openai_compatible", {
+          env = {
+            url = "https://openrouter.ai/api",
+            api_key = "OPENROUTER_API_KEY",
+            chat_url = "/v1/chat/completions",
+          },
+          handlers = {
+            parse_message_meta = function(self, data)
+              local extra = data.extra
+              if extra and extra.reasoning then
+                data.output.reasoning = { content = extra.reasoning }
+                if data.output.content == "" then
+                  data.output.content = nil
+                end
+              end
+              return data
+            end,
+          },
+        })
+      end,
+    },
+  },
+  strategies = {
+    chat = {
+      adapter = "openrouter",
+    },
+    inline = {
+      adapter = "openrouter",
+    },
+  },
+})
+```
+
+## Setup: llama.cpp with `--reasoning-format deepseek`
+
+```lua
+require("codecompanion").setup({
+  adapters = {
+    http = {
+      ["llama.cpp"] = function()
+        return require("codecompanion.adapters").extend("openai_compatible", {
+          env = {
+            url = "http://127.0.0.1:8080", -- replace with your llama.cpp instance
+            api_key = "TERM",
+            chat_url = "/v1/chat/completions",
+          },
+          handlers = {
+            parse_message_meta = function(self, data)
+              local extra = data.extra
+              if extra and extra.reasoning_content then
+                data.output.reasoning = { content = extra.reasoning_content }
+                if data.output.content == "" then
+                  data.output.content = nil
+                end
+              end
+              return data
+            end,
+          },
+        })
+      end,
+    },
+  },
+  strategies = {
+    chat = {
+      adapter = "llama.cpp",
+    },
+    inline = {
+      adapter = "llama.cpp",
+    },
+  },
+})
+```

doc/extending/adapters.md

@@ -176,6 +176,7 @@ These handlers parse LLM responses:
 - `response.parse_chat` - Format chat output for the chat buffer
 - `response.parse_inline` - Format output for inline insertion
 - `response.parse_tokens` - Extract token count from the response
+- `response.parse_meta` - Process non-standard fields in the response (currently only supported by OpenAI-based adapters)
 
 ### Tool Handlers
 
@@ -376,6 +377,43 @@ handlers = {
 }
 ```
 
+### `response.parse_meta`
+
+Some OpenAI-compatible API providers like deepseek, Gemini and OpenRouter implement a superset of the standard specification, and provide reasoning tokens/summaries within their response.
+The non-standard fields in the [`message` (non-streaming)](https://platform.openai.com/docs/api-reference/chat/object#chat-object-choices-message) or [`delta` (streaming)](https://platform.openai.com/docs/api-reference/chat-streaming/streaming#chat_streaming-streaming-choices-delta) object are captured by the OpenAI adapter and can be used to extract the reasoning.
+
+For example, the DeepSeek API provides the reasoning tokens in the `delta.reasoning_content` field.
+We can therefore use the following `parse_meta` handler to extract the reasoning tokens and put them into the appropriate output fields: 
+
+```lua
+handlers = {
+  response = {
+    ---@param self CodeCompanion.HTTPAdapter
+    --- `data` is the output of the `parse_chat` handler
+    ---@param data {status: string, output: {role: string?, content: string?}, extra: table}
+    ---@return {status: string, output: {role: string?, content: string?, reasoning:{content: string?}?}}
+    parse_meta = function(self, data)
+      local extra = data.extra
+      if extra.reasoning_content then
+        -- codecompanion expect the reasoning tokens in this format
+        data.output.reasoning = { content = extra.reasoning_content } 
+        -- so that codecompanion doesn't mistake this as a normal response with empty string as the content
+        if data.output.content == "" then
+          data.output.content = nil
+        end
+      end
+      return data
+    end
+  }
+}
+```
+
+Notes: 
+
+1. You don't always have to set `data.output.content` to `nil`. This is mostly intended for `streaming`, and you may encounter issues in non-stream mode if you do that.
+2. It's expected that the processed `data` table is returned at the end.
+3. For adapters that are using the legacy flat handler formats, this handler should be named `handlers.parse_message_meta`. The function signature stays the same.
+
 ### `request.build_parameters`
 
 For the purposes of the OpenAI adapter, no additional parameters need to be created. So we just pass this through: