The goal

The agent loop has one growing liability: messages. Every turn appends the assistant's reply and then a batch of tool_results, and nothing ever shrinks it. A model's context window is finite; a long task will eventually push the transcript past it, and the very next API call is rejected — the loop dies not because the work is hard but because it remembered too much.

Stage 4 fixes this with the smallest honest version of Claude Code's compaction: before each API call, estimate how full the window is, and if it's near the limit, fold the oldest turns into a single summary message and keep only a recent tail — while never severing a tool_result from the tool_use that produced it.

Build it

Everything lives in tutorial/04-context/compact.ts, wired into the loop from tutorial/04-context/agent.ts.

First, we need to know how full the desk is. We don't have exact token counts, so we use a cheap character heuristic:

export const KEEP_RECENT = 4;

export function estimateTokens(messages: Anthropic.MessageParam[]): number {
  // ~4 chars per token. Cheap and wrong-but-useful; the real harness reads
  // usage.input_tokens off every API response instead.
  return Math.ceil(JSON.stringify(messages).length / 4);
}

maybeCompact is a no-op until two conditions both allow a cut — the estimate must exceed the limit, and there must be more than the tail worth trimming:

if (estimateTokens(messages) <= limit || messages.length <= KEEP_RECENT + 1) return messages;

When it does fire, the interesting part is choosing where to cut. The naive answer is messages.length - KEEP_RECENT. But the transcript is full of pairs: an assistant tool_use block is answered on the next message by a user message whose content starts with a tool_result. If our cut lands so that the kept tail begins with a tool_result whose matching tool_use got summarized away, the API rejects the whole request — an orphaned tool_result is illegal. So we walk the boundary forward past any such message:

let cut = messages.length - KEEP_RECENT;
const startsWithToolResult = (m: Anthropic.MessageParam) =>
  Array.isArray(m.content) && m.content[0]?.type === 'tool_result';
while (cut < messages.length && startsWithToolResult(messages[cut]!)) cut++;
const old = messages.slice(0, cut);
const recent = messages.slice(cut);
if (old.length === 0) return messages;

The old slice goes to a summarizer call — a plain model request under a system prompt that tells it to preserve the task, file paths, findings, decisions, and what's unfinished — and the whole conversation collapses to [summary, ...recent]:

const res = await client.messages.create({
  model, max_tokens: 1024, system: SUMMARIZER,
  messages: [{ role: 'user', content: JSON.stringify(old) }],
});
const summary = res.content.filter((b) => b.type === 'text').map((b) => (b as Anthropic.TextBlock).text).join('\n');
return [{ role: 'user', content: `[COMPACTED HISTORY — summary of ${old.length} earlier messages]\n${summary}` }, ...recent];

The loop calls it at the top of every iteration, before the API request, so the window is trimmed on the way in rather than after it overflows (tutorial/04-context/agent.ts):

while (true) {
  messages = await maybeCompact(client, MODEL, messages, CONTEXT_LIMIT);
  console.log(`  📏 ~${estimateTokens(messages)} tokens of ${CONTEXT_LIMIT}`);
  const res = await client.messages.create({ model: MODEL, max_tokens: 2048, messages, tools });
  ...

Run it

Set a deliberately small CONTEXT_LIMIT so a short session trips the fold:

ANTHROPIC_API_KEY=sk-… CONTEXT_LIMIT=1500 \
  bun run tutorial/04-context/agent.ts "read a couple of files, then tell me what this project does"

A trimmed transcript:

$📏 ~120 tokens of 1500
  ⚙ read_file({"path":"package.json"}) — allow
  📏 ~640 tokens of 1500
  ⚙ read_file({"path":"src/index.ts"}) — allow
  📏 ~1180 tokens of 1500
  ⚙ read_file({"path":"README.md"}) — allow
  🗜 compacted 5 messages → 1 summary
  📏 ~430 tokens of 1500
This project is a … (final answer)$

The 🗜 line is the desk being cleared: five old messages became one summary, and the token estimate drops back under the limit for the next turn.

对照 the real one

Our ~40 lines are the same shape as Claude Code's compaction, minus the caching tricks. Piece by piece:

• The fullness check. Our estimateTokens is chars / 4; the real harness never guesses — it reads usage.input_tokens off every response and compares against a threshold of the effective window minus a 13K buffer reserved for the summary's own output (getAutoCompactThreshold, claude-code/src/services/compact/autoCompact.ts:62-76).
• Firing on the way in. We call maybeCompact at the top of the loop; the real query loop runs micro-compaction and then autocompaction before each API request, so a cheap trim can make the expensive summarize a no-op (claude-code/src/query.ts:414-468). The autocompact entry itself gates on a circuit breaker and shouldAutoCompact, and prefers a pre-extracted session summary before paying for a fresh summarization (claude-code/src/services/compact/autoCompact.ts:241-351).
• Fold old → one summary. Our single client.messages.create under SUMMARIZER is the miniature of compactConversation: PreCompact hooks → streamed summary → re-injected file attachments (claude-code/src/services/compact/compact.ts:387-763), returning a CompactionResult of a boundary marker plus summary messages plus the tail to keep (claude-code/src/services/compact/compact.ts:299-310).
• Keep a recent tail. Our KEEP_RECENT = 4 is a constant; the real calculateMessagesToKeepIndex expands backward from the last summarized message until it meets a token minimum and a text-block-message minimum, or hits a max cap (claude-code/src/services/compact/sessionMemoryCompact.ts:324-397).
• Never orphan a tool_result. Our forward walk past a leading tool_result protects the same invariant as the real counterpart, adjustIndexToPreserveAPIInvariants, but from the opposite direction: the real function walks backward from the cut and pulls the assistant message owning an orphaned tool_result (and its paired thinking blocks) into the kept tail, growing the kept region earlier, while our toy walks forward and evicts the orphan out of the tail into the summary, shrinking the kept region. Same invariant, inverse repair (claude-code/src/services/compact/sessionMemoryCompact.ts:232-314).

The full mechanism — the layered micro/auto strategy, the cost gradient, the cache-preserving cache_edits path — is unpacked in the deep-dives at /stories/context/1/ and /stories/context/2/.

What breaks without it

Stage 3 (tutorial/03-permissions/agent.ts) is identical except it has no maybeCompact. Its loop only ever grows messages: messages.push({ role: 'assistant', … }) and then messages.push({ role: 'user', content: results }) on every single turn, and nothing trims it. For a two-step task that's fine. But point it at a real repository and let it read a dozen files, and the transcript climbs monotonically toward — and then past — the model's context window. The next client.messages.create comes back a hard 400 prompt_too_long, and the agent dies mid-task, not because it couldn't do the work but because it kept every scrap of paper it ever touched. Stage 4 is the one habit that lets a small desk carry an arbitrarily long job.