@sayknow-cli/agent-core 0.5.1 → 0.5.6

package/CHANGELOG.md

@@ -2,7 +2,13 @@
 
 ## [Unreleased]
 
-## [0.12.0] - 2026-07-28
+## [0.5.6] - 2026-08-28
+
+## [0.5.3] - 2026-08-28
+
+### Fixed
+
+- Compaction now serializes malformed persisted tool calls with null or missing arguments instead of throwing inside the recovery path, and long managed sessions trigger an emergency rewrite before their append-only transcript reaches the storage file-size ceiling.
 
 ## [0.11.11] - 2026-07-26
 

package/dist/types/agent-loop.d.ts

@@ -2,9 +2,9 @@
  * Agent loop that works with AgentMessage throughout.
  * Transforms to Message[] only at the LLM call boundary.
  */
-import { type Context, EventStream } from "@sayknow-cli/ai";
+import { type AssistantMessage, type Context, EventStream, type TSchema } from "@sayknow-cli/ai";
 import { type AgentRunCoverage, type AgentRunSummary } from "./run-collector";
-import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, StreamFn } from "./types";
+import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, AgentTool, StreamFn } from "./types";
 /** Sentinel returned by the abort race in `streamAssistantResponse`. */
 /**
  * Defensive caps for a provisional managed attempt. These are intentionally
@@ -13,6 +13,15 @@ import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, StreamFn
  */
 export declare const MANAGED_ATTEMPT_MAX_STAGED_EVENTS = 10000;
 export declare const MANAGED_ATTEMPT_MAX_STAGED_BYTES: number;
