Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@cmd/recordapi/main.go`:
- Around line 95-111: The routes "responses" and "responses_stream" currently
build requests unconditionally; add a provider-endpoint capability check before
constructing/sending these requests so unsupported providers return a clear
local error. In cmd/recordapi/main.go update the logic that registers/handles
"responses" and "responses_stream" (the map entries shown) to call the provider
capability check (e.g., Provider.SupportsEndpoint or
Provider.Capabilities/Has("responses")) and short-circuit with a 400/501 error
if the provider does not support "/v1/responses"; ensure both the non-stream and
stream handlers use the same validation and return a concise error message
mentioning the missing "responses" capability.

In `@internal/providers/gemini/gemini.go`:
- Around line 154-162: The models auth header function `headers` currently uses
q.Add and doesn't forward trace headers; make it idempotent by using
q.Set("key", p.apiKey) instead of q.Add so repeated calls replace the key rather
than appending, and copy the incoming "X-Request-Id" into the outgoing request
headers (matching the behavior in `setHeaders`) to preserve trace propagation;
update `headers` to read any existing X-Request-Id from the incoming context/req
and set it on req.Header before returning.
- Around line 152-153: ListModels currently constructs a fresh client via
llmclient.DefaultConfig("gemini", p.modelsURL) and only copies p.hooks, which
bypasses the provider's configured retry/circuit-breaker/resilience settings;
change the implementation to reuse the provider's already-configured llmclient
(or derive the models config from the provider's existing client/config) instead
of DefaultConfig so the retry and circuit-breaker options are preserved—e.g.,
obtain the config or client from p (referencing p.modelsURL, p.hooks, modelsCfg,
llmclient.DefaultConfig) and call ListModels through that existing client or
cloned config that carries over the resilience settings (apply same change for
the other occurrence at lines 164-169).

In `@tests/contract/anthropic_test.go`:
- Around line 27-141: Restore golden-file validation in the Anthropic contract
replay tests by replacing/augmenting the current shallow assertions in
TestAnthropicReplayChatCompletion, TestAnthropicReplayStreamChatCompletion,
TestAnthropicReplayResponses, and TestAnthropicReplayStreamResponses with full
normalized output comparisons against committed golden fixtures (use the
existing json/sse fixture routes as the golden artifacts), add the required
build tag comment (`//go:build contract` / `// +build contract`) and a 5-minute
test timeout comment at the top of the file, and ensure stream outputs are
serialized/normalized before comparing; record or update the golden files by
running make record-api after changes.

In `@tests/contract/gemini_test.go`:
- Around line 18-26: The helper newGeminiReplayProvider duplicates common setup;
extract its body into a shared test helper (e.g., newReplayProvider or
newGeminiReplayProvider) in the shared replay harness test file and have
existing provider contract tests call that shared helper. Move the creation
logic that calls newReplayHTTPClient(t, routes),
gemini.NewWithHTTPClient("test-api-key", client, llmclient.Hooks{}), and the
provider.SetBaseURL/SetModelsURL calls into the shared helper while preserving
the function signature (t *testing.T, routes map[string]replayRoute) and return
type core.Provider; update all places that currently define this helper to
import/use the shared helper and remove the duplicate local definitions. Ensure
the shared helper has the same package scope and required imports so tests
compile.
- Around line 28-155: The tests in TestGeminiReplay* only assert selected
fields; update each test (TestGeminiReplayChatCompletion,
TestGeminiReplayStreamChatCompletion, TestGeminiReplayListModels,
TestGeminiReplayResponses, TestGeminiReplayStreamResponses) to perform
normalized golden-file validation: serialize the full normalized response
output, compare against a committed golden file, and fail if different; provide
a way to re-record goldens via make record-api. Also add the required build tag
and 5-minute timeout to the top of the file (per tests/contract/**/*_test.go
guidelines) so the file uses -tags=contract and the test harness timeout. Ensure
stream tests write/normalize stream output before comparing to their respective
golden files.

In `@tests/contract/groq_test.go`:
- Around line 27-154: The tests (TestGroqReplayChatCompletion,
TestGroqReplayStreamChatCompletion, TestGroqReplayListModels,
TestGroqReplayResponses, TestGroqReplayStreamResponses) currently assert
individual fields; replace those field-level checks with full golden-file
validation: produce a normalized representation of the response/stream output
and compare it against a golden artifact (use the repo's golden helpers and
normalization used by other contract tests), add the required `// +build
contract` (or `//go:build contract`) build tag and set the test timeout to 5
minutes, and update/record the new golden files by running `make record-api` so
the tests validate complete outputs rather than only selective fields.

