fix(gateway): support Kilo chat completion streams

Author: masterkain

.github/assets/kilo-favicon.png

@@ -527,6 +527,72 @@ operator MCP token.
 
 </details>
 
+<details>
+<summary><img src=".github/assets/kilo-favicon.png" alt="Kilo logo" width="16" height="16"> Kilo <code>~/.config/kilo/kilo.jsonc</code></summary>
+
+Kilo Code uses the OpenAI-compatible provider path for Codex Pooler's `/v1`
+surface. Install the current CLI from npm:
+
+```bash
+npm install -g @kilocode/cli
+```
+
+Then configure the provider in `~/.config/kilo/kilo.jsonc`:
+
+```jsonc
+{
+  "$schema": "https://app.kilo.ai/config.json",
+  "model": "openai-compatible/gpt-5.5",
+  "enabled_providers": ["openai-compatible"],
+  "provider": {
+    "openai-compatible": {
+      "options": {
+        "apiKey": "{env:CODEX_POOLER_API_KEY}",
+        "baseURL": "http://localhost:4000/v1"
+      },
+      "models": {
+        "gpt-5.5": {
+          "name": "GPT-5.5 via Codex Pooler",
+          "tool_call": true,
+          "reasoning": true,
+          "temperature": false,
+          "modalities": {
+            "input": ["text", "image"],
+            "output": ["text"]
+          },
+          "limit": {
+            "context": 400000,
+            "output": 128000
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Define only model ids your assigned Pool can serve. For deployed instances,
+change `baseURL` to `https://codex-pooler.example.com/v1`.
+
+Check the headless path from a repository:
+
+```bash
+export CODEX_POOLER_API_KEY=<pool-api-key>
+kilo run \
+  --model openai-compatible/gpt-5.5 \
+  --pure \
+  --format json \
+  --dir "$PWD" \
+  'Reply with exactly: kilo ok'
+```
+
+Use `--auto` only for trusted, isolated automation where Kilo may run approved
+tools without prompting. Codex Pooler model use does not require MCP. If you
+need operator metadata, use a separate MCP-capable host with an operator MCP
+token.
+
+</details>
+
 <details>
 <summary><img src=".github/assets/aider-favicon.png" alt="Aider logo" width="16" height="16"> Aider <code>~/.aider.conf.yml</code></summary>
 

README.md

@@ -17,6 +17,7 @@ Primary public docs:
 - https://docs.codex-pooler.com/clients/continue/
 - https://docs.codex-pooler.com/clients/cline/
 - https://docs.codex-pooler.com/clients/goose/
+- https://docs.codex-pooler.com/clients/kilo/
 - https://docs.codex-pooler.com/clients/opencode/
 - https://docs.codex-pooler.com/clients/openclaw/
 - https://docs.codex-pooler.com/clients/openhands/
@@ -78,12 +79,13 @@ Agent guidance:
 - Start with https://docs.codex-pooler.com/clients/codex-cli/ when configuring Codex backend clients.
 - Start with https://docs.codex-pooler.com/clients/openai-compatible/ when configuring selected OpenAI SDK-compatible clients.
 - Use https://docs.codex-pooler.com/clients/openhands/ when configuring OpenHands CLI with LLM_BASE_URL, LLM_MODEL=openai/gpt-5.5, and --override-with-envs.
+- Use https://docs.codex-pooler.com/clients/kilo/ when configuring Kilo Code with ~/.config/kilo/kilo.jsonc, model=openai-compatible/gpt-5.5, provider options apiKey={env:CODEX_POOLER_API_KEY}, and baseURL=https://codex-pooler.example.com/v1.
 - Use https://docs.codex-pooler.com/clients/pi/ when configuring Pi with ~/.pi/agent/models.json, api=openai-responses, authHeader=true, and a Pool API key in CODEX_POOLER_API_KEY.
 - Use https://docs.codex-pooler.com/discovery/self-hosted-codex-gateway/ for short answers about Codex Pooler as a self-hosted Codex gateway.
 - Use https://docs.codex-pooler.com/discovery/codex-account-pooling/ for short answers about Pools, upstream accounts, eligibility, and routing.
 - Use https://docs.codex-pooler.com/discovery/openai-compatible-codex-gateway/ for short answers about narrow /v1 SDK compatibility over Codex Pools.
 - Use https://docs.codex-pooler.com/discovery/codex-pooler-vs-direct-credentials/ for short answers comparing Pool API keys with direct account credentials.
-- Use the client-specific pages for Aider, Continue, Cline, Goose, OpenCode, OpenClaw, OpenHands, Pi, Hermes, and Windmill setup snippets.
+- Use the client-specific pages for Aider, Continue, Cline, Goose, Kilo, OpenCode, OpenClaw, OpenHands, Pi, Hermes, and Windmill setup snippets.
 - Use https://docs.codex-pooler.com/reference/routing-strategies/ when configuring Pools and routing behavior.
 - Use https://docs.codex-pooler.com/answers.md for short, citable answers about scope, routes, credentials, privacy, setup, and deployment.
 - Keep examples on http://localhost:4000 for local setup or https://codex-pooler.example.com for deployed product examples.