+/**
+ * Validate provider-observed escaped arguments before permitting the only
+ * exception to the fail-closed tool boundary. The raw JSON must decode to the
+ * exact parsed arguments, every decoded non-ASCII scalar must be under a
+ * tool-declared display path, and the wire must not contain ASCII escapes.
+ */
+export declare function displaySafeEscapedArguments(tool: AgentTool<TSchema> | undefined, toolCall: Extract<AssistantMessage["content"][number], {
+    type: "toolCall";
+}>): boolean;
 /**
  * Start an agent loop with a new prompt message.
  * The prompt is added to the context and events are emitted for it.

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

@@ -80,7 +80,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" | "retainedMemory" | "providerBytes" | "messageCount" | "imageBytes";
+export type CompactionTriggerReason = "token" | "heap" | "retainedMemory" | "transcriptFile" | "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). */
@@ -99,6 +99,8 @@ export interface EmergencyCompactionSample {
     tuiChatChildren?: number;
     /** Bytes retained by TUI render caches. */
     tuiCachedRenderBytes?: number;
+    /** On-disk JSONL transcript file size in bytes; 0/undefined when unknown. */
+    transcriptFileBytes?: number;
 }
 export interface EmergencyCompactionLimits {
     heapUsedBytes: number;
@@ -109,6 +111,7 @@ export interface EmergencyCompactionLimits {
     retainedMemoryDiagnosticBytes?: number;
     tuiChatChildren?: number;
     tuiChatChildrenDiagnostic?: number;
+    transcriptFileBytes?: number;
 }
 export declare function resetEmergencyRetainedMemoryDiagnosticsForTests(): void;
 export declare function resolveEmergencyCompactionLimits(totalMemoryBytes?: number): EmergencyCompactionLimits;
@@ -119,7 +122,7 @@ export declare function resolveEmergencyCompactionLimits(totalMemoryBytes?: numb
  */
 export declare const DEFAULT_EMERGENCY_COMPACTION_LIMITS: EmergencyCompactionLimits;
 /**
- * Returns the first emergency limit exceeded (heap > retainedMemory > providerBytes > imageBytes > messageCount),
+ * Returns the first emergency limit exceeded (heap > retainedMemory > transcriptFile > 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.
  */

package/dist/types/types.d.ts

@@ -461,6 +461,13 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any
      * - function: `_i` is NOT injected; intent is derived dynamically from (potentially partial / streaming) args.
      */
     intent?: "omit" | "optional" | "require" | ((args: Partial<Static<TParameters>>) => string | undefined);
+    /**
+     * Argument fields (dotted paths into the arguments object) that render as
+     * pure display text. A corroborated `\uXXXX`-escaped non-ASCII payload may
+     * execute with a warning only when every decoded non-ASCII value is under
+     * one of these paths. IDs, metadata, and all undeclared fields fail closed.
+     */
+    displaySafeEscapedArgFields?: readonly string[];
     /** The main execution callback for this tool. */
     execute: AgentToolExecFn<TParameters, TDetails, TTheme>;
     /** Optional custom rendering for tool call display (returns UI component) */

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/agent-core",
-	"version": "0.5.1",
+	"version": "0.5.6",
 	"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.1",
-		"@sayknow-cli/natives": "0.5.1",
-		"@sayknow-cli/utils": "0.5.1",
+		"@sayknow-cli/ai": "0.5.6",
+		"@sayknow-cli/natives": "0.5.6",
+		"@sayknow-cli/utils": "0.5.6",
 		"@opentelemetry/api": "^1.9.0"
 	},
 	"devDependencies": {

package/src/agent-loop.ts

@@ -21,7 +21,7 @@ import {
 	zodToWireSchema,
 } from "@sayknow-cli/ai";
 import { isInvalidPromptError, neutralizeReservedControlTokens } from "@sayknow-cli/ai/utils";
-import { sanitizeText } from "@sayknow-cli/utils";
+import { logger, sanitizeText } from "@sayknow-cli/utils";
 import {
 	createHarmonyAuditEvent,
 	detectHarmonyLeakInAssistantMessage,
@@ -113,6 +113,62 @@ const ABORTED: unique symbol = Symbol("agent-loop-aborted");
  * bounded too.
  */
 const MAX_CONSECUTIVE_MALFORMED_TURNS = 5;
+/**
+ * Validate provider-observed escaped arguments before permitting the only
+ * exception to the fail-closed tool boundary. The raw JSON must decode to the
+ * exact parsed arguments, every decoded non-ASCII scalar must be under a
+ * tool-declared display path, and the wire must not contain ASCII escapes.
+ */
+export function displaySafeEscapedArguments(
+	tool: AgentTool<TSchema> | undefined,
+	toolCall: Extract<AssistantMessage["content"][number], { type: "toolCall" }>,
+): boolean {
+	const fields = tool?.displaySafeEscapedArgFields;
+	const raw = toolCall.escapedNonAsciiArgumentsRaw;
+	if (!fields?.length || !raw) return false;
+
+	let decoded: unknown;
+	try {
+		decoded = JSON.parse(raw);
+	} catch {
+		return false;
+	}
+	if (JSON.stringify(decoded) !== JSON.stringify(toolCall.arguments)) return false;
+
+	const displayPaths = fields.map(field => field.split("."));
+	const path: string[] = [];
+	const isDisplayPath = () =>
+		displayPaths.some(
+			segments => segments.length === path.length && segments.every((segment, index) => path[index] === segment),
+		);
+	const walk = (value: unknown): boolean => {
+		if (typeof value === "string") {
+			return [...value].every(character => character.codePointAt(0)! < 0x80 || isDisplayPath());
+		}
+		if (Array.isArray(value)) return value.every(walk);
+		if (value && typeof value === "object") {
+			return Object.entries(value).every(([key, child]) => {
+				if (!/^[\x00-\x7f]*$/.test(key)) return false;
+				path.push(key);
+				const valid = walk(child);
+				path.pop();
+				return valid;
+			});
+		}
+		return true;
+	};
+	if (!walk(toolCall.arguments)) return false;
+
+	const escapes = [...raw.matchAll(/\\u([0-9a-fA-F]{4})/g)].map(match => Number.parseInt(match[1]!, 16));
+	return escapes.length > 0 && escapes.every(codeUnit => codeUnit >= 0x80);
+}
+
+function clearEscapedArgumentMetadata(
+	toolCall: Extract<AssistantMessage["content"][number], { type: "toolCall" }>,
+): void {
+	delete toolCall.escapedNonAsciiArguments;
+	delete toolCall.escapedNonAsciiArgumentsRaw;
+}
 function managedContextOverflow(message: AssistantMessage, config: AgentLoopConfig): boolean {
 	const transportFailure = managedTransportFailure(message);
 	// Managed empty-stop responses may be repaired by the managed shell below; only
@@ -1541,6 +1597,7 @@ async function runLoopBody(
 				type ToolCallContent = Extract<AssistantMessage["content"][number], { type: "toolCall" }>;
 				const toolCalls = message.content.filter((c): c is ToolCallContent => c.type === "toolCall");
 				const toolResults: ToolResultMessage[] = [];
+				for (const toolCall of toolCalls) clearEscapedArgumentMetadata(toolCall);
 				for (const toolCall of toolCalls) {
 					const result = createAbortedToolResult(toolCall, stream, message.stopReason, message.errorMessage);
 					currentContext.messages.push(result);
@@ -1571,6 +1628,7 @@ async function runLoopBody(
 			let repeatedMalformedToolCall = false;
 			if (hasMoreToolCalls) {
 				if (wasRecoveryAttempt) {
+					for (const toolCall of toolCalls) clearEscapedArgumentMetadata(toolCall);
 					for (const toolCall of toolCalls) {
 						const result = createAbortedToolResult(
 							toolCall,
@@ -2195,6 +2253,19 @@ async function executeToolCalls(
 
 		await runInActiveSpan(toolSpan, async () => {
 			try {
+				if (toolCall.escapedNonAsciiArguments) {
+					const displaySafe = displaySafeEscapedArguments(tool, toolCall);
+					clearEscapedArgumentMetadata(toolCall);
+					if (!displaySafe) {
+						record.argumentValidationFailed = true;
+						throw new Error(
+							"Tool call arguments contained unverified \\uXXXX-escaped non-ASCII text and were rejected.",
+						);
+					}
+					logger.warn("agent: executing a tool-call whose display-safe arguments were \\uXXXX-escaped", {
+						mode: config.fallbackManaged ? "managed" : "in_loop",
+					});
+				}
 				if (toolCall.incompleteArguments) {
 					record.argumentValidationFailed = true;
 					// The provider flagged this call's argument JSON as truncated

package/src/compaction/compaction.ts

@@ -253,6 +253,7 @@ export type CompactionTriggerReason =
 	| "token"
 	| "heap"
 	| "retainedMemory"
+	| "transcriptFile"
 	| "providerBytes"
 	| "messageCount"
 	| "imageBytes";
@@ -275,6 +276,8 @@ export interface EmergencyCompactionSample {
 	tuiChatChildren?: number;
 	/** Bytes retained by TUI render caches. */
 	tuiCachedRenderBytes?: number;
+	/** On-disk JSONL transcript file size in bytes; 0/undefined when unknown. */
+	transcriptFileBytes?: number;
 }
 
 export interface EmergencyCompactionLimits {
@@ -286,6 +289,7 @@ export interface EmergencyCompactionLimits {
 	retainedMemoryDiagnosticBytes?: number;
 	tuiChatChildren?: number;
 	tuiChatChildrenDiagnostic?: number;
+	transcriptFileBytes?: number;
 }
 
 const MAX_EMERGENCY_HEAP_FLOOR_BYTES = 1_536 * 1024 * 1024; // 1.5 GiB resident heap
@@ -293,6 +297,7 @@ 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;
+const EMERGENCY_TRANSCRIPT_FILE_BYTES = 48 * 1024 * 1024; // 48 MiB (75% of the 64 MiB managed cap)
 let retainedMemoryDiagnosticActive = false;
 let tuiChatChildrenDiagnosticActive = false;
 
@@ -315,6 +320,7 @@ export function resolveEmergencyCompactionLimits(totalMemoryBytes: number = os.t
 		retainedMemoryDiagnosticBytes: DIAGNOSTIC_RETAINED_MEMORY_BYTES,
 		tuiChatChildren: EMERGENCY_TUI_CHAT_CHILDREN,
 		tuiChatChildrenDiagnostic: DIAGNOSTIC_TUI_CHAT_CHILDREN,
+		transcriptFileBytes: EMERGENCY_TRANSCRIPT_FILE_BYTES,
 	};
 }
 
@@ -326,7 +332,7 @@ export function resolveEmergencyCompactionLimits(totalMemoryBytes: number = os.t
 export const DEFAULT_EMERGENCY_COMPACTION_LIMITS: EmergencyCompactionLimits = resolveEmergencyCompactionLimits();
 
 /**
- * Returns the first emergency limit exceeded (heap > retainedMemory > providerBytes > imageBytes > messageCount),
+ * Returns the first emergency limit exceeded (heap > retainedMemory > transcriptFile > 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.
  */
@@ -360,6 +366,11 @@ export function emergencyCompactionReason(
 		tuiChatChildren >= (limits.tuiChatChildren ?? EMERGENCY_TUI_CHAT_CHILDREN)
 	)
 		return "retainedMemory";
+	if (
+		sample.transcriptFileBytes &&
+		sample.transcriptFileBytes > (limits.transcriptFileBytes ?? EMERGENCY_TRANSCRIPT_FILE_BYTES)
+	)
+		return "transcriptFile";
 	if (sample.providerBytes > limits.providerBytes) return "providerBytes";
 	if (sample.imageBytes > limits.imageBytes) return "imageBytes";
 	if (sample.messageCount > limits.messageCount) return "messageCount";

package/src/compaction/utils.ts

@@ -147,8 +147,12 @@ export function serializeConversation(messages: Message[]): string {
 				} else if (block.type === "thinking") {
 					thinkingParts.push(block.thinking);
 				} else if (block.type === "toolCall") {
-					const args = block.arguments as Record<string, unknown>;
-					const argsStr = Object.entries(args)
+					// `arguments` is typed non-null, but persisted history can carry a
+					// null/non-object payload from an aborted or malformed tool call.
+					// Summarization must never throw here: this runs inside compaction,
+					// which is itself the recovery path for context overflow.
+					const args = block.arguments as Record<string, unknown> | null | undefined;
+					const argsStr = Object.entries(args && typeof args === "object" && !Array.isArray(args) ? args : {})
 						.map(([k, v]) => `${k}=${JSON.stringify(v)}`)
 						.join(", ");
 					toolCalls.push(`${block.name}(${argsStr})`);

package/src/types.ts

@@ -539,6 +539,13 @@ export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any
 	 * - function: `_i` is NOT injected; intent is derived dynamically from (potentially partial / streaming) args.
 	 */
 	intent?: "omit" | "optional" | "require" | ((args: Partial<Static<TParameters>>) => string | undefined);
+	/**
+	 * Argument fields (dotted paths into the arguments object) that render as
+	 * pure display text. A corroborated `\uXXXX`-escaped non-ASCII payload may
+	 * execute with a warning only when every decoded non-ASCII value is under
+	 * one of these paths. IDs, metadata, and all undeclared fields fail closed.
+	 */
+	displaySafeEscapedArgFields?: readonly string[];
 
 	/** The main execution callback for this tool. */
 	execute: AgentToolExecFn<TParameters, TDetails, TTheme>;