Except there was a gap. Every streaming call cost $0.00 in the ledger. Silently. No error, no warning – just wrong numbers.

I found the gap, fixed it, and got the PR merged. This is the story of how streaming cost tracking actually works.

What AgentBudget does

AgentBudget is an open-source SDK that puts a hard dollar limit on AI agent sessions. Two lines, no infrastructure:

1import agentbudget
2agentbudget.init("$5.00")

It works by monkey-patching Completions.create (OpenAI) and Messages.create (Anthropic) at init time. Every call goes through a wrapper that looks up the model cost, accumulates spend, and raises BudgetExhausted when the limit is hit.

The non-streaming path worked fine. The streaming path did not.

The bug

When stream=True, the patched method receives a Stream object back from the SDK – not a completed response with token counts. The original code had no handling for this case. It silently passed the stream through untracked.

Every streaming call registered as $0.00 in the ledger. Any agent using streaming could blow past its budget with zero resistance. The circuit breaker was blind to half its traffic.

Why streaming is harder to cost

Non-streaming is straightforward: the response comes back with a usage object containing prompt_tokens and completion_tokens. Multiply by the per-token rate, done.

Streaming returns a sequence of chunks. Token counts are not available upfront – they only appear after the stream is exhausted. For OpenAI specifically, usage data on the final chunk is opt-in: you need stream_options={"include_usage": True} in the request, otherwise the final chunk carries no usage data and there is nothing to cost.

Anthropic handles it differently. Usage data is always present, split across two events: message_start carries input tokens, message_delta carries output tokens at the end.

The fix: transparent wrapper classes

The solution is four wrapper classes that intercept the stream, yield every chunk unchanged, and record cost after the iterator is exhausted:

Each wrapper is fully transparent to the caller. The existing code pattern – for chunk in stream: or async for chunk in stream: or with client.stream(...) as stream: – continues to work without any changes.

The wrapper accumulates token counts as chunks arrive, then records the cost in the session ledger once the stream ends.

For OpenAI:

 1class _OpenAIStreamWrapper:
 2    def __init__(self, stream, session, model):
 3        self._stream = stream
 4        self._session = session
 5        self._model = model
 6
 7    def __iter__(self):
 8        for chunk in self._stream:
 9            # Track usage from the final chunk
10            if chunk.usage:
11                cost = price(self._model, chunk.usage)
12                self._session.record(cost)
13            yield chunk
14
15    # Full protocol: __enter__, __exit__, close()

For Anthropic, the accumulation spans two event types:

 1class _AnthropicStreamWrapper:
 2    def __iter__(self):
 3        input_tokens = 0
 4        output_tokens = 0
 5        for event in self._stream:
 6            if event.type == "message_start":
 7                input_tokens = event.message.usage.input_tokens
 8            elif event.type == "message_delta":
 9                output_tokens = event.usage.output_tokens
10            yield event
11        cost = price(self._model, input_tokens, output_tokens)
12        self._session.record(cost)

The detection of whether a response is a stream happens via isinstance checks guarded by ImportError, so the wrapper degrades gracefully if only one SDK is installed.

Implementing the full protocol

The tricky part is not the cost tracking logic – it is making the wrapper implement the full stream protocol correctly.

Python streams support multiple usage patterns: iterator (for chunk in stream), context manager (with stream), async iterator, async context manager, and explicit close()/aclose(). Missing any of these means certain callers will break with an AttributeError or a resource leak.

The wrapper needs to implement all of them:

 1# Sync: iterator + context manager + close
 2def __iter__(self): ...
 3def __enter__(self): return self
 4def __exit__(self, *args): self.close()
 5def close(self): self._stream.close()
 6
 7# Async: async iterator + async context manager + aclose
 8async def __aiter__(self): ...
 9async def __aenter__(self): return self
10async def __aexit__(self, *args): await self.aclose()
11async def aclose(self): await self._stream.aclose()

Getting this wrong is invisible in unit tests with mocks but breaks immediately against real SDK objects.

Tests

The PR added 19 tests covering:

• Cost recorded correctly after stream exhaustion
• Chunks with no usage data skipped without error
• Passthrough identity – every chunk the caller sees is unchanged
• BudgetExhausted propagates correctly mid-stream
• Both for chunk in stream: and with client.stream() as stream: patterns
• close() and aclose() delegation to the underlying stream
• Drop-in mode (agentbudget.init()) wrapping end-to-end
• No-session noop – if no budget session is active, streaming is fully transparent

All 129 pre-existing tests continued to pass. 148 total passing at merge.

