@gajae-code/agent-core 0.11.1 → 0.11.3

package/CHANGELOG.md

@@ -2,10 +2,17 @@
 
 ## [Unreleased]
 
+## [0.11.3] - 2026-07-19
+
+### Fixed
+- Pre-compaction pruning now preserves bounded, actionable error evidence instead of discarding it, while enforcing exact positive-savings admission and accounting so a prune is only applied when it demonstrably reduces context cost (#2635).
+
 ## [0.11.1] - 2026-07-16
 
 ### Fixed
 
+- Hardened the managed fallback attempt snapshot: staged agent events and assistant partials were cloned with a bare `structuredClone`, so a single non-cloneable value in a staged payload (e.g. a live `Headers` inside `transportFailure`) threw `DataCloneError` ("The object can not be cloned."), masked the real provider outcome, and deterministically failed every attempt until the fallback chain exhausted. The snapshot now degrades to a cycle-aware sanitizing deep clone that always returns a detached, JSON-serializable value (unsupported leaves become placeholders), so event-time replay semantics are preserved and no local snapshot failure can masquerade as a provider attempt failure. Byte accounting in the provisional buffer measures the raw event before the snapshot duplicates it (over-limit payloads are rejected pre-clone), re-measures degraded snapshots so the retained sanitized form is what gets accounted, and uses the sanitized detached form as the cycle-safe estimator for cyclic payloads.
+- Enforced the managed fallback authority boundary for local staging failures: `ManagedAttemptBufferOverflowError` no longer carries a synthetic provider-like `503` status, so exceeding the provisional event buffer limit (like any other local snapshot failure) is non-retryable, never converts into `transportFailure { kind: "transport", status: 503 }` evidence, and never rotates or consumes the model fallback chain — it surfaces as an explicit local error instead. Only original typed provider transport facts may authorize provider fallback.
 - Added a bounded, neutralize-only `invalid_prompt` circuit breaker to the agent loop (#2282). A poisoned-history rejection (`Request blocked (code=invalid_prompt)`) is a deterministic content fault: re-sending the same history re-triggers it, so uncontrolled session auto-retry would burn its budget re-poisoning the model. On the first `invalid_prompt` of a run, leaked reserved control tokens are neutralized in place across history (no item is ever dropped). If that changes the outgoing bytes, the turn is resent exactly once with the repaired history; if neutralization cannot change anything, the run fails fast immediately with no resend. The repaired history is persisted for a clean resume, the breaker fires at most once per run (budget = one repaired resend), and it is scoped to the non-managed session path since managed fallback owns its own retry policy.
 
 ## [0.10.2] - 2026-07-14

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

@@ -27,6 +27,50 @@ export declare function agentLoop(prompts: AgentMessage[], context: AgentContext
  * This cannot be validated here since `convertToLlm` is only called once per turn.
  */
 export declare function agentLoopContinue(context: AgentContext, config: AgentLoopConfig, signal?: AbortSignal, streamFn?: StreamFn, emitManagedAgentStart?: boolean): EventStream<AgentEvent, AgentMessage[]>;
+/**
+ * Hard work budget for one degraded snapshot: every visited node AND every
+ * enumerated own key is debited against this budget before it is processed
+ * (accessor keys and re-visits of shared objects included), and any remainder
+ * collapses to the deterministic `"[truncated]"` placeholder. Well above
+ * ordinary streamed events; it only bounds hostile graphs.
+ */
+export declare const MANAGED_SNAPSHOT_MAX_NODES = 100000;
+/**
+ * Cycle-aware deep clone that always returns a detached, JSON-serializable
+ * value. Used whenever a detached snapshot cannot be safely obtained or
+ * measured: after `structuredClone` fails, and again when a (successfully
+ * cloned) snapshot cannot be serialized for byte accounting.
+ *
+ * Totality rules — the walk must never dispatch through payload-controlled
+ * code, throw, or do unbounded work:
+ * - proxies (revoked or live) are collapsed to `"[unserializable]"` BEFORE
+ *   any reflective operation, so `ownKeys`/descriptor traps are never
+ *   dispatched (`util.types.isProxy` identifies proxies without touching
+ *   their handlers);
+ * - only intrinsics are used on the remaining ordinary objects (no
+ *   `input.map`, no `input.getTime()`, no `input.length` reads);
+ * - arrays are enumerated through their own present keys, never their
+ *   declared length, so a sparse array cannot force a dense allocation
+ *   proportional to `length`; sparse/exotic arrays degrade to a null-proto
+ *   record of their present indices, and the dense-shape decision verifies
+ *   every index against its ordinal;
+ * - the walk debits `maxNodes` budget per visited node and per enumerated
+ *   key before processing it; anything beyond the budget becomes
+ *   `"[truncated]"` (the one linear primitive per visited node is a single
+ *   `Object.keys` call on a non-proxy object the process already holds);
+ * - property values are read via own-property descriptors, so accessors are
+ *   never invoked (a snapshot must not cause observable side effects) and are
+ *   replaced with `"[accessor]"`;
+ * - functions/symbols and any property that cannot be read safely become
+ *   short placeholders, `bigint` becomes its decimal string, and references
+ *   back into the current path collapse to `"[Circular]"`;
+ * - records are built on a null prototype so a `__proto__` key cannot mutate
+ *   the clone's prototype chain.
+ *
+ * Exported for direct regression coverage of the budget accounting; runtime
+ * callers use the default budget via {@link managedAttemptSnapshot}.
+ */
+export declare function sanitizedDetachedClone<T>(value: T, maxNodes?: number): T;
 /**
  * Detailed-result handle returned by {@link agentLoopDetailed}. Adds the
  * run-level telemetry/coverage rollup to the existing `AgentMessage[]`

package/dist/types/agent.d.ts

@@ -184,6 +184,10 @@ export interface AgentPromptOptions {
     /** Receives a discarded managed attempt without exposing assistant lifecycle events. */
     onManagedAttemptOutcome?: AgentLoopConfig["onManagedAttemptOutcome"];
 }
+export type AgentQueueSnapshot = {
+    steering: AgentMessage[];
+    followUp: AgentMessage[];
+};
 export declare class Agent {
     #private;
     get intentTracing(): boolean;
@@ -376,6 +380,10 @@ export declare class Agent {
     snapshotFollowUp(): AgentMessage[];
     /** Restore previously snapshotted follow-up messages ahead of any newly queued ones. */
     restoreFollowUp(messages: AgentMessage[]): void;
+    /** Snapshot both executable queues as one atomic session-level view. */
+    snapshotQueues(): AgentQueueSnapshot;
+    /** Replace both executable queues with a prior snapshot. */
+    restoreQueues(snapshot: AgentQueueSnapshot): void;
     /**
      * Remove and return the last steering message from the queue (LIFO).
      * Used by dequeue keybinding.

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

@@ -192,8 +192,7 @@ export interface SummaryOptions {
     /**
      * Optional telemetry handle. When provided, every LLM call emitted during
      * compaction is wrapped in an OTEL chat span tagged with
-     * `pi.gen_ai.oneshot.kind` (`compaction_summary`, `compaction_short_summary`,
-     * or `compaction_turn_prefix`). `undefined` keeps the call paths zero-cost.
+     * `pi.gen_ai.oneshot.kind` (`compaction_summary` or `compaction_turn_prefix`).
      */
     telemetry?: AgentTelemetry;
     authCredentialType?: "api_key" | "oauth";
@@ -301,6 +300,11 @@ export interface PrepareCompactionOptions {
      * (the confounded raw promptTokens/estimatedTokens quotient is never used).
      */
     tokenCorrectionRatio?: number;
+    /**
+     * Model context-window size. Windows below 66k retain the legacy fixed
+     * keepRecentTokens behavior; larger windows scale the keep window to 30%.
+     */
+    contextWindow?: number;
 }
 export declare function prepareCompaction(pathEntries: SessionEntry[], settings: CompactionSettings, options?: PrepareCompactionOptions): CompactionPreparation | undefined;
 /**

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

@@ -49,7 +49,7 @@ export declare function pruneAssistantToolArguments(entries: SessionEntry[], con
  * 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): {
+export declare function estimateToolOutputPruneSavings(entries: SessionEntry[], config?: PruneConfig, options?: PruneToolOutputsOptions): {
     prunableCount: number;
     tokensSaved: number;
 };
@@ -66,4 +66,8 @@ export declare function shouldRunMaintenancePrune(args: {
     minSavings: number;
     cacheEpochResetCost: number;
 }): boolean;
-export declare function pruneToolOutputs(entries: SessionEntry[], config?: PruneConfig): PruneResult;
+export interface PruneToolOutputsOptions {
+    /** Lower the usual minimum only when the caller is already over its compaction threshold. */
+    relaxedMinimum?: number;
+}
+export declare function pruneToolOutputs(entries: SessionEntry[], config?: PruneConfig, options?: PruneToolOutputsOptions): PruneResult;

package/dist/types/proxy.d.ts

@@ -33,6 +33,17 @@ export type ProxyAssistantMessageEvent = {
     type: "thinking_end";
     contentIndex: number;
     contentSignature?: string;
+} | {
+    type: "reasoning_summary_start";
+    contentIndex: number;
+} | {
+    type: "reasoning_summary_delta";
+    contentIndex: number;
+    delta: string;
+} | {
+    type: "reasoning_summary_end";
+    contentIndex: number;
+    content?: string;
 } | {
     type: "toolcall_start";
     contentIndex: number;

package/dist/types/types.d.ts

@@ -1,4 +1,4 @@
-import type { AssistantMessage, AssistantMessageEvent, AssistantMessageEventStream, Effort, ImageContent, Message, Model, SimpleStreamOptions, Static, streamSimple, TextContent, Tool, ToolChoice, ToolResultMessage, TSchema } from "@gajae-code/ai";
+import type { AssistantMessage, AssistantMessageEvent, AssistantMessageEventStream, Effort, ImageContent, Message, Model, SimpleStreamOptions, Static, streamSimple, TextContent, Tool, ToolChoice, ToolResultMessage, TransportFailureFacts, TSchema } from "@gajae-code/ai";
 import type { AppendOnlyContextManager } from "./append-only-context";
 import type { HarmonyAuditEvent } from "./harmony-leak";
 import type { AgentRunCoverage, AgentRunSummary } from "./run-collector";
@@ -35,6 +35,9 @@ export type ManagedAttemptContinuation = (ownership: ManagedAttemptContinuationO
 export type ManagedAttemptDecision = {
     type: "retry";
     continuation: ManagedAttemptContinuation;
+} | {
+    type: "maintenance";
+    continuation: ManagedAttemptContinuation;
 } | {
     type: "terminal";
     terminal: RunTerminalRequest;
@@ -45,8 +48,11 @@ export type ManagedAttemptOutcome = {
     failure: {
         message: AssistantMessage;
         /** Exact provider transport facts, including retry headers, for fallback policy. */
-        transportFailure?: import("@gajae-code/ai").TransportFailureFacts;
+        transportFailure?: TransportFailureFacts;
     };
+} | {
+    type: "context_overflow_discarded";
+    message: AssistantMessage;
 } | {
     type: "run_terminal";
     reason: "cancelled" | "error" | "exhausted";

package/package.json

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