@oh-my-pi/pi-agent-core 18.2.11 → 18.3.1

package/src/compaction/compaction.ts

@@ -43,9 +43,8 @@ import { ThinkingLevel } from "../thinking";
 import { Tokenizer } from "../tokenizer";
 import type { AgentMessage } from "../types";
 import {
-	ANTHROPIC_COMPACTION_MIN_CONTEXT_TOKENS,
 	buildAnthropicCompactionInstructions,
-	describeRetainedTail,
+	findAnthropicCompactionCut,
 	getPreservedAnthropicCompactionData,
 	requestAnthropicNativeCompaction,
 	shouldUseAnthropicNativeCompaction,
@@ -1252,6 +1251,8 @@ export interface CompactionPreparation {
 	turnPrefixMessages: AgentMessage[];
 	/** Messages kept in full after compaction (recent history) */
 	recentMessages: AgentMessage[];
+	/** Entry IDs parallel to recentMessages, for an Anthropic-safe keep-tail boundary. */
+	recentEntryIds?: string[];
 	/** Whether this is a split turn (cut point in middle of turn) */
 	isSplitTurn: boolean;
 	tokensBefore: number;
@@ -1380,16 +1381,22 @@ export function prepareCompaction(
 			}
 		}
 	} else if (previousCompaction) {
-		// Local summaries exclude the retained tail, whose original entries precede
-		// the compaction record. Native replay already carries that tail. Only look
-		// backwards: advisor snapshots put all retained messages after the summary
-		// and may carry a keep ID from their previous, differently indexed snapshot.
+		// Local and Anthropic summaries exclude the retained tail, whose
+		// original entries precede the compaction record.
 		for (let i = resetBoundaryIndex + 1; i < prevCompactionIndex; i++) {
 			if (pathEntries[i].id === previousCompaction.firstKeptEntryId) {
 				boundaryStart = i;
 				break;
 			}
 		}
+		if (previousCompaction.firstKeptEntryId === "" && previousCompaction.providerReplayThroughEntryId) {
+			// An empty snapshot tail can still have turns appended during
+			// background compaction; those start after the summarized snapshot.
+			const snapshotIdx = pathEntries.findIndex(
+				entry => entry.id === previousCompaction.providerReplayThroughEntryId,
+			);
+			if (snapshotIdx >= 0 && snapshotIdx < prevCompactionIndex) boundaryStart = snapshotIdx + 1;
+		}
 	}
 
 	// Keep original IDs beside the converted messages so estimation, cutting,
@@ -1437,6 +1444,11 @@ export function prepareCompaction(
 		return undefined;
 	}
 
+	const recentEntryIds: string[] = [];
+	for (let i = cutPoint.firstKeptEntryIndex; i < compactionEntries.length; i++) {
+		recentEntryIds.push(compactionEntries[i].id);
+	}
+
 	// Extract file operations from messages and previous compaction
 	const fileOps = extractFileOperations(messagesToSummarize, pathEntries, prevCompactionIndex);
 