The known limitation

OpenAI streaming requires the caller to pass stream_options={"include_usage": True}. Without it, the final chunk carries no usage data, and the cost is silently $0.

This is OpenAI’s API behaviour – usage data on streams is opt-in. The limitation is documented in the module docstring. A future improvement could auto-inject the option at the patch layer, but that requires modifying the outbound request, which is a bigger change than this PR intended to be.

Anthropic has no equivalent limitation – usage is always present.

What I learned

Transparent wrappers need the full protocol. It is tempting to implement just __iter__ and call it done. But real callers use context managers, explicit close, and async variants. Implementing the minimum breaks production code in ways that are hard to debug.

Streaming costs are provider-specific. OpenAI and Anthropic have different conventions for where usage data appears in the stream. Any SDK that claims to support both needs to handle both separately.

Test against real SDK objects, not just mocks. The isinstance detection and chunk structure only behave correctly against live SDK classes. Mock-based tests passed for the wrong reasons until I verified against an actual installed SDK.

Links

• PR #6 – feat: track costs for streaming OpenAI and Anthropic responses
• AgentBudget on GitHub
• PyPI

This is the story of setting that up in one session, and the parts that went sideways.

The Stack

Four moving parts:

• Bifrost – LLM gateway already running on localhost:24242, routing to Ollama cloud models
• Hermes Agent – open-source AI agent framework by Nous Research, pointed at Bifrost
• Ollama – cloud relay for gemma4 and qwen3.5 cloud models via ollama.com
• Camoufox – Firefox fork with TLS fingerprint spoofing for scraping tasks

The goal was to have Hermes run as a Telegram bot so I could assign it tasks from my phone, with all model traffic flowing through Bifrost so routing stays centralized.

Bifrost First

Bifrost was already up on port 24242 with Ollama configured. The only addition needed was an ollama-cloud provider pointing at https://ollama.com rather than localhost. This is a non-obvious distinction.

The trap: Ollama’s OpenAI-compatible endpoint (/v1/chat/completions) does not work for cloud models. It hangs. Cloud models only work through Ollama’s native /api/chat endpoint. Pointing Bifrost directly at https://ollama.com instead of localhost:11434 bypasses the broken compat layer and hits the right path.

Once the provider was registered and OLLAMA_API_KEY was set in .zshrc, both cloud models confirmed working:

1ollama pull gemma4:31b-cloud
2ollama pull qwen3.5:cloud

Installing Hermes

1curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

That puts everything under ~/.hermes/. The setup wizard runs next:

1hermes setup

