Conversation history replay and correction
Conversation history replay keeps prior model state usable when a later turn uses a different provider, protocol, or connection. It preserves provider-native reasoning when the destination can accept it, converts readable parts into safe context when it cannot, and makes one targeted correction when an upstream rejects old history.
History replay model
History replay treats saved provider output as more than plain text. A replay carrier keeps the native item together with its source provider, protocol, endpoint, connection identity, and model so the next request can decide whether to restore the native form or create a compatible projection.
Replay provenance
Replay provenance is the record of where a native history item came from. The destination accepts native state only when the provider and protocol match and the endpoint and connection identity remain compatible; the model name can change because a public model alias does not always equal the model that produced the item. Credentials are not stored in the record. A hashed connection identity is derived from the account, key, or auth header so the system can detect a different account without exposing the credential.
The carrier uses a versioned, URL-safe value. It validates the shape of the source data before the value enters a provider request, and it still understands the earlier Messages carrier format so saved conversations can continue across upgrades. Some Messages records can carry an association that joins metadata from one assistant message into one replay record before request projection.
References: src/…/history_replay.py• L14-18 src/…/history_replay.py• L31-47 src/…/history_replay.py• L86-213 src/…/history_replay.py• L216-260 src/…/history_replay.py• L31-120
Native and readable forms
Native form is the exact provider record, such as a Responses reasoning item, a signed Messages thinking block, or structured Chat reasoning details. Readable form is the text or summary that can preserve the meaning of that record without its provider-bound data. The replay system keeps these forms separate so it does not send foreign signatures or opaque content to an upstream that cannot verify them.
The destination receives one of these results:
- The exact native record when its provenance is accepted.
- A provider-native readable representation when the destination supports one.
- Original readable reasoning or earlier-tool context when only plain context is safe.
- No replay of an unreadable record when the source cannot provide a safe representation.
The source conversation remains unchanged. Each request receives a fresh projected copy, which allows the same saved history to return to its original provider or move to another provider without accumulating prior corrections.
References: src/…/history_replay.py• L181-250 src/…/history_replay.py• L263-309 src/…/history_replay.py• L435-526 tests/…/test_history_replay.py• L37-58 tests/…/test_history_replay.py• L61-111
Cross-provider history flow
The replay flow starts with a completed response that carries enough native state for a later turn. It validates that state, identifies the current upstream connection, projects the saved history for that destination, and wraps new output so the next turn can repeat the process.
This diagram shows how completed output becomes reusable history and then becomes a destination-specific request.
flowchart LR
A[Completed provider output] --> B[Replay carrier with native state]
B --> C[Saved conversation history]
C --> D{Destination accepts source?}
D -->|Yes| E[Restore native history]
D -->|No| F[Create readable compatible context]
E --> G[Provider transport]
F --> G
G --> H[New output with destination provenance]
H --> B
Destination projection
Destination projection maps one conversation into the wire shape required by the current transport. Responses history can restore a matching reasoning item or replace foreign reasoning with readable assistant context. Messages history can restore signed or redacted thinking only for an accepted source. Chat history can restore structured reasoning details and can place readable reasoning in the configured reasoning field when the turn continues a tool call.
The projection scope controls how much readable reasoning enters a Chat request. The normal scope favors reasoning needed to continue tool work. A broader scope is used when the provider needs all prior reasoning. This choice preserves useful context without treating every internal record as new model instruction.
The projection creates a new request copy. It can also normalize a single Responses input item into the list form used for projection and remove empty assistant shells after their history fields are converted. These changes affect only the outbound copy.
References: src/…/history_replay.py• L315-360 src/…/history_replay.py• L425-506 src/…/history_replay.py• L523-653 src/…/client.py• L25-58
Transport boundaries
The three upstream transport families apply the same replay rule at their request boundary. The Messages transport prepares a Messages body, the Responses transport prepares a Responses body, and Chat providers prepare a Chat body. Each transport also gives its output presenter the current origin so completed reasoning can become a replay carrier in the public history returned to the caller.
This boundary keeps public model names and upstream model names distinct. When an upstream reports the model that actually produced the response, the carrier records that returned model rather than a gateway alias. The result is stable history when a request crosses adapters or uses a fallback provider.
The provider boundary validates replay carriers before credentials or inference. For Messages requests, it also resolves saved replay associations before any conversion can lose the information needed to choose a safe projection. The normalization returns a fresh request copy, so the source history stays unchanged while the later transport-specific request build receives resolved content. This keeps normalization separate from request serialization. See Gemini protocol adapter, provider integrations, and protocol adapters for the wider provider and transport boundary models.
References: src/…/transport.py• L102-129 src/…/transport.py• L286-295 src/…/transport.py• L220-270 src/…/transport.py• L376-445 src/…/provider.py• L732-760 src/…/provider.py• L889-912 src/…/native_stream.py• L254-302 src/…/history_replay.py• L31-60
Provider correction
Provider correction handles a narrow class of failures caused by old history rather than by the new request. It reads the upstream error, identifies the rejected history item, creates a corrected copy, and retries only while the request still has an uncommitted output boundary.
Targeted correction
The correction path responds to explicit history errors such as an invalid Responses item ID, invalid encrypted content, or an invalid Messages thinking signature. It accepts only the status range used for history validation and searches nested upstream error details for a rejected record. It locates the item by the upstream path, an item ID, or a unique opaque record. It does not guess when several history items could match, and it does not discard history for a general validation, rate, authentication, or server error.
The correction preserves meaning where possible. An invalid ID is replaced with a safe local form and matching references are updated. Invalid native reasoning becomes marked readable context. Other messages, tools, and request options stay in place. The original request object is not changed.
References: src/…/history_replay.py• L123-205 src/…/history_replay.py• L208-301 tests/…/test_history_corrections.py• L23-66 tests/…/test_history_corrections.py• L68-116
Retry and commit boundary
Correction is part of the same bounded attempt budget as other provider recovery. A correction can retry before visible output is committed, and the stream recovery layer drops the failed attempt's uncommitted events. After output is committed, the system does not replay the request because doing so could duplicate content or tool work; it returns the failure with the output already made visible.
The sequence is:
- Send the destination-specific history copy.
- Inspect an upstream failure for a precise history rejection.
- Build one corrected copy if the rejection identifies a safe target.
- Retry within the shared execution budget when no public output is committed.
- Stop correction and report the failure when the budget ends or output is already committed.
This rule keeps history repair from becoming an unbounded retry loop and keeps partial streams from being silently duplicated.
References: src/…/transport.py• L350-404 src/…/transport.py• L466-493 src/…/provider.py• L870-952 tests/…/test_history_transports.py• L269-336 tests/…/test_history_transports.py• L339-407
Compatible request context
History replay preserves the context needed for the next model turn while respecting the limits of the destination protocol. It carries readable reasoning once, keeps tool records as quoted history, and prevents a provider-owned unfinished tool action from crossing into another protocol.
Reasoning and tool context
Reasoning may appear as plain text, a summary, structured details, signed thinking, or opaque provider data. The replay system preserves the distinction between full reasoning and a summary while it creates readable context, but it passes that context as the original text without adding generated reasoning headings. It also removes carrier values from foreign requests, so an upstream sees useful text instead of an internal replay marker.
Tool history remains historical data rather than a new instruction. A pending hosted tool call cannot continue through a different protocol unless its result is present. This prevents a destination transport from claiming ownership of work that belongs to another upstream.
References: src/…/history_replay.py• L263-344 src/…/history_replay.py• L347-370 tests/…/test_history_transports.py• L723-759 tests/…/test_history_transports.py• L765-821
Stream output preservation
Stream presenters attach replay provenance as output becomes complete. Messages output replaces provider-bound signature data with a replay carrier, Responses output carries the native reasoning item through its encrypted-content field, and Chat output stores structured reasoning in a carrier that can be restored on the next request.
The presenter also keeps the public stream contract stable. It can expose the gateway model while recording the actual upstream model in the carrier, and it can retain reasoning fragments until their block is complete. This lets a later request reconstruct one complete history item instead of several partial records.
References: src/…/native_stream.py• L254-302 src/…/messages_stream.py• L340-364 src/…/stream_output.py• L79-144 tests/…/test_history_transports.py• L491-645
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the carrier validation rules aligned with every protocol's output presenter and request projector.
- Keep source and destination provenance rules aligned with endpoint changes, account refresh, provider fallback, and model aliases.
- Keep readable reasoning labels and summary handling aligned across Responses, Messages, and Chat projections so text is not repeated or lost.
- Keep Messages association rules aligned with stream output so anchor and final metadata resolve to one record in the right order.
- Keep correction matching narrow enough that unrelated upstream errors cannot remove history.
- Keep correction retries inside the shared attempt budget and behind the public output commit boundary.
- Keep tool-call ownership checks aligned with protocol conversion so an unfinished hosted tool call cannot cross transports.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A replay carrier is malformed or has an unsupported protocol shape | The request could send invalid native state or fail later at the provider | Validate the carrier before credentials or inference and reject malformed history |
| Native history comes from another connection or provider | Foreign signatures or opaque reasoning are rejected upstream | Match provenance and project only readable context when the source is not accepted |
| Associated Messages carriers conflict or arrive in the wrong order | Split reasoning metadata could be joined to the wrong history item or silently lost | Require one origin per association and a valid anchor-before-final order |
| An upstream reports a general 400-level validation error | Valid history could be removed and the request meaning could change | Correct only known history errors with a uniquely identified record |
| A history rejection arrives after public output is committed | Replaying could duplicate visible text or tool work | Stop correction at the commit boundary and return the stream failure |
| A pending hosted tool call has no matching result | A different transport could continue work owned by the first provider | Reject the cross-protocol continuation |
| Several opaque history records could match one rejection | The wrong record could be discarded | Do not correct when the rejected record cannot be identified uniquely |
Key files
| File | Why to read it |
|---|---|
| src/…/history_replay.py | Defines the shared carrier, provenance rules, readable projection, association resolution, and protocol-neutral history preparation. |
| src/…/history_replay.py | Defines connection identity, carrier validation, Messages replay normalization, and targeted history correction at the provider boundary. |
| src/…/transport.py | Shows how Messages requests prepare history, publish replay carriers, and retry a rejected history copy. |
| src/…/transport.py | Shows the same lifecycle for Responses requests and native reasoning output. |
| src/…/provider.py | Shows Chat history scope, destination-specific projection, and correction within streaming retries. |
| src/…/native_stream.py | Shows how Messages stream output carries provider-native reasoning for later replay. |
| src/…/messages_stream.py | Shows how converted Messages reasoning becomes replayable Responses history. |
| src/…/stream_output.py | Shows how Chat reasoning output is grouped and stored for the next turn. |
| tests/…/test_history_transports.py | Demonstrates provider switching, transport switching, correction behavior, stream commit limits, and context preservation. |
| tests/…/test_history_corrections.py | Defines the safety boundary for targeted corrections and non-history failures. |