In `@tests/contract/openai_test.go`:
- Around line 114-116: The test currently skips when required golden fixtures
are missing (uses goldenFileExists(...) and t.Skip), which lets CI pass
silently; change the conditional to fail the test instead by replacing
t.Skip(...) with t.Fatalf(...) or t.Fatal(...) including a message that names
the missing fixture ("openai/responses.json") and instructs to record via "make
record-api"; apply the same replacement for the other occurrence that also
checks goldenFileExists in this file so contract tests fail CI when fixtures are
absent.
- Around line 27-112: Tests are only asserting selected fields; update
TestOpenAIReplayChatCompletion, TestOpenAIReplayStreamChatCompletion, and
TestOpenAIReplayListModels to perform full normalized output vs. golden-file
validation using the repository's golden helpers (e.g., produce a normalized
response and call the compare/validate golden helper) and add the required
contract build tag comment at the top of the file (//go:build contract) and
ensure the test run is documented to use a 5-minute timeout (tests are intended
to be run with -tags=contract and -timeout=5m); record any new golden artifacts
by running make record-api and commit those golden files.
- Around line 153-160: The test TestOpenAIReplayStreamResponses currently checks
for response events but not that the stream terminated; update the assertions
after parseResponsesStream to also verify the stream termination by asserting
the presence of the "[DONE]" termination marker (e.g. require.Contains(raw,
"[DONE]") or assert.True(t, hasResponsesEvent(events, "[DONE]"))), keeping the
existing checks (readAllStream, parseResponsesStream, hasResponsesEvent for
"response.created"/"response.output_text.delta"/"response.completed" and
extractResponsesStreamText) intact.

In `@tests/contract/README.md`:
- Around line 34-46: Update the tests/contract/README.md to align commands with
the contract-test policy: change the contract test run instruction to include
the build tag and five-minute timeout (use "-tags=contract" and "-timeout=5m")
and document the canonical golden-file recording command as "make record-api"
(or reference cmd/recordapi) for updating fixtures; also state that contract
tests under tests/contract/**/*_test.go must use golden file validation and be
run with those flags so local and CI workflows remain consistent.

In `@tests/contract/replay_harness_test.go`:
- Around line 115-125: The flush closure currently appends one sseEvent per
entry in dataLines, causing multi-line SSE `data:` blocks to become multiple
events; update flush (referencing flush, dataLines, events, sseEvent, and
currentName) to join all entries in dataLines with newline separators into a
single sseEvent.Data (e.g., strings.Join(dataLines, "\n")), append that single
event with Name set to currentName to events, then reset currentName and clear
dataLines so multi-line SSE payloads are emitted as one event.

In `@tests/contract/xai_test.go`:
- Around line 27-98: Add golden-file validation and contract build tag/timeout:
add the contract build tag header to this test file (//go:build contract) and
ensure tests run under the 5-minute contract timeout when executing (run with
-timeout=5m in CI or document running via make record-api). Replace the current
field-level assertions in TestXAIReplayChatCompletion,
TestXAIReplayStreamChatCompletion, and TestXAIReplayListModels with golden
comparisons that serialize/normalize the full responses (resp from
ChatCompletion/ListModels and the reconstructed stream chunks from
StreamChatCompletion) and compare them against dedicated golden files (e.g.,
testdata/golden/xai/*.golden.json); if a RECORD flag is set (or when running
make record-api) update/write those golden files. Use existing helpers like
newXAIReplayProvider, jsonFixtureRoute, sseFixtureRoute, readAllStream,
parseChatStream and extractChatStreamText to obtain the actual outputs to
serialize, and fail the test if the normalized output differs from the golden
artifact.
- Around line 101-103: Replace the t.Skip branch that hides missing golden
fixtures with a failing assertion: in tests/contract/xai_test.go (the test
function using goldenFileExists), remove the t.Skip("golden file not found -
record xai responses first") and instead call t.Fatalf with a clear message that
the golden file xai/responses.json is missing and instruct contributors to
regenerate fixtures (e.g., "missing golden file xai/responses.json; run `make
record-api` to create/update contract fixtures"). Apply the same change to the
other checks around the same test (the occurrences noted at lines ~126-128) so
contract tests fail-fast when fixtures are absent.
- Around line 140-148: The test reads the raw stream via readAllStream and
parses events but doesn't assert the stream termination marker; update
TestXAIReplayStreamResponses to assert the terminal "[DONE]" marker is present
in the raw stream (use the raw variable returned from readAllStream) — e.g., add
a require.Contains(raw, "[DONE]") or require.True(strings.HasSuffix(raw,
"[DONE]\n")) after events are parsed to ensure StreamResponses emits the final
"[DONE]" sentinel; keep existing checks using parseResponsesStream,
hasResponsesEvent, and extractResponsesStreamText.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.github/workflows/test.yml:
- Around line 88-102: Update the contract tests README to reflect the migration
to replay-harness behavior: edit the contract tests README
(tests/contract/README.md) to describe the new contributor-facing steps for
running contract replay tests (referencing the CI job name test-contract) and
the exact local command developers should run (go test -v -tags=contract
-timeout=5m ./tests/contract/...) plus updated guidance on golden file
validation and how to regenerate/verify golden outputs under the replay harness.

In `@internal/providers/gemini/gemini.go`:
- Line 269: Replace the plain fmt.Errorf("unexpected Gemini models response
format") return with a structured GatewayError (or existing gateway error type)
so downstream middleware can distinguish parsing failures; create/populate a
GatewayError (e.g., &GatewayError{Code: "parse_error", Message: "unexpected
Gemini models response format", Details: <optional raw payload>}) and return
that (or wrap it with fmt.Errorf("%w: ...", gwErr) if wrappers are required),
updating the site that checks for GatewayError via errors.As accordingly.

In `@tests/contract/gemini_test.go`:
- Around line 71-81: The test TestGeminiReplayListModels couples the API key
into the route key string (replayKey(http.MethodGet,
"/models?key=test-api-key")), making it fragile; update the test to decouple the
key by either using replayKey(http.MethodGet, "/models") (i.e., match the path
without query params) or construct the route key dynamically from the provider
created by newGeminiReplayProvider so it uses the same API key value; modify the
replayRoute entry accordingly (touching TestGeminiReplayListModels,
newGeminiReplayProvider usage, and the replayKey call) so the route matching no
longer hardcodes "?key=test-api-key".

In `@tests/contract/golden_helpers_test.go`:
- Around line 93-105: The normalizeGeneratedID function only treats resp_ and
msg_ suffixes as generated when the remainder parses as a UUID; extend its
normalization to also detect known provider-specific ID formats used in golden
files (e.g., OpenAI 56-char hex for resp_, Anthropic 24-char base62-like for
msg_, and Groq/ULID-like req_ patterns) so those are mapped to resp_<generated>,
msg_<generated>, or req_<generated> respectively. Modify normalizeGeneratedID to
check for these additional patterns (in addition to the existing uuid.Parse
path) using deterministic checks (length + allowed character sets or a ULID
regex) and return the normalized token when matched; keep the existing behavior
for strings.HasPrefix("resp_"), strings.HasPrefix("msg_"), and add support for
"req_" as well so golden-file comparisons are consistent.

In `@tests/contract/testdata/golden/anthropic/messages_with_tools.golden.json`:
- Around line 4-9: The fixture shows "finish_reason": "tool_use" but the message
object only has plain text (message.content) so tooling assertions won't run;
update this golden file to include structured tool-call data under the message
(e.g., add a "tool_calls" array/object alongside message.content) that contains
the invoked tool name and its arguments (matching the adapter's expected keys)
so tests validate the tool name and args mapping when finish_reason is
"tool_use".

In `@tests/contract/testdata/golden/gemini/chat_with_tools.golden.json`:
- Around line 4-9: The fixture's assistant message has finish_reason set to
"tool_calls" but the message object lacks the required tool_calls array; update
the JSON in tests/contract/testdata/golden/gemini/chat_with_tools.golden.json so
that the "message" object includes a "tool_calls" array containing the tool call
entries (with fields like id, type, and function) similar to the OpenAI/Groq
fixtures, ensuring the array reflects the same structure and content used by the
other golden files.

In `@tests/contract/testdata/golden/groq/chat_with_tools.golden.json`:
- Around line 4-9: The golden fixtures declare a tool-calling completion with
"finish_reason": "tool_calls" but lack the required message.tool_calls payload;
update each affected golden file so the assistant message includes a tool_calls
array containing objects with id, type, and function (with name and arguments),
then re-record the fixtures (e.g., run make record-api and/or RECORD=1 go test
-v -tags=contract ./tests/contract/...) to capture real tool-call payloads, and
add a short note in the contract tests README describing that when finish_reason
== "tool_calls" the message must include message.tool_calls with id, type, and
function{name, arguments}.

In `@tests/contract/testdata/golden/openai/chat_completion_reasoning.golden.json`:
- Around line 25-30: The prompt_tokens_details object is inconsistent with
prompt_tokens: update the detail counts so they sum to prompt_tokens (13) —
since this is a text-only prompt, set "text_tokens" to 13 and keep
"audio_tokens", "cached_tokens", and "image_tokens" at 0; ensure the
"prompt_tokens" field and the sum of prompt_tokens_details remain consistent
going forward (verify any generation logic that produces these fields uses the
same source for totals).

In `@tests/contract/testdata/golden/openai/chat_with_tools.golden.json`:
- Around line 4-9: Add a ToolCalls field to the core message schema and wire
through provider parsing: update the core.Message struct to include ToolCalls
[]ToolCall (create a ToolCall type if missing with fields matching the OpenAI
tool_calls payload), then update each provider adapter (the OpenAI adapter
parsing messages and any other providers that emit tool-invocation responses) to
detect finish_reason == "tool_calls" and populate Message.ToolCalls by
normalizing the provider-specific tool call objects into the new ToolCall type;
ensure all downstream code that constructs or marshals core.Message
(serializers, tests like chat_with_tools.golden.json, and any response builders)
handle the new field.

In `@tests/contract/testdata/golden/xai/responses_stream.golden.json`:
- Around line 2322-2449: The stream uses inconsistent message IDs across related
events: response.output_item.added/response.output_item.done use
"msg_<generated>" while response.content_part.added and response.output_text.*
use "msg_9f619ea5-7275-4a31-cb4c-35f8adb5c6b0"; update the golden so all events
for the same output item share one canonical ID (pick either "msg_<generated>"
or "msg_9f619ea5-7275-4a31-cb4c-35f8adb5c6b0") for the entries with Name values
response.output_item.added, response.content_part.added,
response.output_text.delta, response.output_text.done,
response.content_part.done, and response.output_item.done to preserve
correlation semantics.

In `@tests/contract/xai_test.go`:
- Around line 109-110: Replace the hardcoded golden file paths passed to
compareGoldenJSON with calls to goldenPathForFixture so XAI tests use the
centralized fixture naming; specifically, update the compareGoldenJSON(t,
"xai/responses.golden.json", resp) calls (and the similar occurrences around the
later block at lines 133-136) to compareGoldenJSON(t,
goldenPathForFixture("xai/responses.golden.json"), resp) so the test uses
goldenPathForFixture(...) consistently.

---

Duplicate comments:
In `@internal/providers/gemini/gemini.go`:
- Around line 79-81: NewWithHTTPClient currently builds modelsCfg via
llmclient.DefaultConfig("gemini", defaultModelsBaseURL) (and assigns it to
p.modelsClientConf) which applies default retry/circuit-breaker settings and
creates an asymmetry with New that accepts ProviderOptions; modify
NewWithHTTPClient to accept the same ProviderOptions (or a resilience config)
parameter and use that to construct modelsCfg instead of
llmclient.DefaultConfig, or provide an overload that takes a ResilienceConfig
and merges it into modelsCfg before assigning to p.modelsClientConf so
resilience settings are consistent with New.

In `@tests/contract/openai_test.go`:
- Around line 121-149: TestOpenAIReplayStreamResponses currently validates event
types but doesn't assert the stream termination; after reading the raw stream
(raw := readAllStream(t, stream)) add a termination assertion to verify the
provider emitted the "[DONE]" marker (for example: require.Contains(t,
string(raw), "[DONE]") or require.True(t, hasResponsesEvent(events, "[DONE]"))),
ensuring the stream is properly terminated like the Anthropic/Groq tests.