It walks through provider selection interactively. I pointed it at the Bifrost custom endpoint (http://localhost:24242/v1) and picked ollama-cloud/gemma4:31b-cloud as the default model.

Key config paths:

~/.hermes/config.yaml    -- main settings
~/.hermes/.env           -- secrets and API keys
~/.hermes/skills/        -- reusable agent procedures
~/.hermes/sessions/      -- full conversation history (searchable)

After setup, a quick smoke test confirmed the agent was up and routing through Bifrost correctly:

1hermes chat -q "what model are you using and where does traffic go"

Context Window

The default context length was under 20k tokens. Ollama cloud models support much larger windows. One config set:

1hermes config set model.context_length 200000

Takes effect on the next session restart.

Telegram Bot

This is where Hermes gets genuinely useful. The gateway turns it into a bot that accepts tasks from any platform you connect.

Create a bot via BotFather, get the token, then add it to ~/.hermes/.env:

1TELEGRAM_BOT_TOKEN=<your-bot-token>
2TELEGRAM_ALLOWED_USERS=<your-numeric-telegram-id>

TELEGRAM_ALLOWED_USERS takes the numeric user ID, not the username. Lock it down. Anyone who finds the bot URL can send it commands if this is not set.

Start the gateway:

1hermes gateway run

For persistent background operation, install it as a service:

1hermes gateway install
2hermes gateway start

A set of aliases in .zshrc makes it easier to manage day to day:

1alias hermes-gateway-start="hermes gateway start"
2alias hermes-gateway-stop="hermes gateway stop"
3alias hermes-gateway-log="tail -f ~/.hermes/logs/gateway.log"

First run hit a missing Python dependency and failed silently. The fix was running hermes gateway run in the foreground once to see the real error, installing the missing package, then moving back to the service.

Camoufox

Camoufox is a Firefox fork built for scraping. It spoofs TLS fingerprints so sites see a legitimate browser rather than a Playwright or CDP signature. It exposes a CDP endpoint that Hermes’s browser tool connects to.

1git clone https://github.com/daijro/camoufox
2cd camoufox && npm install
3python -m camoufox fetch   # ~300MB download

The camoufox fetch step downloads the actual browser binary and does not run automatically via postinstall. If you skip it, the first start fails silently. Run it manually and wait for the download to finish before starting the server.

Start it on port 9377:

1python -m camoufox server --port 9377 &

Smoke test via Hermes:

1hermes chat -q "use the browser to fetch the title of example.com"

Aliases for day-to-day:

1alias camofox-start="python -m camoufox server --port 9377 &"
2alias camofox-stop="pkill -f 'camoufox server'"

What Actually Went Wrong

Ollama native vs compat endpoint. Already covered above, but it cost a couple of hours. If a cloud model hangs at the provider level, check whether your gateway is talking to the right API path.

Camoufox silent failure. The binary fetch is not in postinstall. No error, just no browser. Always run python -m camoufox fetch explicitly before the first start.

Hermes gateway dependency. First start printed nothing useful. Run in foreground before daemonizing so you can see the actual error.

Bifrost and empty API keys. Ollama initially rejected non-empty dummy keys in the Authorization header. Setting the key to an empty string before switching to the real OLLAMA_API_KEY got things unstuck. The order mattered.

Session corruption in OpenCode. An OpenCode session used to orchestrate this setup got a zombie assistant message from an interrupted stream. The message had an empty string for content. Bifrost converted that empty string to null before forwarding, and the upstream provider rejected the entire next request with messages.315.member.content must not be null. Every retry included the same zombie in history, so the error was permanent until manually fixed.

The fix is to delete the zombie row directly from the OpenCode SQLite database:

1sqlite3 ~/.local/share/opencode/opencode.db \
2  "DELETE FROM message WHERE id = '<zombie-message-id>' AND session_id = '<session-id>';"

There is no built-in repair command. Back up the database before editing it.

Final State

Services running when done:

bifrost    :24242  -- Ollama cloud routes
ollama     :11434  -- cloud relay (gemma4, qwen3.5)
camoufox   :9377   -- CDP browser endpoint
hermes     gateway -- Telegram bot (restricted to single user)

The agent receives messages on Telegram, runs tool calls locally (terminal, browser, file ops, web search), and routes all model traffic through Bifrost.

What’s Left

The original plan included running a local Qwen3.5-27B model via llama.cpp with Metal acceleration. That is a 13.5GB download and a build-from-source step, so it was deferred to the next session. The cloud routing setup works fine in the meantime.

References

• Hermes Agent: https://github.com/NousResearch/hermes-agent
• Hermes docs: https://hermes-agent.nousresearch.com/docs/
• Bifrost: https://github.com/maximhq/bifrost
• Camoufox: https://github.com/daijro/camoufox
• OpenCode: https://opencode.ai

So I built freeseek-proxy: a local proxy that sits between OpenAI-compatible clients (opencode, Claude Code, any SDK) and DeepSeek’s web chat backend. You send standard /v1/chat/completions requests; it handles sessions, PoW, TLS fingerprinting, and SSE translation behind the scenes.

This post covers the four hardest problems I had to solve.

The architecture (it’s two processes, not one)

The proxy is split into two halves that talk over localhost:

                  ┌──────────────────────────┐
                  │   Client                 │
                  │   (opencode / curl / SDK)│
                  └────────────┬─────────────┘
                               │
                  POST /v1/chat/completions
                       (OpenAI format)
                               │
                  ┌────────────▼─────────────┐
                  │   TypeScript Proxy       │
                  │   Hono on Bun :9123      │
                  │                          │
                  │   · Request normalization│
                  │   · Tool-call compat     │
                  │   · SSE reformatting     │
                  │   · Session management   │
                  └────────────┬─────────────┘
                               │
                    HTTP localhost:8081
                               │
                  ┌────────────▼─────────────┐
                  │   Python Backend         │
                  │   FastAPI + uvicorn      │
                  │                          │
                  │   · curl_cffi (TLS spoof)│
                  │   · WASM PoW solver      │
                  │   · Cookie management    │
                  │   · Auth (token / login) │
                  └────────────┬─────────────┘
                               │
                   HTTPS chat.deepseek.com
                               │
                  ┌────────────▼─────────────┐
                  │      DeepSeek API        │
                  └──────────────────────────┘

Why two languages? DeepSeek does browser fingerprinting. Their servers check TLS fingerprints, and if yours looks like python-requests or node-fetch, you get blocked. The Python side uses curl_cffi with impersonate="chrome120" to produce a TLS handshake indistinguishable from Chrome. The TypeScript side handles everything else — request translation, streaming, tool calls — where Bun’s performance and type safety matter more.

Problem 1: Proof-of-Work with a WASM SHA3 solver

DeepSeek doesn’t just check your auth token. Before every chat completion, you must solve a Proof-of-Work challenge. The flow is:

1. Request a challenge from /api/v0/chat/create_pow_challenge
2. The server returns a challenge string, salt, difficulty, and expiry
3. You run a SHA3-based hash computation until you find a valid answer
4. Encode the answer as base64 JSON and send it as x-ds-pow-response header

The catch: DeepSeek’s PoW algorithm is implemented in a WebAssembly module. In the browser, this runs natively. Outside the browser, you need a WASM runtime.

The solver uses wasmtime (a standalone WASM runtime for Python) to load DeepSeek’s own sha3_wasm_bg.wasm binary and call its exported wasm_solve function:

 1class DeepSeekHash:
 2    def init(self, wasm_path: str):
 3        engine = wasmtime.Engine()
 4        with open(wasm_path, "rb") as f:
 5            wasm_bytes = f.read()
 6        module = wasmtime.Module(engine, wasm_bytes)
 7        self.store = wasmtime.Store(engine)
 8        linker = wasmtime.Linker(engine)
 9        linker.define_wasi()
10        self.instance = linker.instantiate(self.store, module)
11        self.memory = self.instance.exports(self.store)["memory"]
12        return self
13
14    def calculate_hash(self, algorithm, challenge, salt, difficulty, expire_at):
15        prefix = f"{salt}_{expire_at}_"
16        # Allocate WASM memory, write challenge + prefix
17        challenge_ptr, challenge_len = self._write_to_memory(challenge)
18        prefix_ptr, prefix_len = self._write_to_memory(prefix)
19        # Call the exported solver
20        self.instance.exports(self.store)["wasm_solve"](
21            self.store, retptr,
22            challenge_ptr, challenge_len,
23            prefix_ptr, prefix_len,
24            float(difficulty),
25        )
26        # Read the answer from WASM memory
27        value_bytes = bytes(memory_view[retptr + 8 : retptr + 16])
28        value = np.frombuffer(value_bytes, dtype=np.float64)[0]
29        return int(value)

The memory management is manual — you allocate via __wbindgen_export_0, write UTF-8 bytes one at a time, call the solver, then read the result from a return pointer. Stack pointer cleanup happens in a finally block. It’s the kind of code where one off-by-one error means silent corruption.

Why Python 3.11 specifically? The wasmtime + numpy + curl_cffi stack was verified working on 3.11. Python 3.14 caused silent failures in the WASM path during testing — the process would get killed mid-computation with no error message. This isn’t a “should work” situation; it’s a “was tested and doesn’t” situation.

Problem 2: TLS fingerprinting and Cloudflare

DeepSeek sits behind Cloudflare. Standard HTTP clients get 403s or “Just a moment…” challenge pages because their TLS Client Hello doesn’t match what a real browser sends.

The fix is curl_cffi with browser impersonation:

1response = requests.post(
2    f"{BASE_URL}{path}",
3    headers=headers,
4    json=body,
5    cookies=cookies,
6    impersonate="chrome120",  # TLS fingerprint matches Chrome 120
7    stream=stream,
8)

impersonate="chrome120" makes the TLS handshake (cipher suites, extensions, ALPN) identical to Chrome 120. This is why the backend is Python, not Node — there’s no equivalent library in the JS ecosystem that matches real browser TLS fingerprints this precisely.

The cookie management layer adds another defense: if a request hits Cloudflare anyway, the proxy can automatically refresh cookies via a configurable shell command:

1def refresh_cookies(self) -> dict[str, str]:
2    if not self.refresh_command:
3        return self.load_cookies()
4    subprocess.run(self.refresh_command, shell=True, check=True)
5    cookies = self.load_cookies()
6    self.save_cookies(cookies)
7    return cookies

This lets you plug in whatever cookie extraction tool you prefer — a headless browser script, a browser extension export, etc.

Problem 3: Translating SSE formats

DeepSeek’s streaming format is not OpenAI’s streaming format. Both use Server-Sent Events, but the payload structure is completely different.

OpenAI format (what clients expect):

1data: {"choices":[{"delta":{"content":"Hello"},"index":0}],"model":"gpt-4"}

DeepSeek format (what the server sends):

1data: {"v":{"response":{"fragments":[{"type":"text","content":"Hello"}]}},"o":"APPEND"}

DeepSeek uses a nested structure where content lives inside response.fragments, operations can be APPEND, SET, or BATCH, and thinking content is separated from regular content by fragment type. There’s also metadata like response/status and response/accumulated_token_usage mixed into the stream that clients don’t want.

The proxy handles this translation in parseSSELine and extractDeepSeekContent:

 1function extractDeepSeekContent(
 2  data: DeepSeekSSEData,
 3  includeThinking: boolean
 4): string {
 5  // DeepSeek nests content in multiple possible locations
 6  const target = data.v?.response ?? data.response ?? data;
 7  const fragments = target?.fragments;
 8
 9  if (Array.isArray(fragments)) {
10    return fragments
11      .filter(f => includeThinking || f.type !== "thinking")
12      .map(f => f.content)
13      .join("");
14  }
15
16  // Fallback: direct content field
17  if (typeof data.v === "string") return data.v;
18  if (typeof data.content === "string") return data.content;
19  return "";
20}

For streaming responses, each DeepSeek SSE chunk gets translated into an OpenAI chat.completion.chunk on the fly. For non-streaming, the proxy accumulates all chunks, then builds a single chat.completion response.

Problem 4: Tool calls on a model that doesn’t support them

This is the most interesting problem. DeepSeek’s web chat API doesn’t support OpenAI-style tool calls. There’s no tools parameter, no tool_choice, no tool_calls in the response. But clients like opencode and Claude Code rely heavily on tool use — without it, the agent can’t read files, run commands, or interact with your codebase.

The solution is a prompt-engineering compatibility layer. When the proxy detects tool-related fields in the request, it:

1. Injects a system prompt describing available tools and the expected JSON format
2. Flattens the conversation into a single prompt (including tool results from previous turns)
3. Parses the model’s response for JSON tool call envelopes
4. Translates back into OpenAI’s tool_calls format

The injected system prompt instructs the model to output tool calls as JSON:

 1function buildToolSystemPrompt(tools, toolChoice) {
 2  return [
 3    "You are replying through an OpenAI-compatible proxy that supports tool use.",
 4    toolChoiceRule, // varies by mode: auto/required/none/function
 5    `If you decide to call a tool, output only valid JSON with this exact shape:`,
 6    `{"opencode_tool_call": {"name": "tool_name", "arguments": { ... }}}.`,
 7    `For multiple calls: {"opencode_tool_calls": [...]}.`,
 8    "Do not wrap the JSON in markdown.",
 9    "Available tools:",
10    availableTools, // name, description, JSON schema for each
11  ].join("\n\n");
12}

The conversation history gets flattened because DeepSeek’s chat API takes a single prompt string, not an array of messages:

 1function formatConversationForDeepSeek(messages) {
 2  return messages.map(message => {
 3    if (message.role === "system") return `System: ${content}`;
 4    if (message.role === "user") return `User: ${content}`;
 5    if (message.role === "assistant") {
 6      if (message.tool_calls?.length)
 7        return `Assistant tool request: ${formatted calls}`;
 8      return `Assistant: ${content}`;
 9    }
10    if (message.role === "tool")
11      return `Tool (${message.tool_call_id}) result: ${content}`;
12  }).join("\n\n");
13}

On the response side, parseToolEnvelope scans the model output for JSON objects containing opencode_tool_call or opencode_tool_calls keys, validates that the function names match known tools, and converts them into proper OpenAI tool_calls with generated IDs:

 1function parseToolEnvelope(text, tools) {
 2  for (const candidate of extractJsonObjectCandidates(text.trim())) {
 3    const payload = JSON.parse(candidate);
 4    const rawCalls = payload.opencode_tool_calls ?? [payload.opencode_tool_call];
 5    const toolCalls = rawCalls
 6      .filter(call => tools.some(t => t.function.name === call.name))
 7      .map(call => ({
 8        id: `call_${uuidv4()}`,
 9        type: "function",
10        function: { name: call.name, arguments: JSON.stringify(call.arguments) },
11      }));
12    if (toolCalls.length) return { toolCalls };
13  }
14  return null;
15}

The JSON extraction is deliberately robust — it uses a bracket-depth parser to find JSON objects embedded in natural language, handles escaped strings, and tries multiple candidates. This matters because the model sometimes wraps tool calls in explanatory text despite being told not to.

For streaming with tools, there’s an extra step. The proxy can’t stream tool calls token-by-token (the client needs the complete tool call object). So when tools are present, the proxy collects the full response first, parses tool calls, then re-streams the result as a synthetic SSE sequence. This adds ~latency but is the only correct approach.

What the client sees

After all this translation, what comes out the other end is a standard OpenAI response:

1curl http://localhost:9123/v1/chat/completions \
2  -H "Content-Type: application/json" \
3  -d '{
4    "model": "deepseek-chat",
5    "messages": [{"role": "user", "content": "Hello"}],
6    "stream": true
7  }'

