@gajae-code/agent-core 0.15.3 → 0.15.4

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [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

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/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/agent-core",
-	"version": "0.15.3",
+	"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.3",
-		"@gajae-code/natives": "0.15.3",
-		"@gajae-code/utils": "0.15.3",
+		"@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/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;
 }
 
 // ============================================================================

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";