@gajae-code/agent-core 0.15.2 → 0.15.4

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [Unreleased]
 
+## [0.15.4] - 2026-08-29
+
+### Added
+
+- Added opt-in adaptive compaction thresholding based on context fullness and recent call rate. The default remains disabled, fixed token thresholds keep precedence, and the bounded tracker resets after successful compaction to avoid repeated immediate compactions.
+
+## [0.15.3] - 2026-08-27
+
+### Changed
+
+- Escaped non-ASCII tool-call arguments whose every `\uXXXX` escape corroborates a decoded non-ASCII character inside a tool's declared `displaySafeEscapedArgFields` now degrade to a single warning and execute the decoded call, instead of discarding the turn and charging the bounded resample/managed-fallback retry chain. Previously even purely cosmetic display text (e.g. an `ask` question written in Korean or with emoji) burned the full resample budget and then failed the run closed, which made the default Anthropic presets error out on a model-side encoding habit. Raw-evidence corroboration is now per-scalar (offset + process-keyed scalar tag against any decoded non-ASCII character in a declared display field) rather than restricted to U+2014, and literal non-ASCII display text alongside a corroborated escape no longer needs evidence. Load-bearing fields, ASCII-landing escapes, missing/malformed evidence, and non-display-safe tools keep the fail-closed discard-and-reject behavior. (#4983)
+### Fixed
+
+- Compaction no longer crashes on a persisted tool call whose `arguments` payload is null. `serializeConversation` passed that value straight into `Object.entries`, which threw `TypeError: Object.entries requires that input parameter not be null or undefined`. Because this runs inside compaction — itself the recovery path for context overflow — the failure surfaced as `Context overflow recovery failed: Object.entries requires ...`, and the next request went out uncompacted until the provider rejected it with `prompt is too long`. Malformed argument payloads now serialize as an empty argument list instead of aborting the summary.
+
 ## [0.15.2] - 2026-08-25
 
 ### Changed

package/dist/types/compaction/adaptive.d.ts

@@ -0,0 +1,31 @@
+export interface AdaptiveCompactionState {
+    turnsSinceCompact: number;
+    callsInWindow: number;
+    windowStart: number;
+    lastContextTokens: number;
+    lastCompactContextTokens: number | null;
+    lastCompactTs: number | null;
+}
+export interface AdaptiveCompactionDecisionState {
+    turnsSinceCompact: number;
+    callsInWindow: number;
+    lastContextTokens?: number;
+}
+export interface AdaptiveCompactionOptions {
+    enabled: boolean;
+    turnWindow: number;
+    baseThresholdPercent: number;
+    aggression: number;
+    minThresholdPercent?: number;
+}
+export declare class AdaptiveCompactionTracker {
+    #private;
+    windowMs: number;
+    constructor(windowMs?: number, now?: number);
+    setWindowMs(windowMs: number, now?: number): void;
+    reset(now?: number): void;
+    recordCall(contextTokens: number, now?: number): void;
+    recordCompact(contextTokens: number, now?: number): void;
+    snapshot(): AdaptiveCompactionState;
+    decisionState(): AdaptiveCompactionDecisionState;
+}

package/dist/types/compaction/compaction.d.ts

@@ -7,6 +7,7 @@
 import { type MessageAttribution, type Model, type ProviderSessionState, type Usage } from "@gajae-code/ai";
 import { type AgentTelemetry } from "../telemetry";
 import type { AgentMessage, AgentTool } from "../types";
+import type { AdaptiveCompactionDecisionState, AdaptiveCompactionOptions } from "./adaptive";
 import type { SessionEntry } from "./entries";
 import { type ConvertToLlm } from "./messages";
 import { type FileOperations } from "./utils";
