@sayknow-cli/agent-core 0.5.6 → 0.5.8

package/CHANGELOG.md

@@ -2,7 +2,13 @@
 
 ## [Unreleased]
 
-## [0.5.6] - 2026-08-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
 

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;
@@ -127,7 +132,15 @@ 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;
+/**
+ * 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/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/agent-core",
-	"version": "0.5.6",
+	"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.6",
-		"@sayknow-cli/natives": "0.5.6",
-		"@sayknow-cli/utils": "0.5.6",
+		"@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/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;
 }
 
@@ -377,10 +382,63 @@ export function emergencyCompactionReason(
 	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;
@@ -389,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";