[danielkov]

Summary

Preserve typed context-length rejections and add opt-in, bounded transcript recovery at the model-request boundary. Hosts can compact canonical history and retry the rejected inference without replaying completed tools.

Motivation

Usage reports can lag unexpectedly large requests. Recovering after a provider rejects the context requires both reliable error classification and a mutation point before the loop terminates the logical turn.

Impact

Recovery is disabled by default. Hosts opt in with ContextRecoveryPolicy and handle MutationPoint::ContextLengthRejected; AgentKit does not choose what history to remove or estimate whether a request fits. Hosts retaining transcript state must implement TranscriptObserver::on_transcript_replaced to persist committed recovery replacements rather than staged mutator edits.

OpenAI Responses HTTP, SSE, and WebSocket paths preserve exact context-length codes, including subscription requests. Confirmed context rejections bypass unchanged-request provider retries. OpenAI chat-completions HTTP and Anthropic HTTP/SSE prompt-length rejections also receive typed classification; generic compatible-provider and completions SSE coverage is unchanged.

Technical details

Transactional and bounded recovery

Recovery mutators edit a staged transcript. The driver validates it and checks cancellation and the shared deadline before committing and notifying replacement observers. Unchanged candidates stop recovery. The retry preserves session/turn identity, tools, and cache settings; any exposed response delta or tool call prevents recovery, including output later superseded by the provider.

Attempt limits and one absolute deadline cover recovery mutations and replacement generation from the first rejection. Production deadline handling remains runtime-agnostic, using the already-locked futures-timer dependency without introducing package versions or features.

Provider-confirmed classification

LoopError::is_context_length_exceeded() uses a sanitized typed code, not rendered error text or generic HTTP 400 status. OpenAI error-body inspection is byte/time bounded. Anthropic classification requires its structured invalid-request envelope and specific prompt-length message prefix. Confirmed errors retain no prompt or error-body text.

Integration compatibility

The replacement observer method has a default no-op implementation. Existing mutation-point encodings are unchanged; closed downstream decoders need to recognize ContextLengthRejected when opting into recovery. The new upstream error kind retains the existing unknown-value fallback.

[kit-code-agent]

Recovery can commit unsendable history, miss replayed Anthropic context rejections, and leave cancellation/usage observers inconsistent. Replacement requests also retain stale trace inputs and introduce redundant full-transcript copies.

_{Took 14 min}

[kit-code-agent]

Recovered turns append duplicate input-message attributes to a shared OTel span when input capture is enabled.

_{Took 20 min}

[kit-code-agent]

No issues found. The changes look good to merge.

_{Took 13 min}