data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant"},"index":0}]}
data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"},"index":0}]}
data: {"id":"chatcmpl-abc","object":"chat.completion.chunk","choices":[{"delta":{"content":"!"},"index":0}]}
data: [DONE]

Indistinguishable from OpenAI. Any client that speaks the OpenAI protocol works without modification.

What I learned

WASM outside the browser is viable but fragile

The wasmtime runtime works, but debugging WASM memory issues from Python is miserable. There’s no stack trace when you read the wrong offset — you just get garbage bytes. The debug flags in pow.py exist because I needed them.

TLS fingerprinting is the real gate, not auth tokens

I initially thought the hard part would be authentication. It wasn’t. The hard part was making HTTP requests that don’t get blocked. curl_cffi with browser impersonation is the only reliable solution I found for Python. If you’re building any kind of web scraper or API proxy in 2026, TLS fingerprinting is the first problem you’ll hit.

Tool call compatibility via prompting is surprisingly reliable

I expected the prompt-engineering approach to tool calls to be flaky. It’s not. DeepSeek’s models are good at following structured output instructions, and the JSON extraction parser handles edge cases well. The key is being very explicit about the expected format and validating against the known tool list.

Two-process architecture was the right call

Splitting into TypeScript + Python felt like overengineering at first. It wasn’t. Each language does what it’s best at: Python for the “pretend to be a browser” parts (TLS, WASM), TypeScript for the “translate between API formats” parts (streaming, types, request handling). Trying to do both in one language would have meant worse tooling for at least half the problem.