@@ -1452,6 +1464,7 @@ export function prepareCompaction(
 		messagesToSummarize,
 		turnPrefixMessages,
 		recentMessages,
+		recentEntryIds,
 		isSplitTurn: cutPoint.isSplitTurn,
 		tokensBefore,
 		previousSummary: previousCompaction?.summary,
@@ -1579,6 +1592,7 @@ export async function compact(
 		messagesToSummarize,
 		turnPrefixMessages,
 		recentMessages,
+		recentEntryIds,
 		isSplitTurn,
 		tokensBefore,
 		previousSummary,
@@ -1826,35 +1840,19 @@ export async function compact(
 		}
 	}
 
-	// Anthropic server-side compaction: the live turn's request shape plus the
-	// compact edit, so the API summarizes from its cached prefix. The summary is
-	// real text, persisted both as the entry summary and as the native replay
-	// payload. A context below the API's trigger floor cannot compact remotely
-	// and takes the local summarizer instead — an eligibility boundary, not a
-	// failure.
+	// On-demand compaction summarizes only the prefix; the tail is never sent
+	// to this request and is replayed after the returned signed block.
 	let nativeSummary: string | undefined;
-	let nativeEncryptedContent: string | undefined;
+	let nativeSignature: string | undefined;
+	let nativeFirstKeptEntryId = firstKeptEntryId;
 	let nativeUsedTokens: number | undefined;
-	if (
-		!usedRemoteCompaction &&
-		settings.remoteEnabled !== false &&
-		shouldUseAnthropicNativeCompaction(model) &&
-		tokensBefore >= ANTHROPIC_COMPACTION_MIN_CONTEXT_TOKENS
-	) {
+	if (!usedRemoteCompaction && settings.remoteEnabled !== false && shouldUseAnthropicNativeCompaction(model)) {
 		const previousNative = getPreservedAnthropicCompactionData(previousPreserveData);
-		// Lead with the previous summary exactly as the live context renders it:
-		// natively when this provider wrote it, as text otherwise. The request
-		// then shares the live turn's prefix byte-for-byte. A prior snapcompact
-		// archive is already merged into that summary text, so the archive
-		// migration message the OpenAI lanes carry is omitted here.
-		// The rewrite marker must precede every message this request replays —
-		// summarized history and retained tail alike — exactly like the live
-		// context rebuild predates its tail. A previous compaction's commit
-		// timestamp is newer than re-retained or re-summarized turns, so
-		// reusing it would strip their bound thinking only in this request,
-		// diverging from the cached live prefix (and possibly dropping below
-		// the trigger). Manually built preparations with no input at all fall
-		// back to the current time.
+		// Lead with the previous summary as the live context renders it:
+		// natively when this provider wrote it, as text otherwise.
+		// A prior snapcompact archive is already merged into that summary
+		// text. Predate the rewrite marker before all replayed messages so
+		// retained thinking stays bound to the original prefix.
 		const firstReplayed = messagesToSummarize[0] ?? turnPrefixMessages[0] ?? recentMessages[0];
 		const previousSummaryAt =
 			firstReplayed !== undefined ? new Date(firstReplayed.timestamp - 1).toISOString() : new Date().toISOString();
@@ -1866,6 +1864,7 @@ export async function compact(
 									type: "anthropicCompaction",
 									provider: previousNative.provider,
 									content: previousNative.content,
+									...(previousNative.signature ? { signature: previousNative.signature } : {}),
 									...(previousNative.encryptedContent
 										? { encryptedContent: previousNative.encryptedContent }
 										: {}),
@@ -1874,29 +1873,40 @@ export async function compact(
 							: undefined,
 				})
 			: undefined;
-		const convertToLlm = summaryOptions.convertToLlm ?? defaultConvertToLlm;
-		const retainedTail = convertToLlm(recentMessages);
-		const messages = [
-			...convertToLlm([
-				...(previousSummaryMessage ? [previousSummaryMessage] : []),
-				...messagesToSummarize,
-				...turnPrefixMessages,
-			]),
-			...retainedTail,
-		];
+		const allMessages = [...messagesToSummarize, ...turnPrefixMessages, ...recentMessages];
+		const originalCut = messagesToSummarize.length + turnPrefixMessages.length;
+		const nativeCut = findAnthropicCompactionCut(allMessages, originalCut);
+		// Hand-built preparations lacking entry IDs cannot move their persisted
+		// boundary into the tail. Summarizing all is still safe.
+		const safeCut =
+			nativeCut > originalCut && nativeCut < allMessages.length && !recentEntryIds?.[nativeCut - originalCut]
+				? allMessages.length
+				: nativeCut;
+		nativeFirstKeptEntryId =
+			safeCut === allMessages.length
+				? ""
+				: safeCut === originalCut
+					? firstKeptEntryId
+					: (recentEntryIds?.[safeCut - originalCut] ?? "");
+		for (let i = originalCut; i < safeCut; i++) extractFileOpsFromMessage(allMessages[i], fileOps);
+		const messages = (summaryOptions.convertToLlm ?? defaultConvertToLlm)([
+			...(previousSummaryMessage ? [previousSummaryMessage] : []),
+			...allMessages.slice(0, safeCut),
+		]);
 		try {
 			const remote = await requestAnthropicNativeCompaction(
 				model,
 				apiKey,
 				{
-					systemPrompt: summaryOptions.remoteSystemPrompt ?? [SUMMARIZATION_SYSTEM_PROMPT],
+					// The live prompt, not the local summarizer's synthetic system
+					// prompt: kept thinking remains valid only under identical controls.
+					systemPrompt: summaryOptions.remoteSystemPrompt ?? [],
 					messages,
 					tools: summaryOptions.tools,
 					instructions: buildAnthropicCompactionInstructions(
 						summaryOptions.promptOverride ?? SUMMARIZATION_PROMPT,
 						customInstructions,
 						formatAdditionalContext(summaryOptions.extraContext).trim() || undefined,
-						describeRetainedTail(retainedTail),
 					),
 					maxTokens: Math.min(Math.floor(0.8 * reserveTokens), MAX_SUMMARY_TOKENS),
 					reasoning: resolveCompactionEffort(model, summaryOptions.thinkingLevel),
@@ -1915,7 +1925,7 @@ export async function compact(
 				},
 			);
 			nativeSummary = remote.content;
-			nativeEncryptedContent = remote.encryptedContent;
+			nativeSignature = remote.signature;
 			nativeUsedTokens = calculatePromptTokens(remote.usage);
 			usedRemoteCompaction = true;
 		} catch (err) {
@@ -2004,7 +2014,7 @@ export async function compact(
 	summary = upsertFileOperations(summary, readFiles, modifiedFiles, fileOps.read);
 	if (nativeSummary !== undefined) {
 		// The replayed block stays byte-identical to the API's summary so it
-		// matches `encryptedContent`. The harness file lists above travel
+		// matches its signature. The harness file lists above travel
 		// separately: the converter replaces the summary message with the
 		// block and skips its text, so they would otherwise be invisible to
 		// this provider. Every other provider keeps reading the entry text.
@@ -2012,7 +2022,7 @@ export async function compact(
 		preserveData = withAnthropicCompactionPreserveData(preserveData, {
 			provider: model.provider,
 			content: nativeSummary,
-			...(nativeEncryptedContent ? { encryptedContent: nativeEncryptedContent } : {}),
+			...(nativeSignature ? { signature: nativeSignature } : {}),
 			...(filesText ? { filesText } : {}),
 			model: model.id,
 			usedTokens: nativeUsedTokens,
@@ -2034,7 +2044,7 @@ export async function compact(
 	return {
 		summary,
 		shortSummary,
-		firstKeptEntryId,
+		firstKeptEntryId: nativeSummary !== undefined ? nativeFirstKeptEntryId : firstKeptEntryId,
 		tokensBefore,
 		details: { readFiles, modifiedFiles } as CompactionDetails,
 		preserveData: finalPreserveData,

package/src/compaction/messages.ts

@@ -64,6 +64,13 @@ export interface CompactionSummaryMessage {
 	images?: ImageContent[];
 	/** Post-pass dead-end warning attached to this compaction (progress guard). */
 	warning?: string;
+	/**
+	 * Thinking-binding rewrite marker when it must differ from `timestamp`: a
+	 * natively replayed summary predates it before the retained tail so that
+	 * tail's bound thinking stays valid. `timestamp` remains the commit time,
+	 * which is what invalidates the tail's pre-compaction usage reports.
+	 */
+	historyRewriteAt?: number;
 	timestamp: number;
 }
 
@@ -135,6 +142,8 @@ export interface CompactionSummaryMessageOptions {
 	method?: string;
 	/** Estimated context tokens after the rewrite, for display alongside `tokensBefore`. */
 	tokensAfter?: number;
+	/** See {@link CompactionSummaryMessage.historyRewriteAt}. */
+	historyRewriteAt?: number;
 }
 
 export function createCompactionSummaryMessage(
@@ -143,7 +152,7 @@ export function createCompactionSummaryMessage(
 	timestamp: string,
 	options: CompactionSummaryMessageOptions = {},
 ): CompactionSummaryMessage {
-	const { shortSummary, providerPayload, images, blocks, warning, method, tokensAfter } = options;
+	const { shortSummary, providerPayload, images, blocks, warning, method, tokensAfter, historyRewriteAt } = options;
 	const imageBlocks =
 		blocks?.filter((block): block is ImageContent => block.type === "image") ??
 		(images && images.length > 0 ? images : undefined);
@@ -158,6 +167,7 @@ export function createCompactionSummaryMessage(
 		blocks: blocks && blocks.length > 0 ? blocks : undefined,
 		images: imageBlocks && imageBlocks.length > 0 ? imageBlocks : undefined,
 		warning,
+		historyRewriteAt,
 		timestamp: new Date(timestamp).getTime(),
 	};
 }
@@ -246,7 +256,7 @@ export function convertMessageToLlm(message: AgentMessage): Message | undefined
 									...(message.images ?? []),
 								],
 					attribution: "agent",
-					historyRewriteAt: message.timestamp,
+					historyRewriteAt: message.historyRewriteAt ?? message.timestamp,
 					providerPayload: message.providerPayload,
 					timestamp: message.timestamp,
 				};

package/src/compaction/prompts/anthropic-compaction-instructions.md

@@ -1,8 +1,4 @@
-{{#if retainedTail}}
-SCOPE: The conversation's final {{#when retainedTail.count "==" 1}}{{retainedTail.role}} message stays{{else}}{{retainedTail.count}} messages, starting with a {{retainedTail.role}} message, stay{{/when}} in context verbatim after your summary. Summarize ONLY the history before those messages. You MUST NOT restate anything from those final messages — the reader sees them right after the summary — and you MUST treat them as the most recent state when describing progress and next steps.
-{{else}}
-SCOPE: The conversation above is the transcript to summarize. The API replaces everything before your summary with it, so nothing you leave out survives into the next context window.
-{{/if}}
+The conversation above is the complete history to summarize. The API replaces every message in this request with your summary; no message you leave out survives.
 
 {{#if extraContext}}
 {{extraContext}}
@@ -14,4 +10,4 @@ SCOPE: The conversation above is the transcript to summarize. The API replaces e
 Additional focus: {{customInstructions}}
 {{/if}}
 
-You MUST NOT call any tools while writing the summary; respond with the summary text only.
+You MUST NOT call any tools while writing the summary; respond with the summary text only.

package/src/compaction/transcript-tokens.ts

@@ -18,7 +18,7 @@
  * - `hasContextTokenUsage(usage)`: the report must carry usable context numbers.
  */
 
-import type { AssistantMessage } from "@oh-my-pi/pi-ai";
+import type { AssistantMessage, Message } from "@oh-my-pi/pi-ai";
 import type { MessageCountOptions, Tokenizer } from "../tokenizer";
 import type { AgentMessage } from "../types";
 import { calculateContextTokens, hasContextTokenUsage } from "./compaction";
@@ -67,6 +67,36 @@ export function findTranscriptUsageAnchor(
 	return undefined;
 }
 
+/**
+ * Newest assistant turn in a provider request's `messages` whose usage still
+ * describes the prefix it sits on, or `undefined` when none does.
+ *
+ * Request contexts carry no compaction index, so staleness is read from the
+ * rewrite markers themselves: a compaction/branch summary or pruned tool result
+ * (`prunedAt`) replaced text that every report made at or before the rewrite
+ * already counted. A summary's rewrite time is its `timestamp` (commit time);
+ * its `historyRewriteAt` may be predated before a natively replayed retained
+ * tail so that tail's bound thinking survives, but the tail's usage still
+ * counted the summarized prefix.
+ */
+export function findRequestUsageAnchor(messages: readonly Message[]): TranscriptUsageAnchor | undefined {
+	let rewriteAt = Number.NEGATIVE_INFINITY;
+	let anchorIndex = -1;
+	let anchor: AssistantMessage | undefined;
+	for (let index = 0; index < messages.length; index++) {
+		const message = messages[index];
+		if (message.role === "user" && message.historyRewriteAt !== undefined) {
+			rewriteAt = Math.max(rewriteAt, message.historyRewriteAt, message.timestamp);
+		} else if (message.role === "toolResult" && message.prunedAt !== undefined) {
+			rewriteAt = Math.max(rewriteAt, message.prunedAt);
+		} else if (isTranscriptUsageAnchor(message) && message.timestamp > rewriteAt) {
+			anchorIndex = index;
+			anchor = message;
+		}
+	}
+	return anchor && { index: anchorIndex, message: anchor, tokens: calculateContextTokens(anchor.usage) };
+}
+
 /** Options for {@link estimateTranscriptTokens}. */
 export interface TranscriptTokenOptions {
 	/**

package/src/index.ts

@@ -6,6 +6,8 @@ export * from "./agent-loop";
 export * from "./append-only-context";
 // Compaction
 export * from "./compaction";
+// Output cap sized to the remaining context window
+export * from "./output-budget";
 // Process-global pause gate
 export * from "./pause";
 // Proxy utilities
@@ -14,12 +16,16 @@ export * from "./proxy";
 export * from "./replay-policy";
 // Run-level telemetry collector + aggregators
 export * from "./run-collector";
+// Tool definitions remembered for Anthropic inactive-tool re-declaration
+export * from "./sent-tool-definitions";
 // Speculative execution coordinator
 export * from "./speculative-execution";
 // Telemetry
 export * from "./telemetry";
 // Thinking selectors
 export * from "./thinking";
+// Tool-context augmentation
+export * from "./tool-context";
 // Tokenizer choice
 export * from "./tokenizer";
 // Types

package/src/live-steering.ts

@@ -0,0 +1,89 @@
+/**
+ * Agent side of provider live steering ({@link LiveSteering}).
+ *
+ * A provider that can put user input into the response it is streaming (OpenAI
+ * Responses `response.steer`) pulls queued steering through a
+ * {@link LiveSteeringChannel}. The loop records what the provider accepted right
+ * after that response, so the transcript matches what the model saw; anything
+ * it declined is injected at the next boundary like ordinary steering.
+ */
+import type { LiveSteerClaim, LiveSteering, UserMessage } from "@oh-my-pi/pi-ai";
+import { logger } from "@oh-my-pi/pi-utils";
+import type { AgentMessage } from "./types";
+
+/** Steering-queue access for one provider call, supplied by the agent loop. */
+export interface LiveSteeringQueue {
+	/** Resolves once steering is queued or `signal` aborts; never consumes. */
+	wait(signal: AbortSignal): Promise<void>;
+	/** Dequeues the next steering batch. */
+	take(signal: AbortSignal): Promise<AgentMessage[]>;
+	/**
+	 * Provider view of `messages` appended to the in-flight call's context, or
+	 * `undefined` when that view is not purely user messages.
+	 */
+	toProvider(messages: AgentMessage[], signal: AbortSignal): Promise<UserMessage[] | undefined>;
+}
+
+/** One provider call's {@link LiveSteering} source. */
+export class LiveSteeringChannel implements LiveSteering {
+	/** Steering the provider delivered into the in-flight response, in queue order. */
+	readonly accepted: AgentMessage[] = [];
+	/** Steering taken from the queue but not delivered; always queued after {@link accepted}. */
+	readonly deferred: AgentMessage[] = [];
+	readonly #queue: LiveSteeringQueue;
+
+	constructor(queue: LiveSteeringQueue) {
+		this.#queue = queue;
+	}
+
+	wait(signal: AbortSignal): Promise<void> {
+		// Once input is deferred, later input must follow it at the boundary;
+		// delivering it live would reorder the user's messages.
+		if (this.deferred.length === 0) return this.#queue.wait(signal);
+		if (signal.aborted) return Promise.resolve();
+		const { promise, resolve } = Promise.withResolvers<void>();
+		signal.addEventListener("abort", () => resolve(), { once: true });
+		return promise;
+	}
+
+	async claim(signal: AbortSignal): Promise<LiveSteerClaim | undefined> {
+		if (this.deferred.length > 0 || signal.aborted) return undefined;
+		let messages: AgentMessage[];
+		try {
+			messages = await this.#queue.take(signal);
+		} catch (error) {
+			// The queue restores what it could not hand over.
+			logger.debug("Live steering dequeue failed", {
+				error: error instanceof Error ? error.message : String(error),
+			});
+			return undefined;
+		}
+		if (messages.length === 0) return undefined;
+		let providerMessages: UserMessage[] | undefined;
+		try {
+			providerMessages = await this.#queue.toProvider(messages, signal);
+		} catch (error) {
+			logger.debug("Live steering conversion failed", {
+				error: error instanceof Error ? error.message : String(error),
+			});
+		}
+		if (!providerMessages) {
+			this.deferred.push(...messages);
+			return undefined;
+		}
+		let settled = false;
+		return {
+			messages: providerMessages,
+			accept: () => {
+				if (settled) return;
+				settled = true;
+				this.accepted.push(...messages);
+			},
+			reject: () => {
+				if (settled) return;
+				settled = true;
+				this.deferred.push(...messages);
+			},
+		};
+	}
+}

package/src/output-budget.ts

@@ -0,0 +1,130 @@
+import type { Context, Model, Tool } from "@oh-my-pi/pi-ai";
+import { stopsOutputAtContextWindow } from "@oh-my-pi/pi-catalog/compat/output-limits";
+import { stringifyJson } from "@oh-my-pi/pi-utils";
+import { findRequestUsageAnchor } from "./compaction/transcript-tokens";
+import type { Tokenizer } from "./tokenizer";
+
+/** Smallest output cap {@link fitOutputTokensToContextWindow} will request. */
+export const MIN_FITTED_OUTPUT_TOKENS = 1024;
+
+/**
+ * Local counts are padded by 1/this before sizing the output cap: the
+ * provider's tokenizer can disagree with ours by a few percent, and
+ * undercounting reproduces the overflow this guards against. This is a
+ * tokenizer-error margin on locally counted text only (provider-reported
+ * usage is exact), not a context reserve; compaction's own reserve
+ * (`resolveBudgetReserveTokens`) still decides when to compact.
+ */
+const PROMPT_ESTIMATE_MARGIN_DIVISOR = 10;
+
+/**
+ * Output cap for a request, so prompt plus output stays inside the model's
+ * context window.
+ *
+ * Chat Completions-style providers (DeepSeek, OpenAI, vLLM, ...) reject a
+ * request whose prompt tokens plus `max_tokens` exceed the window. Every
+ * request asks for `model.maxTokens` of output by default, so without this a
+ * large model output cap (DeepSeek V4: ~384k of a ~1M window) makes every
+ * request fail once the prompt passes window minus output cap, long before
+ * compaction triggers, and side turns (`/btw`, recaps) have no overflow
+ * recovery at all.
+ *
+ * The prompt size is the provider's own report from the newest trustworthy
+ * assistant turn (see {@link findRequestUsageAnchor}) plus a local count of
+ * only the messages appended after it; the whole context is counted locally
+ * only when no turn can anchor (fresh or freshly rewritten context).
+ *
+ * Returns `maxTokens` unchanged when the requested cap already fits, the
+ * model declares no window, the host ends generation at the window itself
+ * instead of rejecting the request (`stops-output-at-context-window`, e.g.
+ * Claude 4.5+ on the Claude API), or nothing would be requested (including an
+ * OpenRouter-hosted model with no caller cap: the transport omits the catalog
+ * default there so each upstream self-caps, and a fitted value would turn into
+ * an explicit cap that filters upstreams). Otherwise returns
+ * the remaining room (never below {@link MIN_FITTED_OUTPUT_TOKENS}); a
+ * prompt that fills the whole window still overflows and is left to the
+ * caller's compaction. Near a full window the floor means a turn can stop on
+ * `length` instead of failing with a 400.
+ *
+ * Lives here, not next to the default in pi-ai's `mapOptionsForApi`, because
+ * pi-ai has no tokenizer; callers apply it in their `streamFn` (coding-agent
+ * does so in its shared settings-aware wrapper).
+ *
+ * Not fixed: Anthropic budget-thinking transports raise `max_tokens` back to
+ * at least the thinking budget plus a fallback buffer downstream
+ * (`ensureMaxTokensForThinking`), so a fitted cap below that is overridden
+ * and the request can still exceed the window as before.
+ */
+export function fitOutputTokensToContextWindow(
+	model: Model,
+	context: Context,
+	maxTokens: number | undefined,
+	tokenizer: Tokenizer,
+): number | undefined {
+	if (maxTokens === undefined && omitsDefaultOutputCap(model.compat)) return undefined;
+	const requested = maxTokens ?? model.maxTokens;
+	const contextWindow = model.contextWindow;
+	if (!requested || !contextWindow || contextWindow <= 0) return maxTokens;
+	if (stopsOutputAtContextWindow(model)) return maxTokens;
+
+	const room = contextWindow - countPromptTokens(context, tokenizer);
+	if (room >= requested) return maxTokens;
+	return Math.max(MIN_FITTED_OUTPUT_TOKENS, room);
+}
+
+/** OpenRouter hosts drop the catalog default cap unless the endpoint always needs one. */
+function omitsDefaultOutputCap(compat: Model["compat"] | undefined): boolean {
+	return (
+		compat !== undefined && "isOpenRouterHost" in compat && compat.isOpenRouterHost && !compat.alwaysSendMaxTokens
+	);
+}
+
+/**
+ * Framing tokens (system prompt, tool definitions) memoized per array: these
+ * are stable identities for the life of a turn, so side turns and repeat
+ * requests do not re-stringify and re-tokenize them. Length is part of the key
+ * to catch in-place growth.
+ */
+const framingCounts = new WeakMap<readonly unknown[], { tokenizer: Tokenizer; length: number; tokens: number }>();
+
+function countFraming(items: readonly unknown[] | undefined, tokenizer: Tokenizer, fragments: () => string[]): number {
+	if (!items || items.length === 0) return 0;
+	const cached = framingCounts.get(items);
+	if (cached && cached.tokenizer === tokenizer && cached.length === items.length) return cached.tokens;
+	const tokens = tokenizer.countTokens(fragments());
+	framingCounts.set(items, { tokenizer, length: items.length, tokens });
+	return tokens;
+}
+
+function toolFragments(tools: readonly Tool[]): string[] {
+	const fragments: string[] = [];
+	for (const tool of tools) fragments.push(tool.name, tool.description, stringifyJson(tool.parameters) ?? "");
+	return fragments;
+}
+
+function withMargin(localTokens: number): number {
+	return localTokens + Math.ceil(localTokens / PROMPT_ESTIMATE_MARGIN_DIVISOR);
+}
+
+/** Provider-anchored prompt size; falls back to a full local count when nothing anchors. */
+function countPromptTokens(context: Context, tokenizer: Tokenizer): number {
+	const { messages } = context;
+	const anchor = findRequestUsageAnchor(messages);
+	if (!anchor) return withMargin(countContextTokens(context, tokenizer));
+	let tail = 0;
+	for (let index = anchor.index + 1; index < messages.length; index++) {
+		tail += tokenizer.countMessage(messages[index]);
+	}
+	return anchor.tokens + withMargin(tail);
+}
+
+function countContextTokens(context: Context, tokenizer: Tokenizer): number {
+	const { systemPrompt, tools, inactiveTools } = context;
+	return (
+		countFraming(systemPrompt, tokenizer, () => [...(systemPrompt ?? [])]) +
+		countFraming(tools, tokenizer, () => toolFragments(tools ?? [])) +
+		// Anthropic replays retired tool definitions, so they are prompt too.
+		countFraming(inactiveTools, tokenizer, () => toolFragments(inactiveTools ?? [])) +
+		tokenizer.countMessages(context.messages)
+	);
+}

package/src/sent-tool-definitions.ts

@@ -0,0 +1,40 @@
+import type { Message, Tool } from "@oh-my-pi/pi-ai";
+
+/**
+ * Last wire definition this Agent sent for each tool name, so a provider that keeps
+ * withdrawn tools declared (Anthropic `tool_removal`) can re-declare them byte-identically.
+ * Used by prepareProviderCall and Agent.buildSideRequestContext.
+ */
+export class SentToolDefinitions {
+	#byName = new Map<string, Tool>();
+
+	/** Remember the definitions a request is about to send. */
+	record(tools: readonly Tool[]): void {
+		for (const tool of tools) this.#byName.set(tool.name, tool);
+	}
+
+	/**
+	 * Definitions for names the latest `requestControls.tools.declared` in `messages` holds
+	 * that are not in `active`; undefined when none. Names never sent by this Agent are
+	 * skipped: the provider drops them from the declaration.
+	 */
+	inactiveFor(messages: readonly Message[], active: readonly Tool[]): Tool[] | undefined {
+		let declared: readonly string[] | undefined;
+		for (let index = messages.length - 1; index >= 0; index--) {
+			const message = messages[index];
+			if (message?.role === "assistant" && message.requestControls?.tools) {
+				declared = message.requestControls.tools.declared;
+				break;
+			}
+		}
+		if (!declared) return undefined;
+		const activeNames = new Set(active.map(tool => tool.name));
+		const inactive: Tool[] = [];
+		for (const name of declared) {
+			if (activeNames.has(name)) continue;
+			const tool = this.#byName.get(name);
+			if (tool) inactive.push(tool);
+		}
+		return inactive.length > 0 ? inactive : undefined;
+	}
+}

package/src/tool-context.ts

@@ -0,0 +1,49 @@
+import type { ToolResultMessage } from "@oh-my-pi/pi-ai";
+import type { AgentMessage } from "./types";
+
+/**
+ * Symbol-keyed carrier for passive context reported by a tool executed outside
+ * the agent loop (Cursor exec-channel dispatch). The executor attaches the
+ * joined context to the {@link ToolResultMessage} it returns; `Agent` reads it
+ * when the provider hands the result back and injects it after the buffered
+ * results. Symbol keys never serialize, so the context cannot leak into the
+ * persisted tool result.
+ */
+export const TOOL_RESULT_ADDITIONAL_CONTEXT = Symbol("tool-result-additional-context");
+
+/** A tool result optionally carrying {@link TOOL_RESULT_ADDITIONAL_CONTEXT}. */
+export type ToolResultWithAdditionalContext = ToolResultMessage & { [TOOL_RESULT_ADDITIONAL_CONTEXT]?: string };
+
+/**
+ * True for a passive-context value worth delivering: a string with at least
+ * one non-whitespace character. Shared by every producer and aggregation site
+ * so blank values never produce a developer message.
+ */
+export function isNonBlankContext(value: unknown): value is string {
+	return typeof value === "string" && value.trim().length > 0;
+}
+
+/**
+ * Join passive context values in order, dropping blanks. Returns undefined
+ * when nothing remains.
+ */
+export function joinAdditionalContext(values: Iterable<string | undefined>): string | undefined {
+	const kept: string[] = [];
+	for (const value of values) {
+		if (isNonBlankContext(value)) kept.push(value);
+	}
+	return kept.length > 0 ? kept.join("\n\n") : undefined;
+}
+
+/**
+ * Build the developer message that carries passive tool context to the next
+ * provider request. Emitted after the tool results it belongs to.
+ */
+export function createAdditionalContextMessage(text: string): AgentMessage {
+	return {
+		role: "developer",
+		content: [{ type: "text", text }],
+		attribution: "agent",
+		timestamp: Date.now(),
+	};
+}