Module compact 

Making a long conversation fit.

Every turn sends the whole history, so a session that runs long enough stops being able to send anything at all. Compaction replaces the middle of the transcript with a summary and keeps the ends: the task at the top, so the agent still knows what it was asked, and the most recent turns verbatim, because that is where the work actually is.

The constraint that decides the design

A tool_result is only valid if its tool_use is still in the conversation — the next request 400s otherwise, and that is the whole run gone. So the cut cannot land anywhere convenient; it has to land somewhere legal. The transcript alternates user and assistant, and tool results arrive in the user message immediately after the assistant turn that asked for them, so the only safe place to resume is at an assistant message. Cutting there drops each tool_use together with the results answering it.

The logic here is deliberately pure and provider-free. Getting the boundary wrong produces a 400 from a real API twenty turns into a real session, which is the worst possible place to discover it.

Enums

SummaryVerdict

What the validator said about a summary.

Constants

CARRIED_HEADER

Marks the block holding tool state carried across a compaction.

SUMMARY_INSTRUCTION

The prompt handed to the summariser.

SUMMARY_SYSTEM

What the summariser is told it is.

SUPERSEDED_MARKER

Starts every evicted result, so a second pass can tell it has already been here — and so the model can tell a stale result from a short one.

THINNED_RESULT_CHARS

How much of a tool result survives thinning.

TRUNCATION_MARKER

Appended to a result whose middle was removed, so the model can tell the difference between a short file and a shortened one.

VALIDATE_SYSTEM

What the summary validator is told it is. Like the summariser, a separate persona: it reads two texts, it does not act on either.

Functions

cut_point

The first index at or after target where the transcript can be cut.

evict_superseded_results

Replace tool results that a later call has superseded.

orphaned_tool_results

Every tool_result whose tool_use is missing — the error that 400s.

orphaned_tool_uses

Every tool_use id in the transcript that has no matching tool_result.

parse_omissions

Read a verdict out of the validator’s reply. None means it said nothing usable — the caller treats that as no verdict, not as a failure, because a validator that cannot run must not be able to veto a compaction the run may need to survive.

rebuild

Rebuild the transcript around summary.

render_for_summary

Flatten messages into plain text for the summariser.

retry_instruction

The summariser’s second attempt: the same instruction, plus what the first attempt lost. Naming the omissions is the whole intervention — the summariser cannot see its own gaps, and a bare “try again” would sample the same blind spot.

thin_old_results

Shorten old tool results, leaving the tool calls that produced them.

validate_instruction

Build the validator’s one user message.

worth_compacting

Whether compacting would actually remove anything worth the round trip.