Links

• Repo: freeseek-proxy
• curl_cffi: docs — Python HTTP client with browser TLS impersonation
• wasmtime-py: GitHub — Python bindings for the Wasmtime WASM runtime
• Hono: hono.dev — Lightweight web framework for Bun/Node/Deno

Except it doesn’t. It concatenates them all into one call: search_documentsget_usersearch_documents. The agent hallucinates, retries, and loops. I stared at the telemetry for twenty minutes before I realized the bug wasn’t in the agent — it was in the gateway’s streaming accumulator.

This is the story of how I found and fixed a parallel tool call merging bug in Bifrost, a 2.6k-star open-source AI gateway.

What is Bifrost?

Bifrost is a high-performance AI gateway written in Go. It sits between your application and LLM providers (OpenAI, Anthropic, Bedrock, Vertex, etc.), providing a unified OpenAI-compatible API with automatic failover, load balancing, semantic caching, and streaming support. Think of it as an intelligent reverse proxy for AI — one API, fifteen providers, ~11µs overhead at 5k RPS.

The relevant piece here is the streaming accumulator. When you make a streaming chat completion request, the LLM sends back a sequence of Server-Sent Events (SSE), each containing a small delta — a few tokens of text, or a fragment of a tool call’s arguments. The accumulator’s job is to reassemble these deltas into complete messages.