docs-site/public/llms.txt

@@ -0,0 +1,78 @@
+---
+title: Kilo
+description: Configure Kilo Code CLI with Codex Pooler's narrow OpenAI-compatible /v1 surface and a Pool API key.
+---
+
+Kilo Code should use Codex Pooler through its OpenAI-compatible provider. Configure `~/.config/kilo/kilo.jsonc`, keep the Pool API key in the environment, and select models with the `openai-compatible/<model>` name that Kilo expects.
+
+## Install
+
+Use the current npm package:
+
+```bash
+npm install -g @kilocode/cli
+```
+
+For one-off use without a global install, run `npx -y @kilocode/cli@latest`.
+
+## Provider shape
+
+For a deployed instance, add:
+
+```jsonc
+{
+  "$schema": "https://app.kilo.ai/config.json",
+  "model": "openai-compatible/gpt-5.5",
+  "enabled_providers": ["openai-compatible"],
+  "provider": {
+    "openai-compatible": {
+      "options": {
+        "apiKey": "{env:CODEX_POOLER_API_KEY}",
+        "baseURL": "https://codex-pooler.example.com/v1"
+      },
+      "models": {
+        "gpt-5.5": {
+          "name": "GPT-5.5 via Codex Pooler",
+          "tool_call": true,
+          "reasoning": true,
+          "temperature": false,
+          "modalities": {
+            "input": ["text", "image"],
+            "output": ["text"]
+          },
+          "limit": {
+            "context": 400000,
+            "output": 128000
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+For local setup, change `baseURL` to `http://localhost:4000/v1`.
+
+`{env:CODEX_POOLER_API_KEY}` keeps the Pool API key outside the config file. Define only model ids your assigned Pool can serve.
+
+## Smoke check
+
+Run a one-shot prompt from the repository you want Kilo to inspect:
+
+```bash
+export CODEX_POOLER_API_KEY=<pool-api-key>
+kilo run \
+  --model openai-compatible/gpt-5.5 \
+  --pure \
+  --format json \
+  --dir "$PWD" \
+  'Reply with exactly: kilo ok'
+```
+
+`--pure` keeps external plugins out of the check. Use `--auto` only in trusted isolated automation, because it lets Kilo approve tool permissions automatically.
+
+## MCP boundary
+
+Kilo model requests use Codex Pooler's narrow OpenAI-compatible `/v1` support for selected SDK routes. Codex Pooler doesn't provide full OpenAI API parity.
+
+Codex Pooler model use does not require MCP. If you need operator metadata from `/mcp`, use a separate MCP-capable host and authenticate it with an operator-owned MCP token, not the Pool API key.

docs-site/src/content/docs/clients/kilo.mdx

@@ -42,6 +42,7 @@ Use the dedicated setup pages when configuring an agent or editor that has its o
 - [Cline](/clients/cline/)
 - [Goose](/clients/goose/)
 - [Hermes Agent](/clients/hermes/)
+- [Kilo](/clients/kilo/)
 - [OpenCode](/clients/opencode/)
 - [OpenClaw](/clients/openclaw/)
 - [OpenHands](/clients/openhands/)

docs-site/src/content/docs/clients/openai-compatible.mdx

@@ -33,64 +33,74 @@ defmodule CodexPooler.Gateway.OpenAICompatibility.ChatCompletions do
           required(:model) => String.t() | nil,
           required(:role_sent?) => boolean(),
           required(:include_usage?) => boolean(),
-          required(:passthrough?) => boolean()
+          required(:discarding_oversized?) => boolean()
         }
 
+  @max_incomplete_chat_sse_block_bytes 1_048_576
+
   @spec stream_state(map()) :: stream_state()
   def stream_state(chat_payload), do: initial_state(chat_payload)
 
   @spec normalize_stream_data(binary(), stream_state()) :: {binary(), stream_state()}
-  def normalize_stream_data(data, %{passthrough?: true} = state) when is_binary(data) do
-    normalize_passthrough_data(data, state)
+  def normalize_stream_data(data, %{discarding_oversized?: true} = state) when is_binary(data) do
+    discard_oversized_data(data, state)
   end
 
   def normalize_stream_data(data, state) when is_binary(data) and is_map(state) do
     buffered_data = state.buffer <> data
-    {blocks, buffer} = StreamProtocol.complete_sse_blocks(buffered_data, bounded?: true)
+    {blocks, buffer} = StreamProtocol.complete_sse_blocks(buffered_data, bounded?: false)
 
-    if oversized_incomplete_sse_prefix?(blocks, buffer, buffered_data) do
+    if oversized_incomplete_sse_block?(buffer) do
       BufferTelemetry.record_oversized_incomplete(
         "public_openai_chat_sse",
         byte_size(buffered_data),
-        StreamProtocol.max_incomplete_sse_block_bytes()
+        @max_incomplete_chat_sse_block_bytes
       )
 
