@sayknow-cli/agent-core 0.5.2 → 0.5.8

package/CHANGELOG.md

@@ -2,7 +2,19 @@
 
 ## [Unreleased]
 
-## [0.12.0] - 2026-07-28
+## [0.5.8] - 2026-09-10
+
+## [0.5.7] - 2026-09-10
+
+### Added
+
+- Opt-in adaptive compaction. A fixed threshold compacts at the same context percentage no matter how fast a session fills its window, so a tool-call burst can overshoot between two checks while a quiet session compacts more often than it needs to. `AdaptiveCompactionTracker` records calls per window and `computeAdaptiveThresholdPercent` lowers the threshold in proportion to that rate, bounded by a configurable floor. Disabled by default and inert when disabled: a fixed `thresholdTokens` still wins, `thresholdPercent` is returned unchanged, and the reserve-based default path is untouched. When enabled it still returns the base while the context sits below 70% of it, and during a short post-compaction grace, so a burst cannot chain compactions.
+
+## [0.5.3] - 2026-08-28
+
+### Fixed
+
+- Compaction now serializes malformed persisted tool calls with null or missing arguments instead of throwing inside the recovery path, and long managed sessions trigger an emergency rewrite before their append-only transcript reaches the storage file-size ceiling.
 
 ## [0.11.11] - 2026-07-26
 

package/dist/types/agent-loop.d.ts

@@ -2,9 +2,9 @@
  * Agent loop that works with AgentMessage throughout.
  * Transforms to Message[] only at the LLM call boundary.
  */
-import { type Context, EventStream } from "@sayknow-cli/ai";
+import { type AssistantMessage, type Context, EventStream, type TSchema } from "@sayknow-cli/ai";
 import { type AgentRunCoverage, type AgentRunSummary } from "./run-collector";
-import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, StreamFn } from "./types";
+import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, AgentTool, StreamFn } from "./types";
 /** Sentinel returned by the abort race in `streamAssistantResponse`. */
 /**
  * Defensive caps for a provisional managed attempt. These are intentionally
@@ -13,6 +13,15 @@ import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, StreamFn
  */
 export declare const MANAGED_ATTEMPT_MAX_STAGED_EVENTS = 10000;
 export declare const MANAGED_ATTEMPT_MAX_STAGED_BYTES: number;