The bug: recency-based routing

Here’s the scenario. You ask Claude or GPT to call two tools in parallel:

User: "Search for compliance circulars about RBI and also get the user's profile"

The model decides to call both search_circulars and get_user_profile simultaneously. During streaming, the provider sends interleaved deltas:

Delta 1: tool_call[0] name="search" (index=0, id=call_abc)
Delta 2: tool_call[1] name="get_us" (index=1, id=call_xyz)
Delta 3: tool_call[0] args='{"query": "RBI'   (index=0)
Delta 4: tool_call[1] args='{"user_id": "u'   (index=1)
Delta 5: tool_call[0] args=' circulars"}'      (index=0)
Delta 6: tool_call[1] args='123"}'             (index=1)

Each delta carries an index (and optionally an id) that identifies which tool call it belongs to. The expected behavior: two distinct tool calls with their own names and arguments.

The actual behavior in Bifrost’s accumulator before the fix:

1// Old logic (simplified)
2if deltaToolCall.Function.Name != nil {
3    // New tool call — create it
4    existingToolCalls = append(existingToolCalls, newToolCall)
5} else {
6    // Argument delta — append to the LAST tool call
7    toolCallToModify = &existingToolCalls[len(existingToolCalls)-1]
8    toolCallToModify.Function.Arguments += deltaToolCall.Function.Arguments
9}

