fix: Altimate Base header timeout too short (10s) for reasoning backend

Merged
AN
2mo ago
+23-3

Issue for this PR

Closes #1259

Type of change

  • Bug fix

What does this PR do?

Beta.3 users on Altimate Base hit Provider response headers timed out after 10000ms.

The altimate-free loader borrowed the openai loader's 10s header timeout (OPENAI_HEADER_TIMEOUT_DEFAULT, added in #1256 to catch a hung gateway). That value is correct for OpenAI (near-instant headers) but wrong for Altimate Base: its gateway holds the HTTP 200 until the backend's first token, and queue wait / cold start / reasoning latency routinely exceeds 10s — so healthy requests abort client-side.

Changes:

  • Add FREE_TIER_HEADER_TIMEOUT_DEFAULT = 300_000ms (matching DEFAULT_CHUNK_TIMEOUT, the SSE chunk watchdog) and use it in the free-tier loader instead of the 10s OpenAI default.
  • Add an ALTIMATE_BASE_HEADER_TIMEOUT_MS env override (positive ms, or 0/off/false/none to disable). The free-tier provider is deliberately excluded from opencode.json config merging (provider.ts filters PROVIDER_ID), so this env var is the only field-tunable override for affected users.

Why it works: the 5-min chunkTimeout still guards mid-stream hangs, so the header phase only needs to tolerate the backend's real time-to-first-byte. nginx already streams the completions path (proxy_buffering off, proxy_read_timeout 900s), confirming the delay is litellm holding headers until the first upstream token — so the client timeout is the correct fix.

How did you verify your code works?

  • tsc --noEmit on packages/opencode — provider.ts compiles clean (remaining errors are pre-existing fresh-worktree module-resolution noise, unrelated).
  • Upstream marker guard clean (analyze.ts --markers --base origin/main --strict).
  • Static gateway audit: nginx completions path is unbuffered with a 900s read timeout, so the header delay is not a proxy-buffering issue — the client-side timeout value is the correct remedy.
  • Not verified: a live reproduction against prod (needs a managed credential); the value is chosen to comfortably exceed the backend's worst-case reasoning latency.

Checklist

  • I have tested my changes locally
  • I have not included unrelated changes in this PR

[!NOTE]
Low Risk
Scoped to Altimate Base provider options; behavior is more permissive by default with an env override, and does not alter auth or other providers.

Overview
Fixes false Provider response headers timed out after 10000ms errors on Altimate Base (altimate-free) when the gateway is slow to return the first byte (queue, cold start, or reasoning before headers).

The free-tier loader no longer reuses OpenAI’s 10s headerTimeout. It now defaults to 300_000ms (aligned with the SSE chunk watchdog) via freeTierHeaderTimeout(), and operators can tune or disable it with ALTIMATE_BASE_HEADER_TIMEOUT_MS (positive milliseconds, or 0/off/false/none to turn the header timeout off). OpenAI’s loader is unchanged at 10s.

Reviewed by Cursor Bugbot for commit 39a7beb28b7d18fbb8962651817a6741e9ee3794. Bugbot is set up for automated code reviews on this repo. Configure here.

Summary by cubic

Fixes Altimate Base requests aborting on healthy requests with Provider response headers timed out after 10000ms. The free-tier loader now uses a 300s header timeout instead of OpenAI's 10s default, since Altimate's gateway holds response headers until the first token (queue wait, cold start, or reasoning).

  • Adds an ALTIMATE_BASE_HEADER_TIMEOUT_MS env override (positive ms, or 0/off/false/none to disable).
  • The 5-minute chunk timeout still guards mid-stream hangs.

Summary by CodeRabbit

  • Bug Fixes

    • Improved connection reliability for the Altimate Base free tier by allowing more time for initial response headers.
    • The default header timeout is now five minutes, reducing premature timeouts during slower responses.

  • Configuration

    • Administrators can customize the header timeout in milliseconds using ALTIMATE_BASE_HEADER_TIMEOUT_MS.
    • Set the value to 0, off, false, or none to disable the header timeout.