@gajae-code/agent-core 0.14.0 → 0.14.1

package/CHANGELOG.md

@@ -2,10 +2,18 @@
 
 ## [Unreleased]
 
+## [0.14.1] - 2026-08-18
+- Compaction pruning no longer kills the turn when a persisted `toolCall.arguments` is `null`. Sessions written by an earlier cold-spill eviction path store `null` where the spill sentinel belongs, and the staleness index dereferenced that payload unguarded, so reloading such a session threw `null is not an object (evaluating 'args.path')` as a turn-fatal error instead of skipping the one unusable call. `ToolCall.arguments` is typed non-nullable, so no type check flagged the gap. Every read of a persisted argument bag — path extraction, `apply_patch` header parsing, idempotent-bash keys, and search target keys — now treats a non-object payload as absent. The original arguments are not lost: the eviction marker still names the blob and rehydration restores them.
+
+### Added
+
+- `toolFailureEnvelope` / `isToolFailureEnvelope` / `ToolFailureEnvelope` name the result details the loop attaches when a tool call fails without the tool returning details of its own. The guard matches only that envelope, so a consumer can tell it apart from a tool that reports a `failureKind` alongside its own details before dereferencing a tool-owned detail shape.
+
 ## [0.14.0] - 2026-08-17
 
 ### Fixed
 
+- Managed fallback no longer kills a long turn with `Managed fallback attempt exceeded the provisional event buffer limit`. Every staged streaming frame carries the whole accumulated partial (once as `message`, once as `assistantMessageEvent.partial`), so staged bytes grew quadratically with the response length and a reasoning-heavy turn of a few thousand tokens crossed the 16 MiB cap even though no single event came close to it. Reaching the cap now first reclaims the staged `*_delta` increments, whose complete value is re-published by the retained `*_end` and terminal `message_end`/`done` frames, and only a batch that still cannot fit fails. Attempt atomicity is unchanged: nothing is published early, so a discarded attempt stays unobservable, and a single oversized event keeps its pre-clone rejection with no provider-fallback authority.
 - Non-managed lossless response staging now commits its buffered lifecycle and switches to ordinary pass-through publication when the provisional event cap is reached, instead of turning a large reasoning-only response into a fatal `local_snapshot_failure`. Managed fallback attempts keep the strict bounded-buffer rejection required for atomic retry and provider-fallback isolation.
 - Managed snapshot machinery no longer fails runs on benign payload-class or readable-proxy roots: an assistant message or stream event whose fields live on prototype getters (which `structuredClone` drops — it copies only own enumerable properties) or behind a proxy whose gets are readable is repaired through the existing guarded-read path instead of throwing a deterministic `shell.role`/`event.unknownType`/`event.snapshot` local snapshot failure. The run-loop message_update replay also builds its event through the managed event snapshot instead of a naive `{ ...event }` spread, which silently dropped prototype-carried fields before the snapshot boundary could see them. Hostile shapes (throwing get traps, sentinel-marked degraded content, malformed non-string event types) keep their named fail-fast diagnostics with no retry authority.
 

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

@@ -5,7 +5,7 @@
 import { type AssistantMessage, type AssistantMessageEvent, type Context, EventStream } from "@gajae-code/ai";
 import type { AttemptScope } from "./attempt-scope";
 import { type AgentRunCoverage, type AgentRunSummary } from "./run-collector";
-import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, StreamFn } from "./types";
+import { type AgentContext, type AgentEvent, type AgentLoopConfig, type AgentMessage, type StreamFn } from "./types";
 /** Sentinel returned by the abort race in `streamAssistantResponse`. */
 /**
  * Defensive caps for a provisional managed attempt. These are intentionally

package/dist/types/types.d.ts

@@ -693,3 +693,25 @@ export type AgentEvent = {
     isError?: boolean;
     scope?: AttemptScope;
 };
+/**
+ * Why a tool call failed when the loop — not the tool — produced the result.
+ *
+ * `argument_validation` means the call never dispatched: the arguments were
+ * rejected before `execute` ran. `execution` means `execute` threw.
+ */
+export type ToolFailureKind = "argument_validation" | "execution";
+/**
+ * The result details the loop attaches when a tool call fails without the tool
+ * returning its own details. It carries no tool-owned field, so a consumer that
+ * dereferences a tool's own detail shape must recognise it first.
+ */
+export interface ToolFailureEnvelope {
+    failureKind: ToolFailureKind;
+}
+export declare function toolFailureEnvelope(kind: ToolFailureKind): ToolFailureEnvelope;
+/**
+ * True only for the loop's own envelope. Tools that report a `failureKind`
+ * alongside their own details (`todo_write`, todo persistence) keep those fields,
+ * so their renderers still own the result and are left alone.
+ */
+export declare function isToolFailureEnvelope(value: unknown): value is ToolFailureEnvelope;

