one-code-extension 0.1.3 → 0.3.0

package/extensions/compaction/index.ts

@@ -28,16 +28,20 @@
  *     prefix thinking-cleared while this call sends full thinking blocks, and the
  *     mismatch invalidates the message-block cache (system+tools still read).
  *
+ * Not every compaction can replay — `fit.ts` explains when and why the
+ * standalone shape (the doomed span alone, trimmed to the window) is used.
+ *
  * Any failure returns nothing, so pi's own compaction serves — a different
  * summary style, never a broken compaction. CC_COMPACTION=0 opts out.
  */
 
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import type { Api, Model, Tool } from "@earendil-works/pi-ai";
+import type { Api, Context, Message, Model, Tool } from "@earendil-works/pi-ai";
 import { completeSimple } from "@earendil-works/pi-ai/compat";
 import {
 	convertToLlm,
 	type ExtensionAPI,
+	type ExtensionContext,
 	type SessionBeforeCompactEvent,
 } from "@earendil-works/pi-coding-agent";
 import {
@@ -46,14 +50,26 @@ import {
 	clearThinkingApplies,
 	clearThinkingEnabled,
 	isAnthropicOAuth,
-	looksLikeAnthropicRequest,
 	withClearThinking,
 } from "../context-management/index.ts";
+import { looksLikeAnthropicRequest } from "../lib/anthropic-payload.ts";
+import { forcedReasoningLevel } from "../lib/model-policy.ts";
+import { fitToBudget, replayFits, withoutUsage } from "./fit.ts";
 import { buildCompactionInstruction, COMPACTION_MAX_TOKENS, continuationSummary, extractSummary } from "./prompt.ts";
 
 /** Compaction reads a whole context window; give it more room than the classifier's 30s. */
 const COMPACTION_TIMEOUT_MS = 120_000;
 
+/**
+ * The system prompt of a standalone (non-replay) request. The session's own is
+ * left out along with the tools: neither helps a request that cannot hit the
+ * cache, and together they cost ~20k tokens the doomed span needs on an overflow.
+ */
+export const STANDALONE_SYSTEM_PROMPT =
+	"You are the coding assistant from the conversation below, asked to summarize it so work can continue in a fresh context. Respond with text only.";
+
+type Preparation = Pick<SessionBeforeCompactEvent["preparation"], "messagesToSummarize" | "turnPrefixMessages" | "isSplitTurn" | "previousSummary">;
+
 export default function compactionExtension(pi: ExtensionAPI) {
 	/**
 	 * The exact message array the session last handed the provider, captured
@@ -68,8 +84,8 @@ export default function compactionExtension(pi: ExtensionAPI) {
 	 * `convertToLlm` on the captured array, so the message prefix we send is
 	 * byte-identical to the turn's, and appending only the instruction keeps that
 	 * whole prefix reusable. Reconstructing from session entries instead (the
-	 * fallback) diverges at message one, because those injected reminders never
-	 * become entries — so it cannot reproduce the cached prefix at all.
+	 * standalone path) diverges at message one, because those injected reminders
+	 * never become entries — so it cannot reproduce the cached prefix at all.
 	 *
 	 * We hold the reference, not a copy: `emitContext` hands each handler a fresh
 	 * structuredClone the session never mutates again, and compaction is the
@@ -80,39 +96,53 @@ export default function compactionExtension(pi: ExtensionAPI) {
 	pi.on("context", (event) => {
 		capturedMessages = event.messages;
 	});
+	// After a compaction the capture describes the pre-compaction request. A
+	// second /compact before any turn would otherwise re-summarize history the
+	// first one already folded away (and mis-scope the kept tail); the standalone
+	// reconstruction from entries serves until the next request recaptures.
+	pi.on("session_compact", () => {
+		capturedMessages = undefined;
+	});
+	// A /tree branch switch stays in the same process and fires no `context`
+	// event (navigateTree rebuilds the messages itself), so the capture would
+	// still describe the abandoned branch — and a /compact before the next turn
+	// summarized work the kept branch never did (review H1). Same remedy.
+	pi.on("session_tree", () => {
+		capturedMessages = undefined;
+	});
 
 	pi.on("session_before_compact", async (event, ctx) => {
 		if (process.env.CC_COMPACTION === "0") return undefined;
 
 		const model = ctx.model;
 		if (!model) return undefined;
+		// Snapshot before the first await so the capture and pi's preparation
+		// describe the same request even if a context event lands meanwhile.
+		const captured = capturedMessages;
 
 		try {
 			const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
 			if (!auth.ok) return undefined;
 			const baseUrl = (auth as { baseUrl?: string }).baseUrl;
 
-			// Prefer the captured request prefix — it is cache-aligned and already
-			// carries the leading compactionSummary message on a re-compaction.
-			// Fall back to reconstructing from session entries only when nothing
-			// has been captured yet (e.g. /compact as the first action in a freshly
-			// resumed session, before any turn ran); that path cannot hit the cache.
-			const messages = capturedMessages ?? reconstructFromEntries(event.preparation);
-
-			const instruction = buildCompactionInstruction({
-				reason: event.reason,
-				customInstructions: event.customInstructions,
-			});
+			const maxTokens = Math.min(COMPACTION_MAX_TOKENS, model.maxTokens || COMPACTION_MAX_TOKENS);
 
-			// The active tool definitions, in their active order — kept in the
-			// request purely so the cached prefix (tools come first) still matches.
-			// A mismatch costs cache hits, never correctness.
-			const byName = new Map(pi.getAllTools().map((tool) => [tool.name, tool]));
-			const tools = pi
-				.getActiveTools()
-				.map((name) => byName.get(name))
-				.filter((tool) => tool !== undefined)
-				.map(({ name, description, parameters }) => ({ name, description, parameters }) as Tool);
+			// Prefer the captured request prefix — it is cache-aligned and already
+			// carries the leading compactionSummary message on a re-compaction — as
+			// long as pi's max_tokens clamp leaves it room for the reply (fit.ts).
+			// Otherwise (no capture yet, an overflow, a nearly full window) the
+			// standalone shape summarizes the doomed span pi isolated. An overflow
+			// never replays, so its replay request is not even built.
+			const replay = captured && event.reason !== "overflow" ? replayRequest(pi, ctx, captured, event) : undefined;
+			const request =
+				replay && replayFits(event.reason, model, replay, maxTokens)
+					? replay
+					: standaloneRequest(
+							model,
+							event.preparation,
+							buildCompactionInstruction({ reason: event.reason, customInstructions: event.customInstructions }),
+							maxTokens,
+						);
 
 			// When context-management (clear_thinking) is active for this session,
 			// the agent loop's cached message prefix has old thinking blocks cleared
@@ -134,48 +164,42 @@ export default function compactionExtension(pi: ExtensionAPI) {
 				: auth.headers;
 
 			const timeout = AbortSignal.timeout(COMPACTION_TIMEOUT_MS);
-			const result = await completeSimple(
-				baseUrl ? ({ ...model, baseUrl } as Model<Api>) : model,
-				{
-					systemPrompt: ctx.getSystemPrompt(),
-					messages: [...convertToLlm(messages), { role: "user", content: instruction, timestamp: Date.now() }],
-					tools,
-				},
-				{
-					apiKey: auth.apiKey,
-					headers,
-					env: auth.env,
-					signal: AbortSignal.any([event.signal, timeout]),
-					maxTokens: Math.min(COMPACTION_MAX_TOKENS, model.maxTokens || COMPACTION_MAX_TOKENS),
-					// The session id is the prompt-cache key / routing affinity on the
-					// providers that use one (openai-codex prompt_cache_key, session
-					// headers). Without it the replayed prefix cannot hit the session's
-					// cache no matter how well the bytes match.
-					sessionId: ctx.sessionManager.getSessionId(),
-					// Reasoning config is part of the cache identity on the Responses
-					// API: with a byte-identical prefix, prompt_cache_key, tools, and
-					// system prompt, omitting `reasoning` on a reasoning-configured
-					// session still misses the cache entirely (measured: cacheRead 0).
-					// Mirror the session's own thinking level so the request matches
-					// the prefix the session cached. Unlike the auto-mode classifier —
-					// which may run a *different*, unvalidated model where reasoning
-					// fails closed — this is the session's own model, already proven to
-					// accept this level, and streamSimple clamps an unsupported level
-					// down rather than erroring, so mirroring never fails closed here.
-					// "off" carries no reasoning (matching what such a session sends).
-					reasoning: ctx.thinkingLevel === "off" ? undefined : ctx.thinkingLevel,
-					// The clear_thinking body edit, matching the session's requests (see
-					// the header note above). Only attached on Anthropic requests that
-					// carry thinking, exactly as the context-management extension gates it.
-					onPayload: clearThinking
-						? (payload: unknown) =>
-								looksLikeAnthropicRequest(payload) &&
-								clearThinkingApplies(payload as Record<string, unknown>, cmModel.compat?.forceAdaptiveThinking === true)
-									? withClearThinking(payload as Record<string, unknown>)
-									: payload
-						: undefined,
-				},
-			);
+			const result = await completeSimple(baseUrl ? ({ ...model, baseUrl } as Model<Api>) : model, request, {
+				apiKey: auth.apiKey,
+				headers,
+				env: auth.env,
+				signal: AbortSignal.any([event.signal, timeout]),
+				maxTokens,
+				// The session id is the prompt-cache key / routing affinity on the
+				// providers that use one (openai-codex prompt_cache_key, session
+				// headers). Without it the replayed prefix cannot hit the session's
+				// cache no matter how well the bytes match.
+				sessionId: ctx.sessionManager.getSessionId(),
+				// Reasoning config is part of the cache identity on the Responses
+				// API: with a byte-identical prefix, prompt_cache_key, tools, and
+				// system prompt, omitting `reasoning` on a reasoning-configured
+				// session still misses the cache entirely (measured: cacheRead 0).
+				// Mirror the session's own thinking level so the request matches
+				// the prefix the session cached. Unlike the auto-mode classifier —
+				// which may run a *different*, unvalidated model where reasoning
+				// fails closed — this is the session's own model, already proven to
+				// accept this level, and streamSimple clamps an unsupported level
+				// down rather than erroring, so mirroring never fails closed here.
+				// "off" carries no reasoning (matching what such a session sends) —
+				// unless the model cannot disable thinking, where an off-request
+				// would 400 (forcedReasoningLevel sends its lowest level instead).
+				reasoning: ctx.thinkingLevel === "off" ? forcedReasoningLevel(model) : ctx.thinkingLevel,
+				// The clear_thinking body edit, matching the session's requests (see
+				// the header note above). Only attached on Anthropic requests that
+				// carry thinking, exactly as the context-management extension gates it.
+				onPayload: clearThinking
+					? (payload: unknown) =>
+							looksLikeAnthropicRequest(payload) &&
+							clearThinkingApplies(payload as Record<string, unknown>, cmModel.compat?.forceAdaptiveThinking === true)
+								? withClearThinking(payload as Record<string, unknown>)
+								: payload
+					: undefined,
+			});
 
 			const text = result.content
 				.filter((block): block is { type: "text"; text: string } => block.type === "text")
@@ -201,10 +225,91 @@ export default function compactionExtension(pi: ExtensionAPI) {
 }
 
 /**
- * Fallback message construction from session entries, used only when no live
- * request was captured. This cannot hit the prompt cache (the request-time
- * <system-reminder> injections are absent from entries), but it still yields a
- * correct summary — and if it fails, pi's own compaction serves.
+ * The cache-aligned shape: the session's system prompt, the active tool
+ * definitions in their active order — kept purely so the cached prefix (tools
+ * come first) still matches; a mismatch costs cache hits, never correctness —
+ * the captured request verbatim, and the instruction as one more user message.
+ *
+ * pi keeps the tail after the cut point verbatim (keepRecentTokens, ~20k
+ * tokens); the captured request still carries that tail, so the instruction
+ * names it (`keptTailOf`). Cutting the tail off the request instead was
+ * rejected: Anthropic checks cache hits only ~20 blocks back from the
+ * breakpoint, so a request ending well before the last cached block misses
+ * the cache the whole replay exists to hit.
+ */
+function replayRequest(pi: ExtensionAPI, ctx: ExtensionContext, captured: AgentMessage[], event: SessionBeforeCompactEvent): Context {
+	const byName = new Map(pi.getAllTools().map((tool) => [tool.name, tool]));
+	const tools = pi
+		.getActiveTools()
+		.map((name) => byName.get(name))
+		.filter((tool) => tool !== undefined)
+		.map(({ name, description, parameters }) => ({ name, description, parameters }) as Tool);
+	const instruction = buildCompactionInstruction({
+		reason: event.reason,
+		customInstructions: event.customInstructions,
+		keptTail: keptTailOf(captured, event.preparation),
+	});
+	return { systemPrompt: ctx.getSystemPrompt(), messages: [...convertToLlm(captured), instructionMessage(instruction)], tools };
+}
+
+/**
+ * The standalone shape: the doomed span reconstructed from session entries,
+ * its assistant usage zeroed and its largest tool results cleared until pi's
+ * clamp leaves room for the summary (`fit.ts`), no tools, a one-line system
+ * prompt. Gets no kept-tail note: it holds only the doomed span. If it fails,
+ * pi's own compaction serves. Exported for the unit test.
+ */
+export function standaloneRequest(model: Model<Api>, preparation: Preparation, instruction: string, maxTokens: number): Context {
+	const messages = [...withoutUsage(convertToLlm(reconstructFromEntries(preparation))), instructionMessage(instruction)];
+	return fitToBudget(model, { systemPrompt: STANDALONE_SYSTEM_PROMPT, messages }, maxTokens).request;
+}
+
+const instructionMessage = (instruction: string): Message => ({ role: "user", content: instruction, timestamp: Date.now() });
+
+/**
+ * The verbatim-kept tail of the captured request: everything after the doomed
+ * span. pi builds the context as `[compactionSummary?] + one message per entry`
+ * (`sessionEntryToContextMessages`) and `prepareCompaction` derives
+ * `messagesToSummarize`/`turnPrefixMessages` with the same mapping, so the
+ * doomed span is a prefix of the captured array. Alignment is checked role by
+ * role; on any mismatch (an extension that inserted a message) no note is made
+ * rather than a wrong one. Exported for the unit test.
+ */
+export function keptTailOf(
+	captured: readonly { role: string; content?: unknown }[],
+	preparation: Preparation,
+): { count: number; opening?: string } | undefined {
+	const doomed: { role: string }[] = [
+		...(preparation.previousSummary ? [{ role: "compactionSummary" }] : []),
+		...preparation.messagesToSummarize,
+		...(preparation.isSplitTurn ? preparation.turnPrefixMessages : []),
+	];
+	if (doomed.length === 0 || doomed.length > captured.length) return undefined;
+	for (let i = 0; i < doomed.length; i++) {
+		if (captured[i].role !== doomed[i].role) return undefined;
+	}
+	const count = captured.length - doomed.length;
+	if (count === 0) return { count };
+	return { count, opening: openingText(captured[doomed.length]) };
+}
+
+/** The first ~80 characters of a message's text, single-line, for the landmark quote. */
+function openingText(message: { content?: unknown }): string | undefined {
+	const content = message.content;
+	const text =
+		typeof content === "string"
+			? content
+			: Array.isArray(content)
+				? (content.find((b) => b && typeof b === "object" && (b as { type?: string }).type === "text") as { text?: string } | undefined)?.text
+				: undefined;
+	if (!text) return undefined;
+	const line = text.replace(/\s+/g, " ").trim();
+	return line.length > 80 ? `${line.slice(0, 80)}…` : line;
+}
+
+/**
+ * The doomed span as messages, from session entries — the standalone path's
+ * input.
  *
  * A previous compaction's summary is excluded from messagesToSummarize
  * (prepareCompaction starts after that entry), yet the live context carries it
@@ -213,7 +318,7 @@ export default function compactionExtension(pi: ExtensionAPI) {
  * turn's discarded prefix has no separate summary on this path, so it is
  * summarized with the rest.
  */
-function reconstructFromEntries(preparation: SessionBeforeCompactEvent["preparation"]): AgentMessage[] {
+function reconstructFromEntries(preparation: Preparation): AgentMessage[] {
 	const doomed = preparation.isSplitTurn
 		? [...preparation.messagesToSummarize, ...preparation.turnPrefixMessages]
 		: preparation.messagesToSummarize;

package/extensions/compaction/prompt.ts

@@ -132,6 +132,13 @@ REMINDER: Do NOT call any tools. Respond with plain text only — an <analysis>
 export function buildCompactionInstruction(options: {
 	reason: "manual" | "threshold" | "overflow";
 	customInstructions?: string;
+	/**
+	 * How many trailing messages of the conversation pi keeps verbatim after
+	 * the cut (its `keepRecentTokens` tail). When set and > 0 the instruction
+	 * says so, so the summary covers the part that is actually discarded
+	 * instead of re-telling what the model will still see in full.
+	 */
+	keptTail?: { count: number; opening?: string };
 }): string {
 	const notice =
 		options.reason === "manual"
@@ -141,10 +148,23 @@ export function buildCompactionInstruction(options: {
 	if (options.customInstructions?.trim()) {
 		parts.push(`<system-reminder>\n## Compact Instructions\n${options.customInstructions.trim()}\n</system-reminder>`);
 	}
-	parts.push(`<system-reminder>\n${notice}\n${COMPACTION_INSTRUCTION}\n</system-reminder>`);
+	const tail = options.keptTail && options.keptTail.count > 0 ? keptTailNote(options.keptTail) : "";
+	parts.push(`<system-reminder>\n${notice}${tail}\n${COMPACTION_INSTRUCTION}\n</system-reminder>`);
 	return parts.join("\n\n");
 }
 
+/**
+ * The scope note for pi's kept tail: the summary replaces only what precedes
+ * it. Quoting how the first kept message opens gives the model a landmark it
+ * can find in the transcript, since a bare count is easy to miscount.
+ */
+export function keptTailNote(tail: { count: number; opening?: string }): string {
+	const landmark = tail.opening?.trim() ? `, beginning with the message that opens "${tail.opening.trim()}"` : "";
+	return ` Only the earlier part of the conversation is being summarized: the final ${tail.count} ${
+		tail.count === 1 ? "message" : "messages"
+	}${landmark}, stay in context verbatim after the summary. Do not summarize them; cover everything before them, and use them only to judge which earlier details still matter.`;
+}
+
 /**
  * Claude Code's continuation preamble, baked into the *stored* summary so
  * every future context — and the reattached compactionSummary message on a

package/extensions/context-budget/budget.ts

@@ -0,0 +1,61 @@
+/**
+ * Claude Code's `<total_tokens>N tokens left</total_tokens>` signal, pure half.
+ *
+ * What the number is (read off a live Claude Code session and the 2.1.261
+ * capture, findings §14): a PER-TURN token budget, not the context window. It
+ * reads 15,000,000 at every turn start — the last line of the system prompt
+ * before the gitStatus block, and the end of every user message — and counts
+ * down on the tool results within the turn by roughly what each round added
+ * (tool results, assistant output); the next user message resets it. Constant
+ * at the cached-prefix positions, variable only on the tail, so it never busts
+ * the prefix. One Code approximates the countdown as the growth of the context
+ * since the turn started (pi's context-usage estimate), the same quantity to
+ * within the estimator's error. `CC_TOTAL_TOKENS_BUDGET` overrides the figure.
+ */
+
+/** Claude Code's per-turn budget as observed; the meaning of the figure is CC's max tokens per turn with compaction. */
+export const DEFAULT_TURN_TOKEN_BUDGET = 15_000_000;
+
+/** The configured budget: `CC_TOTAL_TOKENS_BUDGET` when it is a positive number, else Claude Code's default. */
+export function turnTokenBudget(env: Record<string, string | undefined> = process.env): number {
+	const raw = env.CC_TOTAL_TOKENS_BUDGET;
+	const n = raw === undefined || raw.trim() === "" ? Number.NaN : Number(raw);
+	return Number.isFinite(n) && n > 0 ? Math.round(n) : DEFAULT_TURN_TOKEN_BUDGET;
+}
+
+function finite(n: number | null | undefined): number | undefined {
+	return typeof n === "number" && Number.isFinite(n) ? n : undefined;
+}
+
+/**
+ * One turn's countdown. `startTurn` takes the context size the turn begins
+ * from; `left` takes the size now and returns what remains of the budget. The
+ * value never rises within a turn (as CC's does not), the first known size
+ * becomes the baseline when the turn started without an estimate, and an
+ * unknown size repeats the last value.
+ */
+export class TurnBudget {
+	private start: number | undefined;
+	private spent = 0;
+
+	constructor(readonly budget: number) {}
+
+	startTurn(contextTokens: number | null | undefined): void {
+		this.start = finite(contextTokens);
+		this.spent = 0;
+	}
+
+	left(contextTokens: number | null | undefined): number {
+		const now = finite(contextTokens);
+		if (now !== undefined) {
+			if (this.start === undefined) this.start = now;
+			this.spent = Math.max(this.spent, now - this.start);
+		}
+		return Math.max(0, this.budget - this.spent);
+	}
+}
+
+/** The bare block Claude Code appends, byte-for-byte. */
+export function totalTokensBlock(left: number): string {
+	return `<total_tokens>${left} tokens left</total_tokens>`;
+}

package/extensions/context-budget/index.ts

@@ -0,0 +1,66 @@
+/**
+ * context-budget extension — Claude Code's `<total_tokens>N tokens left</total_tokens>`
+ * line, in the three places CC puts it (budget.ts says what the number is):
+ *
+ * - the end of every user message: the constant budget, a raw `sticky-append`
+ *   reminder keyed once per session (`since: 0`, so a resumed session's earlier
+ *   user messages carry it too — byte-identical to what they carried before);
+ * - every tool result: the countdown, a RAW `last-append` one-shot queued at
+ *   `tool_result` time and written into the stored result by system-reminder
+ *   (so it persists in the session like CC's and no later request re-caches the
+ *   message). That is why this extension sits BEFORE `system-reminder` in the
+ *   package manifest — pi runs `tool_result` handlers in load order, and the
+ *   block must be queued before system-reminder's handler takes the one-shots.
+ *   It emits only at runtime, never at load, so the "listeners load first" rule
+ *   for the bus is not at stake;
+ * - the system prompt, before the gitStatus block — appended by the
+ *   system-prompt extension from the same pure module.
+ *
+ * A turn starts at the first `agent_start` after a settle (whoever opened it: a
+ * prompt or a harness notification) and its baseline is pi's context estimate
+ * at that moment. CC_TOTAL_TOKENS=0 turns all three off.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { REMINDER_CHANNEL, type ReminderPayload } from "../lib/reminders.ts";
+import { totalTokensBlock, TurnBudget, turnTokenBudget } from "./budget.ts";
+
+const USER_MESSAGE_KEY = "total-tokens";
+
+export default function contextBudgetExtension(pi: ExtensionAPI) {
+	const enabled = () => process.env.CC_TOTAL_TOKENS !== "0";
+	const budget = new TurnBudget(turnTokenBudget());
+	/** True between the first agent_start of a turn and agent_settled. */
+	let busy = false;
+
+	pi.on("session_start", () => {
+		busy = false;
+		if (!enabled()) return;
+		pi.events.emit(REMINDER_CHANNEL, {
+			text: totalTokensBlock(budget.budget),
+			scope: "every-turn",
+			key: USER_MESSAGE_KEY,
+			placement: "sticky-append",
+			raw: true,
+			since: 0,
+		} satisfies ReminderPayload);
+	});
+
+	pi.on("agent_start", (_event, ctx) => {
+		if (busy) return;
+		busy = true;
+		budget.startTurn(ctx.getContextUsage()?.tokens);
+	});
+	pi.on("agent_settled", () => {
+		busy = false;
+	});
+
+	pi.on("tool_result", (_event, ctx) => {
+		if (!enabled()) return;
+		pi.events.emit(REMINDER_CHANNEL, {
+			text: totalTokensBlock(budget.left(ctx.getContextUsage()?.tokens)),
+			placement: "last-append",
+			raw: true,
+		} satisfies ReminderPayload);
+	});
+}

package/extensions/context-management/index.ts

@@ -1,10 +1,16 @@
 /**
- * context-management extension — asks Anthropic to drop old thinking blocks.
+ * context-management extension — asks Anthropic to KEEP old thinking blocks.
  *
  * Claude Code sends `context_management: { edits: [{ type: "clear_thinking_20251015",
- * keep: "all" }] }` on every request, which keeps long sessions from carrying
- * every past reasoning block. pi does not, so a long One Code session
- * accumulates more context than Claude Code would.
+ * keep: "all" }] }` on every request. Despite the edit's name, `keep: "all"` is
+ * a cache preserver, not a trimmer: models that strip previous-turn thinking by
+ * default (Haiku through 4.5, Sonnet <= 4.5, Opus <= 4.1) would otherwise
+ * invalidate the messages cache at the first stripped block; with the edit the
+ * API keeps every block and the cached prefix survives (Anthropic's docs: "keeps
+ * all thinking blocks (maximizes cache hits)"). It does not reduce context. pi
+ * does not send it, so a long One Code session on such a model would re-cache
+ * its history every turn without this extension — do not "optimize" the
+ * parameter away (findings §9, CACHE-REVIEW-2026-09-04 L1).
  *
  * Two things the parameter needs, both found empirically against the live API
  * (2026-08-05, api.anthropic.com):
@@ -14,9 +20,11 @@
  *   Setting the header from `before_provider_headers` REPLACES the value pi
  *   computes at client creation (extension headers merge last), so we must
  *   rebuild pi's own beta list and append ours — see anthropicBetas(). That
- *   replicates pi-ai's createClient logic (pinned v0.83): OAuth identity betas,
- *   fine-grained tool streaming for models without eager input streaming, and
- *   interleaved thinking for non-adaptive models. Re-check on pi upgrades.
+ *   replicates pi-ai's createClient logic: OAuth identity betas, fine-grained
+ *   tool streaming for models without eager input streaming, interleaved
+ *   thinking for non-adaptive models, and server-side fallback for models with
+ *   `compat.allowedFallbackModels` (pi also puts a `fallbacks` body field on
+ *   those, which 400s if this beta is missing). Re-check on pi upgrades.
  *
  * - `thinking` enabled or an adaptive-thinking model, or the API 400s with
  *   "`clear_thinking_20251015` strategy requires `thinking` to be enabled or
@@ -33,6 +41,8 @@
 import { readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { type ExtensionAPI, getAgentDir } from "@earendil-works/pi-coding-agent";
+import { looksLikeAnthropicRequest } from "../lib/anthropic-payload.ts";
+import { CACHE_RETENTION_ENV, mainSessionCacheRetention } from "../lib/cache-retention.ts";
 
 const CLEAR_THINKING_EDIT = { type: "clear_thinking_20251015", keep: "all" };
 const CONTEXT_MANAGEMENT_BETA = "context-management-2025-06-27";
@@ -42,10 +52,18 @@ const CONTEXT_MANAGEMENT_BETA = "context-management-2025-06-27";
 const OAUTH_BETAS = ["claude-code-20250219", "oauth-2025-04-20"];
 const FINE_GRAINED_TOOL_STREAMING_BETA = "fine-grained-tool-streaming-2025-05-14";
 const INTERLEAVED_THINKING_BETA = "interleaved-thinking-2025-05-14";
+// Newer pi versions add a `fallbacks` body field for models whose compat
+// carries `allowedFallbackModels` (server-side fallback, e.g. opus-5 →
+// opus-4-8), gated on this beta. Because we overwrite the whole header, we must
+// re-add the beta whenever pi added the body field, or the API 400s with
+// "fallbacks: Extra inputs are not permitted" (verified live, api.anthropic.com
+// 2026-09-01). Mirrors pi's shouldUseServerSideFallbackBeta.
+const SERVER_SIDE_FALLBACK_BETA = "server-side-fallback-2026-07-01";
 
 export interface AnthropicModelCompat {
 	forceAdaptiveThinking?: boolean;
 	supportsEagerToolInputStreaming?: boolean;
+	allowedFallbackModels?: unknown[];
 }
 
 /** pi's beta list for this model/auth, with the context-management beta appended. */
@@ -55,19 +73,15 @@ export function anthropicBetas(oauth: boolean, compat: AnthropicModelCompat | un
 	// pi sends this only when tools are present; we always register tools.
 	if (compat?.supportsEagerToolInputStreaming === false) betas.push(FINE_GRAINED_TOOL_STREAMING_BETA);
 	if (compat?.forceAdaptiveThinking !== true) betas.push(INTERLEAVED_THINKING_BETA);
+	// pi puts a `fallbacks` body field on these models; the beta must ride along.
+	if ((compat?.allowedFallbackModels?.length ?? 0) > 0) betas.push(SERVER_SIDE_FALLBACK_BETA);
 	betas.push(CONTEXT_MANAGEMENT_BETA);
 	return betas.join(",");
 }
 
-/** Anthropic Messages API shape: `messages` + `max_tokens`, and not an OpenAI `input`. */
-export function looksLikeAnthropicRequest(payload: unknown): boolean {
-	if (!payload || typeof payload !== "object") return false;
-	const record = payload as Record<string, unknown>;
-	if (!Array.isArray(record.messages)) return false;
-	if ("input" in record) return false;
-	const model = typeof record.model === "string" ? record.model : "";
-	return model.includes("claude") || typeof record.max_tokens === "number";
-}
+// The payload predicate lives in lib (pure, shared with compaction and
+// tool-search); re-exported so existing importers keep working.
+export { looksLikeAnthropicRequest } from "../lib/anthropic-payload.ts";
 
 /** The edit is rejected unless thinking is enabled or the model is adaptive. */
 export function clearThinkingApplies(payload: Record<string, unknown>, forceAdaptiveThinking: boolean): boolean {
@@ -130,6 +144,16 @@ export function clearThinkingEnabled(flag: string | undefined, model: Anthropici
 export default function contextManagementExtension(pi: ExtensionAPI) {
 	const flag = () => process.env.CC_CLEAR_THINKING;
 
+	// Prompt-cache TTL for the main session: one hour in the interactive modes,
+	// the way Claude Code caches (a pause between turns no longer re-writes the
+	// context); a `-p`/json run keeps pi's 5-minute default, and so do
+	// in-process children (lib/cache-retention.ts). pi reads the variable per
+	// request, so setting it here, before the first prompt, is early enough.
+	pi.on("session_start", (_event, ctx) => {
+		const value = mainSessionCacheRetention(ctx.mode, process.env[CACHE_RETENTION_ENV]);
+		if (value) process.env[CACHE_RETENTION_ENV] = value;
+	});
+
 	pi.on("before_provider_headers", (event, ctx) => {
 		const model = ctx.model as AnthropicishModel | undefined;
 		if (!clearThinkingEnabled(flag(), model)) return;