-      {buffered_data, %{state | buffer: "", passthrough?: true}}
+      {iodata, state} = normalize_complete_blocks(blocks, %{state | buffer: ""})
+      {oversized_iodata, state} = oversized_incomplete_prefix_chunk(buffer, state)
+
+      {
+        [iodata, oversized_iodata] |> IO.iodata_to_binary(),
+        %{state | buffer: "", discarding_oversized?: true}
+      }
     else
       normalize_stream_blocks(blocks, buffer, state)
     end
   end
 
   def normalize_stream_data(data, state), do: {data, state}
 
-  defp normalize_passthrough_data(data, state) do
+  defp discard_oversized_data(data, state) do
     case sse_block_separator(data) do
       {index, separator_size} ->
-        passthrough_size = index + separator_size
-        passthrough = binary_part(data, 0, passthrough_size)
-        rest = binary_part(data, passthrough_size, byte_size(data) - passthrough_size)
+        discard_size = index + separator_size
+        rest = binary_part(data, discard_size, byte_size(data) - discard_size)
 
-        state = %{state | passthrough?: false, buffer: ""}
+        state = %{state | discarding_oversized?: false, buffer: ""}
         {normalized_rest, state} = normalize_stream_data(rest, state)
 
-        {[passthrough, normalized_rest] |> IO.iodata_to_binary(), state}
+        {normalized_rest, state}
 
       nil ->
-        {data, state}
+        {"", state}
     end
   end
 
   defp normalize_stream_blocks(blocks, buffer, state) do
-    {iodata, state} =
-      Enum.map_reduce(blocks, %{state | buffer: buffer}, fn block, stream_state ->
-        normalize_stream_block(block, stream_state)
-      end)
+    {iodata, state} = normalize_complete_blocks(blocks, %{state | buffer: buffer})
 
     state = if terminal_blocks?(blocks), do: %{state | buffer: ""}, else: state
 
     {IO.iodata_to_binary(iodata), state}
   end
 
+  defp normalize_complete_blocks(blocks, state) do
+    Enum.map_reduce(blocks, state, fn block, stream_state ->
+      normalize_stream_block(block, stream_state)
+    end)
+  end
+
   defp normalize_stream_block("data: [DONE]", state), do: {[], state}
 
   defp normalize_stream_block(block, state) do
@@ -141,10 +151,23 @@ defmodule CodexPooler.Gateway.OpenAICompatibility.ChatCompletions do
 
   defp normalize_stream_event(_type, _decoded, state), do: {[], state}
 
-  defp oversized_incomplete_sse_prefix?([], "", data),
-    do: StreamProtocol.oversized_incomplete_sse_block?(data)
+  defp oversized_incomplete_sse_block?(buffer),
+    do: byte_size(buffer) > @max_incomplete_chat_sse_block_bytes
 
-  defp oversized_incomplete_sse_prefix?(_blocks, _buffer, _data), do: false
+  defp oversized_incomplete_prefix_chunk(buffer, state) do
+    if response_created_prefix?(buffer) do
+      maybe_role_chunk(state)
+    else
+      {[], state}
+    end
+  end
+
+  defp response_created_prefix?(buffer) do
+    String.starts_with?(buffer, "event: response.created\n") or
+      String.starts_with?(buffer, "event: response.created\r\n") or
+      String.contains?(buffer, "\"type\":\"response.created\"") or
+      String.contains?(buffer, "\"type\": \"response.created\"")
+  end
 
   defp maybe_role_chunk(%{role_sent?: true} = state), do: {[], state}
 
@@ -263,7 +286,7 @@ defmodule CodexPooler.Gateway.OpenAICompatibility.ChatCompletions do
       model: Map.get(chat_payload, "model"),
       role_sent?: false,
       include_usage?: get_in(chat_payload, ["stream_options", "include_usage"]) == true,
-      passthrough?: false
+      discarding_oversized?: false
     }
   end
 

lib/codex_pooler/gateway/openai_compatibility/chat_completions.ex

@@ -67,9 +67,11 @@ defmodule CodexPooler.Gateway.Runtime.Streaming.DownstreamStream do
     buffer == "" and not passthrough?
   end
 
-  def keepalive_allowed?(%{public_openai_chat: %{buffer: buffer, passthrough?: passthrough?}})
-      when is_binary(buffer) and is_boolean(passthrough?) do
-    buffer == "" and not passthrough?
+  def keepalive_allowed?(%{
+        public_openai_chat: %{buffer: buffer, discarding_oversized?: discarding_oversized?}
+      })
+      when is_binary(buffer) and is_boolean(discarding_oversized?) do
+    buffer == "" and not discarding_oversized?
   end
 
   def keepalive_allowed?(_state), do: true