package/package.json

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

package/src/agent-loop.ts

@@ -68,17 +68,18 @@ import {
 	bindDispatchedToolIdentity,
 	markNonDispatchedToolEvent,
 } from "./tool-dispatch-identity";
-import type {
-	AgentContext,
-	AgentEvent,
-	AgentLoopConfig,
-	AgentMessage,
-	AgentTool,
-	AgentToolContext,
-	AgentToolResult,
-	ManagedAttemptOutcome,
-	StandaloneRunOwnership,
-	StreamFn,
+import {
+	type AgentContext,
+	type AgentEvent,
+	type AgentLoopConfig,
+	type AgentMessage,
+	type AgentTool,
+	type AgentToolContext,
+	type AgentToolResult,
+	type ManagedAttemptOutcome,
+	type StandaloneRunOwnership,
+	type StreamFn,
+	toolFailureEnvelope,
 } from "./types";
 
 // Capture the intrinsic before any tool/hook can replace `Reflect.apply`. Calling this
@@ -1204,9 +1205,28 @@ function warnManagedSnapshotFailure(
  * commits the transaction.
  */
 type ManagedAttemptBatchItem =
-	| { type: "event"; event: AgentEvent }
+	| { type: "event"; event: AgentEvent; bytes?: number }
 	| { type: "assistant_event"; message: AssistantMessage; event: AssistantMessageEvent };
 
+/**
+ * Streaming increments whose complete value is re-published by the block's own
+ * `*_end` frame and by the terminal `message_end` / `done` frames. Those
+ * terminal frames are never reclaimed, so dropping the increments loses no
+ * content — only the intermediate frames that carried it on the way there.
+ */
+const MANAGED_SUPERSEDED_DELTA_EVENT_TYPES: ReadonlySet<string> = new Set([
+	"text_delta",
+	"thinking_delta",
+	"reasoning_summary_delta",
+	"toolcall_delta",
+]);
+
+function isSupersededStreamingDelta(item: ManagedAttemptBatchItem): boolean {
+	if (item.type === "assistant_event") return MANAGED_SUPERSEDED_DELTA_EVENT_TYPES.has(item.event.type);
+	if (item.event.type !== "message_update") return false;
+	return MANAGED_SUPERSEDED_DELTA_EVENT_TYPES.has(item.event.assistantMessageEvent.type);
+}
+
 class ManagedAttemptTransaction {
 	#batch: ManagedAttemptBatchItem[] = [];
 	#stagedEventCount = 0;
@@ -1369,6 +1389,48 @@ class ManagedAttemptTransaction {
 		);
 	}
 
+	/**
+	 * Reclaim staged frames that later staged frames already supersede.
+	 *
+	 * Every staged streaming frame carries the WHOLE accumulated partial (once as
+	 * `message`, once as `assistantMessageEvent.partial`), so a turn that streams
+	 * N increments stages ~N * length bytes: quadratic in the response length. A
+	 * reasoning-heavy turn of a few thousand tokens therefore used to exhaust the
+	 * provisional cap and kill the whole run, even though the attempt itself was
+	 * healthy and the cap exists only to bound memory.
+	 *
+	 * Each `*_delta` increment is re-published in full by its block's `*_end`
+	 * frame and by the terminal `message_end` / `done` frames, and those are
+	 * retained, so dropping the increments reclaims the growth without inventing
+	 * or losing content. Nothing is published here: the batch stays
+	 * all-or-nothing, so a discarded attempt remains unobservable and the
+	 * fallback chain is still untouched.
+	 *
+	 * Returns whether anything was reclaimed, so the caller can re-test the cap
+	 * and keep failing fast on a single payload that cannot fit on its own.
+	 */
+	#compactSupersededFrames(): boolean {
+		if (this.#batch.length === 0) return false;
+		const retained: ManagedAttemptBatchItem[] = [];
+		let reclaimedBytes = 0;
+		let reclaimedEvents = 0;
+		for (const item of this.#batch) {
+			if (!isSupersededStreamingDelta(item)) {
+				retained.push(item);
+				continue;
+			}
+			if (item.type === "event") {
+				reclaimedBytes += item.bytes ?? 0;
+				reclaimedEvents += 1;
+			}
+		}
+		if (retained.length === this.#batch.length) return false;
+		this.#batch = retained;
+		this.#stagedBytes -= reclaimedBytes;
+		this.#stagedEventCount -= reclaimedEvents;
+		return true;
+	}
+
 	#stage(event: AgentEvent): void {
 		if (this.snapshotMode === "lossless") {
 			const snapshot = this.#repairAssistantEvent(event);
@@ -1402,7 +1464,7 @@ class ManagedAttemptTransaction {
 				this.push(detached);
 				return;
 			}
-			this.#batch.push({ type: "event", event: detached });
+			this.#batch.push({ type: "event", event: detached, bytes: detachedBytes });
 			this.#stagedEventCount++;
 			this.#stagedBytes += detachedBytes;
 			return;
@@ -1420,8 +1482,14 @@ class ManagedAttemptTransaction {
 			bytes = undefined;
 		}
 		if (bytes !== undefined && this.#wouldOverflow(bytes)) {
-			this.discard();
-			throw new ManagedAttemptBufferOverflowError("overflow.preMeasure");
+			// A long turn reaches the cap through accumulated streaming increments,
+			// not through one oversized payload. Reclaim the superseded increments
+			// first; only a batch that still cannot fit is a real local overflow.
+			this.#compactSupersededFrames();
+			if (this.#wouldOverflow(bytes)) {
+				this.discard();
+				throw new ManagedAttemptBufferOverflowError("overflow.preMeasure");
+			}
 		}
 		const repaired = this.#repairAssistantEvent(event);
 		const detailed = managedAttemptSnapshotDetailed(repaired);
@@ -1441,10 +1509,15 @@ class ManagedAttemptTransaction {
 			throw new ManagedAttemptSnapshotError("staging.sanitize");
 		}
 		if (this.#wouldOverflow(bytes)) {
-			this.discard();
-			throw new ManagedAttemptBufferOverflowError("overflow.staged");
+			this.#compactSupersededFrames();
+			if (this.#wouldOverflow(bytes)) {
+				this.discard();
+				throw new ManagedAttemptBufferOverflowError("overflow.staged");
+			}
 		}
-		this.#batch.push({ type: "event", event: snapshot });
+		// Retain each frame's accounted size so compaction can debit exactly what
+		// it reclaims instead of re-measuring the whole batch.
+		this.#batch.push({ type: "event", event: snapshot, bytes });
 		this.#stagedEventCount += 1;
 
 		this.#stagedBytes += bytes;
@@ -3518,9 +3591,7 @@ async function executeToolCalls(
 				caughtError = e;
 				result = {
 					content: [{ type: "text", text: e instanceof Error ? e.message : String(e) }],
-					details: {
-						failureKind: record.argumentValidationFailed ? "argument_validation" : "execution",
-					},
+					details: toolFailureEnvelope(record.argumentValidationFailed ? "argument_validation" : "execution"),
 				};
 				isError = true;
 			}

package/src/compaction/pruning.ts

@@ -233,9 +233,25 @@ interface PrunedToolArgumentsSentinel {
 
 const EDIT_TOOL_NAMES = new Set(["edit", "write", "apply_patch", "ast_edit"]);
 
+/**
+ * A tool call's arguments, or `undefined` when the persisted payload is not an
+ * object.
+ *
+ * `ToolCall.arguments` is typed non-nullable, but sessions written by an older
+ * cold-spill eviction path carry `arguments: null` where the spill sentinel
+ * should be. Reading `.path` off that null threw a TypeError that surfaced as
+ * `null is not an object (evaluating 'args.path')` and killed the turn, so
+ * every reader of persisted arguments must treat them as untrusted.
+ */
+function toolArguments(call: ToolCall): Record<string, unknown> | undefined {
+	const args = call.arguments;
+	return typeof args === "object" && args !== null ? args : undefined;
+}
+
 /** Extract the file-path argument from a tool call, when the tool has one. */
 function toolCallPath(call: ToolCall): string | undefined {
-	const args = call.arguments;
+	const args = toolArguments(call);
+	if (!args) return undefined;
 	const path = args.path ?? args.file_path ?? args.filePath;
 	return typeof path === "string" && path.length > 0 ? path : undefined;
 }
@@ -260,7 +276,7 @@ const APPLY_PATCH_HEADER = /^\*\*\* (?:((?:Add|Update|Delete) File)|(Move to)):
 function editToolPathGroups(call: ToolCall): string[][] {
 	const path = toolCallPath(call);
 	if (path !== undefined) return [[path]];
-	const input = call.arguments.input;
+	const input = toolArguments(call)?.input;
 	if (typeof input !== "string") return [];
 	const groups: string[][] = [];
 	for (const match of input.matchAll(APPLY_PATCH_HEADER)) {
@@ -422,11 +438,13 @@ const IDEMPOTENT_BASH_COMMAND =
 
 function normalizedIdempotentBashCommand(call: ToolCall): string | undefined {
 	if (call.name !== "bash") return undefined;
-	const command = call.arguments.command;
+	const args = toolArguments(call);
+	if (!args) return undefined;
+	const command = args.command;
 	if (typeof command !== "string") return undefined;
 	const normalized = command.trim().replace(/\s+/g, " ");
 	if (/[;&|]/.test(normalized) || !IDEMPOTENT_BASH_COMMAND.test(normalized)) return undefined;
-	return JSON.stringify([normalized, typeof call.arguments.cwd === "string" ? call.arguments.cwd : undefined]);
+	return JSON.stringify([normalized, typeof args.cwd === "string" ? args.cwd : undefined]);
 }
 
 function toolTargetKey(call: ToolCall): string | undefined {
@@ -434,13 +452,15 @@ function toolTargetKey(call: ToolCall): string | undefined {
 	if (path !== undefined) return JSON.stringify([call.name, "path", path]);
 	const command = normalizedIdempotentBashCommand(call);
 	if (command !== undefined) return JSON.stringify([call.name, "command", command]);
-	const pattern = call.arguments.pattern;
+	const args = toolArguments(call);
+	if (!args) return undefined;
+	const pattern = args.pattern;
 	if (typeof pattern === "string" && pattern.length > 0) {
-		const paths = call.arguments.paths;
+		const paths = args.paths;
 		const pathList = Array.isArray(paths) ? paths.filter((p): p is string => typeof p === "string") : [];
-		const skip = typeof call.arguments.skip === "number" ? call.arguments.skip : 0;
-		const caseInsensitive = call.arguments.i === true;
-		const gitignore = call.arguments.gitignore !== false;
+		const skip = typeof args.skip === "number" ? args.skip : 0;
+		const caseInsensitive = args.i === true;
+		const gitignore = args.gitignore !== false;
 		return JSON.stringify([call.name, "pattern", pattern, pathList, skip, caseInsensitive, gitignore]);
 	}
 	return undefined;

package/src/types.ts

@@ -777,3 +777,37 @@ export type AgentEvent =
 			isError?: boolean;
 			scope?: AttemptScope;
 	  };
+
+/**
+ * Why a tool call failed when the loop — not the tool — produced the result.
+ *
+ * `argument_validation` means the call never dispatched: the arguments were
+ * rejected before `execute` ran. `execution` means `execute` threw.
+ */
+export type ToolFailureKind = "argument_validation" | "execution";
+
+/**
+ * The result details the loop attaches when a tool call fails without the tool
+ * returning its own details. It carries no tool-owned field, so a consumer that
+ * dereferences a tool's own detail shape must recognise it first.
+ */
+export interface ToolFailureEnvelope {
+	failureKind: ToolFailureKind;
+}
+
+export function toolFailureEnvelope(kind: ToolFailureKind): ToolFailureEnvelope {
+	return { failureKind: kind };
+}
+
+/**
+ * True only for the loop's own envelope. Tools that report a `failureKind`
+ * alongside their own details (`todo_write`, todo persistence) keep those fields,
+ * so their renderers still own the result and are left alone.
+ */
+export function isToolFailureEnvelope(value: unknown): value is ToolFailureEnvelope {
+	if (!value || typeof value !== "object") return false;
+	const keys = Object.keys(value);
+	if (keys.length !== 1 || keys[0] !== "failureKind") return false;
+	const kind = (value as ToolFailureEnvelope).failureKind;
+	return kind === "argument_validation" || kind === "execution";
+}