+/**
+ * Validate provider-observed escaped arguments before permitting the only
+ * exception to the fail-closed tool boundary. The raw JSON must decode to the
+ * exact parsed arguments, every decoded non-ASCII scalar must be under a
+ * tool-declared display path, and the wire must not contain ASCII escapes.
+ */
+export declare function displaySafeEscapedArguments(tool: AgentTool<TSchema> | undefined, toolCall: Extract<AssistantMessage["content"][number], {
+    type: "toolCall";
+}>): boolean;
 /**
  * Start an agent loop with a new prompt message.
  * The prompt is added to the context and events are emitted for it.

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

@@ -0,0 +1,50 @@
+/**
+ * Adaptive compaction state.
+ *
+ * A fixed threshold compacts at the same context percentage regardless of how
+ * fast the session is filling the window. During a tool-call burst the context
+ * can jump well past the threshold between two checks, while a slow session
+ * compacts more often than it needs to. The tracker records call rate per
+ * window so {@link ../compaction!computeAdaptiveThresholdPercent} can lower the
+ * threshold while a session is busy and leave it alone otherwise.
+ *
+ * Opt-in: with `compaction.adaptive.enabled` false the tracker is still cheap to
+ * run but its state never reaches a threshold decision.
+ */
+export interface AdaptiveCompactionState {
+    turnsSinceCompact: number;
+    callsInWindow: number;
+    windowStart: number;
+    lastContextTokens: number;
+    lastCompactContextTokens: number | null;
+    lastCompactTs: number | null;
+}
+/** The subset a threshold decision reads; keeps the decision path pure. */
+export interface AdaptiveCompactionDecisionState {
+    turnsSinceCompact: number;
+    callsInWindow: number;
+    lastContextTokens?: number;
+}
+export interface AdaptiveCompactionOptions {
+    enabled: boolean;
+    /** Minutes of recent calls considered when measuring call rate. */
+    turnWindow: number;
+    /** Context percentage used when the session is not busy. */
+    baseThresholdPercent: number;
+    /** How strongly call rate lowers the threshold, 0 to 1. */
+    aggression: number;
+    /** Lowest percentage the threshold may be lowered to. */
+    minThresholdPercent?: number;
+}
+export declare class AdaptiveCompactionTracker {
+    #private;
+    constructor(windowMs?: number, now?: number);
+    get windowMs(): number;
+    /** Changing the window restarts the current count so a resize cannot inherit a rate measured over a different span. */
+    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 "@sayknow-cli/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,10 @@ export interface CompactionSettings {
     strategy?: "context-full" | "handoff" | "off";
     thresholdPercent?: number;
     thresholdTokens?: number;
+    /** Opt-in adaptive threshold controls. Absent or disabled keeps the fixed threshold. */
+    adaptive?: AdaptiveCompactionOptions;
+    /** Call-rate state a threshold decision reads; supplied by the session's tracker. */
+    adaptiveState?: AdaptiveCompactionDecisionState;
     reserveTokens: number;
     keepRecentTokens: number;
     autoContinue?: boolean;
@@ -80,7 +85,7 @@ export declare function effectiveReserveTokens(contextWindow: number, settings:
  */
 export declare function shouldCompact(contextTokens: number, contextWindow: number, settings: CompactionSettings, maxOutputTokens?: number): boolean;
 /** Reason a compaction was triggered. `token` is the normal user-configurable path; the rest are emergency floors. */
-export type CompactionTriggerReason = "token" | "heap" | "retainedMemory" | "providerBytes" | "messageCount" | "imageBytes";
+export type CompactionTriggerReason = "token" | "heap" | "retainedMemory" | "transcriptFile" | "providerBytes" | "messageCount" | "imageBytes";
 /** A point-in-time resource sample. Supplied by an injectable sampler so tests never read real RSS. */
 export interface EmergencyCompactionSample {
     /** Resident heap bytes (e.g. process.memoryUsage().heapUsed). */
@@ -99,6 +104,8 @@ export interface EmergencyCompactionSample {
     tuiChatChildren?: number;
     /** Bytes retained by TUI render caches. */
     tuiCachedRenderBytes?: number;
+    /** On-disk JSONL transcript file size in bytes; 0/undefined when unknown. */
+    transcriptFileBytes?: number;
 }
 export interface EmergencyCompactionLimits {
     heapUsedBytes: number;
@@ -109,6 +116,7 @@ export interface EmergencyCompactionLimits {
     retainedMemoryDiagnosticBytes?: number;
     tuiChatChildren?: number;
     tuiChatChildrenDiagnostic?: number;
+    transcriptFileBytes?: number;
 }
 export declare function resetEmergencyRetainedMemoryDiagnosticsForTests(): void;
 export declare function resolveEmergencyCompactionLimits(totalMemoryBytes?: number): EmergencyCompactionLimits;
@@ -119,12 +127,20 @@ export declare function resolveEmergencyCompactionLimits(totalMemoryBytes?: numb
  */
 export declare const DEFAULT_EMERGENCY_COMPACTION_LIMITS: EmergencyCompactionLimits;
 /**
- * Returns the first emergency limit exceeded (heap > retainedMemory > providerBytes > imageBytes > messageCount),
+ * Returns the first emergency limit exceeded (heap > retainedMemory > transcriptFile > providerBytes > imageBytes > messageCount),
  * or null when none is. Pure apart from retained-memory diagnostics; the caller routes the result through the
  * 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;
+/**
+ * Lower the compaction threshold while a session is filling its window quickly.
+ *
+ * Returns `basePercent` untouched unless adaptive mode is enabled and the session
+ * is both near the base threshold and past a short post-compaction grace, so a
+ * quiet or just-compacted session keeps the fixed behavior exactly.
+ */
+export declare function computeAdaptiveThresholdPercent(basePercent: number, contextTokens: number, contextWindow: number, state: AdaptiveCompactionDecisionState | undefined, options: AdaptiveCompactionOptions | undefined): 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

@@ -461,6 +461,13 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any
      * - function: `_i` is NOT injected; intent is derived dynamically from (potentially partial / streaming) args.
      */
     intent?: "omit" | "optional" | "require" | ((args: Partial<Static<TParameters>>) => string | undefined);
+    /**
+     * Argument fields (dotted paths into the arguments object) that render as
+     * pure display text. A corroborated `\uXXXX`-escaped non-ASCII payload may
+     * execute with a warning only when every decoded non-ASCII value is under
+     * one of these paths. IDs, metadata, and all undeclared fields fail closed.
+     */
+    displaySafeEscapedArgFields?: readonly string[];
     /** The main execution callback for this tool. */
     execute: AgentToolExecFn<TParameters, TDetails, TTheme>;
     /** Optional custom rendering for tool call display (returns UI component) */

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/agent-core",
-	"version": "0.5.2",
+	"version": "0.5.8",
 	"description": "General-purpose agent with transport abstraction, state management, and attachment support",
 	"homepage": "https://sayknow-cli.com",
 	"author": "jaybeyond",
@@ -35,9 +35,9 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@sayknow-cli/ai": "0.5.2",
-		"@sayknow-cli/natives": "0.5.2",
-		"@sayknow-cli/utils": "0.5.2",
+		"@sayknow-cli/ai": "0.5.8",
+		"@sayknow-cli/natives": "0.5.8",
+		"@sayknow-cli/utils": "0.5.8",
 		"@opentelemetry/api": "^1.9.0"
 	},
 	"devDependencies": {

package/src/agent-loop.ts

@@ -21,7 +21,7 @@ import {
 	zodToWireSchema,
 } from "@sayknow-cli/ai";
 import { isInvalidPromptError, neutralizeReservedControlTokens } from "@sayknow-cli/ai/utils";
-import { sanitizeText } from "@sayknow-cli/utils";
+import { logger, sanitizeText } from "@sayknow-cli/utils";
 import {
 	createHarmonyAuditEvent,
 	detectHarmonyLeakInAssistantMessage,
@@ -113,6 +113,62 @@ const ABORTED: unique symbol = Symbol("agent-loop-aborted");
  * bounded too.
  */
 const MAX_CONSECUTIVE_MALFORMED_TURNS = 5;
+/**
+ * Validate provider-observed escaped arguments before permitting the only
+ * exception to the fail-closed tool boundary. The raw JSON must decode to the
+ * exact parsed arguments, every decoded non-ASCII scalar must be under a
+ * tool-declared display path, and the wire must not contain ASCII escapes.
+ */
+export function displaySafeEscapedArguments(
+	tool: AgentTool<TSchema> | undefined,
+	toolCall: Extract<AssistantMessage["content"][number], { type: "toolCall" }>,
+): boolean {
+	const fields = tool?.displaySafeEscapedArgFields;
+	const raw = toolCall.escapedNonAsciiArgumentsRaw;
+	if (!fields?.length || !raw) return false;
+
+	let decoded: unknown;
+	try {
+		decoded = JSON.parse(raw);
+	} catch {
+		return false;
+	}
+	if (JSON.stringify(decoded) !== JSON.stringify(toolCall.arguments)) return false;
+
+	const displayPaths = fields.map(field => field.split("."));
+	const path: string[] = [];
+	const isDisplayPath = () =>
+		displayPaths.some(
+			segments => segments.length === path.length && segments.every((segment, index) => path[index] === segment),
+		);
+	const walk = (value: unknown): boolean => {
+		if (typeof value === "string") {
+			return [...value].every(character => character.codePointAt(0)! < 0x80 || isDisplayPath());
+		}
+		if (Array.isArray(value)) return value.every(walk);
+		if (value && typeof value === "object") {
+			return Object.entries(value).every(([key, child]) => {
+				if (!/^[\x00-\x7f]*$/.test(key)) return false;
+				path.push(key);
+				const valid = walk(child);
+				path.pop();
+				return valid;
+			});
+		}
+		return true;
+	};
+	if (!walk(toolCall.arguments)) return false;
+
+	const escapes = [...raw.matchAll(/\\u([0-9a-fA-F]{4})/g)].map(match => Number.parseInt(match[1]!, 16));
+	return escapes.length > 0 && escapes.every(codeUnit => codeUnit >= 0x80);
+}
+
+function clearEscapedArgumentMetadata(
+	toolCall: Extract<AssistantMessage["content"][number], { type: "toolCall" }>,
+): void {
+	delete toolCall.escapedNonAsciiArguments;
+	delete toolCall.escapedNonAsciiArgumentsRaw;
+}
 function managedContextOverflow(message: AssistantMessage, config: AgentLoopConfig): boolean {
 	const transportFailure = managedTransportFailure(message);
 	// Managed empty-stop responses may be repaired by the managed shell below; only
@@ -1541,6 +1597,7 @@ async function runLoopBody(
 				type ToolCallContent = Extract<AssistantMessage["content"][number], { type: "toolCall" }>;
 				const toolCalls = message.content.filter((c): c is ToolCallContent => c.type === "toolCall");
 				const toolResults: ToolResultMessage[] = [];
+				for (const toolCall of toolCalls) clearEscapedArgumentMetadata(toolCall);
 				for (const toolCall of toolCalls) {
 					const result = createAbortedToolResult(toolCall, stream, message.stopReason, message.errorMessage);
 					currentContext.messages.push(result);
@@ -1571,6 +1628,7 @@ async function runLoopBody(
 			let repeatedMalformedToolCall = false;
 			if (hasMoreToolCalls) {
 				if (wasRecoveryAttempt) {
+					for (const toolCall of toolCalls) clearEscapedArgumentMetadata(toolCall);
 					for (const toolCall of toolCalls) {
 						const result = createAbortedToolResult(
 							toolCall,
@@ -2195,6 +2253,19 @@ async function executeToolCalls(
 
 		await runInActiveSpan(toolSpan, async () => {
 			try {
+				if (toolCall.escapedNonAsciiArguments) {
+					const displaySafe = displaySafeEscapedArguments(tool, toolCall);
+					clearEscapedArgumentMetadata(toolCall);
+					if (!displaySafe) {
+						record.argumentValidationFailed = true;
+						throw new Error(
+							"Tool call arguments contained unverified \\uXXXX-escaped non-ASCII text and were rejected.",
+						);
+					}
+					logger.warn("agent: executing a tool-call whose display-safe arguments were \\uXXXX-escaped", {
+						mode: config.fallbackManaged ? "managed" : "in_loop",
+					});
+				}
 				if (toolCall.incompleteArguments) {
 					record.argumentValidationFailed = true;
 					// The provider flagged this call's argument JSON as truncated

package/src/compaction/adaptive.ts

@@ -0,0 +1,116 @@
+/**
+ * Adaptive compaction state.
+ *
+ * A fixed threshold compacts at the same context percentage regardless of how
+ * fast the session is filling the window. During a tool-call burst the context
+ * can jump well past the threshold between two checks, while a slow session
+ * compacts more often than it needs to. The tracker records call rate per
+ * window so {@link ../compaction!computeAdaptiveThresholdPercent} can lower the
+ * threshold while a session is busy and leave it alone otherwise.
+ *
+ * Opt-in: with `compaction.adaptive.enabled` false the tracker is still cheap to
+ * run but its state never reaches a threshold decision.
+ */
+
+export interface AdaptiveCompactionState {
+	turnsSinceCompact: number;
+	callsInWindow: number;
+	windowStart: number;
+	lastContextTokens: number;
+	lastCompactContextTokens: number | null;
+	lastCompactTs: number | null;
+}
+
+/** The subset a threshold decision reads; keeps the decision path pure. */
+export interface AdaptiveCompactionDecisionState {
+	turnsSinceCompact: number;
+	callsInWindow: number;
+	lastContextTokens?: number;
+}
+
+export interface AdaptiveCompactionOptions {
+	enabled: boolean;
+	/** Minutes of recent calls considered when measuring call rate. */
+	turnWindow: number;
+	/** Context percentage used when the session is not busy. */
+	baseThresholdPercent: number;
+	/** How strongly call rate lowers the threshold, 0 to 1. */
+	aggression: number;
+	/** Lowest percentage the threshold may be lowered to. */
+	minThresholdPercent?: number;
+}
+
+const DEFAULT_WINDOW_MS = 60_000;
+
+function initialState(now: number): AdaptiveCompactionState {
+	return {
+		turnsSinceCompact: 0,
+		callsInWindow: 0,
+		windowStart: now,
+		lastContextTokens: 0,
+		lastCompactContextTokens: null,
+		lastCompactTs: null,
+	};
+}
+
+export class AdaptiveCompactionTracker {
+	#state: AdaptiveCompactionState;
+	#windowMs: number;
+
+	constructor(windowMs: number = DEFAULT_WINDOW_MS, now: number = Date.now()) {
+		this.#windowMs = Number.isFinite(windowMs) && windowMs > 0 ? windowMs : DEFAULT_WINDOW_MS;
+		this.#state = initialState(now);
+	}
+
+	get windowMs(): number {
+		return this.#windowMs;
+	}
+
+	/** Changing the window restarts the current count so a resize cannot inherit a rate measured over a different span. */
+	setWindowMs(windowMs: number, now: number = 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: number = Date.now()): void {
+		this.#state = initialState(now);
+	}
+
+	recordCall(contextTokens: number, now: number = 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 = Number.isFinite(contextTokens) ? Math.max(0, contextTokens) : 0;
+	}
+
+	recordCompact(contextTokens: number, now: number = Date.now()): void {
+		const timestamp = Number.isFinite(now) ? now : Date.now();
+		const safeContextTokens = Number.isFinite(contextTokens) ? Math.max(0, contextTokens) : 0;
+		this.#state.turnsSinceCompact = 0;
+		this.#state.callsInWindow = 0;
+		this.#state.windowStart = timestamp;
+		this.#state.lastContextTokens = safeContextTokens;
+		this.#state.lastCompactContextTokens = safeContextTokens;
+		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 "@sayknow-cli/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 {
@@ -136,6 +137,10 @@ export interface CompactionSettings {
 	strategy?: "context-full" | "handoff" | "off";
 	thresholdPercent?: number;
 	thresholdTokens?: number;
+	/** Opt-in adaptive threshold controls. Absent or disabled keeps the fixed threshold. */
+	adaptive?: AdaptiveCompactionOptions;
+	/** Call-rate state a threshold decision reads; supplied by the session's tracker. */
+	adaptiveState?: AdaptiveCompactionDecisionState;
 	reserveTokens: number;
 	keepRecentTokens: number;
 	autoContinue?: boolean;
@@ -244,7 +249,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;
 }
 
@@ -253,6 +258,7 @@ export type CompactionTriggerReason =
 	| "token"
 	| "heap"
 	| "retainedMemory"
+	| "transcriptFile"
 	| "providerBytes"
 	| "messageCount"
 	| "imageBytes";
@@ -275,6 +281,8 @@ export interface EmergencyCompactionSample {
 	tuiChatChildren?: number;
 	/** Bytes retained by TUI render caches. */
 	tuiCachedRenderBytes?: number;
+	/** On-disk JSONL transcript file size in bytes; 0/undefined when unknown. */
+	transcriptFileBytes?: number;
 }
 
 export interface EmergencyCompactionLimits {
@@ -286,6 +294,7 @@ export interface EmergencyCompactionLimits {
 	retainedMemoryDiagnosticBytes?: number;
 	tuiChatChildren?: number;
 	tuiChatChildrenDiagnostic?: number;
+	transcriptFileBytes?: number;
 }
 
 const MAX_EMERGENCY_HEAP_FLOOR_BYTES = 1_536 * 1024 * 1024; // 1.5 GiB resident heap
@@ -293,6 +302,7 @@ const EMERGENCY_RETAINED_MEMORY_BYTES = 128 * 1024 * 1024;
 const DIAGNOSTIC_RETAINED_MEMORY_BYTES = 64 * 1024 * 1024;
 const EMERGENCY_TUI_CHAT_CHILDREN = 1000;
 const DIAGNOSTIC_TUI_CHAT_CHILDREN = 700;
+const EMERGENCY_TRANSCRIPT_FILE_BYTES = 48 * 1024 * 1024; // 48 MiB (75% of the 64 MiB managed cap)
 let retainedMemoryDiagnosticActive = false;
 let tuiChatChildrenDiagnosticActive = false;
 
@@ -315,6 +325,7 @@ export function resolveEmergencyCompactionLimits(totalMemoryBytes: number = os.t
 		retainedMemoryDiagnosticBytes: DIAGNOSTIC_RETAINED_MEMORY_BYTES,
 		tuiChatChildren: EMERGENCY_TUI_CHAT_CHILDREN,
 		tuiChatChildrenDiagnostic: DIAGNOSTIC_TUI_CHAT_CHILDREN,
+		transcriptFileBytes: EMERGENCY_TRANSCRIPT_FILE_BYTES,
 	};
 }
 
@@ -326,7 +337,7 @@ export function resolveEmergencyCompactionLimits(totalMemoryBytes: number = os.t
 export const DEFAULT_EMERGENCY_COMPACTION_LIMITS: EmergencyCompactionLimits = resolveEmergencyCompactionLimits();
 
 /**
- * Returns the first emergency limit exceeded (heap > retainedMemory > providerBytes > imageBytes > messageCount),
+ * Returns the first emergency limit exceeded (heap > retainedMemory > transcriptFile > providerBytes > imageBytes > messageCount),
  * or null when none is. Pure apart from retained-memory diagnostics; the caller routes the result through the
  * normal pair-safe `compact()` cut logic so a tool_use/tool_result pair is never split.
  */
@@ -360,16 +371,74 @@ export function emergencyCompactionReason(
 		tuiChatChildren >= (limits.tuiChatChildren ?? EMERGENCY_TUI_CHAT_CHILDREN)
 	)
 		return "retainedMemory";
+	if (
+		sample.transcriptFileBytes &&
+		sample.transcriptFileBytes > (limits.transcriptFileBytes ?? EMERGENCY_TRANSCRIPT_FILE_BYTES)
+	)
+		return "transcriptFile";
 	if (sample.providerBytes > limits.providerBytes) return "providerBytes";
 	if (sample.imageBytes > limits.imageBytes) return "imageBytes";
 	if (sample.messageCount > limits.messageCount) return "messageCount";
 	return null;
 }
 
+/**
+ * Lower the compaction threshold while a session is filling its window quickly.
+ *
+ * Returns `basePercent` untouched unless adaptive mode is enabled and the session
+ * is both near the base threshold and past a short post-compaction grace, so a
+ * quiet or just-compacted session keeps the fixed behavior exactly.
+ */
+export function computeAdaptiveThresholdPercent(
+	basePercent: number,
+	contextTokens: number,
+	contextWindow: number,
+	state: AdaptiveCompactionDecisionState | undefined,
+	options: AdaptiveCompactionOptions | undefined,
+): number {
+	if (!options?.enabled) return basePercent;
+	const clampedBasePercent = Number.isFinite(basePercent) ? Math.min(99, Math.max(1, basePercent)) : 85;
+	if (!state || !Number.isFinite(contextWindow) || contextWindow <= 0) return clampedBasePercent;
+	if (!Number.isFinite(options.turnWindow) || options.turnWindow <= 0) return clampedBasePercent;
+
+	// Far from the base threshold there is nothing to bring forward.
+	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;
+
+	// Grace after a compaction so a burst cannot chain compactions back to back.
+	const turnsSinceCompact = Number.isFinite(state.turnsSinceCompact) ? Math.max(0, state.turnsSinceCompact) : 0;
+	if (turnsSinceCompact <= 3) return clampedBasePercent;
+
+	const callsInWindow = Number.isFinite(state.callsInWindow) ? Math.max(0, state.callsInWindow) : 0;
+	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)));
+}
+
+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;
+}
+
 export function resolveThresholdTokens(
 	contextWindow: number,
 	settings: CompactionSettings,
 	maxOutputTokens = 0,
+	contextTokens?: number,
 ): number {
 	// Fixed token limit takes priority over percentage
 	const thresholdTokens = settings.thresholdTokens;
@@ -378,13 +447,39 @@ export function resolveThresholdTokens(
 		return Math.min(contextWindow - 1, Math.max(1, thresholdTokens));
 	}
 
+	const effectiveContextTokens = adaptiveContextTokens(contextTokens, settings.adaptiveState?.lastContextTokens);
+
 	// 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);
+		}
+		// No configured percentage: adaptive supplies its own base.
+		const adaptiveBasePercent = Number.isFinite(settings.adaptive.baseThresholdPercent)
+			? Math.min(99, Math.max(1, settings.adaptive.baseThresholdPercent))
+			: 85;
+		const adaptiveThresholdPercent = computeAdaptiveThresholdPercent(
+			adaptiveBasePercent,
+			effectiveContextTokens,
+			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));
+	if (!settings.adaptive?.enabled) {
+		return Math.floor(contextWindow * (clampedThresholdPercent / 100));
+	}
+	const adaptiveThresholdPercent = computeAdaptiveThresholdPercent(
+		settings.adaptive.baseThresholdPercent ?? clampedThresholdPercent,
+		effectiveContextTokens,
+		contextWindow,
+		settings.adaptiveState,
+		settings.adaptive,
+	);
+	return Math.floor(contextWindow * (adaptiveThresholdPercent / 100));
 }
 
 // ============================================================================

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" && !Array.isArray(args) ? args : {})
 						.map(([k, v]) => `${k}=${JSON.stringify(v)}`)
 						.join(", ");
 					toolCalls.push(`${block.name}(${argsStr})`);

package/src/types.ts

@@ -539,6 +539,13 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any
 	 * - function: `_i` is NOT injected; intent is derived dynamically from (potentially partial / streaming) args.
 	 */
 	intent?: "omit" | "optional" | "require" | ((args: Partial<Static<TParameters>>) => string | undefined);
+	/**
+	 * Argument fields (dotted paths into the arguments object) that render as
+	 * pure display text. A corroborated `\uXXXX`-escaped non-ASCII payload may
+	 * execute with a warning only when every decoded non-ASCII value is under
+	 * one of these paths. IDs, metadata, and all undeclared fields fail closed.
+	 */
+	displaySafeEscapedArgFields?: readonly string[];
 
 	/** The main execution callback for this tool. */
 	execute: AgentToolExecFn<TParameters, TDetails, TTheme>;