@gajae-code/agent-core 0.8.2 → 0.9.0

package/dist/types/append-only-context.d.ts

@@ -92,10 +92,23 @@ export declare class AppendOnlyLog {
  * ctx = mgr.build(context);        // subsequent calls use cache
  * ```
  */
+export interface AppendOnlyContextManagerOptions {
+    /**
+     * Invoked whenever the stable prefix fingerprint changes on `build()` (a
+     * provider prompt-cache prefix reset). Used for per-session diagnostics; must
+     * not throw. `from` is `<unbuilt>` on the first build.
+     */
+    readonly onPrefixChange?: (info: {
+        from: string;
+        to: string;
+        version: number;
+    }) => void;
+}
 export declare class AppendOnlyContextManager {
     #private;
     readonly prefix: StablePrefix;
     readonly log: AppendOnlyLog;
+    constructor(options?: AppendOnlyContextManagerOptions);
     static forkFromSeed(args: {
         prefixSnapshot?: StablePrefixSnapshot;
         messages?: readonly Message[];

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

@@ -98,6 +98,11 @@ export declare const DEFAULT_EMERGENCY_COMPACTION_LIMITS: EmergencyCompactionLim
  */
 export declare function emergencyCompactionReason(sample: EmergencyCompactionSample, limits?: EmergencyCompactionLimits): CompactionTriggerReason | null;
 export declare function resolveThresholdTokens(contextWindow: number, settings: CompactionSettings, maxOutputTokens?: number): number;
+/**
+ * Image content has no tokenizer representation; charge a fixed estimate
+ * matching what providers typically bill for inline images.
+ */
+export declare const IMAGE_TOKEN_ESTIMATE = 1200;
 /**
  * Native-free chars/4 token estimate for a message. This is the only message
  * token estimator: provider usage (see {@link calculatePromptTokens}) anchors
@@ -243,8 +248,32 @@ export interface CompactionPreparation {
     fileOps: FileOperations;
     /** Compaction settions from settings.jsonl	*/
     settings: CompactionSettings;
+    /**
+     * Diagnostics for the keep-window token correction (Finding 7). `ratio` is the
+     * clamped heuristic→actual correction that was applied (1 when none supplied);
+     * `keepRecentTokensCorrected` is the heuristic budget findCutPoint actually used.
+     */
+    tokenCorrection: {
+        ratio: number;
+        keepRecentTokensCorrected: number;
+    };
+}
+/** Bounds for the keep-window token correction (Finding 7): never trust a ratio
+ * beyond 2x in either direction so a bad estimate cannot balloon or collapse the
+ * kept window. */
+export declare const TOKEN_CORRECTION_MIN_RATIO = 0.5;
+export declare const TOKEN_CORRECTION_MAX_RATIO = 2;
+export interface PrepareCompactionOptions {
+    /**
+     * Observed heuristic→actual token correction for the post-boundary keep window
+     * (actualTokens / chars-4-heuristicTokens), supplied by the caller from per-turn
+     * Usage deltas or a stable-prefix-subtracted comparison. Clamped to
+     * [0.5, 2] and applied bidirectionally. When omitted, no correction is applied
+     * (the confounded raw promptTokens/estimatedTokens quotient is never used).
+     */
+    tokenCorrectionRatio?: number;
 }
-export declare function prepareCompaction(pathEntries: SessionEntry[], settings: CompactionSettings): CompactionPreparation | undefined;
+export declare function prepareCompaction(pathEntries: SessionEntry[], settings: CompactionSettings, options?: PrepareCompactionOptions): CompactionPreparation | undefined;
 /**
  * Generate summaries for compaction using prepared data.
  * Returns CompactionResult - SessionManager adds id/parentId when saving.

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

@@ -44,4 +44,26 @@ export interface AssistantArgumentPruneResult {
     prunedEntries: SessionMessageEntry[];
 }
 export declare function pruneAssistantToolArguments(entries: SessionEntry[], config?: PruneConfig): AssistantArgumentPruneResult;
+/**
+ * Estimate the token savings {@link pruneToolOutputs} would achieve, without
+ * mutating any entry. Returns 0 savings when below the configured minimum so the
+ * caller sees the same gate the real prune enforces.
+ */
+export declare function estimateToolOutputPruneSavings(entries: SessionEntry[], config?: PruneConfig): {
+    prunableCount: number;
+    tokensSaved: number;
+};
+/**
+ * Evidence gate for below-threshold maintenance pruning (Finding 13). Pruning
+ * forces a prompt-cache-epoch reset, so it only runs when opted in AND the
+ * estimated stale savings clear a high minimum AND exceed the one-time reset
+ * cost (so the reclaim pays the reset back). Default-off/blocked until live
+ * evidence justifies enabling.
+ */
+export declare function shouldRunMaintenancePrune(args: {
+    enabled: boolean;
+    estimatedSavings: number;
+    minSavings: number;
+    cacheEpochResetCost: number;
+}): boolean;
 export declare function pruneToolOutputs(entries: SessionEntry[], config?: PruneConfig): PruneResult;

package/package.json

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

package/src/agent-loop.ts

@@ -342,9 +342,136 @@ export function normalizeMessagesForProvider(
 	return changed ? normalized : messages;
 }
 
+interface ConvertedContextCacheEntry {
+	messageHashes: string[];
+	modelKey: string;
+	toolKey: string;
+	intentTracing: boolean;
+	convertToLlm: AgentLoopConfig["convertToLlm"];
+	transformContext: AgentLoopConfig["transformContext"];
+	llmMessages: Context["messages"];
+	normalizedMessages: Context["messages"];
+}
+
+const convertedContextCache = new WeakMap<AgentLoopConfig, ConvertedContextCacheEntry>();
+
+function stableCacheString(value: unknown): string | undefined {
+	try {
+		return JSON.stringify(value, (_key, item) =>
+			typeof item === "function" ? `[Function:${item.name || "anonymous"}]` : item,
+		);
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Hash a message by full content serialization.
+ *
+ * Deliberately NOT memoized by object identity: callers mutate messages in
+ * place (compaction rewrites, obfuscation, abort markers) and the cache's
+ * correctness contract requires detecting those mutations. The per-turn
+ * serialization cost is the price of that contract; the win is skipping
+ * convertToLlm + normalize on stable contexts, which dominates for
+ * image-heavy histories.
+ */
+function hashMessageContent(message: AgentMessage): string | undefined {
+	return stableCacheString(message);
+}
+
+function buildConvertedContextCacheKeys(
+	messages: AgentMessage[],
+	context: AgentContext,
+	config: AgentLoopConfig,
+): Pick<ConvertedContextCacheEntry, "messageHashes" | "modelKey" | "toolKey" | "intentTracing"> | undefined {
+	const intentTracing = !!config.intentTracing;
+	const messageHashes = messages.map(hashMessageContent);
+	const modelKey = stableCacheString(config.model);
+	const toolKey = stableCacheString(normalizeTools(context.tools, intentTracing) ?? []);
+	if (messageHashes.some(hash => hash === undefined) || modelKey === undefined || toolKey === undefined) {
+		return undefined;
+	}
+	return {
+		messageHashes: messageHashes as string[],
+		modelKey,
+		toolKey,
+		intentTracing,
+	};
+}
+
+function findStablePrefixLength(previous: string[], next: string[]): number {
+	const max = Math.min(previous.length, next.length);
+	let index = 0;
+	while (index < max && previous[index] === next[index]) index++;
+	return index;
+}
+
+async function convertAndNormalizeMessages(
+	messages: AgentMessage[],
+	context: AgentContext,
+	config: AgentLoopConfig,
+): Promise<Context["messages"]> {
+	const keys = buildConvertedContextCacheKeys(messages, context, config);
+	if (!keys) {
+		return normalizeMessagesForProvider(await config.convertToLlm(messages), config.model);
+	}
+	const previous = convertedContextCache.get(config);
+	const canReuse =
+		previous &&
+		previous.convertToLlm === config.convertToLlm &&
+		previous.transformContext === config.transformContext &&
+		previous.modelKey === keys.modelKey &&
+		previous.toolKey === keys.toolKey &&
+		previous.intentTracing === keys.intentTracing;
+
+	if (canReuse) {
+		const stablePrefixLength = findStablePrefixLength(previous.messageHashes, keys.messageHashes);
+		if (stablePrefixLength === keys.messageHashes.length && stablePrefixLength === previous.messageHashes.length) {
+			return previous.normalizedMessages;
+		}
+		// Append-only fast path: convert only the new suffix and concatenate.
+		// CONTRACT: `convertToLlm` must be per-message (each output message
+		// derived solely from its input message). The bundled converters
+		// satisfy this — they map/filter message-by-message. A converter that
+		// merges adjacent messages or pairs across the suffix boundary would
+		// diverge from a full rebuild; such converters must not be combined
+		// with appendOnlyContext. Covered by the suffix-equivalence test in
+		// agent-loop-context-cache.test.ts.
+		if (
+			config.appendOnlyContext &&
+			stablePrefixLength === previous.messageHashes.length &&
+			keys.messageHashes.length > previous.messageHashes.length
+		) {
+			const suffix = messages.slice(stablePrefixLength);
+			const convertedSuffix = await config.convertToLlm(suffix);
+			const llmMessages = [...previous.llmMessages, ...convertedSuffix];
+			const normalizedMessages = normalizeMessagesForProvider(llmMessages, config.model);
+			convertedContextCache.set(config, {
+				...keys,
+				convertToLlm: config.convertToLlm,
+				transformContext: config.transformContext,
+				llmMessages,
+				normalizedMessages,
+			});
+			return normalizedMessages;
+		}
+	}
+
+	const llmMessages = await config.convertToLlm(messages);
+	const normalizedMessages = normalizeMessagesForProvider(llmMessages, config.model);
+	convertedContextCache.set(config, {
+		...keys,
+		convertToLlm: config.convertToLlm,
+		transformContext: config.transformContext,
+		llmMessages,
+		normalizedMessages,
+	});
+	return normalizedMessages;
+}
+
 export const INTENT_FIELD = "_i";
 
-function injectIntentIntoSchema(schema: unknown, mode: "require" | "optional" = "require"): unknown {
+function injectIntentIntoSchema(schema: unknown, mode: "require" | "optional" = "optional"): unknown {
 	if (!schema || typeof schema !== "object" || Array.isArray(schema)) return schema;
 	const schemaRecord = schema as Record<string, unknown>;
 	const propertiesValue = schemaRecord.properties;
@@ -400,7 +527,7 @@ export function normalizeTools(tools: AgentContext["tools"], injectIntent: boole
 function resolveIntentMode(intent: AgentTool["intent"]): "require" | "optional" | "omit" {
 	if (typeof intent === "function") return "omit";
 	if (intent === "optional" || intent === "omit") return intent;
-	return "require";
+	return intent === "require" ? "require" : "optional";
 }
 
 function extractIntent(args: Record<string, unknown>): { intent?: string; strippedArgs: Record<string, unknown> } {
@@ -711,9 +838,9 @@ async function streamAssistantResponse(
 		messages = await config.transformContext(messages, signal);
 	}
 
-	// Convert to LLM-compatible messages (AgentMessage[] → Message[])
-	const llmMessages = await config.convertToLlm(messages);
-	const normalizedMessages = normalizeMessagesForProvider(llmMessages, config.model);
+	// Convert to LLM-compatible messages (AgentMessage[] → Message[]) and normalize at the LLM boundary.
+	// Cache hits are keyed by provider-visible content hashes, never message object identity.
+	const normalizedMessages = await convertAndNormalizeMessages(messages, context, config);
 
 	// Build LLM context — append-only mode caches system prompt + tools
 	// AND keeps an append-only message log so prior-turn bytes are stable.

package/src/append-only-context.ts

@@ -194,6 +194,15 @@ export class AppendOnlyLog {
  * ctx = mgr.build(context);        // subsequent calls use cache
  * ```
  */
+export interface AppendOnlyContextManagerOptions {
+	/**
+	 * Invoked whenever the stable prefix fingerprint changes on `build()` (a
+	 * provider prompt-cache prefix reset). Used for per-session diagnostics; must
+	 * not throw. `from` is `<unbuilt>` on the first build.
+	 */
+	readonly onPrefixChange?: (info: { from: string; to: string; version: number }) => void;
+}
+
 export class AppendOnlyContextManager {
 	readonly prefix = new StablePrefix();
 	readonly log = new AppendOnlyLog();
@@ -203,6 +212,11 @@ export class AppendOnlyContextManager {
 	#syncedHashes: (number | bigint)[] = [];
 	/** Number of provider-normalized messages that were seeded before child-local messages. */
 	#seededPrefixCount = 0;
+	readonly #onPrefixChange: AppendOnlyContextManagerOptions["onPrefixChange"];
+
+	constructor(options: AppendOnlyContextManagerOptions = {}) {
+		this.#onPrefixChange = options.onPrefixChange;
+	}
 
 	static forkFromSeed(args: {
 		prefixSnapshot?: StablePrefixSnapshot;
@@ -220,7 +234,15 @@ export class AppendOnlyContextManager {
 	}
 
 	build(context: AgentContext, options: BuildOptions): Context {
-		this.prefix.build(context, options);
+		const previousFingerprint = this.prefix.fingerprint;
+		const changed = this.prefix.build(context, options);
+		if (changed && this.#onPrefixChange) {
+			this.#onPrefixChange({
+				from: previousFingerprint,
+				to: this.prefix.fingerprint,
+				version: this.prefix.version,
+			});
+		}
 		const { systemPrompt, tools } = this.prefix.toContext();
 		return { systemPrompt, messages: this.log.toMessages(), tools };
 	}

package/src/compaction/compaction.ts

@@ -315,7 +315,7 @@ export function resolveThresholdTokens(
  * Image content has no tokenizer representation; charge a fixed estimate
  * matching what providers typically bill for inline images.
  */
-const IMAGE_TOKEN_ESTIMATE = 1200;
+export const IMAGE_TOKEN_ESTIMATE = 1200;
 /**
  * Estimate tokens for collected message fragments using the native-free
  * heuristic. Provider usage is the authoritative anchor for context-changing
@@ -977,11 +977,35 @@ export interface CompactionPreparation {
 	fileOps: FileOperations;
 	/** Compaction settions from settings.jsonl	*/
 	settings: CompactionSettings;
+	/**
+	 * Diagnostics for the keep-window token correction (Finding 7). `ratio` is the
+	 * clamped heuristic→actual correction that was applied (1 when none supplied);
+	 * `keepRecentTokensCorrected` is the heuristic budget findCutPoint actually used.
+	 */
+	tokenCorrection: { ratio: number; keepRecentTokensCorrected: number };
+}
+
+/** Bounds for the keep-window token correction (Finding 7): never trust a ratio
+ * beyond 2x in either direction so a bad estimate cannot balloon or collapse the
+ * kept window. */
+export const TOKEN_CORRECTION_MIN_RATIO = 0.5;
+export const TOKEN_CORRECTION_MAX_RATIO = 2;
+
+export interface PrepareCompactionOptions {
+	/**
+	 * Observed heuristic→actual token correction for the post-boundary keep window
+	 * (actualTokens / chars-4-heuristicTokens), supplied by the caller from per-turn
+	 * Usage deltas or a stable-prefix-subtracted comparison. Clamped to
+	 * [0.5, 2] and applied bidirectionally. When omitted, no correction is applied
+	 * (the confounded raw promptTokens/estimatedTokens quotient is never used).
+	 */
+	tokenCorrectionRatio?: number;
 }
 
 export function prepareCompaction(
 	pathEntries: SessionEntry[],
 	settings: CompactionSettings,
+	options: PrepareCompactionOptions = {},
 ): CompactionPreparation | undefined {
 	if (pathEntries.length > 0 && pathEntries[pathEntries.length - 1].type === "compaction") {
 		return undefined;
@@ -999,17 +1023,22 @@ export function prepareCompaction(
 
 	const lastUsage = getLastAssistantUsage(pathEntries);
 	const tokensBefore = lastUsage ? calculateContextTokens(lastUsage) : 0;
-	let keepRecentTokens = settings.keepRecentTokens;
-	if (lastUsage) {
-		const estimatedTokens = estimateEntriesTokens(pathEntries, boundaryStart, boundaryEnd);
-		const promptTokens = calculatePromptTokens(lastUsage);
-		const ratio = estimatedTokens > 0 ? promptTokens / estimatedTokens : 0;
-		if (Number.isFinite(ratio) && ratio > 1) {
-			keepRecentTokens = Math.max(1, Math.floor(keepRecentTokens / ratio));
-		}
-	}
 
-	const cutPoint = findCutPoint(pathEntries, boundaryStart, boundaryEnd, keepRecentTokens);
+	// Correct the keep-window budget for the chars/4 heuristic error using the
+	// caller-supplied observed ratio (actual/heuristic). The legacy raw
+	// promptTokens/estimatedTokens quotient is intentionally NOT used: promptTokens
+	// counts system+tools+full history while estimatedTokens counted only the
+	// post-boundary slice, so it was confounded and only ever shrank the window.
+	// Here the correction is bidirectional and clamped to [0.5, 2].
+	const keepRecentTokens = settings.keepRecentTokens;
+	const rawRatio = options.tokenCorrectionRatio;
+	const appliedRatio =
+		rawRatio !== undefined && Number.isFinite(rawRatio) && rawRatio > 0
+			? Math.min(TOKEN_CORRECTION_MAX_RATIO, Math.max(TOKEN_CORRECTION_MIN_RATIO, rawRatio))
+			: 1;
+	const keepRecentTokensCorrected = Math.max(1, Math.round(keepRecentTokens / appliedRatio));
+
+	const cutPoint = findCutPoint(pathEntries, boundaryStart, boundaryEnd, keepRecentTokensCorrected);
 
 	// Get ID of first kept entry
 	const firstKeptEntry = pathEntries[cutPoint.firstKeptEntryIndex];
@@ -1077,6 +1106,7 @@ export function prepareCompaction(
 		previousPreserveData,
 		fileOps,
 		settings,
+		tokenCorrection: { ratio: appliedRatio, keepRecentTokensCorrected },
 	};
 }
 

package/src/compaction/pruning.ts

@@ -527,14 +527,29 @@ export function pruneAssistantToolArguments(
 	return { argumentPrunedCount: candidates.length, argumentTokensSaved, prunedEntries };
 }
 
-export function pruneToolOutputs(entries: SessionEntry[], config: PruneConfig = DEFAULT_PRUNE_CONFIG): PruneResult {
+interface ToolOutputPruneCandidate {
+	entry: SessionMessageEntry;
+	tokens: number;
+	notice: string;
+	savings: number;
+}
+
+/**
+ * Read-only pass that collects the tool-result entries that {@link pruneToolOutputs}
+ * would prune, plus the total estimated token savings. Shared by the mutating
+ * prune and the non-mutating {@link estimateToolOutputPruneSavings} so the
+ * maintenance gate (Finding 13) can decide whether pruning is worth a cache-epoch
+ * reset without rewriting history.
+ */
+function collectToolOutputPruneCandidates(
+	entries: SessionEntry[],
+	config: PruneConfig,
+): { candidates: ToolOutputPruneCandidate[]; tokensSaved: number } {
 	let accumulatedTokens = 0;
-	let tokensSaved = 0;
-	let prunedCount = 0;
 
 	const { staleResultIndices } = buildStalenessIndex(entries);
 	const staleOverridable = new Set(config.staleOverridableTools ?? []);
-	const candidates: Array<{ entry: SessionMessageEntry; tokens: number; notice: string; savings: number }> = [];
+	const candidates: ToolOutputPruneCandidate[] = [];
 
 	for (let i = entries.length - 1; i >= 0; i--) {
 		const entry = entries[i];
@@ -574,14 +589,56 @@ export function pruneToolOutputs(entries: SessionEntry[], config: PruneConfig =
 		accumulatedTokens += tokens;
 	}
 
+	let tokensSaved = 0;
 	for (const candidate of candidates) {
 		tokensSaved += candidate.savings;
 	}
+	return { candidates, tokensSaved };
+}
+
+/**
+ * Estimate the token savings {@link pruneToolOutputs} would achieve, without
+ * mutating any entry. Returns 0 savings when below the configured minimum so the
+ * caller sees the same gate the real prune enforces.
+ */
+export function estimateToolOutputPruneSavings(
+	entries: SessionEntry[],
+	config: PruneConfig = DEFAULT_PRUNE_CONFIG,
+): { prunableCount: number; tokensSaved: number } {
+	const { candidates, tokensSaved } = collectToolOutputPruneCandidates(entries, config);
+	if (tokensSaved < config.minimumSavings || candidates.length === 0) {
+		return { prunableCount: 0, tokensSaved: 0 };
+	}
+	return { prunableCount: candidates.length, tokensSaved };
+}
+
+/**
+ * Evidence gate for below-threshold maintenance pruning (Finding 13). Pruning
+ * forces a prompt-cache-epoch reset, so it only runs when opted in AND the
+ * estimated stale savings clear a high minimum AND exceed the one-time reset
+ * cost (so the reclaim pays the reset back). Default-off/blocked until live
+ * evidence justifies enabling.
+ */
+export function shouldRunMaintenancePrune(args: {
+	enabled: boolean;
+	estimatedSavings: number;
+	minSavings: number;
+	cacheEpochResetCost: number;
+}): boolean {
+	if (!args.enabled) return false;
+	if (args.estimatedSavings < args.minSavings) return false;
+	return args.estimatedSavings > args.cacheEpochResetCost;
+}
+
+export function pruneToolOutputs(entries: SessionEntry[], config: PruneConfig = DEFAULT_PRUNE_CONFIG): PruneResult {
+	const { candidates, tokensSaved } = collectToolOutputPruneCandidates(entries, config);
 
 	if (tokensSaved < config.minimumSavings || candidates.length === 0) {
 		return { prunedCount: 0, tokensSaved: 0, prunedEntries: [] };
 	}
 
+	let prunedCount = 0;
+
 	const prunedAt = Date.now();
 	const prunedEntries: SessionMessageEntry[] = [];
 	for (const candidate of candidates) {