fix(providers): send the request shape reasoning models require

[LorenzoGentile]

What

OpenAIProvider picks the token-limit field from the model id instead of always sending max_tokens, and can attach reasoning_effort. Two env overrides cover ids that prefix detection cannot classify.

Why

complete, stream, and toolCall each hard-coded max_tokens. The o-series and GPT-5 families reject it:

Unsupported parameter: 'max_tokens' is not supported with this model.
Use 'max_completion_tokens' instead.

That 400 comes back on the first extraction request of a compile, before any page is written — so these models are not degraded under llmwiki, they are unusable. The SDK agrees on the direction: openai@6.42.0 documents max_tokens as "now deprecated in favor of max_completion_tokens".

Separately, some of these models reject a request that carries function tools without reasoning_effort — which is the shape of every compile extraction call, since it goes through toolCall with tool_choice: "required".

I ran into both while evaluating a GPT-5-class model for a compile workload, and had to put a local proxy in front of llmwiki that rewrote the request body. That proxy is what this PR makes unnecessary.

Design

• src/providers/openai-request.ts owns the two decisions. It is a separate module mostly because openai.ts was at 299 lines against the 400-line limit in CLAUDE.md.
• The three completion methods now share a private requestBase(...). That is what stops one of them from drifting back to a hard-coded field — the duplication was the reason all three had to be fixed at once.
• Detection is by model-id prefix (o1, o3, o4, gpt-5, case-insensitive). I deliberately did not try to infer anything from arbitrary vendor ids: behind an OpenAI-compatible gateway a reasoning model can be called anything, and a guess would misfire in both directions. LLMWIKI_OPENAI_TOKEN_PARAM is the escape hatch for exactly that case, and it is how I tested this.
• LLMWIKI_OPENAI_REASONING_EFFORT is opt-in and unset by default. llmwiki does not guess an effort level — the right value is a property of the model and the workload, and silently choosing one would change cost and latency on models that were working fine.
• Both variables are validated against the accepted values on read, so a typo fails immediately with them named rather than as an opaque 400 part-way through a compile. That follows the direction Allow a separate embedding endpoint for Claude Agent #154 took with the embedding-provider guard.

Defaults are byte-identical for every model that does not match a reasoning prefix.

What this PR does not do

It does not touch tool_choice: "required". That hard-coding causes a separate incompatibility with thinking-capable models on some non-OpenAI gateways, but I do not have a verified fix for it, so I have written it up as an issue rather than guessing here.

How to test

npx tsc --noEmit
npm run build
npm test
npm run fallow:ci

test/openai-request-shape.test.ts covers prefix detection across both families, both override directions, rejection of unknown values, the full reasoning_effort value set, and — most importantly — the actual bodies the provider hands the SDK on the complete and toolCall paths, asserting that the reasoning path sends max_completion_tokens and not max_tokens, and that tool_choice is untouched. No network access: the SDK's create is swapped for a capture.

Full suite on this branch: 4881 passed, 3 skipped, no regressions. npm run fallow:ci: 0 above threshold, maintainability 91.3.

Against a live gateway:

LLMWIKI_PROVIDER=openai LLMWIKI_MODEL=<gpt-5-class-id> \
LLMWIKI_OPENAI_TOKEN_PARAM=max_completion_tokens \
LLMWIKI_OPENAI_REASONING_EFFORT=none \
llmwiki compile

Docs updated in docs/configuration/environment-variables.mdx, plus a CHANGELOG entry under Unreleased.

[ethanj]

Good fix, and the restraint is the best part: defaulting GPT-5 to none but leaving the o-series alone, with the docstring explaining why the two prefix lists differ. I checked the diagnosis too, and extraction-phase.ts does rethrow, so "unusable rather than degraded" is accurate. After this there's no max_tokens left anywhere in openai.ts, which is the drift guard you promised.

One thing to fix.

Invalid override values get retried as transient API failures. callClaude decides retriability by matching the error message against /^4(?!29)\d\d\b/. OpenAIRequestConfigError starts with the variable name, not a status code, so a local typo enters the four-attempt backoff ladder. With LLMWIKI_OPENAI_REASONING_EFFORT=bogus: attempts 1/4 through 3/4, failure after the fourth, 15.2 seconds and no network call. At the default concurrency of 5 that runs on five calls at once.

Worth noting #154 went the other way on this. From ensureEmbeddingProviderAvailable: "Runs HERE, at the door [...] One misspelled variable is not worth three behaviours."

Validate both variables in ensureProviderAvailable() and a typo fails instantly with the variable named, which is what your description claims. Failing that, classify the error non-retriable in llm.ts. Either way, a test asserting one attempt, no backoff.

Three smaller ones:

• Copilot, MiniMax and Ollama all extend OpenAIProvider, so a gpt-5 id on any of them now gets reasoning_effort: none with nothing configured. The default is right, but the docs note shouldn't sit under the OpenAI heading.
• REASONING_EFFORTS matches openai@6.42.0 exactly, but package.json uses ^6.42.0. A conditional-type assertion against Exclude<OpenAI.ReasoningEffort, null> would catch drift at tsc time.
• No stream() case in the tests. complete and toolCall are pinned, stream isn't, and that's the one path spreading requestBase into a differently-typed request.