The routing logic was based on recency: if a delta has a Name, it’s a new tool call; otherwise, append arguments to the most recent one. This works perfectly when tool calls arrive sequentially. It breaks completely when they’re interleaved.

With the deltas above:

• Delta 3 (index=0 args) arrives → appended to the last tool call, which is get_user_profile (index=1). Wrong target.
• Delta 5 (index=0 args) arrives → again appended to get_user_profile. Now get_user_profile has arguments from two different calls mashed together.

The result: concatenated tool names, merged arguments, and an agent stuck in a retry loop trying to invoke search_circularsget_user_profile — a tool that doesn’t exist.

Finding the bug

I hit this in production. Our compliance platform uses an AI agent that calls multiple tools in parallel — searching circulars, fetching regulatory data, looking up user context. The agent kept failing with tool resolution errors, and the telemetry showed impossible tool names:

search_circularsearch_circularsearch_circular

At first I suspected the agent’s tool-calling logic. Then I looked at the raw SSE stream from the provider — the deltas were correct. Each one had the right index and id. The corruption was happening between the provider response and the final accumulated message.

I traced it to accumulateToolCallsInMessage in framework/streaming/accumulator.go. The function had no concept of tool call identity. It used the presence of a Name field as a heuristic for “new vs. continuation,” which is fragile and incorrect when deltas arrive out of order.

The fix

The fix is conceptually simple: route deltas by identity, not by recency.

Each tool call delta carries two potential identifiers:

1. tool_call.id — a string like call_abc123 (set by OpenAI/Anthropic)
2. tool_call.index — an integer position (0, 1, 2, …)

The new logic builds lookup maps on existing tool calls and uses them to route each incoming delta to the correct target:

1// Build lookup maps for identity-based routing
2idToIndex := make(map[string]int, len(existingToolCalls))
3indexToIndex := make(map[uint16]int, len(existingToolCalls))
4for i, toolCall := range existingToolCalls {
5    if toolCall.ID != nil && *toolCall.ID != "" {
6        idToIndex[*toolCall.ID] = i
7    }
8    indexToIndex[toolCall.Index] = i
9}

For each incoming delta, routing follows a priority chain:

 1for _, deltaToolCall := range deltaToolCalls {
 2    index := -1
 3
 4    // Priority 1: match by tool_call.id
 5    if deltaToolCall.ID != nil && *deltaToolCall.ID != "" {
 6        if existingIndex, ok := idToIndex[*deltaToolCall.ID]; ok {
 7            index = existingIndex
 8        }
 9    }
10
11    // Priority 2: match by tool_call.index
12    if index == -1 {
13        if existingIndex, ok := indexToIndex[deltaToolCall.Index]; ok {
14            index = existingIndex
15        }
16    }
17
18    // Priority 3: no match → create new tool call (if name present)
19    if index == -1 {
20        if deltaToolCall.Function.Name == nil {
21            // Can't create a tool call without a name
22            continue
23        }
24        newToolCall := schemas.ChatAssistantMessageToolCall{
25            Index:    deltaToolCall.Index,
26            ID:       deltaToolCall.ID,
27            Function: /* ... */,
28        }
29        existingToolCalls = append(existingToolCalls, newToolCall)
30        // Update maps for future deltas
31        indexToIndex[newToolCall.Index] = len(existingToolCalls) - 1
32        if newToolCall.ID != nil {
33            idToIndex[*newToolCall.ID] = len(existingToolCalls) - 1
34        }
35        continue
36    }
37
38    // Append arguments to the correct tool call
39    existingToolCalls[index].Function.Arguments += deltaToolCall.Function.Arguments
40}

The key insight is that the maps are updated as new tool calls are created, so subsequent deltas for the same call always find their target — even if they arrive many chunks later.

The same bug, twice

During code review, a reviewer (Pratham-Mishra04) pointed out that the same recency-based routing existed in a second code path: the Responses API streaming handler in responses.go.

The Responses API is OpenAI’s newer streaming format (the /v1/responses endpoint). It uses ItemID instead of tool_call.index, but the accumulation logic had the same flaw — FunctionCallArgumentsDelta events were always appended to the last message:

1// Old responses.go logic
2if resp.Delta != nil && len(messages) > 0 {
3    // Always targets the last message — wrong for parallel calls
4    a.appendFunctionArgumentsDeltaToResponsesMessage(
5        &messages[len(messages)-1], *resp.Delta)
6}

