@gajae-code/agent-core 0.9.1 → 0.9.3

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [0.9.2] - 2026-07-09
+
+### Fixed
+
+- Follow-up queues can now mark individual messages as one-at-a-time, so interactive composer queues can remain sequential without disabling the existing batch mode for other callers.
+
 ## [0.8.2] - 2026-07-06
 ### Added
 

package/dist/types/agent.d.ts

@@ -323,8 +323,14 @@ export declare class Agent {
     /**
      * Queue a follow-up message to be processed after the agent finishes.
      * Delivered only when agent has no more tool calls or steering messages.
+     *
+     * `forceOneAtATime` lets UI composer queues preserve prompt-by-prompt
+     * delivery even when the session-wide follow-up mode is set to `all` for
+     * other integration paths.
      */
-    followUp(m: AgentMessage): void;
+    followUp(m: AgentMessage, options?: {
+        forceOneAtATime?: boolean;
+    }): void;
     clearSteeringQueue(): void;
     clearFollowUpQueue(): void;
     clearAllQueues(): void;

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

@@ -67,7 +67,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" | "providerBytes" | "messageCount" | "imageBytes";
+export type CompactionTriggerReason = "token" | "heap" | "retainedMemory" | "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). */
@@ -78,13 +78,27 @@ export interface EmergencyCompactionSample {
     messageCount: number;
     /** Approximate inline image bytes in the provider context. */
     imageBytes: number;
+    /** Bytes retained by session resident image sentinels; separate from provider-visible bytes. */
+    sessionResidentImageBytes?: number;
+    /** Bytes retained by non-provider materialized/session-local caches. */
+    materializedResidentBytes?: number;
+    /** Number of live TUI chat-container children. */
+    tuiChatChildren?: number;
+    /** Bytes retained by TUI render caches. */
+    tuiCachedRenderBytes?: number;
 }
 export interface EmergencyCompactionLimits {
     heapUsedBytes: number;
     providerBytes: number;
     messageCount: number;
     imageBytes: number;
+    retainedMemoryBytes?: number;
+    retainedMemoryDiagnosticBytes?: number;
+    tuiChatChildren?: number;
+    tuiChatChildrenDiagnostic?: number;
 }
+export declare function resetEmergencyRetainedMemoryDiagnosticsForTests(): void;
+export declare function resolveEmergencyCompactionLimits(totalMemoryBytes?: number): EmergencyCompactionLimits;
 /**
  * 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
@@ -92,8 +106,8 @@ export interface EmergencyCompactionLimits {
  */
 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
+ * Returns the first emergency limit exceeded (heap > retainedMemory > 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;

package/dist/types/image-placeholder-guard.d.ts

@@ -0,0 +1,4 @@
+import type { ImageContent, TextContent } from "@gajae-code/ai";
+export declare const IMAGE_PLACEHOLDER_ATTACHMENT_GUIDANCE = "Image placeholder text was submitted without an image payload. Paste the image with #paste-image, attach it with @path/to/image.png, or save the image and provide the saved file path.";
+export declare function isImagePlaceholderOnlyText(text: string): boolean;
+export declare function assertImagePlaceholdersHavePayload(text: string, content: readonly (TextContent | ImageContent)[] | undefined): void;

package/dist/types/index.d.ts

@@ -3,6 +3,7 @@ export * from "./agent-loop";
 export * from "./append-only-context";
 export * from "./compaction";
 export * from "./harmony-leak";
+export * from "./image-placeholder-guard";
 export * from "./proxy";
 export * from "./run-collector";
 export * from "./telemetry";

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/agent-core",
-	"version": "0.9.1",
+	"version": "0.9.3",
 	"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.9.1",
-		"@gajae-code/natives": "0.9.1",
-		"@gajae-code/utils": "0.9.1",
+		"@gajae-code/ai": "0.9.3",
+		"@gajae-code/natives": "0.9.3",
+		"@gajae-code/utils": "0.9.3",
 		"@opentelemetry/api": "^1.9.0"
 	},
 	"devDependencies": {

package/src/agent.ts

@@ -23,6 +23,7 @@ import {
 import { agentLoop, agentLoopContinue } from "./agent-loop";
 import type { AppendOnlyContextManager } from "./append-only-context";
 import type { HarmonyAuditEvent } from "./harmony-leak";
+import { assertImagePlaceholdersHavePayload } from "./image-placeholder-guard";
 import type {
 	AgentContext,
 	AgentEvent,
@@ -35,6 +36,23 @@ import type {
 	ToolCallContext,
 } from "./types";
 
+function assertUserImagePlaceholdersHavePayload(messages: readonly AgentMessage[]): void {
+	for (const message of messages) {
+		if (!("role" in message) || message.role !== "user") continue;
+		const content = message.content;
+		if (typeof content === "string") {
+			assertImagePlaceholdersHavePayload(content, undefined);
+			continue;
+		}
+		if (!Array.isArray(content)) continue;
+		const text = content
+			.filter(part => part.type === "text")
+			.map(part => part.text)
+			.join("\n");
+		assertImagePlaceholdersHavePayload(text, content);
+	}
+}
+
 /**
  * Default convertToLlm: Keep only LLM-compatible messages, convert attachments.
  */
@@ -275,6 +293,7 @@ export class Agent {
 	#transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
 	#steeringQueue: AgentMessage[] = [];
 	#followUpQueue: AgentMessage[] = [];
+	#followUpForceOneAtATime = new WeakSet<AgentMessage>();
 	#steeringMode: "all" | "one-at-a-time";
 	#followUpMode: "all" | "one-at-a-time";
 	#interruptMode: "immediate" | "wait";
@@ -859,14 +878,23 @@ export class Agent {
 	 * Delivered after current tool execution, skips remaining tools.
 	 */
 	steer(m: AgentMessage) {
+		assertUserImagePlaceholdersHavePayload([m]);
 		this.#steeringQueue.push(m);
 	}
 
 	/**
 	 * Queue a follow-up message to be processed after the agent finishes.
 	 * Delivered only when agent has no more tool calls or steering messages.
+	 *
+	 * `forceOneAtATime` lets UI composer queues preserve prompt-by-prompt
+	 * delivery even when the session-wide follow-up mode is set to `all` for
+	 * other integration paths.
 	 */
-	followUp(m: AgentMessage) {
+	followUp(m: AgentMessage, options?: { forceOneAtATime?: boolean }) {
+		assertUserImagePlaceholdersHavePayload([m]);
+		if (options?.forceOneAtATime) {
+			this.#followUpForceOneAtATime.add(m);
+		}
 		this.#followUpQueue.push(m);
 	}
 
@@ -942,8 +970,18 @@ export class Agent {
 			}
 			return [];
 		}
-		const followUp = this.#followUpQueue.slice();
-		this.#followUpQueue = [];
+
+		const first = this.#followUpQueue[0];
+		if (!first) return [];
+		if (this.#followUpForceOneAtATime.has(first)) {
+			this.#followUpQueue = this.#followUpQueue.slice(1);
+			return [first];
+		}
+
+		const forcedIndex = this.#followUpQueue.findIndex(message => this.#followUpForceOneAtATime.has(message));
+		const takeCount = forcedIndex === -1 ? this.#followUpQueue.length : forcedIndex;
+		const followUp = this.#followUpQueue.slice(0, takeCount);
+		this.#followUpQueue = this.#followUpQueue.slice(takeCount);
 		return followUp;
 	}
 
@@ -1100,6 +1138,8 @@ export class Agent {
 			promptOptions = imagesOrOptions as AgentPromptOptions | undefined;
 		}
 
+		assertUserImagePlaceholdersHavePayload(msgs);
+
 		await this.#runLoop(msgs, promptOptions);
 	}
 

package/src/compaction/compaction.ts

@@ -5,6 +5,7 @@
  * and after compaction the session is reloaded.
  */
 
+import * as os from "node:os";
 import {
 	type AssistantMessage,
 	Effort,
@@ -237,7 +238,13 @@ export function shouldCompact(
 }
 
 /** 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";
+export type CompactionTriggerReason =
+	| "token"
+	| "heap"
+	| "retainedMemory"
+	| "providerBytes"
+	| "messageCount"
+	| "imageBytes";
 
 /** A point-in-time resource sample. Supplied by an injectable sampler so tests never read real RSS. */
 export interface EmergencyCompactionSample {
@@ -249,6 +256,14 @@ export interface EmergencyCompactionSample {
 	messageCount: number;
 	/** Approximate inline image bytes in the provider context. */
 	imageBytes: number;
+	/** Bytes retained by session resident image sentinels; separate from provider-visible bytes. */
+	sessionResidentImageBytes?: number;
+	/** Bytes retained by non-provider materialized/session-local caches. */
+	materializedResidentBytes?: number;
+	/** Number of live TUI chat-container children. */
+	tuiChatChildren?: number;
+	/** Bytes retained by TUI render caches. */
+	tuiCachedRenderBytes?: number;
 }
 
 export interface EmergencyCompactionLimits {
@@ -256,6 +271,40 @@ export interface EmergencyCompactionLimits {
 	providerBytes: number;
 	messageCount: number;
 	imageBytes: number;
+	retainedMemoryBytes?: number;
+	retainedMemoryDiagnosticBytes?: number;
+	tuiChatChildren?: number;
+	tuiChatChildrenDiagnostic?: number;
+}
+
+const MAX_EMERGENCY_HEAP_FLOOR_BYTES = 1_536 * 1024 * 1024; // 1.5 GiB resident heap
+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;
+let retainedMemoryDiagnosticActive = false;
+let tuiChatChildrenDiagnosticActive = false;
+
+export function resetEmergencyRetainedMemoryDiagnosticsForTests(): void {
+	retainedMemoryDiagnosticActive = false;
+	tuiChatChildrenDiagnosticActive = false;
+}
+
+export function resolveEmergencyCompactionLimits(totalMemoryBytes: number = os.totalmem()): EmergencyCompactionLimits {
+	// Invalid or non-positive total memory (bad injection, exotic platform)
+	// must never disable the heap floor — fall back to the fixed 1.5 GiB cap.
+	const safeTotal =
+		Number.isFinite(totalMemoryBytes) && totalMemoryBytes > 0 ? totalMemoryBytes : Number.POSITIVE_INFINITY;
+	return {
+		heapUsedBytes: Math.min(MAX_EMERGENCY_HEAP_FLOOR_BYTES, Math.floor(0.5 * safeTotal)),
+		providerBytes: 24 * 1024 * 1024, // 24 MiB serialized provider context
+		messageCount: 4000,
+		imageBytes: 64 * 1024 * 1024, // 64 MiB inline image bytes
+		retainedMemoryBytes: EMERGENCY_RETAINED_MEMORY_BYTES,
+		retainedMemoryDiagnosticBytes: DIAGNOSTIC_RETAINED_MEMORY_BYTES,
+		tuiChatChildren: EMERGENCY_TUI_CHAT_CHILDREN,
+		tuiChatChildrenDiagnostic: DIAGNOSTIC_TUI_CHAT_CHILDREN,
+	};
 }
 
 /**
@@ -263,23 +312,43 @@ export interface EmergencyCompactionLimits {
  * 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
-};
+export const DEFAULT_EMERGENCY_COMPACTION_LIMITS: EmergencyCompactionLimits = resolveEmergencyCompactionLimits();
 
 /**
- * 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
+ * Returns the first emergency limit exceeded (heap > retainedMemory > 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 function emergencyCompactionReason(
 	sample: EmergencyCompactionSample,
-	limits: EmergencyCompactionLimits = DEFAULT_EMERGENCY_COMPACTION_LIMITS,
+	limits: EmergencyCompactionLimits = resolveEmergencyCompactionLimits(),
 ): CompactionTriggerReason | null {
+	const retainedMemoryBytes = (sample.materializedResidentBytes ?? 0) + (sample.tuiCachedRenderBytes ?? 0);
+	const tuiChatChildren = sample.tuiChatChildren ?? 0;
+	const retainedDiagnostic =
+		retainedMemoryBytes >= (limits.retainedMemoryDiagnosticBytes ?? DIAGNOSTIC_RETAINED_MEMORY_BYTES);
+	const childDiagnostic = tuiChatChildren >= (limits.tuiChatChildrenDiagnostic ?? DIAGNOSTIC_TUI_CHAT_CHILDREN);
+	if (retainedDiagnostic && !retainedMemoryDiagnosticActive) {
+		logger.warn("Emergency compaction retained-memory diagnostic threshold crossed", {
+			retainedMemoryBytes,
+			limitBytes: limits.retainedMemoryDiagnosticBytes ?? DIAGNOSTIC_RETAINED_MEMORY_BYTES,
+		});
+	}
+	if (childDiagnostic && !tuiChatChildrenDiagnosticActive) {
+		logger.warn("Emergency compaction TUI chat-child diagnostic threshold crossed", {
+			tuiChatChildren,
+			limit: limits.tuiChatChildrenDiagnostic ?? DIAGNOSTIC_TUI_CHAT_CHILDREN,
+		});
+	}
+	retainedMemoryDiagnosticActive = retainedDiagnostic;
+	tuiChatChildrenDiagnosticActive = childDiagnostic;
+
 	if (sample.heapUsedBytes > limits.heapUsedBytes) return "heap";
+	if (
+		retainedMemoryBytes >= (limits.retainedMemoryBytes ?? EMERGENCY_RETAINED_MEMORY_BYTES) ||
+		tuiChatChildren >= (limits.tuiChatChildren ?? EMERGENCY_TUI_CHAT_CHILDREN)
+	)
+		return "retainedMemory";
 	if (sample.providerBytes > limits.providerBytes) return "providerBytes";
 	if (sample.imageBytes > limits.imageBytes) return "imageBytes";
 	if (sample.messageCount > limits.messageCount) return "messageCount";

package/src/image-placeholder-guard.ts

@@ -0,0 +1,20 @@
+import type { ImageContent, TextContent } from "@gajae-code/ai";
+
+export const IMAGE_PLACEHOLDER_ATTACHMENT_GUIDANCE =
+	"Image placeholder text was submitted without an image payload. Paste the image with #paste-image, attach it with @path/to/image.png, or save the image and provide the saved file path.";
+
+const IMAGE_PLACEHOLDER_ONLY_PATTERN = /^\s*(?:\[image\s+\d+\]\s*)+$/i;
+
+export function isImagePlaceholderOnlyText(text: string): boolean {
+	return IMAGE_PLACEHOLDER_ONLY_PATTERN.test(text);
+}
+
+export function assertImagePlaceholdersHavePayload(
+	text: string,
+	content: readonly (TextContent | ImageContent)[] | undefined,
+): void {
+	if (!isImagePlaceholderOnlyText(text)) return;
+	const hasImagePayload = content?.some(part => part.type === "image") ?? false;
+	if (hasImagePayload) return;
+	throw new Error(IMAGE_PLACEHOLDER_ATTACHMENT_GUIDANCE);
+}

package/src/index.ts

@@ -7,6 +7,7 @@ export * from "./append-only-context";
 // Compaction
 export * from "./compaction";
 export * from "./harmony-leak";
+export * from "./image-placeholder-guard";
 // Proxy utilities
 export * from "./proxy";
 // Run-level telemetry collector + aggregators