@@ -32,6 +33,8 @@ export interface CompactionSettings {
     strategy?: "context-full" | "handoff" | "off";
     thresholdPercent?: number;
     thresholdTokens?: number;
+    adaptive?: AdaptiveCompactionOptions;
+    adaptiveState?: AdaptiveCompactionDecisionState;
     reserveTokens: number;
     keepRecentTokens: number;
     autoContinue?: boolean;
@@ -52,6 +55,7 @@ export interface RemoteCompactionFallbackHealthHooks {
     recordRemoteCompactionFallback(event: RemoteCompactionFallbackHealthEvent): void;
 }
 export declare const DEFAULT_COMPACTION_SETTINGS: CompactionSettings;
+export declare function computeAdaptiveThresholdPercent(basePercent: number, contextTokens: number, contextWindow: number, state: AdaptiveCompactionDecisionState | undefined, options: AdaptiveCompactionOptions | undefined): number;
 /**
  * Calculate total context tokens from usage.
  * Uses the native totalTokens field when available, falls back to computing from components.
@@ -127,7 +131,7 @@ export declare const DEFAULT_EMERGENCY_COMPACTION_LIMITS: EmergencyCompactionLim
  * normal pair-safe `compact()` cut logic so a tool_use/tool_result pair is never split.
  */
 export declare function emergencyCompactionReason(sample: EmergencyCompactionSample, limits?: EmergencyCompactionLimits): CompactionTriggerReason | null;
-export declare function resolveThresholdTokens(contextWindow: number, settings: CompactionSettings, maxOutputTokens?: number): number;
+export declare function resolveThresholdTokens(contextWindow: number, settings: CompactionSettings, maxOutputTokens?: number, contextTokens?: number): number;
 /**
  * Image content has no tokenizer representation; charge a fixed estimate
  * matching what providers typically bill for inline images.

package/dist/types/compaction/index.d.ts

@@ -1,6 +1,7 @@
 /**
  * Compaction and summarization utilities.
  */
+export * from "./adaptive";
 export * from "./branch-summarization";
 export * from "./compaction";
 export * from "./entries";

package/dist/types/types.d.ts

@@ -166,14 +166,6 @@ export type ManagedAttemptOutcome = {
     type: "escaped_arguments_discarded";
     /** The defective assistant turn; already removed from usable history by the loop. */
     message: AssistantMessage;
-    /**
-     * True when this discarded attempt had no transient steering instruction
-     * attached yet. A managed retry continuation should carry the escaped
-     * non-ASCII recovery instruction exactly once, so a deterministic
-     * escaper has a reason to change its spelling; the instruction never
-     * lands in durable history. Absent/false means steering already ran.
-     */
-    steeringPending?: boolean;
     scope?: AttemptScope;
 } | {
     type: "context_overflow_discarded";
@@ -665,13 +657,13 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any
     /**
      * Argument fields (dotted paths into the arguments object) that render to
      * the user as pure display text — question wording and option labels, never
-     * ids, metadata, or persisted records. The agent loop uses this to bound the
-     * escaped-non-ASCII terminal rejection AFTER the resample budget is spent:
-     * when every non-ASCII character under these fields is benign typographic
-     * punctuation (e.g. an em-dash a JSON encoder escaped), the call executes
-     * instead of failing closed. Every other field of these arguments — and
-     * every field of every other tool — keeps the fail-closed rejection for
-     * unverified `\uXXXX` payloads.
+     * ids, metadata, or persisted records. When every `\uXXXX`-escaped scalar in
+     * a tool call corroborates a decoded non-ASCII character inside these
+     * fields, the agent loop degrades to a single warning and executes the
+     * decoded call instead of discarding the turn: a mistyped hex digit there
+     * can only change what the user reads, never what executes or persists.
+     * Every other field of these arguments — and every field of every other
+     * tool — keeps the fail-closed rejection for unverified `\uXXXX` payloads.
      */
     displaySafeEscapedArgFields?: readonly string[];
     /** The main execution callback for this tool. */

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/agent-core",
-	"version": "0.15.2",
+	"version": "0.15.4",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo and Gajae Code Contributors",
@@ -32,9 +32,9 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/ai": "0.15.2",
-		"@gajae-code/natives": "0.15.2",
-		"@gajae-code/utils": "0.15.2",
+		"@gajae-code/ai": "0.15.4",
+		"@gajae-code/natives": "0.15.4",
+		"@gajae-code/utils": "0.15.4",
 		"@opentelemetry/api": "^1.9.0"
 	},
 	"devDependencies": {

package/src/agent-loop.ts

@@ -437,17 +437,14 @@ function stripUnicodeEscapeEvidence(message: AssistantMessage): void {
 }
 
 /**
- * The complete set of non-ASCII characters an escaped payload may decode to and
- * still execute on a display-safe tool after the resample budget: U+2014 EM DASH
- * only. This is the exact character JSON encoders spell as `\u2014` that
- * motivated the false positive — an English question text like "sessions —
- * in-process?" with no other non-ASCII. Curated deliberately: a mistyped nibble
- * here can only produce another punctuation/letter codepoint, and any such
- * landing (or any other escaped character at all) keeps the fail-closed
- * rejection. Currency, math, full-width, separator, letter, mark, number, and
- * surrogate escapes all stay rejected everywhere.
+ * Display-safe handling for tools that opt specific argument fields into it:
+ * every non-ASCII character of the decoded arguments must live inside one of
+ * the declared display-field paths, and the raw escape evidence must
+ * corroborate each escaped scalar against the decoded display text. A
+ * mistyped nibble here can only change what the user reads on screen, never
+ * what executes or persists, so the call degrades to a single warning instead
+ * of the fail-closed rejection that load-bearing fields keep.
  */
-const DISPLAY_SAFE_ESCAPED_CODEPOINTS = new Set([0x2014]);
 
 /** Structural type for tools that opt specific argument fields into display-safe handling. */
 type DisplaySafeEscapedTool = AgentTool<TSchema> & {
@@ -455,14 +452,6 @@ type DisplaySafeEscapedTool = AgentTool<TSchema> & {
 	displaySafeEscapedArgFields?: readonly string[];
 };
 
-/**
- * Whether a non-ASCII codepoint is benign typographic punctuation that a JSON
- * encoder may escape in display text. See {@link DISPLAY_SAFE_ESCAPED_CODEPOINTS}.
- */
-function isDisplaySafeEscapedCodepoint(cp: number): boolean {
-	return DISPLAY_SAFE_ESCAPED_CODEPOINTS.has(cp);
-}
-
 /** Whether the tool declared any display-only argument fields at all. */
 function isDisplaySafeEscapedTool(tool: AgentTool<TSchema> | undefined): boolean {
 	return ((tool as DisplaySafeEscapedTool | undefined)?.displaySafeEscapedArgFields?.length ?? 0) > 0;
@@ -472,10 +461,9 @@ function isDisplaySafeEscapedTool(tool: AgentTool<TSchema> | undefined): boolean
  * Walk the decoded arguments and decide whether the escaped payload is
  * display-safe: every non-ASCII character must live inside one of the tool's
  * declared display-field paths (dotted, array-index-free: `questions.question`
- * matches every question in the `questions` array) AND be benign typographic
- * punctuation. Any non-ASCII outside the display fields — ids, metadata,
- * persisted records, or an object key — keeps the fail-closed rejection, as
- * does any non-benign codepoint inside them.
+ * matches every question in the `questions` array). Any non-ASCII outside the
+ * display fields — ids, metadata, persisted records, or an object key — keeps
+ * the fail-closed rejection.
  */
 function isDisplaySafeEscapedArguments(tool: AgentTool<TSchema> | undefined, args: Record<string, unknown>): boolean {
 	const fields = (tool as DisplaySafeEscapedTool | undefined)?.displaySafeEscapedArgFields;
@@ -490,8 +478,8 @@ function isDisplaySafeEscapedArguments(tool: AgentTool<TSchema> | undefined, arg
 				const cp = ch.codePointAt(0);
 				if (cp === undefined || cp < 0x80) continue;
 				// Outside the display fields no non-ASCII is tolerated at all;
-				// inside them only the curated punctuation set is.
-				if (!isDisplayPath(path) || !isDisplaySafeEscapedCodepoint(cp)) return false;
+				// inside them any decoded character is display text.
+				if (!isDisplayPath(path)) return false;
 			}
 			return true;
 		}
@@ -517,9 +505,10 @@ function isDisplaySafeEscapedArguments(tool: AgentTool<TSchema> | undefined, arg
 
 /**
  * Validate the original raw escape positions, not just the decoded values.
- * Missing, malformed, overflowed, key-position, non-U+2014, or path-mismatched
- * evidence fails closed. Process-keyed scalar/path tags keep argument text out of the
- * carried metadata while still binding every escape to a declared display field.
+ * Missing, malformed, overflowed, key-position, ASCII-landing, or
+ * path-mismatched evidence fails closed. Process-keyed scalar/path tags keep
+ * argument text out of the carried metadata while still binding every escape
+ * to a decoded non-ASCII character inside a declared display field.
  */
 function isDisplaySafeRawEscapeEvidence(
 	tool: AgentTool<TSchema> | undefined,
@@ -538,7 +527,7 @@ function isDisplaySafeRawEscapeEvidence(
 		return false;
 	if (evidence.positions.length === 0 || evidence.positions.length > 32) return false;
 
-	const allowedValues = new Map<string, { offsets: Set<number>; matched: Set<number> }>();
+	const allowedValues = new Map<string, { offsets: Map<number, string>; matched: Set<number> }>();
 	const valueOrdinals = new Map<string, number>();
 	const prefixes = fields.map(field => field.split("."));
 	const isDisplayPath = (path: readonly string[]): boolean =>
@@ -550,10 +539,10 @@ function isDisplaySafeRawEscapeEvidence(
 			const pathTag = unicodeEscapePathTag(path);
 			const valueOrdinal = valueOrdinals.get(pathTag) ?? 0;
 			valueOrdinals.set(pathTag, valueOrdinal + 1);
-			const offsets = new Set<number>();
+			const offsets = new Map<number, string>();
 			for (let offset = 0; offset < node.length; ) {
 				const codePoint = node.codePointAt(offset);
-				if (codePoint === 0x2014) offsets.add(offset);
+				if (codePoint !== undefined && codePoint >= 0x80) offsets.set(offset, unicodeEscapeScalarTag(codePoint));
 				offset += codePoint !== undefined && codePoint > 0xffff ? 2 : 1;
 			}
 			allowedValues.set(`${pathTag}:${valueOrdinal}`, { offsets, matched: new Set() });
@@ -574,11 +563,10 @@ function isDisplaySafeRawEscapeEvidence(
 	walk(args);
 
 	let previousOffset = -1;
-	const allowedScalarTag = unicodeEscapeScalarTag(0x2014);
 	for (const position of evidence.positions) {
 		if (
 			position.location !== "value" ||
-			position.scalarTag !== allowedScalarTag ||
+			!/^[0-9a-f]{64}$/.test(position.scalarTag) ||
 			!Number.isSafeInteger(position.offset) ||
 			position.offset <= previousOffset ||
 			!/^[0-9a-f]{64}$/.test(position.pathTag) ||
@@ -591,10 +579,44 @@ function isDisplaySafeRawEscapeEvidence(
 		}
 		previousOffset = position.offset;
 		const value = allowedValues.get(`${position.pathTag}:${position.valueOrdinal}`);
-		if (!value?.offsets.has(position.valueOffset) || value.matched.has(position.valueOffset)) return false;
+		// Each escape must corroborate an actual decoded non-ASCII character at
+		// that exact offset inside a declared display string: an ASCII landing
+		// (a possible one-nibble mutation of a non-ASCII escape), a load-bearing
+		// field, or a shifted position all fail closed.
+		if (
+			!value ||
+			value.offsets.get(position.valueOffset) !== position.scalarTag ||
+			value.matched.has(position.valueOffset)
+		)
+			return false;
 		value.matched.add(position.valueOffset);
 	}
-	return [...allowedValues.values()].every(value => value.offsets.size === value.matched.size);
+	return true;
+}
+/**
+ * Whether every escaped tool call in the turn lands entirely on declared
+ * display-safe fields of its registered tool. Only then does the turn skip
+ * the resample/discard chain: a single load-bearing escaped call keeps the
+ * whole turn fail-closed.
+ */
+function allEscapedToolCallsDisplaySafe(
+	message: AssistantMessage,
+	tools: readonly AgentTool<TSchema>[] | undefined,
+): boolean {
+	let sawEscapedCall = false;
+	for (const block of message.content) {
+		if (block.type !== "toolCall") continue;
+		if (block.escapedNonAsciiArguments !== true && block.escapedUnicodeArgumentEvidence === undefined) continue;
+		sawEscapedCall = true;
+		const tool = tools?.find(candidate => candidate.name === block.name);
+		const args = block.arguments as Record<string, unknown>;
+		if (
+			!isDisplaySafeEscapedArguments(tool, args) ||
+			!isDisplaySafeRawEscapeEvidence(tool, args, block.escapedUnicodeArgumentEvidence)
+		)
+			return false;
+	}
+	return sawEscapedCall;
 }
 /** Remove only the exact assistant response committed by its streaming attempt. */
 function removeCommittedAssistantMessage(messages: AgentMessage[], message: AssistantMessage): boolean {
@@ -3711,12 +3733,27 @@ async function runLoopBody(
 			// owns a bounded same-model retry; the defect is never treated as
 			// provider evidence, so the fallback chain never advances on it.
 			//
-			// The budget runs unconditionally for escaped payloads: even a
-			// display-safe tool (whose terminal exemption lives in
-			// `executeToolCalls`) resamples here first, so the model always gets
-			// its chances to emit literal UTF-8 and the fallback stays rare
-			// rather than becoming the default path.
+			// The single bounded exception is the display-safe degrade: when
+			// every escaped call in the turn corroborates its escaped scalars
+			// against decoded non-ASCII text inside the tool's declared
+			// display-only fields, a mistyped nibble can only change what the
+			// user reads on screen. That turn skips the resample/discard chain
+			// entirely — no managed retry is charged — executes the decoded
+			// call, and warns once so the fire rate stays measurable.
 			if (
+				message.stopReason !== "error" &&
+				message.stopReason !== "aborted" &&
+				hasEscapedNonAsciiToolCall(message) &&
+				allEscapedToolCallsDisplaySafe(message, currentContext.tools)
+			) {
+				// Display-safe degrade: execute the decoded arguments as-is and warn
+				// once (shape-only, never names or payload). The turn is neither
+				// resampled nor reported to the managed fallback policy.
+				logger.warn("agent: executing a tool-call turn whose display-safe arguments were \\uXXXX-escaped", {
+					mode: config.fallbackManaged ? "managed" : "in_loop",
+					...escapedNonAsciiToolCallShape(message),
+				});
+			} else if (
 				message.stopReason !== "error" &&
 				message.stopReason !== "aborted" &&
 				escapedNonAsciiResampleAttempt < MAX_ESCAPED_NONASCII_RESAMPLES &&
@@ -3757,10 +3794,9 @@ async function runLoopBody(
 				// outcome below; the policy owns the same-model bounded retry and
 				// only falls back once it declines. The wire defect is not provider
 				// evidence, so the outcome deliberately carries no transport facts
-				// and the fallback chain never advances on it. The outcome names
-				// whether a steering instruction already rode this attempt, so the
-				// policy's retry continuation can carry it exactly once instead of
-				// blindly re-requesting the same defective spelling.
+				// and the fallback chain never advances on it. The policy's retry
+				// continuation attaches transient steering on every bounded re-issue
+				// instead of blindly re-requesting the same defective spelling.
 				if (config.fallbackManaged) {
 					transaction?.discard();
 					currentContext.messages.splice(contextMessageCount);
@@ -3768,7 +3804,6 @@ async function runLoopBody(
 					await config.onManagedAttemptOutcome?.({
 						type: "escaped_arguments_discarded",
 						message,
-						steeringPending: recoveryAttempt?.kind !== "escaped-nonascii",
 						scope: transaction?.scope,
 					});
 					stream.end(newMessages);
@@ -4945,10 +4980,11 @@ async function executeToolCalls(
 					// equally valid character — the payload is unverifiable and cannot be
 					// repaired after parsing, so it is rejected rather than executed on
 					// silently corrupted text. The one bounded exception is a tool that
-					// declared its arguments display-only (see
-					// isDisplaySafeEscapedArguments): user-facing question text whose
-					// only escaped scalars are exact U+2014 positions, corroborated against
-					// the decoded display fields. Missing or ASCII-position evidence rejects.
+					// declared display-only argument fields (see
+					// isDisplaySafeEscapedArguments): user-facing display text whose
+					// escaped scalars all corroborate decoded non-ASCII characters
+					// inside those fields. Missing, malformed, or ASCII-position
+					// evidence rejects.
 					//
 					// Terminal for this call: the resample budget is already spent, so
 					// log it (shape-only) to make the fire rate measurable without

package/src/compaction/adaptive.ts

@@ -0,0 +1,92 @@
+export interface AdaptiveCompactionState {
+	turnsSinceCompact: number;
+	callsInWindow: number;
+	windowStart: number;
+	lastContextTokens: number;
+	lastCompactContextTokens: number | null;
+	lastCompactTs: number | null;
+}
+
+export interface AdaptiveCompactionDecisionState {
+	turnsSinceCompact: number;
+	callsInWindow: number;
+	lastContextTokens?: number;
+}
+
+export interface AdaptiveCompactionOptions {
+	enabled: boolean;
+	turnWindow: number;
+	baseThresholdPercent: number;
+	aggression: number;
+	minThresholdPercent?: number;
+}
+
+export class AdaptiveCompactionTracker {
+	#state: AdaptiveCompactionState;
+	windowMs: number;
+
+	constructor(windowMs = 60_000, now = Date.now()) {
+		this.windowMs = Number.isFinite(windowMs) && windowMs > 0 ? windowMs : 60_000;
+		this.#state = {
+			turnsSinceCompact: 0,
+			callsInWindow: 0,
+			windowStart: now,
+			lastContextTokens: 0,
+			lastCompactContextTokens: null,
+			lastCompactTs: null,
+		};
+	}
+
+	setWindowMs(windowMs: number, now = Date.now()): void {
+		if (!Number.isFinite(windowMs)) return;
+		const nextWindowMs = Math.max(1, windowMs);
+		if (nextWindowMs === this.windowMs) return;
+		this.windowMs = nextWindowMs;
+		this.#state.windowStart = now;
+		this.#state.callsInWindow = 0;
+	}
+
+	reset(now = Date.now()): void {
+		this.#state = {
+			turnsSinceCompact: 0,
+			callsInWindow: 0,
+			windowStart: now,
+			lastContextTokens: 0,
+			lastCompactContextTokens: null,
+			lastCompactTs: null,
+		};
+	}
+
+	recordCall(contextTokens: number, now = Date.now()): void {
+		const timestamp = Number.isFinite(now) ? now : Date.now();
+		this.#state.turnsSinceCompact += 1;
+		if (timestamp - this.#state.windowStart >= this.windowMs) {
+			this.#state.windowStart = timestamp;
+			this.#state.callsInWindow = 0;
+		}
+		this.#state.callsInWindow += 1;
+		this.#state.lastContextTokens = contextTokens;
+	}
+
+	recordCompact(contextTokens: number, now = Date.now()): void {
+		const timestamp = Number.isFinite(now) ? now : Date.now();
+		this.#state.turnsSinceCompact = 0;
+		this.#state.callsInWindow = 0;
+		this.#state.windowStart = timestamp;
+		this.#state.lastContextTokens = contextTokens;
+		this.#state.lastCompactContextTokens = contextTokens;
+		this.#state.lastCompactTs = timestamp;
+	}
+
+	snapshot(): AdaptiveCompactionState {
+		return { ...this.#state };
+	}
+
+	decisionState(): AdaptiveCompactionDecisionState {
+		return {
+			turnsSinceCompact: this.#state.turnsSinceCompact,
+			callsInWindow: this.#state.callsInWindow,
+			lastContextTokens: this.#state.lastContextTokens,
+		};
+	}
+}

package/src/compaction/compaction.ts

@@ -18,6 +18,7 @@ import {
 import { logger, prompt } from "@gajae-code/utils";
 import { type AgentTelemetry, instrumentedCompleteSimple } from "../telemetry";
 import type { AgentMessage, AgentTool } from "../types";
+import type { AdaptiveCompactionDecisionState, AdaptiveCompactionOptions } from "./adaptive";
 import type { CompactionEntry, SessionEntry } from "./entries";
 import { type ConvertToLlm, convertToLlm, createBranchSummaryMessage, createCustomMessage } from "./messages";
 import {
@@ -33,7 +34,6 @@ import compactionSummaryPrompt from "./prompts/compaction-summary.md" with { typ
 import compactionTurnPrefixPrompt from "./prompts/compaction-turn-prefix.md" with { type: "text" };
 import compactionUpdateSummaryPrompt from "./prompts/compaction-update-summary.md" with { type: "text" };
 import handoffDocumentPrompt from "./prompts/handoff-document.md" with { type: "text" };
-
 import {
 	computeFileLists,
 	createFileOps,
@@ -136,6 +136,8 @@ export interface CompactionSettings {
 	strategy?: "context-full" | "handoff" | "off";
 	thresholdPercent?: number;
 	thresholdTokens?: number;
+	adaptive?: AdaptiveCompactionOptions;
+	adaptiveState?: AdaptiveCompactionDecisionState;
 	reserveTokens: number;
 	keepRecentTokens: number;
 	autoContinue?: boolean;
@@ -166,6 +168,40 @@ export const DEFAULT_COMPACTION_SETTINGS: CompactionSettings = {
 	remoteEnabled: true,
 };
 
+export function computeAdaptiveThresholdPercent(
+	basePercent: number,
+	contextTokens: number,
+	contextWindow: number,
+	state: AdaptiveCompactionDecisionState | undefined,
+	options: AdaptiveCompactionOptions | undefined,
+): number {
+	const clampedBasePercent = Number.isFinite(basePercent) ? Math.min(99, Math.max(1, basePercent)) : 85;
+	if (!options?.enabled) return basePercent;
+	if (!state || !Number.isFinite(contextWindow) || contextWindow <= 0) return clampedBasePercent;
+	if (!Number.isFinite(options.turnWindow) || options.turnWindow <= 0) return clampedBasePercent;
+
+	const safeContextTokens = Number.isFinite(contextTokens) ? Math.max(0, contextTokens) : 0;
+	const fillRatio = safeContextTokens / contextWindow;
+	const baseRatio = clampedBasePercent / 100;
+	if (fillRatio < baseRatio * 0.7) return clampedBasePercent;
+
+	const turnsSinceCompact = Number.isFinite(state.turnsSinceCompact) ? Math.max(0, state.turnsSinceCompact) : 0;
+	const callsInWindow = Number.isFinite(state.callsInWindow) ? Math.max(0, state.callsInWindow) : 0;
+	if (turnsSinceCompact <= 3) return clampedBasePercent;
+	const windowTurns = Math.max(1, options.turnWindow * 4);
+	const intensity = Math.min(1, callsInWindow / windowTurns);
+	const aggression = Number.isFinite(options.aggression) ? Math.min(1, Math.max(0, options.aggression)) : 0;
+	const configuredMinThresholdPercent = options.minThresholdPercent;
+	const minThresholdPercent = Math.min(
+		clampedBasePercent,
+		typeof configuredMinThresholdPercent === "number" && Number.isFinite(configuredMinThresholdPercent)
+			? Math.max(1, configuredMinThresholdPercent)
+			: clampedBasePercent * 0.5,
+	);
+	const loweredPercent = clampedBasePercent - (clampedBasePercent - minThresholdPercent) * aggression * intensity;
+	return Math.max(1, Math.min(99, Math.round(loweredPercent)));
+}
+
 // ============================================================================
 // Token calculation
 // ============================================================================
@@ -244,7 +280,7 @@ export function shouldCompact(
 	maxOutputTokens = 0,
 ): boolean {
 	if (!settings.enabled || settings.strategy === "off" || contextWindow <= 0) return false;
-	const thresholdTokens = resolveThresholdTokens(contextWindow, settings, maxOutputTokens);
+	const thresholdTokens = resolveThresholdTokens(contextWindow, settings, maxOutputTokens, contextTokens);
 	return contextTokens > thresholdTokens;
 }
 
@@ -381,6 +417,7 @@ export function resolveThresholdTokens(
 	contextWindow: number,
 	settings: CompactionSettings,
 	maxOutputTokens = 0,
+	contextTokens?: number,
 ): number {
 	// Fixed token limit takes priority over percentage
 	const thresholdTokens = settings.thresholdTokens;
@@ -392,10 +429,38 @@ export function resolveThresholdTokens(
 	// Percentage-based threshold
 	const thresholdPercent = settings.thresholdPercent;
 	if (typeof thresholdPercent !== "number" || !Number.isFinite(thresholdPercent) || thresholdPercent <= 0) {
-		return contextWindow - effectiveReserveTokens(contextWindow, settings, maxOutputTokens);
+		if (!settings.adaptive?.enabled) {
+			return contextWindow - effectiveReserveTokens(contextWindow, settings, maxOutputTokens);
+		}
+		const adaptiveBasePercent = Number.isFinite(settings.adaptive.baseThresholdPercent)
+			? Math.min(99, Math.max(1, settings.adaptive.baseThresholdPercent))
+			: 85;
+		const adaptiveThresholdPercent = computeAdaptiveThresholdPercent(
+			adaptiveBasePercent,
+			adaptiveContextTokens(contextTokens, settings.adaptiveState?.lastContextTokens),
+			contextWindow,
+			settings.adaptiveState,
+			settings.adaptive,
+		);
+		return Math.floor(contextWindow * (adaptiveThresholdPercent / 100));
 	}
 	const clampedThresholdPercent = Math.min(99, Math.max(1, thresholdPercent));
-	return Math.floor(contextWindow * (clampedThresholdPercent / 100));
+	const adaptiveThresholdPercent = computeAdaptiveThresholdPercent(
+		settings.adaptive?.baseThresholdPercent ?? clampedThresholdPercent,
+		adaptiveContextTokens(contextTokens, settings.adaptiveState?.lastContextTokens),
+		contextWindow,
+		settings.adaptiveState,
+		settings.adaptive,
+	);
+	const effectiveThresholdPercent = settings.adaptive?.enabled ? adaptiveThresholdPercent : clampedThresholdPercent;
+	return Math.floor(contextWindow * (effectiveThresholdPercent / 100));
+}
+
+function adaptiveContextTokens(contextTokens: number | undefined, lastContextTokens: number | undefined): number {
+	if (contextTokens !== undefined && Number.isFinite(contextTokens)) return Math.max(0, contextTokens);
+	if (typeof lastContextTokens === "number" && Number.isFinite(lastContextTokens))
+		return Math.max(0, lastContextTokens);
+	return 0;
 }
 
 // ============================================================================
@@ -543,7 +608,11 @@ function collectMessageFragments(message: AgentMessage): { fragments: string[];
 					fragments.push(block.thinking);
 				} else if (block.type === "toolCall") {
 					fragments.push(block.name);
-					fragments.push(JSON.stringify(block.arguments));
+					// `arguments` is typed non-null, but persisted history can carry a
+					// null/undefined payload from an aborted or malformed tool call;
+					// JSON.stringify returns undefined for those, and the token
+					// fingerprint below requires string fragments.
+					fragments.push(JSON.stringify(block.arguments) ?? "null");
 				}
 			}
 			break;

package/src/compaction/index.ts

@@ -2,6 +2,7 @@
  * Compaction and summarization utilities.
  */
 
+export * from "./adaptive";
 export * from "./branch-summarization";
 export * from "./compaction";
 export * from "./entries";

package/src/compaction/utils.ts

@@ -147,8 +147,12 @@ export function serializeConversation(messages: Message[]): string {
 				} else if (block.type === "thinking") {
 					thinkingParts.push(block.thinking);
 				} else if (block.type === "toolCall") {
-					const args = block.arguments as Record<string, unknown>;
-					const argsStr = Object.entries(args)
+					// `arguments` is typed non-null, but persisted history can carry a
+					// null/non-object payload from an aborted or malformed tool call.
+					// Summarization must never throw here: this runs inside compaction,
+					// which is itself the recovery path for context overflow.
+					const args = block.arguments as Record<string, unknown> | null | undefined;
+					const argsStr = Object.entries(args && typeof args === "object" ? args : {})
 						.map(([k, v]) => `${k}=${JSON.stringify(v)}`)
 						.join(", ");
 					toolCalls.push(`${block.name}(${argsStr})`);

package/src/types.ts

@@ -186,14 +186,6 @@ export type ManagedAttemptOutcome =
 			type: "escaped_arguments_discarded";
 			/** The defective assistant turn; already removed from usable history by the loop. */
 			message: AssistantMessage;
-			/**
-			 * True when this discarded attempt had no transient steering instruction
-			 * attached yet. A managed retry continuation should carry the escaped
-			 * non-ASCII recovery instruction exactly once, so a deterministic
-			 * escaper has a reason to change its spelling; the instruction never
-			 * lands in durable history. Absent/false means steering already ran.
-			 */
-			steeringPending?: boolean;
 			scope?: AttemptScope;
 	  }
 	| { type: "context_overflow_discarded"; message: AssistantMessage; scope?: AttemptScope }
@@ -740,13 +732,13 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any
 	/**
 	 * Argument fields (dotted paths into the arguments object) that render to
 	 * the user as pure display text — question wording and option labels, never
-	 * ids, metadata, or persisted records. The agent loop uses this to bound the
-	 * escaped-non-ASCII terminal rejection AFTER the resample budget is spent:
-	 * when every non-ASCII character under these fields is benign typographic
-	 * punctuation (e.g. an em-dash a JSON encoder escaped), the call executes
-	 * instead of failing closed. Every other field of these arguments — and
-	 * every field of every other tool — keeps the fail-closed rejection for
-	 * unverified `\uXXXX` payloads.
+	 * ids, metadata, or persisted records. When every `\uXXXX`-escaped scalar in
+	 * a tool call corroborates a decoded non-ASCII character inside these
+	 * fields, the agent loop degrades to a single warning and executes the
+	 * decoded call instead of discarding the turn: a mistyped hex digit there
+	 * can only change what the user reads, never what executes or persists.
+	 * Every other field of these arguments — and every field of every other
+	 * tool — keeps the fail-closed rejection for unverified `\uXXXX` payloads.
 	 */
 	displaySafeEscapedArgFields?: readonly string[];