The fix follows the same pattern: search for a message matching resp.ItemID, and only fall back to the last message when no ItemID is present. If an ItemID exists but no message matches, create a stub message to hold the delta rather than merging it into the wrong call:

 1if resp.Delta != nil && len(messages) > 0 {
 2    targetIdx := len(messages) - 1
 3    if resp.ItemID != nil {
 4        targetIdx = -1
 5        for i := len(messages) - 1; i >= 0; i-- {
 6            if messages[i].ID != nil && *messages[i].ID == *resp.ItemID {
 7                targetIdx = i
 8                break
 9            }
10        }
11        if targetIdx == -1 {
12            // Create stub to avoid merging into wrong message
13            id := *resp.ItemID
14            messages = append(messages, schemas.ResponsesMessage{ID: &id})
15            targetIdx = len(messages) - 1
16        }
17    }
18    a.appendFunctionArgumentsDeltaToResponsesMessage(
19        &messages[targetIdx], *resp.Delta)
20}

Testing parallel accumulation

The regression test simulates the exact interleaving pattern that triggers the bug:

 1func TestAccumulateToolCallsInterleavedParallel(t *testing.T) {
 2    // ...
 3    toolCallID0 := "call_0"
 4    toolCallID1 := "call_1"
 5    toolNameAdd := "add"
 6    toolNameMultiply := "multiply"
 7
 8    // Simulate interleaved deltas
 9    accumulate(makeDelta(0, &toolCallID0, &toolNameAdd, ""))       // create call 0
10    accumulate(makeDelta(1, &toolCallID1, &toolNameMultiply, ""))  // create call 1
11    accumulate(makeDelta(0, nil, nil, `{"a": 1`))                  // args for call 0
12    accumulate(makeDelta(1, nil, nil, `{"a": 2`))                  // args for call 1
13    accumulate(makeDelta(0, nil, nil, `, "b": 3}`))                // more args for call 0
14    accumulate(makeDelta(1, nil, nil, `, "b": 4}`))                // more args for call 1
15
16    // Assert: two distinct tool calls with correct arguments
17    assert(addCall.Arguments == `{"a": 1, "b": 3}`)
18    assert(multiplyCall.Arguments == `{"a": 2, "b": 4}`)
19}

Without the fix, add would end up with multiply’s arguments concatenated in. With the fix, each call accumulates only its own deltas.

A second test covers the Responses API path with ItemID-based routing, using the same interleaving pattern but with OutputItemAdded + FunctionCallArgumentsDelta events.

The PR lifecycle

I filed Issue #1829 with reproduction details from production telemetry, then opened PR #1830 with the fix and tests.

The review process was smooth:

1. First commit: fix the Chat Completions accumulator + regression test
2. Reviewer feedback: same bug exists in Responses API — please fix there too + add changelog entries
3. Second commit: fix Responses API routing + regression test + changelogs
4. Merged by akshaydeo (Bifrost maintainer)

Total: 3 commits, ~280 lines of Go across 5 files. Same-day turnaround from issue to merge.

What I learned

1. Recency is not identity

The original code used position (last element) as a proxy for identity. This is a common pattern in sequential streaming — and it works, until the stream isn’t sequential. The fix is to use the actual identity field that the protocol already provides.

This is a general principle: if the protocol gives you an ID field, use it. Don’t rely on ordering assumptions that hold today but break when concurrency enters.

2. The same bug pattern repeats across API surfaces

Bifrost supports two streaming formats: Chat Completions (the classic tool_calls array) and Responses API (the newer ItemID-based format). Both had the same routing flaw because the accumulation logic was duplicated rather than shared. The reviewer catching this in a different file was the most valuable part of the review.

3. OSS contributions are about context, not complexity

The fix itself is straightforward — build a map, use it for lookup. The hard part was:

• Finding the bug in a codebase I’d never seen before
• Understanding why the existing approach was wrong
• Testing with realistic interleaved deltas
• Responding to review feedback about a parallel code path I hadn’t initially noticed

The code change was ~100 lines. The context-building was hours.

4. Production telemetry is the best bug report

The issue report included the exact malformed tool name from production: search_circularsearch_circularsearch_circular. That single string made the bug immediately reproducible and the fix trivially verifiable. If you’re filing a bug, include the malformed output — it’s worth more than a paragraph of description.

Links

• PR: fix: preserve parallel tool call deltas — #1830
• Issue: Streaming tool call deltas merge in parallel tool calling — #1829
• Project: Bifrost AI Gateway — 2.6k ⭐, fastest enterprise AI gateway