recoverFromContextOverflow

function recoverFromContextOverflow(session): Promise<OverflowRecoveryResult>;

Strip partial assistant + tool messages that followed the most recent user message — these are in-flight work from the turn that overflowed. The user’s own message is PRESERVED so the retry can still answer it.

Why we keep the user message:

1. The user asked a question. Throwing it away to “recover” is worse than just failing — they have to re-type it.
2. Overflow is almost always caused by accumulated PRIOR-turn weight (long tool outputs, growing history), not by the new user message itself. Once compaction trims the history, the same user message fits.
3. Matches Flue’s recovery semantics: “strip the failed turn” means strip the partial response, not the prompt.

Does NOT trigger compaction itself — that’s the caller’s job, so it can pass force: true and pick the right strategy. This function is pure session mutation and is safe to call before any awaitable work.

Returns the count of messages stripped. A retry is valid even when strippedCount === 0 (e.g. brand-new turn, nothing in-flight to strip) — the caller decides based on its overall recovery policy.

Parameters

Parameter	Type
session	Session

Returns

Promise<OverflowRecoveryResult>