@gajae-code/agent-core 0.5.2 → 0.5.3

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [0.5.3] - 2026-06-16
+
+### Fixed
+
+- Bounded agent context growth, compaction, and token accounting for long-running sessions: `appendMessage` pushes in place instead of rebuilding the array; the append-only context keeps rolling per-message hashes instead of rescanning the full digest; an emergency-compaction floor that cannot be disabled now surfaces its reason; `getSessionStats` is single-pass; and `nativeCountTokens` skips the synchronous ~39 MB BPE tokenizer above a 2 MiB input cap, falling back to the cheap heuristic (#717).
+
 ## [0.5.2] - 2026-06-15
 
 ### Fixed

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

@@ -66,6 +66,37 @@ export declare function effectiveReserveTokens(contextWindow: number, settings:
  * the safe input budget so prompt + reserved output cannot exceed the total window.
  */
 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" | "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). */
+    heapUsedBytes: number;
+    /** Approximate serialized provider-context bytes. */
+    providerBytes: number;
+    /** Provider-visible message count. */
+    messageCount: number;
+    /** Approximate inline image bytes in the provider context. */
+    imageBytes: number;
+}
+export interface EmergencyCompactionLimits {
+    heapUsedBytes: number;
+    providerBytes: number;
+    messageCount: number;
+    imageBytes: number;
+}
+/**
+ * Non-disableable emergency floors. These sit well above normal usage and exist so a
+ * long session on weak hardware compacts before OOM even when token-based compaction is
+ * disabled or its threshold is set too high. They are NOT user-tunable down to zero.
+ */
+export declare const DEFAULT_EMERGENCY_COMPACTION_LIMITS: EmergencyCompactionLimits;
+/**
+ * Returns the first emergency limit exceeded (heap > providerBytes > imageBytes > messageCount),
+ * or null when none is. Pure and sampler-injected; 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;
 /**
  * Estimate token count for a message using the native o200k tokenizer.

package/package.json

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

package/src/agent.ts

@@ -827,7 +827,10 @@ export class Agent {
 	}
 
 	appendMessage(m: AgentMessage) {
-		this.#state.messages = [...this.#state.messages, m];
+		// In-place push (not [...messages, m]): appending M messages over a session of
+		// N is O(N+M), not O(M*N). Consumers read state.messages fresh; run() snapshots
+		// via slice() at the API boundary, so no caller relies on per-append array identity.
+		this.#state.messages.push(m);
 	}
 
 	popMessage(): AgentMessage | undefined {

package/src/append-only-context.ts

@@ -199,8 +199,8 @@ export class AppendOnlyContextManager {
 	readonly log = new AppendOnlyLog();
 	/** How many normalized messages were synced into the log as of the last sync. */
 	#lastSyncCount = 0;
-	/** Fingerprint plus source bytes of synced message content — detects in-place rewrites with no hash-only equality. */
-	#syncedDigest = emptyMessageDigest();
+	/** Per-synced-message content hashes (rolling digest). Detects in-place rewrites without retaining a full serialized-history string. */
+	#syncedHashes: (number | bigint)[] = [];
 	/** Number of provider-normalized messages that were seeded before child-local messages. */
 	#seededPrefixCount = 0;
 
@@ -236,35 +236,41 @@ export class AppendOnlyContextManager {
 		const includesSeedPrefix =
 			seededPrefixLength > 0 &&
 			normalizedMessages.length >= seededPrefixLength &&
-			this.#computeDigestRange(normalizedMessages, 0, seededPrefixLength).source ===
-				this.#computeDigestRange(this.log.entries(), 0, seededPrefixLength).source;
+			this.#rangeHashesEqual(normalizedMessages, this.log.entries(), seededPrefixLength);
 		const messagesToSync =
 			seededPrefixLength > 0 && !includesSeedPrefix
 				? [...this.log.entries().slice(0, seededPrefixLength), ...normalizedMessages]
 				: normalizedMessages;
 
-		// Detect in-place rewrites of already-synced messages.
+		// Detect in-place rewrites of already-synced messages via per-message content
+		// hashes (no retained full serialized-history string; F5).
 		if (
 			this.#lastSyncCount > 0 &&
 			this.#lastSyncCount <= messagesToSync.length &&
-			this.#computeDigestRange(messagesToSync, 0, this.#lastSyncCount).source !== this.#syncedDigest.source
+			this.#prefixChanged(messagesToSync, this.#lastSyncCount)
 		) {
 			if (this.#seededPrefixCount > 0) {
-				throw new Error("AppendOnlyContextManager.syncMessages() seed prefix changed");
+				// F9: a seeded fork whose inherited prefix changed (e.g. after compaction)
+				// rebases onto the new provider context instead of throwing.
+				this.#rebaseToBaseline(normalizedMessages);
+				return;
 			}
 			this.log.clear();
 			this.#lastSyncCount = 0;
+			this.#syncedHashes = [];
 		}
 
-		// Compaction — array shrunk. Seeded forks preserve the inherited prefix
-		// and append child-local deltas, so a shorter child message array is not a
-		// compaction signal while a seed prefix is active.
+		// Compaction — array shrunk. Seeded forks preserve the inherited prefix and
+		// append child-local deltas, so a shorter child array is not a compaction signal
+		// while a seed prefix is active; a genuine seeded compaction rebases (F9).
 		if (messagesToSync.length < this.#lastSyncCount) {
 			if (this.#seededPrefixCount > 0) {
-				throw new Error("AppendOnlyContextManager.syncMessages() cannot compact a seeded fork without reset");
+				this.#rebaseToBaseline(normalizedMessages);
+				return;
 			}
 			this.log.clear();
 			this.#lastSyncCount = 0;
+			this.#syncedHashes = [];
 		}
 
 		const newMsgs = messagesToSync.slice(this.#lastSyncCount);
@@ -273,7 +279,7 @@ export class AppendOnlyContextManager {
 		}
 
 		this.#lastSyncCount = messagesToSync.length;
-		this.#syncedDigest = this.#computeDigest(messagesToSync);
+		this.#syncedHashes = this.#hashRange(messagesToSync, 0, messagesToSync.length);
 	}
 
 	seedNormalizedMessages(messages: readonly Message[], options?: { reset?: boolean }): void {
@@ -284,7 +290,7 @@ export class AppendOnlyContextManager {
 		this.log.clear();
 		this.log.extend(clonedMessages);
 		this.#lastSyncCount = clonedMessages.length;
-		this.#syncedDigest = this.#computeDigest(clonedMessages);
+		this.#syncedHashes = this.#hashRange(clonedMessages, 0, clonedMessages.length);
 		this.#seededPrefixCount = clonedMessages.length;
 	}
 
@@ -293,7 +299,7 @@ export class AppendOnlyContextManager {
 		this.prefix.invalidate();
 		this.log.clear();
 		this.#lastSyncCount = 0;
-		this.#syncedDigest = emptyMessageDigest();
+		this.#syncedHashes = [];
 		this.#seededPrefixCount = 0;
 	}
 
@@ -301,7 +307,7 @@ export class AppendOnlyContextManager {
 	resetSyncCursor(): void {
 		this.log.clear();
 		this.#lastSyncCount = 0;
-		this.#syncedDigest = emptyMessageDigest();
+		this.#syncedHashes = [];
 		this.#seededPrefixCount = 0;
 	}
 
@@ -321,28 +327,45 @@ export class AppendOnlyContextManager {
 		this.prefix.invalidate();
 		this.log.clear();
 		this.#lastSyncCount = 0;
-		this.#syncedDigest = emptyMessageDigest();
+		this.#syncedHashes = [];
 		this.#seededPrefixCount = 0;
 		this.prefix.build(context, options);
 	}
 
-	/**
-	 * Deterministic digest over the provider-visible message payload. The source
-	 * string is kept and compared for equality so the hash is only a fast summary,
-	 * never the authority for accepting append-only sync state.
-	 */
-	#computeDigest(messages: readonly unknown[]): MessageDigest {
-		return this.#computeDigestRange(messages, 0, messages.length);
+	#hashMessage(message: unknown): number | bigint {
+		return hashSource(JSON.stringify(message) ?? "null");
+	}
+
+	#hashRange(messages: readonly unknown[], start: number, end: number): (number | bigint)[] {
+		const out: (number | bigint)[] = [];
+		for (let i = start; i < end; i++) out.push(this.#hashMessage(messages[i]));
+		return out;
+	}
+
+	/** True when the first `count` messages of `a` and `b` are content-equal by per-message hash. */
+	#rangeHashesEqual(a: readonly unknown[], b: readonly unknown[], count: number): boolean {
+		for (let i = 0; i < count; i++) {
+			if (this.#hashMessage(a[i]) !== this.#hashMessage(b[i])) return false;
+		}
+		return true;
 	}
 
-	#computeDigestRange(messages: readonly unknown[], start: number, end: number): MessageDigest {
-		let source = "[";
-		for (let i = start; i < end; i++) {
-			if (i > start) source += ",";
-			source += JSON.stringify(messages[i]) ?? "null";
+	/** True when any of the first `count` already-synced messages changed content (in-place rewrite). */
+	#prefixChanged(messages: readonly unknown[], count: number): boolean {
+		if (count > this.#syncedHashes.length) return false;
+		for (let i = 0; i < count; i++) {
+			if (this.#hashMessage(messages[i]) !== this.#syncedHashes[i]) return true;
 		}
-		source += "]";
-		return { hash: hashSource(source), source };
+		return false;
+	}
+
+	/** F9: reset the seeded log to a new provider-visible baseline (seeded compaction/rebase). */
+	#rebaseToBaseline(messages: readonly unknown[]): void {
+		this.log.clear();
+		this.log.extend([...messages]);
+		this.#lastSyncCount = messages.length;
+		this.#seededPrefixCount = 0;
+		this.#syncedHashes = this.#hashRange(messages, 0, messages.length);
 	}
 }
 
@@ -350,15 +373,6 @@ export class AppendOnlyContextManager {
 // Snapshot helpers
 // ---------------------------------------------------------------------------
 
-type MessageDigest = {
-	hash: number | bigint;
-	source: string;
-};
-
-function emptyMessageDigest(): MessageDigest {
-	return { hash: hashSource("[]"), source: "[]" };
-}
-
 function hashSource(source: string): number | bigint {
 	return typeof Bun !== "undefined" ? Bun.hash(source) : hashString32(source);
 }

package/src/compaction/compaction.ts

@@ -236,6 +236,56 @@ export function shouldCompact(
 	return contextTokens > thresholdTokens;
 }
 
+/** Reason a compaction was triggered. `token` is the normal user-configurable path; the rest are emergency floors. */
+export type CompactionTriggerReason = "token" | "heap" | "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). */
+	heapUsedBytes: number;
+	/** Approximate serialized provider-context bytes. */
+	providerBytes: number;
+	/** Provider-visible message count. */
+	messageCount: number;
+	/** Approximate inline image bytes in the provider context. */
+	imageBytes: number;
+}
+
+export interface EmergencyCompactionLimits {
+	heapUsedBytes: number;
+	providerBytes: number;
+	messageCount: number;
+	imageBytes: number;
+}
+
+/**
+ * Non-disableable emergency floors. These sit well above normal usage and exist so a
+ * long session on weak hardware compacts before OOM even when token-based compaction is
+ * disabled or its threshold is set too high. They are NOT user-tunable down to zero.
+ */
+export const DEFAULT_EMERGENCY_COMPACTION_LIMITS: EmergencyCompactionLimits = {
+	heapUsedBytes: 1_536 * 1024 * 1024, // 1.5 GiB resident heap
+	providerBytes: 24 * 1024 * 1024, // 24 MiB serialized provider context
+	messageCount: 4000,
+	imageBytes: 64 * 1024 * 1024, // 64 MiB inline image bytes
+};
+
+/**
+ * Returns the first emergency limit exceeded (heap > providerBytes > imageBytes > messageCount),
+ * or null when none is. Pure and sampler-injected; the caller routes the result through the
+ * normal pair-safe `compact()` cut logic so a tool_use/tool_result pair is never split.
+ */
+export function emergencyCompactionReason(
+	sample: EmergencyCompactionSample,
+	limits: EmergencyCompactionLimits = DEFAULT_EMERGENCY_COMPACTION_LIMITS,
+): CompactionTriggerReason | null {
+	if (sample.heapUsedBytes > limits.heapUsedBytes) return "heap";
+	if (sample.providerBytes > limits.providerBytes) return "providerBytes";
+	if (sample.imageBytes > limits.imageBytes) return "imageBytes";
+	if (sample.messageCount > limits.messageCount) return "messageCount";
+	return null;
+}
+
 export function resolveThresholdTokens(
 	contextWindow: number,
 	settings: CompactionSettings,
@@ -301,7 +351,18 @@ function nativeTokenizerEntrypoint(): string {
 	return isCompiledBinary() ? COMPILED_NATIVE_TOKENIZER_ENTRYPOINT : SOURCE_NATIVE_TOKENIZER_ENTRYPOINT;
 }
 
+/** Max total fragment chars sent to the synchronous native tokenizer (F22). */
+const MAX_NATIVE_TOKENIZE_CHARS = 2 * 1024 * 1024;
+
 function nativeCountTokens(fragments: string[]): number {
+	let totalChars = 0;
+	for (const fragment of fragments) totalChars += fragment.length;
+	if (totalChars > MAX_NATIVE_TOKENIZE_CHARS) {
+		// F22: skip the synchronous native BPE tokenizer (materializes a ~39MB table and is
+		// O(text)) on pathologically large inputs; the cheap chars/token heuristic is more
+		// than accurate enough for size/budget decisions and never blocks the event loop.
+		return estimateTextTokensHeuristic(fragments);
+	}
 	if (!cachedNativeCountTokens) {
 		const natives = requireFromCompaction(nativeTokenizerEntrypoint()) as NativeTokenizerModule;
 		cachedNativeCountTokens = natives.countTokens;